codetrap 0.1.3 → 0.1.4

package/README.md

@@ -13,7 +13,11 @@ AI coding agents make the same mistakes repeatedly across sessions and projects.
 For detailed setup options, see [Installation](docs/installation.md). Maintainers can use the Chinese [Release Playbook](docs/release-playbook.zh-CN.md) when publishing updates.
 
 ```bash
-# Prerequisites: Bun >= 1.x (https://bun.sh)
+# Prerequisites: Bun >= 1.x (https://bun.sh) for npm/source installs
+
+# npm global install (recommended)
+npm install -g codetrap
+codetrap --help
 
 # Source install
 git clone <repo-url> && cd codetrap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codetrap",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Capture and retrieve coding pitfalls so AI doesn't repeat mistakes",
   "type": "module",
   "license": "MIT",

package/src/commands/workflow.ts

@@ -2,7 +2,6 @@ import { readFileSync } from "node:fs";
 import { TrapStore } from "../lib/store";
 import { formatTrapShort, formatTrapDetails, formatTrapActionCard } from "../lib/format";
 import type { Trap } from "../domain/trap";
-import { SEARCH_MODES, type SearchMode } from "../lib/constants";
 import {
   formatScopeMigrationText,
   runScopeMigration,
@@ -24,6 +23,13 @@ import {
   type CommandResult,
 } from "./command-result";
 import { mutationJsonPayload } from "../lib/trap-mutation-result";
+import {
+  embedRequestFromArgs,
+  evidenceRequestFromArgs,
+  listRequestFromArgs,
+  searchRequestFromArgs,
+  statsRequestFromArgs,
+} from "../lib/command-requests";
 
 type ParsedArgs = {
   opts: Record<string, string>;
@@ -141,21 +147,8 @@ async function cmdSearch(args: string[], operations: TrapOperations): Promise<Co
   }
 
   try {
-    const mode = opts.mode ? parseSearchMode(opts.mode) : undefined;
     const defaults = searchDefaultsFromConfig();
-    const cards = await operations.searchTrapCards({
-      query,
-      category: opts.category,
-      scope: opts.scope ?? defaults.scope,
-      limit: opts.limit ? parseOptionalInt(opts.limit) : defaults.limit,
-      mode: mode ?? defaults.mode,
-      status: opts.status,
-      path: opts.path,
-      module: opts.module,
-      owner: opts.owner,
-      rerank: opts["no-rerank"] !== undefined ? false : defaults.rerank,
-      includeRankingSignals: opts["ranking-signals"] !== undefined,
-    });
+    const cards = await operations.searchTrapCards(searchRequestFromArgs(query, opts, defaults));
     if (opts.json !== undefined) return jsonResult(toCliSearchJson(cards));
     return textResult(cards.length > 0 ? cards.map(formatTrapActionCard).join("\n\n") : "No traps found.");
   } catch (error) {
@@ -166,15 +159,7 @@ async function cmdSearch(args: string[], operations: TrapOperations): Promise<Co
 function cmdList(args: string[], operations: TrapOperations): CommandResult {
   const { opts } = parseArgs(args);
   try {
-    const groups = operations.listTraps({
-      category: opts.category,
-      scope: opts.scope,
-      status: opts.status,
-      path: opts.path,
-      module: opts.module,
-      owner: opts.owner,
-      limit: parseOptionalInt(opts.limit, 50),
-    });
+    const groups = operations.listTraps(listRequestFromArgs(opts));
     if (opts.json !== undefined) return jsonResult(toListJson(groups));
 
     const lines = groups.flatMap((group) =>
@@ -246,13 +231,7 @@ function cmdAddTrapEvidence(args: string[], operations: TrapOperations): Command
   if (typeof id !== "number") return id;
 
   try {
-    const input = opts.json ? JSON.parse(opts.json) : {
-      source_type: opts.source_type ?? opts["source-type"],
-      source_ref: opts.source_ref ?? opts["source-ref"],
-      observed_at: opts.observed_at ?? opts["observed-at"],
-      related_files: parseCsv(opts.related_files ?? opts["related-files"]),
-      note: opts.note,
-    };
+    const input = opts.json ? JSON.parse(opts.json) : evidenceRequestFromArgs(opts);
     const result = operations.addTrapEvidence(id, input, opts.scope);
     if (opts["output-json"] !== undefined) {
       return mutationJsonResult({ id, ...result }, `Trap #${id} not found.`);
@@ -331,8 +310,9 @@ function cmdImport(args: string[], operations: TrapOperations): CommandResult {
 
 function cmdStats(args: string[], operations: TrapOperations): CommandResult {
   const { opts } = parseArgs(args);
-  const stats = operations.getStats();
-  const embeddingStats = operations.getEmbeddingStats();
+  const request = statsRequestFromArgs(opts);
+  const stats = operations.getStats(request.scope);
+  const embeddingStats = operations.getEmbeddingStats(request.scope);
   return opts.json !== undefined
     ? jsonResult(toStatsJson(stats, embeddingStats))
     : textResult(formatStatsText(stats));
@@ -378,13 +358,7 @@ function cmdScopeMigration(
 async function cmdEmbed(args: string[], store: TrapStore): Promise<CommandResult> {
   const { opts } = parseArgs(args);
   try {
-    const result = await store.ensureEmbeddings({
-      scope: opts.scope,
-      category: opts.category,
-      limit: opts.limit ? parseOptionalInt(opts.limit) : undefined,
-      force: opts.force === "true",
-      batchSize: opts["batch-size"] ? parseOptionalInt(opts["batch-size"]) : undefined,
-    });
+    const result = await store.ensureEmbeddings(embedRequestFromArgs(opts));
     return textResult([
       ...result.scopes.map((scoped) =>
         `[${scoped.scope}] embeddings generated: ${scoped.generated}, skipped: ${scoped.skipped}, batches: ${scoped.batches}`
@@ -401,7 +375,9 @@ function formatStatsText(stats: ReturnType<TrapOperations["getStats"]>): string
   if (stats.project) {
     sections.push("── Project ──", formatStatsBlock(stats.project));
   }
-  sections.push("── Global ──", formatStatsBlock(stats.global));
+  if (stats.global) {
+    sections.push("── Global ──", formatStatsBlock(stats.global));
+  }
   return sections.join("\n");
 }
 
@@ -415,41 +391,18 @@ function formatStatsBlock(stats: { total: number; byCategory: Record<string, num
   ].join("\n");
 }
 
-function parseSearchMode(mode: string): SearchMode {
-  if ((SEARCH_MODES as readonly string[]).includes(mode)) return mode as SearchMode;
-  throw new Error(`Invalid search mode: ${mode}. Expected one of: ${SEARCH_MODES.join(", ")}`);
-}
-
 function parseId(value: string | undefined, usage: string): number | CommandResult {
   if (value === undefined) return errorResult(usage);
   const id = Number.parseInt(value, 10);
   return Number.isNaN(id) ? errorResult("Error: id must be a number") : id;
 }
 
-function parseOptionalInt(value: string | undefined, fallback?: number): number {
-  if (value === undefined) {
-    if (fallback === undefined) throw new Error("Missing numeric value.");
-    return fallback;
-  }
-  const parsed = Number.parseInt(value, 10);
-  if (Number.isNaN(parsed)) throw new Error(`Invalid number: ${value}`);
-  return parsed;
-}
-
 function readQuery(positionals: string[]): string {
   if (positionals.length > 0) return positionals.join(" ").trim();
   if (process.stdin.isTTY) return "";
   return readFileSync(0, "utf-8").trim();
 }
 
-function parseCsv(value?: string): string[] | undefined {
-  if (!value) return undefined;
-  return value
-    .split(",")
-    .map((item) => item.trim())
-    .filter(Boolean);
-}
-
 function mutationJsonResult<T extends Record<string, unknown> & { success: boolean }>(
   value: T,
   error: string

package/src/db/queries.ts

@@ -180,6 +180,10 @@ export function listTrapEvidence(db: Database, trapId: number): TrapEvidence[] {
 }
 
 export function archiveTrap(db: Database, id: number): boolean {
+  return markTrapArchived(db, id);
+}
+
+export function markTrapArchived(db: Database, id: number): boolean {
   const result = db
     .prepare(
       `
@@ -208,33 +212,43 @@ export function supersedeTrap(
 
   const key = stateKey ?? oldTrap.state_key ?? newTrap.state_key ?? `trap:${id}`;
   const tx = db.transaction(() => {
-    db.prepare(
-      `
-      UPDATE traps
-      SET status = 'superseded',
-          state_key = ?,
-          valid_until = COALESCE(valid_until, datetime('now')),
-          updated_at = datetime('now')
-      WHERE id = ?
-    `
-    ).run(key, id);
-    db.prepare(
-      `
-      UPDATE traps
-      SET status = 'active',
-          state_key = ?,
-          supersedes_id = ?,
-          valid_from = COALESCE(valid_from, datetime('now')),
-          valid_until = NULL,
-          updated_at = datetime('now')
-      WHERE id = ?
-    `
-    ).run(key, id, supersededById);
+    markTrapSuperseded(db, id, key);
+    markTrapSuperseding(db, supersededById, id, key);
   });
   tx();
   return true;
 }
 
+export function markTrapSuperseded(db: Database, id: number, stateKey: string): boolean {
+  const result = db.prepare(supersedeTrapSql).run(stateKey, id);
+  return result.changes > 0;
+}
+
+export function markTrapSuperseding(db: Database, id: number, supersedesId: number, stateKey: string): boolean {
+  const result = db.prepare(supersedingTrapSql).run(stateKey, supersedesId, id);
+  return result.changes > 0;
+}
+
+const supersedeTrapSql = `
+  UPDATE traps
+  SET status = 'superseded',
+      state_key = ?,
+      valid_until = COALESCE(valid_until, datetime('now')),
+      updated_at = datetime('now')
+  WHERE id = ?
+`;
+
+const supersedingTrapSql = `
+  UPDATE traps
+  SET status = 'active',
+      state_key = ?,
+      supersedes_id = ?,
+      valid_from = COALESCE(valid_from, datetime('now')),
+      valid_until = NULL,
+      updated_at = datetime('now')
+  WHERE id = ?
+`;
+
 export function incrementHitCount(db: Database, id: number): void {
   db.prepare("UPDATE traps SET hit_count = hit_count + 1, updated_at = datetime('now') WHERE id = ?").run(id);
 }
@@ -245,18 +259,22 @@ export function getTopTraps(db: Database, scope: string, limit = 20): Trap[] {
     .all(scope, limit) as Trap[];
 }
 
-export function getStats(db: Database): {
+export function getStats(db: Database, opts: { scope?: string; status?: TrapStatusFilter } = {}): {
   total: number;
   byCategory: Record<string, number>;
   bySeverity: Record<string, number>;
 } {
-  const total = (db.query("SELECT COUNT(*) as c FROM traps").get() as { c: number }).c;
+  const conditions: string[] = [];
+  const params: SQLQueryBindings[] = [];
+  addTrapFilters(conditions, params, opts);
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const total = (db.query(`SELECT COUNT(*) as c FROM traps ${where}`).get(...params) as { c: number }).c;
   const byCategory = db
-    .query("SELECT category, COUNT(*) as c FROM traps GROUP BY category")
-    .all() as { category: string; c: number }[];
+    .query(`SELECT category, COUNT(*) as c FROM traps ${where} GROUP BY category`)
+    .all(...params) as { category: string; c: number }[];
   const bySeverity = db
-    .query("SELECT severity, COUNT(*) as c FROM traps GROUP BY severity")
-    .all() as { severity: string; c: number }[];
+    .query(`SELECT severity, COUNT(*) as c FROM traps ${where} GROUP BY severity`)
+    .all(...params) as { severity: string; c: number }[];
 
   return {
     total,

package/src/db/repository.ts

@@ -8,7 +8,6 @@ import type {
   TrapSearchResult,
   TrapUpdate,
 } from "../domain/trap";
-import * as embeddingQueries from "./embedding-queries";
 import { SearchService, type SearchOptions } from "../lib/search-service";
 import {
   type EmbeddingConfig,
@@ -20,20 +19,24 @@ import { passageFieldsChanged } from "../lib/trap-search-document";
 import * as queries from "./queries";
 import type { TrapStatus } from "../lib/constants";
 import { TrapSearchPolicy } from "../lib/search-policy";
+import { DatabaseEmbeddingIndex } from "../lib/embedding-index";
+import { archiveTrapLifecycle, supersedeTrapLifecycle } from "../lib/trap-lifecycle";
 
 export type TrapStats = ReturnType<typeof queries.getStats>;
-export type EmbeddingStateCounts = ReturnType<typeof embeddingQueries.getEmbeddingStateCounts>;
+export type EmbeddingStateCounts = ReturnType<DatabaseEmbeddingIndex["stateCounts"]>;
 export type TrapRecordInsert = queries.TrapRecordInsert;
 
 export class TrapRepository {
   private readonly searchService: SearchService;
   private readonly searchPolicy = new TrapSearchPolicy();
+  private readonly embeddingIndex: DatabaseEmbeddingIndex;
 
   constructor(
     private readonly db: Database,
     private readonly embedder?: EmbeddingProvider
   ) {
     this.searchService = new SearchService(db, embedder);
+    this.embeddingIndex = new DatabaseEmbeddingIndex(db);
   }
 
   add(input: TrapInput): number {
@@ -67,10 +70,16 @@ export class TrapRepository {
       .slice(0, limit);
   }
 
+  listMisScoped(expectedScope: string): Trap[] {
+    return queries
+      .listTraps(this.db, { status: "all", limit: 100000 })
+      .filter((trap) => trap.scope !== expectedScope);
+  }
+
   update(id: number, input: TrapUpdate): boolean {
     const success = queries.updateTrap(this.db, id, input);
     if (success && passageFieldsChanged(input)) {
-      embeddingQueries.deleteEmbedding(this.db, id);
+      this.embeddingIndex.delete(id);
     }
     return success;
   }
@@ -85,11 +94,11 @@ export class TrapRepository {
   }
 
   archive(id: number): boolean {
-    return queries.archiveTrap(this.db, id);
+    return archiveTrapLifecycle(this.lifecycleAdapter(), id);
   }
 
   supersede(id: number, supersededById: number, stateKey?: string): boolean {
-    return queries.supersedeTrap(this.db, id, supersededById, stateKey);
+    return supersedeTrapLifecycle(this.lifecycleAdapter(), id, supersededById, stateKey);
   }
 
   hit(id: number): void {
@@ -100,12 +109,12 @@ export class TrapRepository {
     return queries.getTopTraps(this.db, scope, limit);
   }
 
-  stats(): TrapStats {
-    return queries.getStats(this.db);
+  stats(opts: { scope?: string; status?: TrapStatus | "all" } = {}): TrapStats {
+    return queries.getStats(this.db, opts);
   }
 
-  embeddingStats(config: EmbeddingConfig | null): EmbeddingStateCounts {
-    return embeddingQueries.getEmbeddingStateCounts(this.db, config);
+  embeddingStats(config: EmbeddingConfig | null, opts: { scope?: string; status?: TrapStatus | "all" } = {}): EmbeddingStateCounts {
+    return this.embeddingIndex.stateCounts(config, opts);
   }
 
   exportAll(): TrapExportRecord[] {
@@ -137,22 +146,22 @@ export class TrapRepository {
   }
 
   getEmbedding(trapId: number): StoredEmbedding | null {
-    return embeddingQueries.getEmbedding(this.db, trapId);
+    return this.embeddingIndex.get(trapId);
   }
 
   upsertEmbedding(record: StoredEmbedding): void {
-    embeddingQueries.upsertEmbedding(this.db, record);
+    this.embeddingIndex.save(record);
   }
 
   deleteEmbedding(trapId: number): void {
-    embeddingQueries.deleteEmbedding(this.db, trapId);
+    this.embeddingIndex.delete(trapId);
   }
 
   getTrapsNeedingEmbeddings(
     config: EmbeddingConfig,
     opts: { scope?: string; category?: string; status?: TrapStatus | "all"; force?: boolean; limit?: number } = {}
   ): Trap[] {
-    return embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, opts);
+    return this.embeddingIndex.trapsNeedingEmbeddings(config, opts);
   }
 
   async ensureEmbeddings(opts: { scope?: string; category?: string; limit?: number; force?: boolean; batchSize?: number } = {}): Promise<{
@@ -166,13 +175,24 @@ export class TrapRepository {
 
     return runEmbeddingJob(
       {
-        countEmbeddable: (countOpts) => embeddingQueries.countEmbeddableTraps(this.db, countOpts),
+        countEmbeddable: (countOpts) => this.embeddingIndex.countEmbeddable(countOpts),
         trapsNeedingEmbeddings: (config, jobOpts) =>
-          embeddingQueries.getTrapsNeedingEmbeddings(this.db, config, jobOpts),
-        saveEmbedding: (record) => embeddingQueries.upsertEmbedding(this.db, record),
+          this.embeddingIndex.trapsNeedingEmbeddings(config, jobOpts),
+        saveEmbedding: (record) => this.embeddingIndex.save(record),
       },
       this.embedder,
       opts
     );
   }
+
+  private lifecycleAdapter() {
+    return {
+      get: (id: number) => queries.getTrap(this.db, id),
+      transaction: <T>(callback: () => T) => this.transaction(callback),
+      markArchived: (id: number) => queries.markTrapArchived(this.db, id),
+      markSuperseded: (id: number, stateKey: string) => queries.markTrapSuperseded(this.db, id, stateKey),
+      markSuperseding: (id: number, supersedesId: number, stateKey: string) =>
+        queries.markTrapSuperseding(this.db, id, supersedesId, stateKey),
+    };
+  }
 }

package/src/domain/trap.ts

@@ -60,10 +60,15 @@ export interface TrapSearchResult {
   rank: number;
   sources?: ("fts" | "semantic")[];
   score?: number;
-  diagnostics?: { code: string; message: string }[];
+  diagnostics?: TrapSearchDiagnostic[];
   ranking_signals?: RankingSignal[];
 }
 
+export interface TrapSearchDiagnostic {
+  code: string;
+  message: string;
+}
+
 export interface RankingSignal {
   code: string;
   weight: number;
@@ -80,14 +85,8 @@ export interface TrapActionCard {
   severity: string;
   score: number | null;
   sources: ("fts" | "semantic")[];
+  diagnostics?: TrapSearchDiagnostic[];
   ranking_signals?: RankingSignal[];
-  next_action: {
-    details_tool: "get_trap";
-    details_args: {
-      id: number;
-      scope: Scope;
-    };
-  };
 }
 
 export type TrapUpdate = Partial<Omit<TrapInput, "scope" | "project_path">>;

package/src/lib/command-requests.ts

@@ -0,0 +1,133 @@
+import { SEARCH_MODES, type SearchMode } from "./constants";
+import type { SearchDefaults } from "./config";
+import type { SearchTrapsArgs, ListTrapsArgs } from "./trap-operations";
+
+type RawArgs = Record<string, unknown>;
+
+export type EmbedRequest = {
+  scope?: string;
+  category?: string;
+  limit?: number;
+  force?: boolean;
+  batchSize?: number;
+};
+
+export type StatsRequest = {
+  scope?: string;
+};
+
+export function searchRequestFromArgs(query: string, args: RawArgs, defaults: SearchDefaults): SearchTrapsArgs {
+  return {
+    query,
+    category: stringOption(args, "category"),
+    scope: stringOption(args, "scope") ?? defaults.scope,
+    limit: intOption(args, "limit", defaults.limit),
+    mode: searchModeOption(args, "mode") ?? defaults.mode,
+    status: stringOption(args, "status"),
+    path: stringOption(args, "path"),
+    module: stringOption(args, "module"),
+    owner: stringOption(args, "owner"),
+    rerank: flagPresent(args, "no-rerank") ? false : booleanOption(args, "rerank") ?? defaults.rerank,
+    includeRankingSignals: booleanOption(args, "ranking_signals", "ranking-signals") ?? false,
+  };
+}
+
+export function listRequestFromArgs(args: RawArgs): ListTrapsArgs {
+  return {
+    category: stringOption(args, "category"),
+    scope: stringOption(args, "scope"),
+    status: stringOption(args, "status"),
+    path: stringOption(args, "path"),
+    module: stringOption(args, "module"),
+    owner: stringOption(args, "owner"),
+    limit: intOption(args, "limit", 50),
+  };
+}
+
+export function statsRequestFromArgs(args: RawArgs): StatsRequest {
+  return {
+    scope: stringOption(args, "scope"),
+  };
+}
+
+export function embedRequestFromArgs(args: RawArgs): EmbedRequest {
+  return {
+    scope: stringOption(args, "scope"),
+    category: stringOption(args, "category"),
+    limit: optionalIntOption(args, "limit"),
+    force: booleanOption(args, "force") === true,
+    batchSize: optionalIntOption(args, "batch_size", "batch-size"),
+  };
+}
+
+export function evidenceRequestFromArgs(args: RawArgs): RawArgs {
+  return {
+    source_type: stringOption(args, "source_type", "source-type"),
+    source_ref: stringOption(args, "source_ref", "source-ref"),
+    observed_at: stringOption(args, "observed_at", "observed-at"),
+    related_files: csvOrArrayOption(args, "related_files", "related-files"),
+    note: stringOption(args, "note"),
+  };
+}
+
+function stringOption(args: RawArgs, ...keys: string[]): string | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return undefined;
+}
+
+function intOption(args: RawArgs, key: string, fallback: number): number {
+  return optionalIntOption(args, key) ?? fallback;
+}
+
+function optionalIntOption(args: RawArgs, ...keys: string[]): number | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (value === undefined) continue;
+    const parsed = typeof value === "number" ? value : Number.parseInt(String(value), 10);
+    if (Number.isInteger(parsed) && parsed > 0) return parsed;
+    throw new Error(`Invalid number: ${String(value)}`);
+  }
+  return undefined;
+}
+
+function searchModeOption(args: RawArgs, key: string): SearchMode | undefined {
+  const value = stringOption(args, key);
+  if (!value) return undefined;
+  if ((SEARCH_MODES as readonly string[]).includes(value)) return value as SearchMode;
+  throw new Error(`Invalid search mode: ${value}. Expected one of: ${SEARCH_MODES.join(", ")}`);
+}
+
+function booleanOption(args: RawArgs, ...keys: string[]): boolean | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (value === undefined) continue;
+    if (typeof value === "boolean") return value;
+    if (typeof value === "string") {
+      if (["true", "1", "yes", "on"].includes(value.toLowerCase())) return true;
+      if (["false", "0", "no", "off"].includes(value.toLowerCase())) return false;
+    }
+    throw new Error(`Invalid boolean: ${String(value)}`);
+  }
+  return undefined;
+}
+
+function flagPresent(args: RawArgs, key: string): boolean {
+  return args[key] !== undefined;
+}
+
+function csvOrArrayOption(args: RawArgs, ...keys: string[]): string[] | undefined {
+  for (const key of keys) {
+    const value = args[key];
+    if (Array.isArray(value)) return value.map(String);
+    if (typeof value === "string" && value.trim() !== "") {
+      return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    }
+  }
+  return undefined;
+}

package/src/lib/doctor.ts

@@ -18,6 +18,11 @@ export type DoctorReport = {
     semantic_available: boolean;
     fallback_reason: HybridFallbackReason | null;
   };
+  diagnostics: {
+    mis_scoped_traps: {
+      global_db_project_traps: ReturnType<TrapStore["diagnostics"]>["mis_scoped_traps"]["global_db_project_traps"];
+    };
+  };
   mcp_hint: string;
 };
 
@@ -35,13 +40,16 @@ export function buildDoctorReport(
     ...scope,
     traps: {
       project: stats.project?.total ?? null,
-      global: stats.global.total,
+      global: stats.global?.total ?? 0,
     },
     embeddings,
     hybrid_search: {
       semantic_available: semanticAvailable,
       fallback_reason: hybridFallbackReason(semanticAvailable, embeddings),
     },
+    diagnostics: {
+      mis_scoped_traps: store.diagnostics().mis_scoped_traps,
+    },
     mcp_hint: "Pass cwd in MCP tool calls, or restart codetrap serve after changing projects.",
   };
 }
@@ -60,6 +68,8 @@ export function formatDoctorText(report: DoctorReport): string {
     "Hybrid search:",
     `  semantic_available: ${report.hybrid_search.semantic_available ? "yes" : "no"}`,
     `  fallback_reason: ${report.hybrid_search.fallback_reason ?? "(none)"}`,
+    "Diagnostics:",
+    `  global_db_project_traps: ${report.diagnostics.mis_scoped_traps.global_db_project_traps.length}`,
     `mcp_hint: ${report.mcp_hint}`,
   ].join("\n");
 }

package/src/lib/embedding-health.ts

@@ -17,7 +17,7 @@ export type EmbeddingStateSummary = EmbeddingStateCounts & {
 
 export type EmbeddingStatsResult = {
   project: EmbeddingStateSummary | null;
-  global: EmbeddingStateSummary;
+  global: EmbeddingStateSummary | null;
 };
 
 export type HybridFallbackReason = "semantic_unavailable" | "semantic_no_candidates";
@@ -42,8 +42,8 @@ export function hybridFallbackReason(
 ): HybridFallbackReason | null {
   if (!providerAvailable) return "semantic_unavailable";
 
-  const fresh = (embeddings.project?.fresh ?? 0) + embeddings.global.fresh;
-  const total = (embeddings.project?.total ?? 0) + embeddings.global.total;
+  const fresh = (embeddings.project?.fresh ?? 0) + (embeddings.global?.fresh ?? 0);
+  const total = (embeddings.project?.total ?? 0) + (embeddings.global?.total ?? 0);
   if (total > 0 && fresh === 0) return "semantic_no_candidates";
   return null;
 }