@hasna/recordings 0.2.11 → 0.2.13

package/dist/mcp/index.js

@@ -4039,19 +4039,196 @@ var coerce = {
 };
 var NEVER = INVALID;
 // 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",
@@ -4068,17 +4245,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 {}
@@ -4095,12 +4278,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) {
@@ -4118,14 +4324,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"]) {
@@ -4144,36 +4422,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);
@@ -4183,7 +4493,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)) {
@@ -4210,7 +4520,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())
@@ -4225,14 +4535,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/sqlite-adapter.ts
@@ -4267,8 +4582,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 = [
@@ -4354,8 +4669,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");
@@ -4411,6 +4726,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 {
@@ -4435,20 +4807,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;
+    }
+    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 getRecording(id, d);
+  });
+  return create();
 }
 function getRecording(id, db) {
   const d = db || getDatabase();
@@ -4460,6 +4848,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) {
@@ -4498,12 +4900,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();
@@ -4576,16 +4973,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 {
@@ -4651,7 +5038,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) {
@@ -4944,6 +5331,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)
@@ -4953,6 +5341,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,
@@ -4969,58 +5358,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) {
@@ -5031,6 +5425,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;
@@ -5112,6 +5536,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)
@@ -5144,13 +5604,15 @@ class EnhancementError extends Error {
 
 // src/lib/transcriber.ts
 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 = {}) {
@@ -5162,7 +5624,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();
@@ -5201,14 +5663,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) {
@@ -5255,6 +5719,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:
@@ -5275,13 +5740,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",
@@ -5299,7 +5765,7 @@ ${systemPrompt}` : basePrompt;
     return {
       original: rawText,
       enhanced,
-      model: config.enhancement_model,
+      model,
       reasoning: null
     };
   } catch (error) {
@@ -5307,27 +5773,77 @@ ${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/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/mcp/index.ts
 var config = loadConfig();
 ensureDataDir(config);
+function runtimeConfig() {
+  return {
+    ...loadConfig(),
+    db_path: config.db_path,
+    audio_dir: config.audio_dir
+  };
+}
 function buildServer() {
   const server = new McpServer({
     name: "recordings",
@@ -5339,34 +5855,205 @@ function buildServer() {
   }
   function errorResult(e) {
     const msg = e instanceof Error ? e.message : String(e);
-    return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+    return { content: [{ type: "text", text: `Error: ${truncateText(msg, 500)}` }], isError: true };
   }
   function compact(r) {
-    const t = (r.processed_text || r.raw_text).slice(0, 80);
-    return `${r.id.slice(0, 8)} | ${r.processing_mode} | ${r.created_at.slice(0, 16)} | ${t}${t.length >= 80 ? "..." : ""}`;
+    const preview = truncateText(r.processed_text || r.raw_text, 100);
+    return `${truncateText(r.id, 8)} | ${truncateText(r.processing_mode, 16)} | ${truncateText(r.created_at, 16)} | ${preview}`;
   }
-  function full(r) {
-    const lines = [`ID: ${r.id}`, `Mode: ${r.processing_mode}`, `Model: ${r.model_used}`];
+  function detail(r) {
+    const lines = [`ID: ${truncateText(r.id, 80)}`, `Mode: ${truncateText(r.processing_mode, 16)}`, `Model: ${truncateText(r.model_used, 80)}`];
     if (r.enhancement_model)
-      lines.push(`Enhanced by: ${r.enhancement_model}`);
+      lines.push(`Enhanced by: ${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.tags.length > 0)
-      lines.push(`Tags: ${r.tags.join(", ")}`);
+      lines.push(`Tags: ${r.tags.map((tag) => truncateText(tag, 80)).join(", ")}`);
     if (r.agent_id)
-      lines.push(`Agent: ${r.agent_id}`);
+      lines.push(`Agent: ${truncateText(r.agent_id, 80)}`);
     if (r.project_id)
-      lines.push(`Project: ${r.project_id}`);
+      lines.push(`Project: ${truncateText(r.project_id, 80)}`);
     if (r.session_id)
-      lines.push(`Session: ${r.session_id}`);
-    lines.push(`Created: ${r.created_at}`);
-    lines.push(`Text: ${r.raw_text}`);
+      lines.push(`Session: ${truncateText(r.session_id, 80)}`);
+    lines.push(`Created: ${truncateText(r.created_at, 40)}`);
+    lines.push(`Text: ${stripTerminalControls(r.raw_text)}`);
     if (r.processed_text && r.processed_text !== r.raw_text) {
-      lines.push(`Enhanced: ${r.processed_text}`);
+      lines.push(`Enhanced: ${stripTerminalControls(r.processed_text)}`);
     }
     return lines.join(`
+`);
+  }
+  function verboseRecording(r) {
+    const lines = [
+      `${truncateText(r.id, 8)} | ${truncateText(r.processing_mode, 16)} | ${truncateText(r.created_at, 16)}`,
+      `Preview: ${truncateText(r.processed_text || r.raw_text, 180)}`,
+      `Model: ${r.enhancement_model ? `${truncateText(r.model_used, 80)} -> ${truncateText(r.enhancement_model, 80)}` : truncateText(r.model_used, 80)}`
+    ];
+    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.tags.length > 0)
+      lines.push(`Tags: ${summarizeTags(r.tags)}`);
+    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(" ")}`);
+    lines.push(`Details: get_recording { "id": "${truncateText(r.id, 8)}" }`);
+    return lines.join(`
+`);
+  }
+  function applyTranscriptionArgs(cfg, args) {
+    if (args.language)
+      cfg.language = args.language;
+    const transcriptionPrompt = args.transcription_prompt ?? args.prompt;
+    if (transcriptionPrompt !== undefined) {
+      cfg.transcription_prompt = transcriptionPrompt;
+    }
+    const transcriberPrompt = args.transcriber_prompt ?? args.system_prompt;
+    if (transcriberPrompt !== undefined) {
+      cfg.transcriber_prompt = transcriberPrompt;
+    }
+    if (args.transcriber_model) {
+      cfg.transcriber_model = args.transcriber_model;
+    } else if (args.enhancement_model) {
+      cfg.enhancement_model = args.enhancement_model;
+      cfg.transcriber_model = args.enhancement_model;
+    }
+    const requestedMode = args.post_processing_mode ?? args.post_processing;
+    if (args.no_enhance || args.enhance === false) {
+      cfg.post_processing_mode = "off";
+      normalizePostProcessingConfig(cfg, true);
+    } else if (args.enhance === true) {
+      cfg.post_processing_mode = "always";
+      normalizePostProcessingConfig(cfg, true);
+    } else if (requestedMode) {
+      cfg.post_processing_mode = normalizePostProcessingMode(requestedMode, cfg.post_processing_mode ?? "auto");
+      normalizePostProcessingConfig(cfg, true);
+    } else {
+      normalizePostProcessingConfig(cfg, false);
+    }
+    return cfg;
+  }
+  function buildTranscriptionMetadata(cfg, processed, sources = {}) {
+    const transcriptionPromptConfigured = Boolean(cfg.transcription_prompt?.trim());
+    const transcriberPromptConfigured = Boolean(cfg.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(cfg)
+    };
+  }
+  function recordingJson(r) {
+    return JSON.stringify({
+      id: r.id,
+      raw_text: r.raw_text,
+      processed_text: r.processed_text,
+      processing_mode: r.processing_mode,
+      model_used: r.model_used,
+      enhancement_model: r.enhancement_model,
+      language: r.language,
+      tags: r.tags,
+      metadata: r.metadata,
+      created_at: r.created_at
+    }, null, 2);
+  }
+  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 resolveMcpPagination(args, defaultLimit = 10) {
+    const requested = Number.isFinite(args.limit) && args.limit && args.limit > 0 ? Math.floor(args.limit) : defaultLimit;
+    const max = args.full ? 10 : 50;
+    const rawOffset = args.cursor ?? args.offset ?? 0;
+    return {
+      limit: Math.min(requested, max),
+      offset: Number.isFinite(rawOffset) ? Math.max(0, Math.floor(rawOffset)) : 0,
+      capped: requested > max
+    };
+  }
+  function withoutPagination(filter) {
+    const { limit: _limit, offset: _offset, ...rest } = filter;
+    return rest;
+  }
+  function formatMcpCollection(label, recordings, options) {
+    if (recordings.length === 0) {
+      return options.total === 0 ? `No ${label} found.` : `No ${label} at cursor ${options.offset}.`;
+    }
+    const format = options.full ? verboseRecording : compact;
+    const separator = options.full ? `
+---
+` : `
+`;
+    const end = options.offset + recordings.length;
+    const total = Math.max(options.total, end);
+    const lines = [
+      `${label}: showing ${recordings.length} of ${total} (${options.offset + 1}-${end}, limit ${options.limit})`,
+      recordings.map(format).join(separator)
+    ];
+    const hints = [];
+    if (options.capped)
+      hints.push(`limit capped at ${options.limit} for MCP output`);
+    if (end < total)
+      hints.push(`next cursor: ${end}`);
+    hints.push("use get_recording { id } for full details; set full=true for richer rows");
+    lines.push(`Hints: ${hints.join("; ")}.`);
+    return lines.join(separator);
+  }
+  function formatMcpPage(label, items, args, format) {
+    const pagination = resolveMcpPagination(args, 20);
+    const page = items.slice(pagination.offset, pagination.offset + pagination.limit);
+    if (page.length === 0) {
+      return items.length === 0 ? `No ${label}.` : `No ${label} at cursor ${pagination.offset}.`;
+    }
+    const end = pagination.offset + page.length;
+    const hints = [];
+    if (pagination.capped)
+      hints.push(`limit capped at ${pagination.limit} for MCP output`);
+    if (end < items.length)
+      hints.push(`next cursor: ${end}`);
+    return [
+      `${label}: showing ${page.length} of ${items.length} (${pagination.offset + 1}-${end}, limit ${pagination.limit})`,
+      page.map(format).join(`
+`),
+      hints.length > 0 ? `Hints: ${hints.join("; ")}.` : ""
+    ].filter(Boolean).join(`
 `);
   }
   async function saveRecordingMemento(args) {
@@ -5394,26 +6081,30 @@ function buildServer() {
     } catch {}
   }
   const toolDocs = {
-    transcribe_audio: `Transcribe audio file. Auto-enhances if needed.
-Params: audio_path (string, required): path to wav/mp3/m4a/webm | language (string): ISO code e.g. en/es/fr | no_enhance (bool): skip AI enhancement | tags (string[]): tags | agent_id (string) | project_id (string) | session_id (string)`,
+    recordings_status: `Show safe service status for agents.
+Params: none
+Returns: JSON with package version, MCP HTTP defaults, active transcription/enhancement models, language, data paths, key-presence booleans, and recording counts. Never returns secret values.`,
+    transcribe_audio: `Transcribe audio file and save raw plus optional processed text.
+Params: audio_path (string, required): path to wav/mp3/m4a/webm | language (string): ISO code e.g. en/es/fr | transcription_prompt or prompt (string): STT vocabulary/context only | transcriber_prompt or system_prompt (string): post-transcription cleanup instructions | post_processing_mode ('off'|'auto'|'always') | transcriber_model (string) | no_enhance (bool): alias for post_processing_mode=off | tags (string[]) | agent_id (string) | project_id (string) | session_id (string)
+Returns: JSON recording summary with raw_text, processed_text, processing_mode, and safe metadata.`,
     save_recording: `Save text as recording. Auto-enhances if needed.
-Params: text (string, required): text to save | enhance (bool): force enhancement | tags (string[]) | agent_id (string) | project_id (string) | session_id (string) | metadata (object)`,
+Params: text (string, required): text to save | enhance (bool): true forces always, false disables | transcriber_prompt or system_prompt (string): post-processing instructions | post_processing_mode ('off'|'auto'|'always') | tags (string[]) | agent_id (string) | project_id (string) | session_id (string) | metadata (object)`,
     get_recording: `Get recording by ID or prefix.
 Params: id (string, required): recording ID or prefix`,
-    list_recordings: `List recordings, compact by default, most recent first.
-Params: limit (number, default 10) | offset (number) | processing_mode ('raw'|'enhanced') | tags (string[]) | search (string): text search | since/until (ISO date) | agent_id | project_id | session_id | full (bool): verbose output`,
-    search_recordings: `Search recordings by text content.
-Params: query (string, required) | limit (number, default 10) | agent_id | project_id | full (bool): verbose output`,
+    list_recordings: `List recordings, compact and capped by default, most recent first.
+Params: limit (number, default 10, max 50 compact / 10 verbose) | offset or cursor (number) | processing_mode ('raw'|'enhanced') | tags (string[]) | search (string): text search | since/until (ISO date) | agent_id | project_id | session_id | full (bool): richer metadata rows with bounded previews. Use get_recording for full text/details.`,
+    search_recordings: `Search recordings by text content, compact and capped by default.
+Params: query (string, required) | limit (number, default 10, max 50 compact / 10 verbose) | offset or cursor (number) | agent_id | project_id | full (bool): richer metadata rows with bounded previews. Use get_recording for full text/details.`,
     delete_recording: `Delete recording by ID.
 Params: id (string, required)`,
-    recording_stats: `Recording count, mode breakdown, duration.
-Params: none`,
+    recording_stats: `Recording count, mode breakdown, duration, and capped model breakdown.
+Params: limit_models (number, default 10, max 10 compact / 50 verbose) | verbose (bool): allow up to 50 model counts`,
     detect_enhancement: `Check if text needs AI enhancement.
 Params: text (string, required)`,
     register_agent: `Register agent (idempotent). Auto-updates last_seen_at on re-register.
 Params: name (string, required) | description (string) | role (string)`,
-    list_agents: `List registered agents.
-Params: none`,
+    list_agents: `List registered agents, capped by default.
+Params: limit (number, default 20, max 50) | offset or cursor (number)`,
     get_agent: `Get agent by ID or name.
 Params: id (string, required)`,
     heartbeat: `Update last_seen_at to signal agent is active.
@@ -5422,16 +6113,59 @@ Params: agent_id (string, required): agent ID or name`,
 Params: agent_id (string, required) | project_id (string, nullable): project ID or null to clear`,
     register_project: `Register project (idempotent).
 Params: name (string, required) | path (string, required): absolute path | description (string)`,
-    list_projects: `List registered projects.
-Params: none`
+    list_projects: `List registered projects, capped by default.
+Params: limit (number, default 20, max 50) | offset or cursor (number)`
   };
   registerTool("describe_tool", "Get full param docs for any tool.", { name: exports_external.string() }, async (args) => {
     const doc = toolDocs[args.name];
-    return doc ? text(doc) : text(`Unknown tool: ${args.name}. Available: ${Object.keys(toolDocs).join(", ")}`);
+    return doc ? text(doc) : text(`Unknown tool: ${truncateText(args.name, 80)}. Available: ${Object.keys(toolDocs).join(", ")}`);
+  });
+  registerTool("recordings_status", "Show safe service status for agents.", {}, async () => {
+    try {
+      const cfg = runtimeConfig();
+      const stats = await getStore().getRecordingStats();
+      return text(JSON.stringify({
+        service: "recordings",
+        version: VERSION,
+        mcp: {
+          default_http_port: DEFAULT_MCP_HTTP_PORT,
+          endpoint: "/mcp"
+        },
+        config: {
+          transcription_model: cfg.transcription_model,
+          realtime_session_model: cfg.realtime_session_model,
+          realtime_transcription_model: cfg.realtime_transcription_model,
+          enhancement_model: cfg.enhancement_model,
+          transcriber_model: resolveTranscriberModel(cfg),
+          language: cfg.language,
+          auto_enhance: cfg.auto_enhance,
+          post_processing_mode: cfg.post_processing_mode,
+          transcription_prompt_configured: Boolean(cfg.transcription_prompt?.trim()),
+          transcriber_prompt_configured: Boolean(cfg.transcriber_prompt?.trim()),
+          max_recording_seconds: cfg.max_recording_seconds,
+          db_path: cfg.db_path,
+          audio_dir: cfg.audio_dir,
+          openai_api_key_configured: Boolean(cfg.openai_api_key),
+          enhancement_api_key_configured: Boolean(cfg.enhancement_api_key || cfg.openai_api_key),
+          config_warnings: cfg.config_warnings ?? []
+        },
+        stats
+      }, null, 2));
+    } catch (e) {
+      return errorResult(e);
+    }
   });
   registerTool("transcribe_audio", "Transcribe audio file. Auto-enhances if needed.", {
     audio_path: exports_external.string(),
     language: exports_external.string().optional(),
+    transcription_prompt: exports_external.string().optional(),
+    prompt: exports_external.string().optional(),
+    transcriber_prompt: exports_external.string().optional(),
+    system_prompt: exports_external.string().optional(),
+    post_processing_mode: exports_external.enum(["off", "auto", "always"]).optional(),
+    post_processing: exports_external.enum(["off", "auto", "always"]).optional(),
+    transcriber_model: exports_external.string().optional(),
+    enhancement_model: exports_external.string().optional(),
     no_enhance: exports_external.boolean().optional(),
     tags: exports_external.array(exports_external.string()).optional(),
     agent_id: exports_external.string().optional(),
@@ -5439,13 +6173,13 @@ Params: none`
     session_id: exports_external.string().optional()
   }, async (args) => {
     try {
-      const cfg = { ...config };
-      if (args.language)
-        cfg.language = args.language;
-      if (args.no_enhance)
-        cfg.auto_enhance = false;
+      const cfg = applyTranscriptionArgs({ ...runtimeConfig() }, args);
       const transcription = await transcribeAudio(args.audio_path, cfg);
       const processed = await processText(transcription.text, cfg);
+      const metadata = buildTranscriptionMetadata(cfg, processed, {
+        transcriptionPromptFromRequest: args.transcription_prompt !== undefined || args.prompt !== undefined,
+        transcriberPromptFromRequest: args.transcriber_prompt !== undefined || args.system_prompt !== undefined
+      });
       const recording = await getStore().createRecording({
         audio_path: args.audio_path,
         raw_text: transcription.text,
@@ -5458,7 +6192,9 @@ Params: none`
         tags: args.tags,
         agent_id: args.agent_id,
         project_id: args.project_id,
-        session_id: args.session_id
+        session_id: args.session_id,
+        machine_id: currentMachineId(),
+        metadata
       });
       if (args.agent_id) {
         await saveRecordingMemento({
@@ -5474,8 +6210,7 @@ Params: none`
           summary: `Recording ${recording.id.slice(0, 8)} for ${args.agent_id}`
         });
       }
-      const output = processed.mode === "enhanced" ? processed.text : transcription.text;
-      return text(`${recording.id.slice(0, 8)} | ${processed.mode} | ${output}`);
+      return text(recordingJson(recording));
     } catch (e) {
       return errorResult(e);
     }
@@ -5483,6 +6218,12 @@ Params: none`
   registerTool("save_recording", "Save text as recording. Auto-enhances if needed.", {
     text: exports_external.string(),
     enhance: exports_external.boolean().optional(),
+    transcriber_prompt: exports_external.string().optional(),
+    system_prompt: exports_external.string().optional(),
+    post_processing_mode: exports_external.enum(["off", "auto", "always"]).optional(),
+    post_processing: exports_external.enum(["off", "auto", "always"]).optional(),
+    transcriber_model: exports_external.string().optional(),
+    enhancement_model: exports_external.string().optional(),
     tags: exports_external.array(exports_external.string()).optional(),
     agent_id: exports_external.string().optional(),
     project_id: exports_external.string().optional(),
@@ -5493,17 +6234,28 @@ Params: none`
     metadata: exports_external.record(exports_external.unknown()).optional()
   }, async (args) => {
     try {
+      const cfg = applyTranscriptionArgs(runtimeConfig(), args);
       let processedText;
       let mode = "raw";
       let enhModel;
-      if (args.enhance !== false) {
-        const processed = await processText(args.text, config, undefined, { force: args.enhance === true });
-        if (processed.mode === "enhanced") {
-          processedText = processed.text;
-          mode = "enhanced";
-          enhModel = processed.enhancement_model || undefined;
-        }
+      let processed = {
+        text: args.text,
+        mode: "raw",
+        enhancement_model: null,
+        post_processing_mode: cfg.post_processing_mode ?? "auto",
+        enhancement_reason: null
+      };
+      if (cfg.post_processing_mode !== "off") {
+        processed = await processText(args.text, cfg);
       }
+      if (processed.mode === "enhanced") {
+        processedText = processed.text;
+        mode = "enhanced";
+        enhModel = processed.enhancement_model || undefined;
+      }
+      const processingMetadata = buildTranscriptionMetadata(cfg, processed, {
+        transcriberPromptFromRequest: args.transcriber_prompt !== undefined || args.system_prompt !== undefined
+      });
       const recording = await getStore().createRecording({
         raw_text: args.text,
         processed_text: processedText,
@@ -5517,10 +6269,13 @@ Params: none`
         goal: args.goal,
         role: args.role,
         task_list_id: args.task_list_id,
-        metadata: args.metadata
+        machine_id: currentMachineId(),
+        metadata: {
+          ...args.metadata ?? {},
+          ...processingMetadata
+        }
       });
-      const output = processedText || args.text;
-      return text(`${recording.id.slice(0, 8)} | ${mode} | ${output}`);
+      return text(recordingJson(recording));
     } catch (e) {
       return errorResult(e);
     }
@@ -5529,8 +6284,8 @@ Params: none`
     try {
       const r = await getStore().getRecording(args.id);
       if (!r)
-        return text(`Not found: ${args.id}`);
-      return text(full(r));
+        return text(`Not found: ${truncateText(args.id, 80)}`);
+      return text(detail(r));
     } catch (e) {
       return errorResult(e);
     }
@@ -5538,6 +6293,7 @@ Params: none`
   registerTool("list_recordings", "List recordings. Compact default, recent first.", {
     limit: exports_external.number().optional(),
     offset: exports_external.number().optional(),
+    cursor: exports_external.number().optional(),
     processing_mode: exports_external.enum(["raw", "enhanced"]).optional(),
     tags: exports_external.array(exports_external.string()).optional(),
     search: exports_external.string().optional(),
@@ -5549,9 +6305,10 @@ Params: none`
     full: exports_external.boolean().optional()
   }, async (args) => {
     try {
+      const pagination = resolveMcpPagination(args);
       const filter = {
-        limit: args.limit || 10,
-        offset: args.offset,
+        limit: pagination.limit,
+        offset: pagination.offset,
         processing_mode: args.processing_mode,
         tags: args.tags,
         search: args.search,
@@ -5561,15 +6318,18 @@ Params: none`
         project_id: args.project_id,
         session_id: args.session_id
       };
-      const recordings = await getStore().listRecordings(filter);
-      if (recordings.length === 0)
-        return text("No recordings found.");
-      const fmt = args.full ? full : compact;
-      const sep = args.full ? `
----
-` : `
-`;
-      return text(`${recordings.length} recording(s):${sep}${recordings.map(fmt).join(sep)}`);
+      const store = getStore();
+      const [recordings, total] = await Promise.all([
+        store.listRecordings(filter),
+        countStoreRecordings(store, withoutPagination(filter))
+      ]);
+      return text(formatMcpCollection("recordings", recordings, {
+        total,
+        offset: pagination.offset,
+        limit: pagination.limit,
+        full: args.full,
+        capped: pagination.capped
+      }));
     } catch (e) {
       return errorResult(e);
     }
@@ -5577,42 +6337,63 @@ Params: none`
   registerTool("search_recordings", "Search recordings by text.", {
     query: exports_external.string(),
     limit: exports_external.number().optional(),
+    offset: exports_external.number().optional(),
+    cursor: exports_external.number().optional(),
     agent_id: exports_external.string().optional(),
     project_id: exports_external.string().optional(),
+    session_id: exports_external.string().optional(),
     full: exports_external.boolean().optional()
   }, async (args) => {
     try {
-      const results = await getStore().searchRecordings(args.query, {
-        limit: args.limit || 10,
+      const pagination = resolveMcpPagination(args);
+      const filter = {
+        limit: pagination.limit,
+        offset: pagination.offset,
         agent_id: args.agent_id,
-        project_id: args.project_id
-      });
-      if (results.length === 0)
-        return text("No results.");
-      const fmt = args.full ? full : compact;
-      const sep = args.full ? `
----
-` : `
-`;
-      return text(`${results.length} result(s):${sep}${results.map(fmt).join(sep)}`);
+        project_id: args.project_id,
+        session_id: args.session_id
+      };
+      const store = getStore();
+      const [results, total] = await Promise.all([
+        store.searchRecordings(args.query, filter),
+        countStoreRecordings(store, withoutPagination({ ...filter, search: args.query }))
+      ]);
+      return text(formatMcpCollection("results", results, {
+        total,
+        offset: pagination.offset,
+        limit: pagination.limit,
+        full: args.full,
+        capped: pagination.capped
+      }));
     } catch (e) {
       return errorResult(e);
     }
   });
   registerTool("delete_recording", "Delete recording by ID.", { id: exports_external.string() }, async (args) => {
     try {
-      return text(await getStore().deleteRecording(args.id) ? `Deleted ${args.id}` : `Not found: ${args.id}`);
+      return text(await getStore().deleteRecording(args.id) ? `Deleted ${truncateText(args.id, 80)}` : `Not found: ${truncateText(args.id, 80)}`);
     } catch (e) {
       return errorResult(e);
     }
   });
-  registerTool("recording_stats", "Recording stats: count, modes, duration.", {}, async () => {
+  registerTool("recording_stats", "Recording stats: count, modes, duration, and capped model breakdown.", {
+    limit_models: exports_external.number().optional(),
+    verbose: exports_external.boolean().optional()
+  }, async (args) => {
     try {
       const s = await getStore().getRecordingStats();
       let out = `Total: ${s.total} | Raw: ${s.raw} | Enhanced: ${s.enhanced} | Duration: ${(s.total_duration_ms / 1000).toFixed(1)}s`;
-      if (Object.keys(s.by_model).length > 0) {
+      const models = Object.entries(s.by_model).sort((a, b) => b[1] - a[1]);
+      if (models.length > 0) {
+        const maxModels = args.verbose ? 50 : 10;
+        const requested = Number.isFinite(args.limit_models) && args.limit_models && args.limit_models > 0 ? Math.floor(args.limit_models) : maxModels;
+        const limit = Math.min(requested, maxModels);
         out += `
-` + Object.entries(s.by_model).map(([m, c]) => `${m}: ${c}`).join(", ");
+Models: ` + models.slice(0, limit).map(([m, c]) => `${truncateText(m, 80)}: ${c}`).join(", ");
+        if (limit < models.length) {
+          out += `
+Hints: ${models.length - limit} more model(s); call recording_stats with verbose=true and limit_models up to 50.`;
+        }
       }
       return text(out);
     } catch (e) {
@@ -5621,7 +6402,7 @@ Params: none`
   });
   registerTool("detect_enhancement", "Check if text needs AI enhancement.", { text: exports_external.string() }, async (args) => {
     try {
-      const r = needsEnhancement(args.text, config);
+      const r = needsEnhancement(args.text, runtimeConfig());
       return text(`${r.needs ? "Yes" : "No"}: ${r.reason}`);
     } catch (e) {
       return errorResult(e);
@@ -5630,18 +6411,19 @@ Params: none`
   registerTool("register_agent", "Register agent (idempotent).", { name: exports_external.string(), description: exports_external.string().optional(), role: exports_external.string().optional() }, async (args) => {
     try {
       const a = await getStore().registerAgent(args.name, args.description, args.role);
-      return text(`${a.id} | ${a.name} | ${a.role}`);
+      return text(`${truncateText(a.id, 80)} | ${truncateText(a.name, 80)} | ${truncateText(a.role, 40)}`);
     } catch (e) {
       return errorResult(e);
     }
   });
-  registerTool("list_agents", "List registered agents.", {}, async () => {
+  registerTool("list_agents", "List registered agents, capped by default.", {
+    limit: exports_external.number().optional(),
+    offset: exports_external.number().optional(),
+    cursor: exports_external.number().optional()
+  }, async (args) => {
     try {
       const agents = await getStore().listAgents();
-      if (agents.length === 0)
-        return text("None.");
-      return text(agents.map((a) => `${a.id} | ${a.name} | ${a.role}`).join(`
-`));
+      return text(formatMcpPage("agents", agents, args, (agent) => `${truncateText(agent.id, 80)} | ${truncateText(agent.name, 80)} | ${truncateText(agent.role, 40)} | last_seen: ${truncateText(agent.last_seen_at, 40)}`));
     } catch (e) {
       return errorResult(e);
     }
@@ -5650,8 +6432,8 @@ Params: none`
     try {
       const a = await getStore().getAgent(args.id);
       if (!a)
-        return text(`Not found: ${args.id}`);
-      return text(`${a.id} | ${a.name} | ${a.role} | ${a.last_seen_at}`);
+        return text(`Not found: ${truncateText(args.id, 80)}`);
+      return text(`${truncateText(a.id, 80)} | ${truncateText(a.name, 80)} | ${truncateText(a.role, 40)} | ${truncateText(a.last_seen_at, 40)}`);
     } catch (e) {
       return errorResult(e);
     }
@@ -5659,18 +6441,19 @@ Params: none`
   registerTool("register_project", "Register project (idempotent).", { name: exports_external.string(), path: exports_external.string(), description: exports_external.string().optional() }, async (args) => {
     try {
       const p = await getStore().registerProject(args.name, args.path, args.description);
-      return text(`${p.id.slice(0, 8)} | ${p.name} | ${p.path}`);
+      return text(`${truncateText(p.id, 8)} | ${truncateText(p.name, 80)} | ${truncateText(p.path, 120)}`);
     } catch (e) {
       return errorResult(e);
     }
   });
-  registerTool("list_projects", "List registered projects.", {}, async () => {
+  registerTool("list_projects", "List registered projects, capped by default.", {
+    limit: exports_external.number().optional(),
+    offset: exports_external.number().optional(),
+    cursor: exports_external.number().optional()
+  }, async (args) => {
     try {
       const projects = await getStore().listProjects();
-      if (projects.length === 0)
-        return text("None.");
-      return text(projects.map((p) => `${p.id.slice(0, 8)} | ${p.name} | ${p.path}`).join(`
-`));
+      return text(formatMcpPage("projects", projects, args, (project) => `${truncateText(project.id, 8)} | ${truncateText(project.name, 80)} | ${truncateText(project.path, 120)}`));
     } catch (e) {
       return errorResult(e);
     }
@@ -5679,8 +6462,8 @@ Params: none`
     try {
       const agent = await getStore().heartbeatAgent(args.agent_id);
       if (!agent)
-        return text(`Agent not found: ${args.agent_id}`);
-      return text(`${agent.id} | ${agent.name} | last_seen: ${agent.last_seen_at}`);
+        return text(`Agent not found: ${truncateText(args.agent_id, 80)}`);
+      return text(`${truncateText(agent.id, 80)} | ${truncateText(agent.name, 80)} | last_seen: ${truncateText(agent.last_seen_at, 40)}`);
     } catch (e) {
       return errorResult(e);
     }
@@ -5689,8 +6472,8 @@ Params: none`
     try {
       const agent = await getStore().setAgentFocus(args.agent_id, args.project_id ?? null);
       if (!agent)
-        return text(`Agent not found: ${args.agent_id}`);
-      return text(args.project_id ? `Focus set: ${args.project_id}` : "Focus cleared");
+        return text(`Agent not found: ${truncateText(args.agent_id, 80)}`);
+      return text(args.project_id ? `Focus set: ${truncateText(args.project_id, 80)}` : "Focus cleared");
     } catch (e) {
       return errorResult(e);
     }