claude-mem 13.9.0 → 13.9.2

package/dist/index.js

@@ -213,7 +213,6 @@ CREATE TABLE IF NOT EXISTS server_sessions (
   last_generated_at TIMESTAMPTZ,
   created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
   updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-  UNIQUE (project_id, external_session_id),
   FOREIGN KEY (project_id, team_id) REFERENCES projects(id, team_id) ON DELETE CASCADE
 );
 
@@ -318,6 +317,7 @@ CREATE TABLE IF NOT EXISTS observation_generation_job_events (
 
 CREATE INDEX IF NOT EXISTS idx_agent_events_project_session ON agent_events(project_id, server_session_id, occurred_at);
 ALTER TABLE server_sessions ADD COLUMN IF NOT EXISTS idempotency_key TEXT;
+ALTER TABLE server_sessions DROP CONSTRAINT IF EXISTS server_sessions_project_id_external_session_id_key;
 -- #2560 \u2014 platform_source on agent_events (consistent with server_sessions and
 -- the plan-09 scoping): which platform produced the event (claude-code,
 -- opencode, cursor, ...). Idempotent so an existing DB upgrades in place.
@@ -334,10 +334,16 @@ ALTER TABLE observation_generation_jobs DROP CONSTRAINT IF EXISTS observation_ge
 CREATE UNIQUE INDEX IF NOT EXISTS idx_server_sessions_project_idempotency
   ON server_sessions(project_id, idempotency_key)
   WHERE idempotency_key IS NOT NULL;
--- Supports the session linkage lookup on the /v1/events ingest path
--- (WHERE content_session_id = $1 AND project_id = $2 ...).
-CREATE INDEX IF NOT EXISTS idx_server_sessions_content_session
-  ON server_sessions(project_id, content_session_id)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_server_sessions_external_session_legacy
+  ON server_sessions(project_id, external_session_id)
+  WHERE external_session_id IS NOT NULL AND platform_source IS NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_server_sessions_external_session_platform
+  ON server_sessions(project_id, platform_source, external_session_id)
+  WHERE external_session_id IS NOT NULL AND platform_source IS NOT NULL;
+DROP INDEX IF EXISTS idx_server_sessions_content_session;
+-- Supports platform-aware session linkage lookup on the /v1/events ingest path.
+CREATE INDEX IF NOT EXISTS idx_server_sessions_content_session_platform
+  ON server_sessions(team_id, project_id, platform_source, content_session_id, started_at DESC)
   WHERE content_session_id IS NOT NULL;
 CREATE UNIQUE INDEX IF NOT EXISTS idx_observations_generation_key_scope
   ON observations(team_id, project_id, generation_key)
@@ -357,6 +363,29 @@ CREATE INDEX IF NOT EXISTS idx_observation_jobs_event ON observation_generation_
 CREATE INDEX IF NOT EXISTS idx_observation_jobs_source ON observation_generation_jobs(source_type, source_id);
 CREATE INDEX IF NOT EXISTS idx_observation_job_events_job_created ON observation_generation_job_events(generation_job_id, created_at);
 CREATE INDEX IF NOT EXISTS idx_audit_log_scope_created ON audit_log(project_id, team_id, created_at);
+
+-- Usage metering: append-only per-team usage, aggregated for quotas + billing.
+-- kind is open-ended ('request', 'tokens_in', 'tokens_out', 'observation', ...).
+CREATE TABLE IF NOT EXISTS usage_events (
+  id TEXT PRIMARY KEY,
+  team_id TEXT NOT NULL REFERENCES teams(id) ON DELETE CASCADE,
+  project_id TEXT REFERENCES projects(id) ON DELETE SET NULL,
+  kind TEXT NOT NULL,
+  quantity BIGINT NOT NULL DEFAULT 1,
+  metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_usage_events_team_created ON usage_events(team_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_usage_events_team_kind_created ON usage_events(team_id, kind, created_at);
+
+-- Fixed-window rate-limit counters. subject_id is the api key id (per-key limit).
+CREATE TABLE IF NOT EXISTS rate_limit_counters (
+  subject_id TEXT NOT NULL,
+  window_start TIMESTAMPTZ NOT NULL,
+  count BIGINT NOT NULL DEFAULT 0,
+  PRIMARY KEY (subject_id, window_start)
+);
+CREATE INDEX IF NOT EXISTS idx_rate_limit_counters_window ON rate_limit_counters(window_start);
 `;
 
 // src/storage/postgres/utils.ts
@@ -430,6 +459,26 @@ function sortJson(value) {
   return value;
 }
 
+// src/shared/platform-source.ts
+var DEFAULT_PLATFORM_SOURCE = "claude";
+function sanitizeRawSource(value) {
+  return value.trim().toLowerCase().replace(/\s+/g, "-");
+}
+function normalizePlatformSource(value) {
+  if (!value) return DEFAULT_PLATFORM_SOURCE;
+  const source = sanitizeRawSource(value);
+  if (!source) return DEFAULT_PLATFORM_SOURCE;
+  if (source === "transcript") return "codex";
+  if (source.includes("codex")) return "codex";
+  if (source.includes("cursor")) return "cursor";
+  if (source.includes("claude")) return "claude";
+  return source;
+}
+function normalizePlatformSourceOrNull(value) {
+  if (typeof value !== "string") return null;
+  return normalizePlatformSource(value);
+}
+
 // src/storage/postgres/agent-events.ts
 var PostgresAgentEventsRepository = class {
   constructor(client) {
@@ -441,6 +490,7 @@ var PostgresAgentEventsRepository = class {
       await assertSessionOwnership(this.client, input.serverSessionId, input.projectId, input.teamId);
     }
     const idempotencyKey = buildAgentEventIdempotencyKey(input);
+    const platformSource = normalizePlatformSourceOrNull(input.platformSource);
     const row = await queryOne(
       this.client,
       `
@@ -463,7 +513,7 @@ var PostgresAgentEventsRepository = class {
         input.sourceEventId ?? null,
         idempotencyKey,
         input.eventType,
-        input.platformSource ?? null,
+        platformSource,
         JSON.stringify(input.payload ?? {}),
         JSON.stringify(input.metadata ?? {}),
         new Date(input.occurredAt)
@@ -495,11 +545,14 @@ var PostgresAgentEventsRepository = class {
   }
 };
 function buildAgentEventIdempotencyKey(input) {
+  const platformSource = normalizePlatformSourceOrNull(input.platformSource);
+  const platformScope = platformSource ? [platformSource] : [];
   if (input.sourceEventId) {
     return `agent_event:v1:${deterministicKey([
       input.teamId,
       input.projectId,
       input.sourceAdapter,
+      ...platformScope,
       input.sourceEventId
     ])}`;
   }
@@ -507,6 +560,7 @@ function buildAgentEventIdempotencyKey(input) {
     input.teamId,
     input.projectId,
     input.sourceAdapter,
+    ...platformScope,
     input.contentSessionId ?? input.serverSessionId ?? null,
     input.eventType,
     new Date(input.occurredAt).toISOString(),
@@ -968,16 +1022,39 @@ var PostgresObservationRepository = class {
     return result.rows.map(mapObservationRow);
   }
   async search(input) {
+    const platformSource = normalizePlatformSourceOrNull(input.platformSource);
     const result = await this.client.query(
       `
-        SELECT * FROM observations
-        WHERE project_id = $1
-          AND team_id = $2
-          AND content_search @@ websearch_to_tsquery('english', $3)
-        ORDER BY ts_rank(content_search, websearch_to_tsquery('english', $3)) DESC, updated_at DESC
+        SELECT observations.* FROM observations
+        LEFT JOIN server_sessions
+          ON server_sessions.id = observations.server_session_id
+          AND server_sessions.project_id = observations.project_id
+          AND server_sessions.team_id = observations.team_id
+        WHERE observations.project_id = $1
+          AND observations.team_id = $2
+          AND observations.content_search @@ websearch_to_tsquery('english', $3)
+          AND (
+            $5::text IS NULL
+            OR server_sessions.platform_source = $5
+            OR (
+              observations.server_session_id IS NULL
+              AND EXISTS (
+                SELECT 1
+                FROM observation_sources
+                INNER JOIN agent_events
+                  ON agent_events.id = observation_sources.agent_event_id
+                  AND agent_events.project_id = observations.project_id
+                  AND agent_events.team_id = observations.team_id
+                WHERE observation_sources.observation_id = observations.id
+                  AND observation_sources.source_type = 'agent_event'
+                  AND agent_events.platform_source = $5
+              )
+            )
+          )
+        ORDER BY ts_rank(observations.content_search, websearch_to_tsquery('english', $3)) DESC, observations.updated_at DESC
         LIMIT $4
       `,
-      [input.projectId, input.teamId, input.query, input.limit ?? 20]
+      [input.projectId, input.teamId, input.query, input.limit ?? 20, platformSource]
     );
     return result.rows.map(mapObservationRow);
   }
@@ -1190,7 +1267,11 @@ var PostgresServerSessionsRepository = class {
   async create(input) {
     await assertProjectOwnership(this.client, input.projectId, input.teamId);
     const id = input.id ?? newId();
-    const idempotencyKey = buildServerSessionIdempotencyKey(input);
+    const platformSource = normalizePlatformSourceOrNull(input.platformSource);
+    const idempotencyKey = buildServerSessionIdempotencyKey({
+      ...input,
+      platformSource
+    });
     const row = await queryOne(
       this.client,
       `
@@ -1219,7 +1300,7 @@ var PostgresServerSessionsRepository = class {
         input.contentSessionId ?? null,
         input.agentId ?? null,
         input.agentType ?? null,
-        input.platformSource ?? null,
+        platformSource,
         input.generationStatus ?? "idle",
         JSON.stringify(input.metadata ?? {})
       ]
@@ -1246,13 +1327,22 @@ var PostgresServerSessionsRepository = class {
     return result.rows.map(mapServerSessionRow);
   }
   async findByExternalIdForScope(input) {
+    const hasPlatformScope = Object.prototype.hasOwnProperty.call(input, "platformSource");
+    const platformSource = hasPlatformScope ? normalizePlatformSourceOrNull(input.platformSource) : null;
     const row = await queryOne(
       this.client,
       `
         SELECT * FROM server_sessions
         WHERE external_session_id = $1 AND project_id = $2 AND team_id = $3
+          AND (
+            $4::boolean = false
+            OR ($5::text IS NULL AND platform_source IS NULL)
+            OR platform_source = $5
+          )
+        ORDER BY started_at DESC
+        LIMIT 1
       `,
-      [input.externalSessionId, input.projectId, input.teamId]
+      [input.externalSessionId, input.projectId, input.teamId, hasPlatformScope, platformSource]
     );
     return row ? mapServerSessionRow(row) : null;
   }
@@ -1260,15 +1350,22 @@ var PostgresServerSessionsRepository = class {
   // /v1/events ingest linkage path, which needs nothing but the id, so we select
   // a single column to keep this hot-path query light.
   async findIdByContentSessionId(input) {
+    const hasPlatformScope = Object.prototype.hasOwnProperty.call(input, "platformSource");
+    const platformSource = hasPlatformScope ? normalizePlatformSourceOrNull(input.platformSource) : null;
     const row = await queryOne(
       this.client,
       `
         SELECT id FROM server_sessions
         WHERE content_session_id = $1 AND project_id = $2 AND team_id = $3
+          AND (
+            $4::boolean = false
+            OR ($5::text IS NULL AND platform_source IS NULL)
+            OR platform_source = $5
+          )
         ORDER BY started_at DESC
         LIMIT 1
       `,
-      [input.contentSessionId, input.projectId, input.teamId]
+      [input.contentSessionId, input.projectId, input.teamId, hasPlatformScope, platformSource]
     );
     return row ? row.id : null;
   }
@@ -1388,30 +1485,35 @@ function mapUnprocessedEventRow(row) {
   };
 }
 function buildServerSessionIdempotencyKey(input) {
+  const platformSource = normalizePlatformSourceOrNull(input.platformSource);
   if (input.externalSessionId) {
-    return `server_session:v1:${deterministicKey([
+    const parts = [
       input.teamId,
       input.projectId,
-      "external",
-      input.externalSessionId
-    ])}`;
+      "external"
+    ];
+    if (platformSource) {
+      parts.push(platformSource);
+    }
+    parts.push(input.externalSessionId);
+    return `server_session:v1:${deterministicKey(parts)}`;
   }
   if (input.contentSessionId) {
     return `server_session:v1:${deterministicKey([
       input.teamId,
       input.projectId,
       "content",
-      input.platformSource ?? null,
+      platformSource,
       input.agentId ?? null,
       input.contentSessionId
     ])}`;
   }
-  if (input.agentId && input.platformSource) {
+  if (input.agentId && platformSource) {
     return `server_session:v1:${deterministicKey([
       input.teamId,
       input.projectId,
       "agent",
-      input.platformSource,
+      platformSource,
       input.agentId,
       input.agentType ?? null
     ])}`;
@@ -1507,6 +1609,77 @@ function mapTeamMemberRow(row) {
   };
 }
 
+// src/storage/postgres/usage.ts
+var PostgresUsageRepository = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async record(input) {
+    await this.client.query(
+      `INSERT INTO usage_events (id, team_id, project_id, kind, quantity, metadata)
+       VALUES ($1, $2, $3, $4, $5, $6::jsonb)`,
+      [
+        newId(),
+        input.teamId,
+        input.projectId ?? null,
+        input.kind,
+        Math.max(0, Math.trunc(input.quantity ?? 1)),
+        JSON.stringify(input.metadata ?? {})
+      ]
+    );
+  }
+  /** Total quantity of one `kind` for a team since `since` — the quota read. */
+  async total(input) {
+    const res = await this.client.query(
+      `SELECT COALESCE(SUM(quantity), 0)::bigint AS total
+         FROM usage_events
+        WHERE team_id = $1 AND kind = $2 AND created_at >= $3`,
+      [input.teamId, input.kind, input.since]
+    );
+    return Number(res.rows[0]?.total ?? 0);
+  }
+  /** Per-kind totals for a team since `since` — the /v1/usage read. */
+  async summarize(input) {
+    const res = await this.client.query(
+      `SELECT kind, SUM(quantity)::bigint AS total
+         FROM usage_events
+        WHERE team_id = $1 AND created_at >= $2
+        GROUP BY kind`,
+      [input.teamId, input.since]
+    );
+    const out = {};
+    for (const row of res.rows) out[row.kind] = Number(row.total);
+    return out;
+  }
+};
+
+// src/storage/postgres/rate-limit.ts
+var PostgresRateLimitRepository = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Atomically increment the current window's counter for `subjectId` and
+   * report whether it is still within `limit`.
+   */
+  async hit(input) {
+    const res = await this.client.query(
+      `INSERT INTO rate_limit_counters (subject_id, window_start, count)
+       VALUES ($1, $2, 1)
+       ON CONFLICT (subject_id, window_start)
+       DO UPDATE SET count = rate_limit_counters.count + 1
+       RETURNING count`,
+      [input.subjectId, input.windowStart]
+    );
+    const count = Number(res.rows[0]?.count ?? 0);
+    return { allowed: count <= input.limit, count, limit: input.limit, windowStart: input.windowStart };
+  }
+  /** Best-effort cleanup of expired windows. Call off the hot path. */
+  async prune(before) {
+    await this.client.query(`DELETE FROM rate_limit_counters WHERE window_start < $1`, [before]);
+  }
+};
+
 // src/storage/postgres/index.ts
 function createPostgresStorageRepositories(client) {
   return {
@@ -1518,14 +1691,16 @@ function createPostgresStorageRepositories(client) {
     observations: new PostgresObservationRepository(client),
     observationSources: new PostgresObservationSourcesRepository(client),
     observationGenerationJobs: new PostgresObservationGenerationJobRepository(client),
-    observationGenerationJobEvents: new PostgresObservationGenerationJobEventsRepository(client)
+    observationGenerationJobEvents: new PostgresObservationGenerationJobEventsRepository(client),
+    usage: new PostgresUsageRepository(client),
+    rateLimits: new PostgresRateLimitRepository(client)
   };
 }
 
 // src/services/sync/ChromaMcpManager.ts
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { execFile as execFile2, execSync } from "child_process";
+import { execFile as execFile2, execSync, spawn as spawn2 } from "child_process";
 import { promisify as promisify2 } from "util";
 import path2 from "path";
 import os from "os";
@@ -1915,10 +2090,6 @@ var SettingsDefaultsManager = class {
     // Default Gemini model (highest free tier RPM)
     CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED: "true",
     // Rate limiting ON by default for free tier users
-    CLAUDE_MEM_GEMINI_MAX_CONTEXT_MESSAGES: "20",
-    // Max messages in Gemini context window
-    CLAUDE_MEM_GEMINI_MAX_TOKENS: "100000",
-    // Max estimated tokens (~100k safety limit)
     CLAUDE_MEM_OPENROUTER_API_KEY: "",
     // Empty by default, can be set via UI or env
     CLAUDE_MEM_OPENROUTER_MODEL: "xiaomi/mimo-v2-flash:free",
@@ -1929,10 +2100,6 @@ var SettingsDefaultsManager = class {
     // Optional: for OpenRouter analytics
     CLAUDE_MEM_OPENROUTER_APP_NAME: "claude-mem",
     // App name for OpenRouter analytics
-    CLAUDE_MEM_OPENROUTER_MAX_CONTEXT_MESSAGES: "20",
-    // Max messages in context window
-    CLAUDE_MEM_OPENROUTER_MAX_TOKENS: "100000",
-    // Max estimated tokens (~100k safety limit)
     CLAUDE_MEM_DATA_DIR: join3(homedir2(), ".claude-mem"),
     CLAUDE_MEM_LOG_LEVEL: "INFO",
     CLAUDE_MEM_PYTHON_VERSION: "3.13",
@@ -1991,6 +2158,7 @@ var SettingsDefaultsManager = class {
     CLAUDE_MEM_CHROMA_API_KEY: "",
     CLAUDE_MEM_CHROMA_TENANT: "default_tenant",
     CLAUDE_MEM_CHROMA_DATABASE: "default_database",
+    CLAUDE_MEM_CHROMA_PREWARM_TIMEOUT_MS: "120000",
     CLAUDE_MEM_TELEGRAM_ENABLED: "true",
     CLAUDE_MEM_TELEGRAM_BOT_TOKEN: "",
     CLAUDE_MEM_TELEGRAM_CHAT_ID: "",
@@ -2822,19 +2990,70 @@ function validateWorkerPidFile(options = {}) {
   return "stale";
 }
 
+// src/shared/dependency-health.ts
+var UVX_VECTOR_SEARCH_REMEDIATION = "Install uv/uvx and make uvx visible to the worker PATH, then restart claude-mem. Try `curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv`.";
+var statuses = /* @__PURE__ */ new Map();
+function recordDependencyStatus(dependency, kind, message, remediation) {
+  const status = {
+    dependency,
+    kind,
+    message,
+    ...remediation ? { remediation } : {},
+    recordedAtMs: Date.now()
+  };
+  statuses.set(dependency, status);
+  return status;
+}
+function recordUvxVectorSearchUnavailable(message) {
+  return recordDependencyStatus("uvx", "vector_search_unavailable", message, UVX_VECTOR_SEARCH_REMEDIATION);
+}
+function clearDependencyStatus(dependency) {
+  statuses.delete(dependency);
+}
+
+// src/services/server/ErrorHandler.ts
+var AppError = class extends Error {
+  constructor(message, statusCode = 500, code, details) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+    this.name = "AppError";
+  }
+};
+
+// src/services/worker/search/errors.ts
+var ChromaUnavailableError = class extends AppError {
+  constructor(message, cause) {
+    super(message, 503, "CHROMA_UNAVAILABLE", cause ? { cause: cause.message } : void 0);
+    this.name = "ChromaUnavailableError";
+  }
+};
+
 // src/services/sync/ChromaMcpManager.ts
 var execFileAsync2 = promisify2(execFile2);
 var CHROMA_MCP_CLIENT_NAME = "claude-mem-chroma";
 var CHROMA_MCP_CLIENT_VERSION = "1.0.0";
 var MCP_CONNECTION_TIMEOUT_MS = 3e4;
+var DEFAULT_CHROMA_PREWARM_TIMEOUT_MS = 12e4;
+var CHROMA_PREWARM_TIMEOUT_SETTING = "CLAUDE_MEM_CHROMA_PREWARM_TIMEOUT_MS";
+var CHROMA_PREWARM_TIMEOUT_BOUNDS = { min: 1, max: 6e5 };
+var CHROMA_PREWARM_REAP_TIMEOUT_MS = 1e3;
 var RECONNECT_BACKOFF_MS = 1e4;
 var DEFAULT_CHROMA_DATA_DIR = paths.chroma();
 var CHROMA_SUPERVISOR_ID = "chroma-mcp";
+var CHROMA_OUTPUT_TAIL_MAX_CHARS = 2048;
 var CHROMA_MCP_PINNED_VERSION = "0.2.6";
 var CHROMA_MCP_DEP_OVERRIDES = [
   "onnxruntime>=1.20",
   "protobuf<7"
 ];
+var ChromaMcpConnectionCancelledError = class extends Error {
+  constructor(message = "chroma-mcp connection cancelled during shutdown") {
+    super(message);
+    this.name = "ChromaMcpConnectionCancelledError";
+  }
+};
 var ChromaMcpManager = class _ChromaMcpManager {
   static instance = null;
   client = null;
@@ -2842,6 +3061,10 @@ var ChromaMcpManager = class _ChromaMcpManager {
   connected = false;
   lastConnectionFailureTimestamp = 0;
   connecting = null;
+  activePrewarmChild = null;
+  connectionGeneration = 0;
+  intentionallyClosingTransports = /* @__PURE__ */ new WeakSet();
+  static uvxAvailabilityProbe = null;
   constructor() {
   }
   static getInstance() {
@@ -2856,7 +3079,7 @@ var ChromaMcpManager = class _ChromaMcpManager {
     }
     const timeSinceLastFailure = Date.now() - this.lastConnectionFailureTimestamp;
     if (this.lastConnectionFailureTimestamp > 0 && timeSinceLastFailure < RECONNECT_BACKOFF_MS) {
-      throw new Error(`chroma-mcp connection in backoff (${Math.ceil((RECONNECT_BACKOFF_MS - timeSinceLastFailure) / 1e3)}s remaining)`);
+      throw new ChromaUnavailableError(`chroma-mcp connection in backoff (${Math.ceil((RECONNECT_BACKOFF_MS - timeSinceLastFailure) / 1e3)}s remaining)`);
     }
     if (this.connecting) {
       await this.connecting;
@@ -2866,6 +3089,10 @@ var ChromaMcpManager = class _ChromaMcpManager {
     try {
       await this.connecting;
     } catch (error) {
+      if (error instanceof ChromaMcpConnectionCancelledError) {
+        logger.debug("CHROMA_MCP", "Connection attempt cancelled during shutdown");
+        throw error;
+      }
       this.lastConnectionFailureTimestamp = Date.now();
       if (error instanceof Error) {
         logger.error("CHROMA_MCP", "Connection attempt failed", {}, error);
@@ -2878,12 +3105,23 @@ var ChromaMcpManager = class _ChromaMcpManager {
     }
   }
   async connectInternal() {
+    const connectionGeneration = this.connectionGeneration;
     await this.disposeCurrentSubprocess();
+    this.assertConnectionNotCancelled(connectionGeneration);
     const commandArgs = this.buildCommandArgs();
-    const spawnEnvironment = this.getSpawnEnv();
+    const uvxPreflightEnv = _ChromaMcpManager.getUvxPreflightEnv();
     getSupervisor().assertCanSpawn("chroma mcp");
     const uvxSpawnCommand = _ChromaMcpManager.resolveUvxCommand();
     const uvxSpawnArgs = commandArgs;
+    if (!_ChromaMcpManager.isUvxAvailable(uvxSpawnCommand, uvxPreflightEnv, process.platform)) {
+      const message = `uvx executable not found for chroma-mcp (${uvxSpawnCommand})`;
+      recordUvxVectorSearchUnavailable(message);
+      throw new ChromaUnavailableError(message);
+    }
+    const spawnEnvironment = this.getSpawnEnv(uvxPreflightEnv);
+    await this.prewarmChromaMcp(uvxSpawnCommand, uvxSpawnArgs, spawnEnvironment, connectionGeneration);
+    this.assertConnectionNotCancelled(connectionGeneration);
+    clearDependencyStatus("uvx");
     logger.info("CHROMA_MCP", "Connecting to chroma-mcp via MCP stdio", {
       command: uvxSpawnCommand,
       args: uvxSpawnArgs.join(" ")
@@ -2895,6 +3133,7 @@ var ChromaMcpManager = class _ChromaMcpManager {
       cwd: os.homedir(),
       stderr: "pipe"
     });
+    const transportStderrTail = _ChromaMcpManager.captureOutputTail(this.transport.stderr);
     this.client = new Client(
       { name: CHROMA_MCP_CLIENT_NAME, version: CHROMA_MCP_CLIENT_VERSION },
       { capabilities: {} }
@@ -2909,10 +3148,18 @@ var ChromaMcpManager = class _ChromaMcpManager {
     });
     try {
       await Promise.race([mcpConnectionPromise, timeoutPromise]);
+      this.assertConnectionNotCancelled(connectionGeneration);
     } catch (connectionError) {
       clearTimeout(timeoutId);
+      if (connectionError instanceof ChromaMcpConnectionCancelledError || this.connectionGeneration !== connectionGeneration) {
+        logger.debug("CHROMA_MCP", "MCP connection cancelled during shutdown");
+        await this.disposeCurrentSubprocess();
+        throw connectionError instanceof ChromaMcpConnectionCancelledError ? connectionError : new ChromaMcpConnectionCancelledError();
+      }
+      const stderrTail = transportStderrTail();
       logger.warn("CHROMA_MCP", "Connection failed, killing subprocess tree to prevent zombie", {
-        error: connectionError instanceof Error ? connectionError.message : String(connectionError)
+        error: connectionError instanceof Error ? connectionError.message : String(connectionError),
+        ...stderrTail ? { stderrTail } : {}
       });
       await this.disposeCurrentSubprocess();
       throw connectionError;
@@ -2928,6 +3175,10 @@ var ChromaMcpManager = class _ChromaMcpManager {
         logger.debug("CHROMA_MCP", "Ignoring stale onclose from previous transport");
         return;
       }
+      if (this.connectionGeneration !== connectionGeneration || this.intentionallyClosingTransports.has(currentTransport)) {
+        logger.debug("CHROMA_MCP", "Ignoring onclose from intentionally closed transport");
+        return;
+      }
       logger.warn("CHROMA_MCP", "chroma-mcp subprocess closed unexpectedly, applying reconnect backoff");
       this.connected = false;
       getSupervisor().unregisterProcess(CHROMA_SUPERVISOR_ID);
@@ -2944,11 +3195,16 @@ var ChromaMcpManager = class _ChromaMcpManager {
       }
     };
   }
+  assertConnectionNotCancelled(connectionGeneration) {
+    if (this.connectionGeneration !== connectionGeneration) {
+      throw new ChromaMcpConnectionCancelledError();
+    }
+  }
   buildCommandArgs() {
     const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
     const chromaMode = settings.CLAUDE_MEM_CHROMA_MODE || "local";
     const pythonVersion = process.env.CLAUDE_MEM_PYTHON_VERSION || settings.CLAUDE_MEM_PYTHON_VERSION || "3.13";
-    const depOverrideFlags = CHROMA_MCP_DEP_OVERRIDES.flatMap((spec) => ["--with", spec]);
+    const launcherPrefix = _ChromaMcpManager.buildLauncherPrefix(pythonVersion);
     if (chromaMode === "remote") {
       const chromaHost = settings.CLAUDE_MEM_CHROMA_HOST || "127.0.0.1";
       const chromaPort = settings.CLAUDE_MEM_CHROMA_PORT || "8000";
@@ -2957,10 +3213,7 @@ var ChromaMcpManager = class _ChromaMcpManager {
       const chromaDatabase = settings.CLAUDE_MEM_CHROMA_DATABASE || "default_database";
       const chromaApiKey = settings.CLAUDE_MEM_CHROMA_API_KEY || "";
       const args = [
-        "--python",
-        pythonVersion,
-        ...depOverrideFlags,
-        `chroma-mcp==${CHROMA_MCP_PINNED_VERSION}`,
+        ...launcherPrefix,
         "--client-type",
         "http",
         "--host",
@@ -2981,16 +3234,160 @@ var ChromaMcpManager = class _ChromaMcpManager {
       return args;
     }
     return [
-      "--python",
-      pythonVersion,
-      ...depOverrideFlags,
-      `chroma-mcp==${CHROMA_MCP_PINNED_VERSION}`,
+      ...launcherPrefix,
       "--client-type",
       "persistent",
       "--data-dir",
       DEFAULT_CHROMA_DATA_DIR.replace(/\\/g, "/")
     ];
   }
+  static buildLauncherPrefix(pythonVersion) {
+    const depOverrideFlags = CHROMA_MCP_DEP_OVERRIDES.flatMap((spec) => ["--with", spec]);
+    return [
+      "--python",
+      pythonVersion,
+      ...depOverrideFlags,
+      "--from",
+      `chroma-mcp==${CHROMA_MCP_PINNED_VERSION}`,
+      "chroma-mcp"
+    ];
+  }
+  static buildPrewarmCommandArgs(commandArgs) {
+    const executableIndex = commandArgs.indexOf("chroma-mcp");
+    const launcherPrefix = executableIndex >= 0 ? commandArgs.slice(0, executableIndex + 1) : commandArgs;
+    return [...launcherPrefix, "--help"];
+  }
+  static parseBoundedTimeoutMs(rawValue) {
+    if (!rawValue) {
+      return null;
+    }
+    const parsed = Number.parseInt(rawValue, 10);
+    if (Number.isFinite(parsed) && parsed >= CHROMA_PREWARM_TIMEOUT_BOUNDS.min && parsed <= CHROMA_PREWARM_TIMEOUT_BOUNDS.max) {
+      return parsed;
+    }
+    return null;
+  }
+  static getChromaPrewarmTimeoutMs() {
+    const settings = SettingsDefaultsManager.loadFromFile(USER_SETTINGS_PATH);
+    const envValue = process.env[CHROMA_PREWARM_TIMEOUT_SETTING];
+    const settingsValue = settings[CHROMA_PREWARM_TIMEOUT_SETTING];
+    const parsed = _ChromaMcpManager.parseBoundedTimeoutMs(envValue ?? settingsValue);
+    if (parsed !== null) {
+      return parsed;
+    }
+    if (envValue !== void 0 || settingsValue) {
+      logger.warn("CHROMA_MCP", `Invalid ${CHROMA_PREWARM_TIMEOUT_SETTING}, using default`, {
+        value: envValue ?? settingsValue,
+        min: CHROMA_PREWARM_TIMEOUT_BOUNDS.min,
+        max: CHROMA_PREWARM_TIMEOUT_BOUNDS.max
+      });
+    }
+    return DEFAULT_CHROMA_PREWARM_TIMEOUT_MS;
+  }
+  static captureOutputTail(stream) {
+    let tail = "";
+    stream?.on("data", (chunk) => {
+      const text = Buffer.isBuffer(chunk) ? chunk.toString() : chunk instanceof Uint8Array ? Buffer.from(chunk).toString() : String(chunk);
+      tail = (tail + text).slice(-CHROMA_OUTPUT_TAIL_MAX_CHARS);
+    });
+    return () => tail.trim();
+  }
+  async prewarmChromaMcp(command, commandArgs, env, connectionGeneration) {
+    this.assertConnectionNotCancelled(connectionGeneration);
+    const args = _ChromaMcpManager.buildPrewarmCommandArgs(commandArgs);
+    const timeoutMs = _ChromaMcpManager.getChromaPrewarmTimeoutMs();
+    logger.info("CHROMA_MCP", "Prewarming chroma-mcp uvx environment", {
+      command,
+      args: args.join(" "),
+      timeoutMs
+    });
+    const child = spawn2(command, args, {
+      cwd: os.homedir(),
+      env,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: process.platform === "win32"
+    });
+    this.activePrewarmChild = child;
+    const stdoutTail = _ChromaMcpManager.captureOutputTail(child.stdout);
+    const stderrTail = _ChromaMcpManager.captureOutputTail(child.stderr);
+    let timeoutId = null;
+    const exitPromise = new Promise((resolve, reject) => {
+      child.once("error", (error) => {
+        if (this.connectionGeneration !== connectionGeneration) {
+          reject(new ChromaMcpConnectionCancelledError());
+          return;
+        }
+        reject(error);
+      });
+      child.once("close", (code, signal) => {
+        if (this.connectionGeneration !== connectionGeneration) {
+          reject(new ChromaMcpConnectionCancelledError());
+          return;
+        }
+        if (code === 0) {
+          resolve();
+          return;
+        }
+        reject(new Error(`chroma-mcp prewarm exited with code ${code ?? "null"}${signal ? ` signal ${signal}` : ""}`));
+      });
+    });
+    const timeoutPromise = new Promise((_, reject) => {
+      timeoutId = setTimeout(
+        () => reject(new Error(`chroma-mcp prewarm timed out after ${timeoutMs}ms`)),
+        timeoutMs
+      );
+    });
+    try {
+      await Promise.race([exitPromise, timeoutPromise]);
+      this.assertConnectionNotCancelled(connectionGeneration);
+      logger.debug("CHROMA_MCP", "chroma-mcp uvx prewarm completed");
+    } catch (error) {
+      if (error instanceof ChromaMcpConnectionCancelledError) {
+        logger.debug("CHROMA_MCP", "chroma-mcp uvx prewarm cancelled during shutdown");
+        throw error;
+      }
+      this.assertConnectionNotCancelled(connectionGeneration);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const pid = child.pid;
+      const stdout = stdoutTail();
+      const stderr = stderrTail();
+      logger.warn("CHROMA_MCP", "chroma-mcp uvx prewarm failed", {
+        command,
+        args: args.join(" "),
+        timeoutMs,
+        ...pid ? { pid } : {},
+        error: errorMessage,
+        ...stdout ? { stdoutTail: stdout } : {},
+        ...stderr ? { stderrTail: stderr } : {}
+      });
+      if (pid) {
+        try {
+          await _ChromaMcpManager.killProcessTree(pid);
+        } catch (killError) {
+          logger.debug("CHROMA_MCP", "prewarm process tree kill finished (best-effort)", {
+            pid,
+            error: killError instanceof Error ? killError.message : String(killError)
+          });
+        }
+      } else {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+      }
+      const unavailableMessage = `chroma-mcp prewarm failed: ${errorMessage}`;
+      recordUvxVectorSearchUnavailable(unavailableMessage);
+      throw new ChromaUnavailableError(unavailableMessage, error instanceof Error ? error : void 0);
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      if (this.activePrewarmChild === child) {
+        this.activePrewarmChild = null;
+      }
+    }
+  }
   async callTool(toolName, toolArguments) {
     await this.ensureConnected();
     logger.debug("CHROMA_MCP", `Calling tool: ${toolName}`, {
@@ -3113,6 +3510,11 @@ var ChromaMcpManager = class _ChromaMcpManager {
    * subprocess (no-op in that case).
    */
   async disposeCurrentSubprocess() {
+    await this.disposeActivePrewarm();
+    const closingTransport = this.transport;
+    if (closingTransport) {
+      this.intentionallyClosingTransports.add(closingTransport);
+    }
     const chromaProcess = this.transport?._process;
     const trackedPid = chromaProcess?.pid;
     if (trackedPid) {
@@ -3125,9 +3527,9 @@ var ChromaMcpManager = class _ChromaMcpManager {
         });
       }
     }
-    if (this.transport) {
+    if (closingTransport) {
       try {
-        await this.transport.close();
+        await closingTransport.close();
       } catch {
       }
     }
@@ -3144,6 +3546,51 @@ var ChromaMcpManager = class _ChromaMcpManager {
     this.transport = null;
     this.connected = false;
   }
+  async disposeActivePrewarm() {
+    const prewarmChild = this.activePrewarmChild;
+    if (!prewarmChild) {
+      return;
+    }
+    if (this.activePrewarmChild === prewarmChild) {
+      this.activePrewarmChild = null;
+    }
+    const pid = prewarmChild.pid;
+    if (pid) {
+      try {
+        await _ChromaMcpManager.killProcessTree(pid);
+      } catch (error) {
+        logger.warn("CHROMA_MCP", "failed to kill in-flight chroma-mcp prewarm tree (best-effort)", {
+          pid,
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    try {
+      prewarmChild.kill("SIGKILL");
+    } catch {
+    }
+    await _ChromaMcpManager.waitForChildClose(prewarmChild, CHROMA_PREWARM_REAP_TIMEOUT_MS);
+  }
+  static async waitForChildClose(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      return;
+    }
+    await new Promise((resolve) => {
+      let timeoutId = null;
+      const finish = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+        child.off("close", finish);
+        child.off("exit", finish);
+        resolve();
+      };
+      timeoutId = setTimeout(finish, timeoutMs);
+      child.once("close", finish);
+      child.once("exit", finish);
+    });
+  }
   /**
    * Gracefully stop the MCP connection and kill the chroma-mcp subprocess tree.
    *
@@ -3157,7 +3604,8 @@ var ChromaMcpManager = class _ChromaMcpManager {
    * pattern from shutdown.ts (Principle 5: OS-supervised teardown).
    */
   async stop() {
-    if (!this.client && !this.transport) {
+    this.connectionGeneration += 1;
+    if (!this.client && !this.transport && !this.activePrewarmChild) {
       logger.debug("CHROMA_MCP", "No active MCP connection to stop");
       this.connecting = null;
       return;
@@ -3389,6 +3837,39 @@ var ChromaMcpManager = class _ChromaMcpManager {
     }
     return "uvx.exe";
   }
+  static isUvxAvailable(command, env, platform) {
+    if (_ChromaMcpManager.uvxAvailabilityProbe) {
+      return _ChromaMcpManager.uvxAvailabilityProbe(command, env, platform);
+    }
+    const executableNames = platform === "win32" && !command.toLowerCase().endsWith(".exe") ? [command, `${command}.exe`] : [command];
+    if (command.includes("/") || command.includes("\\")) {
+      return executableNames.some((candidate) => {
+        try {
+          return fs.existsSync(candidate) && fs.statSync(candidate).isFile();
+        } catch {
+          return false;
+        }
+      });
+    }
+    const sep2 = platform === "win32" ? ";" : ":";
+    const pathKey = Object.keys(env).find((k) => k.toLowerCase() === "path") ?? "PATH";
+    const dirs = (env[pathKey] ?? "").split(sep2).filter(Boolean);
+    for (const dir of dirs) {
+      for (const name of executableNames) {
+        const candidate = path2.join(dir, name);
+        try {
+          if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return true;
+          }
+        } catch {
+        }
+      }
+    }
+    return false;
+  }
+  static setUvxAvailabilityProbeForTesting(probe) {
+    _ChromaMcpManager.uvxAvailabilityProbe = probe;
+  }
   static ensureUvOnPath(env) {
     const sep2 = process.platform === "win32" ? ";" : ":";
     const pathKey = Object.keys(env).find((k) => k.toLowerCase() === "path") ?? "PATH";
@@ -3408,7 +3889,7 @@ var ChromaMcpManager = class _ChromaMcpManager {
       logger.debug("CHROMA_MCP", "Prepended uv bin dir(s) to chroma child PATH", { added: additions });
     }
   }
-  getSpawnEnv() {
+  static getUvxPreflightEnv() {
     const baseEnv = {};
     for (const [key, value] of Object.entries(sanitizeEnv(process.env))) {
       if (value !== void 0) {
@@ -3417,6 +3898,10 @@ var ChromaMcpManager = class _ChromaMcpManager {
     }
     _ChromaMcpManager.ensureUvOnPath(baseEnv);
     if (!baseEnv.ANONYMIZED_TELEMETRY) baseEnv.ANONYMIZED_TELEMETRY = "false";
+    return baseEnv;
+  }
+  getSpawnEnv(preflightEnv) {
+    const baseEnv = preflightEnv ? { ...preflightEnv } : _ChromaMcpManager.getUvxPreflightEnv();
     const combinedCertPath = this.getCombinedCertPath();
     if (!combinedCertPath) {
       return baseEnv;
@@ -3584,6 +4069,7 @@ var ChromaSync = class _ChromaSync {
       memory_session_id: obs.memory_session_id,
       project: obs.project,
       merged_into_project: obs.merged_into_project ?? null,
+      platform_source: obs.platform_source ? normalizePlatformSource(obs.platform_source) : normalizePlatformSource(void 0),
       created_at_epoch: obs.created_at_epoch,
       type: obs.type || "discovery",
       title: obs.title || "Untitled"
@@ -3631,6 +4117,7 @@ var ChromaSync = class _ChromaSync {
       memory_session_id: summary.memory_session_id,
       project: summary.project,
       merged_into_project: summary.merged_into_project ?? null,
+      platform_source: summary.platform_source ? normalizePlatformSource(summary.platform_source) : normalizePlatformSource(void 0),
       created_at_epoch: summary.created_at_epoch,
       prompt_number: summary.prompt_number || 0
     };
@@ -3697,7 +4184,19 @@ var ChromaSync = class _ChromaSync {
     if (documents.length === 0) {
       return 0;
     }
-    await this.ensureCollectionExists();
+    try {
+      await this.ensureCollectionExists();
+    } catch (error) {
+      if (error instanceof ChromaUnavailableError) {
+        logger.warn("CHROMA_SYNC", "Chroma unavailable before write; leaving documents unsynced", {
+          collection: this.collectionName,
+          requested: documents.length,
+          error: error.message
+        });
+        return 0;
+      }
+      throw error;
+    }
     const chromaMcp = ChromaMcpManager.getInstance();
     let written = 0;
     for (let i = 0; i < documents.length; i += this.BATCH_SIZE) {
@@ -3758,12 +4257,13 @@ var ChromaSync = class _ChromaSync {
     });
     return written;
   }
-  async syncObservation(observationId, memorySessionId, project, obs, promptNumber, createdAtEpoch) {
+  async syncObservation(observationId, memorySessionId, project, obs, promptNumber, createdAtEpoch, platformSource) {
     const stored = {
       id: observationId,
       memory_session_id: memorySessionId,
       project,
       merged_into_project: null,
+      platform_source: platformSource ? normalizePlatformSource(platformSource) : normalizePlatformSource(void 0),
       text: null,
       // Legacy field, not used
       type: obs.type,
@@ -3795,12 +4295,13 @@ var ChromaSync = class _ChromaSync {
       });
     }
   }
-  async syncSummary(summaryId, memorySessionId, project, summary, promptNumber, createdAtEpoch) {
+  async syncSummary(summaryId, memorySessionId, project, summary, promptNumber, createdAtEpoch, platformSource) {
     const stored = {
       id: summaryId,
       memory_session_id: memorySessionId,
       project,
       merged_into_project: null,
+      platform_source: platformSource ? normalizePlatformSource(platformSource) : normalizePlatformSource(void 0),
       request: summary.request,
       investigated: summary.investigated,
       learned: summary.learned,
@@ -3837,12 +4338,13 @@ var ChromaSync = class _ChromaSync {
         doc_type: "user_prompt",
         memory_session_id: prompt.memory_session_id,
         project: prompt.project,
+        platform_source: prompt.platform_source,
         created_at_epoch: prompt.created_at_epoch,
         prompt_number: prompt.prompt_number
       }
     };
   }
-  async syncUserPrompt(promptId, memorySessionId, project, promptText, promptNumber, createdAtEpoch) {
+  async syncUserPrompt(promptId, memorySessionId, project, promptText, promptNumber, createdAtEpoch, platformSource) {
     const stored = {
       id: promptId,
       content_session_id: "",
@@ -3851,7 +4353,8 @@ var ChromaSync = class _ChromaSync {
       prompt_text: promptText,
       created_at_epoch: createdAtEpoch,
       memory_session_id: memorySessionId,
-      project
+      project,
+      platform_source: normalizePlatformSource(platformSource)
     };
     const document = this.formatUserPromptDoc(stored);
     logger.info("CHROMA_SYNC", "Syncing user prompt", {
@@ -3966,9 +4469,13 @@ var ChromaSync = class _ChromaSync {
   }
   async backfillObservations(db, backfillProject, watermark) {
     const observations = db.db.prepare(`
-      SELECT * FROM observations
-      WHERE project = ? AND id > ?
-      ORDER BY id ASC
+      SELECT
+        o.*,
+        COALESCE(NULLIF(s.platform_source, ''), 'claude') as platform_source
+      FROM observations o
+      LEFT JOIN sdk_sessions s ON s.memory_session_id = o.memory_session_id
+      WHERE o.project = ? AND o.id > ?
+      ORDER BY o.id ASC
     `).all(backfillProject, watermark);
     if (observations.length === 0) {
       return [];
@@ -4038,9 +4545,13 @@ var ChromaSync = class _ChromaSync {
   }
   async backfillSummaries(db, backfillProject, watermark) {
     const summaries = db.db.prepare(`
-      SELECT * FROM session_summaries
-      WHERE project = ? AND id > ?
-      ORDER BY id ASC
+      SELECT
+        ss.*,
+        COALESCE(NULLIF(s.platform_source, ''), 'claude') as platform_source
+      FROM session_summaries ss
+      LEFT JOIN sdk_sessions s ON s.memory_session_id = ss.memory_session_id
+      WHERE ss.project = ? AND ss.id > ?
+      ORDER BY ss.id ASC
     `).all(backfillProject, watermark);
     if (summaries.length === 0) {
       return [];
@@ -4110,9 +4621,10 @@ var ChromaSync = class _ChromaSync {
       SELECT
         up.*,
         s.project,
-        s.memory_session_id
+        s.memory_session_id,
+        COALESCE(NULLIF(s.platform_source, ''), 'claude') as platform_source
       FROM user_prompts up
-      JOIN sdk_sessions s ON up.content_session_id = s.content_session_id
+      JOIN sdk_sessions s ON up.session_db_id = s.id
       WHERE s.project = ? AND up.id > ?
       ORDER BY up.id ASC
     `).all(backfillProject, watermark);
@@ -4122,7 +4634,7 @@ var ChromaSync = class _ChromaSync {
     const totalPromptCount = db.db.prepare(`
       SELECT COUNT(*) as count
       FROM user_prompts up
-      JOIN sdk_sessions s ON up.content_session_id = s.content_session_id
+      JOIN sdk_sessions s ON up.session_db_id = s.id
       WHERE s.project = ?
     `).get(backfillProject);
     logger.info("CHROMA_SYNC", "Backfilling user prompts", {
@@ -4866,35 +5378,36 @@ function classifyHttpProviderError(input) {
   const body = input.bodyText ?? "";
   const lower = body.toLowerCase();
   const retryAfterMs = input.headers ? parseRetryAfterMs(input.headers.get("retry-after")) : void 0;
+  const cause = status === void 0 ? input.cause : new Error(`${providerLabel} HTTP error (status ${status})`);
   if (lower.includes("quota exceeded") || lower.includes("insufficient credits") || lower.includes("insufficient_quota") || lower.includes("resource_exhausted")) {
     return new ServerClassifiedProviderError(
       `${providerLabel} quota exhausted${status !== void 0 ? ` (status ${status})` : ""}`,
-      { kind: "quota_exhausted", cause: input.cause }
+      { kind: "quota_exhausted", cause }
     );
   }
   if (status === 429) {
     return new ServerClassifiedProviderError(`${providerLabel} rate limit (429)`, {
       kind: "rate_limit",
-      cause: input.cause,
+      cause,
       ...retryAfterMs !== void 0 ? { retryAfterMs } : {}
     });
   }
   if (status === 401 || status === 403) {
     return new ServerClassifiedProviderError(`${providerLabel} auth error (status ${status})`, {
       kind: "auth_invalid",
-      cause: input.cause
+      cause
     });
   }
   if (status === 400 || status === 404) {
     return new ServerClassifiedProviderError(`${providerLabel} bad request (status ${status})`, {
       kind: "unrecoverable",
-      cause: input.cause
+      cause
     });
   }
   if (status !== void 0 && status >= 500 && status < 600) {
     return new ServerClassifiedProviderError(`${providerLabel} upstream error (status ${status})`, {
       kind: "transient",
-      cause: input.cause
+      cause
     });
   }
   if (status === void 0) {
@@ -4905,8 +5418,8 @@ function classifyHttpProviderError(input) {
     });
   }
   return new ServerClassifiedProviderError(
-    `${providerLabel} API error: ${status}${body ? ` - ${body.substring(0, 200)}` : ""}`,
-    { kind: "unrecoverable", cause: input.cause }
+    `${providerLabel} API error (status ${status})`,
+    { kind: "unrecoverable", cause }
   );
 }
 
@@ -5225,6 +5738,41 @@ async function safeReadBody(response) {
 // src/server/generation/providers/GeminiObservationProvider.ts
 var GEMINI_API_URL = "https://generativelanguage.googleapis.com/v1/models";
 var DEFAULT_MODEL2 = "gemini-2.5-flash";
+function categorizeGeminiBadRequest(bodyText) {
+  const lower = bodyText.toLowerCase();
+  if (lower.includes("api key not valid") || lower.includes("api_key_invalid") || lower.includes("api key expired") || lower.includes("invalid api key")) {
+    return "api_key";
+  }
+  if (lower.includes("please ensure that multiturn requests alternate") || lower.includes("alternate between user and model") || lower.includes("first content should be with role") || lower.includes("contents") && lower.includes("role") && (lower.includes("user") || lower.includes("model"))) {
+    return "role_sequence";
+  }
+  if (lower.includes("context limit") || lower.includes("context length") || lower.includes("too many tokens") || lower.includes("input is too long") || lower.includes("prompt is too long") || lower.includes("request payload size exceeds") || lower.includes("token") && (lower.includes("exceed") || lower.includes("maximum") || lower.includes("limit"))) {
+    return "context_limit";
+  }
+  if (lower.includes("model not found") || lower.includes("model_unsupported") || lower.includes("unsupported model") || lower.includes("not supported for generatecontent") || lower.includes("not supported by this model") || lower.includes("model") && lower.includes("not supported") || lower.includes("models/") && lower.includes("not found")) {
+    return "model_unsupported";
+  }
+  return "unknown_bad_request";
+}
+function isQuotaBody(bodyText) {
+  const lower = bodyText.toLowerCase();
+  return lower.includes("quota exceeded") || lower.includes("insufficient credits") || lower.includes("insufficient_quota") || lower.includes("resource_exhausted");
+}
+function classifyGeminiServerError(input) {
+  const status = input.status;
+  const bodyText = input.bodyText ?? "";
+  if (status === 400 && !isQuotaBody(bodyText)) {
+    const category = categorizeGeminiBadRequest(bodyText);
+    return new ServerClassifiedProviderError(`Gemini bad request: ${category}`, {
+      kind: "unrecoverable",
+      cause: new Error("Gemini HTTP error (status 400)")
+    });
+  }
+  return classifyHttpProviderError({
+    ...input,
+    providerLabel: "Gemini"
+  });
+}
 var GeminiObservationProvider = class {
   providerLabel = "gemini";
   apiKey;
@@ -5268,19 +5816,17 @@ var GeminiObservationProvider = class {
         signal
       });
     } catch (networkError) {
-      throw classifyHttpProviderError({
-        cause: networkError,
-        providerLabel: "Gemini"
+      throw classifyGeminiServerError({
+        cause: networkError
       });
     }
     if (!response.ok) {
       const bodyText = await safeReadBody2(response);
-      throw classifyHttpProviderError({
+      throw classifyGeminiServerError({
         status: response.status,
         bodyText,
         headers: response.headers,
-        cause: new Error(`Gemini API error: ${response.status} - ${bodyText}`),
-        providerLabel: "Gemini"
+        cause: new Error(`Gemini HTTP error (status ${response.status})`)
       });
     }
     let data;
@@ -5293,12 +5839,11 @@ var GeminiObservationProvider = class {
       });
     }
     if (data.error) {
-      throw classifyHttpProviderError({
+      throw classifyGeminiServerError({
         status: response.status,
         bodyText: `${data.error.status ?? ""} ${data.error.message ?? ""}`,
         headers: response.headers,
-        cause: new Error(`Gemini API error: ${data.error.status} - ${data.error.message}`),
-        providerLabel: "Gemini"
+        cause: new Error(`Gemini HTTP error (status ${response.status})`)
       });
     }
     const rawText = data.candidates?.[0]?.content?.parts?.[0]?.text?.trim() ?? "";
@@ -5609,7 +6154,7 @@ async function processGeneratedResponse(input) {
   const observationsToWrite = parsed.observations ?? [];
   const skipped = parsed.summary?.skipped === true;
   const privateContentDetected = skipped || observationsToWrite.length === 0;
-  return await withPostgresTransaction(input.pool, async (client) => {
+  const outcome = await withPostgresTransaction(input.pool, async (client) => {
     const obsRepo = new PostgresObservationRepository(client);
     const sourcesRepo = new PostgresObservationSourcesRepository(client);
     const jobsRepo = new PostgresObservationGenerationJobRepository(client);
@@ -5769,6 +6314,35 @@ async function processGeneratedResponse(input) {
       privateContentDetected
     };
   });
+  if (outcome.kind === "completed" && process.env.CLAUDE_MEM_USAGE_METERING === "1") {
+    try {
+      const usageRepo = new PostgresUsageRepository(input.pool);
+      if (input.tokensUsed && input.tokensUsed > 0) {
+        await usageRepo.record({
+          teamId: input.job.teamId,
+          projectId: input.job.projectId,
+          kind: "tokens",
+          quantity: input.tokensUsed,
+          metadata: { jobId: input.job.id, provider: input.providerLabel, model: input.modelId ?? null }
+        });
+      }
+      if (outcome.observations.length > 0) {
+        await usageRepo.record({
+          teamId: input.job.teamId,
+          projectId: input.job.projectId,
+          kind: "observation",
+          quantity: outcome.observations.length,
+          metadata: { jobId: input.job.id }
+        });
+      }
+    } catch (usageError) {
+      logger.warn("SYSTEM", "usage metering record failed (post-commit)", {
+        jobId: input.job.id,
+        error: usageError instanceof Error ? usageError.message : String(usageError)
+      });
+    }
+  }
+  return outcome;
 }
 function renderObservationContent(observation) {
   const parts = [];