@cleocode/core 2026.8.9 → 2026.9.1

package/dist/tasks/duplicate-detector.d.ts

@@ -6,7 +6,11 @@
  *
  * Three-tier escalation (T1681):
  *
- *   Tier 1 — BM25 / vector similarity (current: Jaccard trigrams or cosine):
+ *   Tier 1 — lexical OR vector similarity. NOT BM25, despite the historical
+ *     naming: there is no IDF, no term frequency and no length normalisation.
+ *     Two implementations, selected at runtime (see `runDuplicateCheck`):
+ *       - lexical: Jaccard over CHARACTER TRIGRAMS of a title-2x-weighted blob
+ *       - vector:  cosine over embeddings, when an embedding provider is loaded
  *     score >= 0.92 → reject (clear match)
  *     score <  0.50 → insert (clear different)
  *     score in [0.50, 0.92) → escalate to Tier 2
@@ -19,11 +23,11 @@
  *   Tier 3 — LLM reasoning (max 1 call per cleo add):
  *     are_duplicate=true  → reject
  *     are_duplicate=false → insert
- *     LLM error / timeout → fall back to BM25-only decision (never block on error)
+ *     LLM error / timeout → fall back to Tier-1-only decision (never block on error)
  *
- * Thresholds (original T1633 behavior preserved for BM25 clear-match path):
- *   BM25 score >= 0.85 → warning emitted to stderr (non-blocking)
- *   BM25 score >= 0.92 → rejected with E_DUPLICATE_TASK_LIKELY
+ * Thresholds (original T1633 behavior preserved for the Tier-1 clear-match path):
+ *   Tier-1 score >= 0.85 → warning emitted to stderr (non-blocking)
+ *   Tier-1 score >= 0.92 → rejected with E_DUPLICATE_TASK_LIKELY
  *
  * @epic T1627
  * @task T1633
@@ -32,9 +36,9 @@
 import type { Task } from '@cleocode/contracts';
 import { z } from 'zod';
 import type { DataAccessor } from '../store/data-accessor.js';
-/** BM25 score at which a non-blocking warning is emitted. */
+/** Tier-1 score at which a non-blocking warning is emitted. (Name kept: exported API.) */
 export declare const DUPLICATE_WARN_THRESHOLD = 0.85;
-/** BM25 score at which task creation is rejected (clear match — no escalation). */
+/** Tier-1 score at which creation is rejected (clear match). (Name kept: exported API.) */
 export declare const DUPLICATE_REJECT_THRESHOLD = 0.92;
 /** Maximum number of candidates to surface in the warning/rejection message. */
 export declare const MAX_CANDIDATES = 3;
@@ -64,6 +68,14 @@ export interface DuplicateCheckResult {
      * Which tier produced the final decision.
      * @task T1681
      */
+    /**
+     * Which tier produced the decision.
+     *
+     * `'bm25'` is a HISTORICAL label for the Tier-1 measure, kept because it is
+     * emitted in the envelope and renaming it would break consumers. Tier 1 is
+     * not BM25 — see the module docblock. Reporting WHICH Tier-1 implementation
+     * ran (lexical vs vector) is tracked separately.
+     */
     tier?: 'bm25' | 'jaccard' | 'llm';
 }
 /**
@@ -87,7 +99,7 @@ export type DuplicateReasoning = z.infer<typeof DuplicateReasoningSchema>;
  *
  * Uses Jaccard similarity over character trigrams of a weighted blob
  * (title 2×, description 1×). This is zero-dependency, deterministic,
- * and symmetrical. Used as the BM25 proxy in Tier 1.
+ * and symmetrical. This is the LEXICAL Tier-1 measure — it is not BM25.
  *
  * @param titleA - First title.
  * @param descA - First description.
@@ -98,7 +110,7 @@ export type DuplicateReasoning = z.infer<typeof DuplicateReasoningSchema>;
 export declare function computeLexicalSimilarity(titleA: string, descA: string, titleB: string, descB: string): number;
 /**
  * Compute Jaccard similarity over word-level n-grams including labels.
- * Used as Tier-2 discriminator when BM25 is ambiguous.
+ * Used as Tier-2 discriminator when the Tier-1 score is ambiguous.
  *
  * @param titleA - First title.
  * @param descA - First description.
@@ -114,7 +126,7 @@ export declare function computeJaccardWordSimilarity(titleA: string, descA: stri
  *
  * Cost cap: max 1 call per `cleo add` invocation (enforced by the caller via
  * a `llmCallMade` flag). Never throws — returns null on error/timeout so the
- * caller can fall back to BM25-only decision.
+ * caller can fall back to a Tier-1-only decision.
  *
  * @param incomingTitle - Title of the task being added.
  * @param incomingDescription - Description of the task being added.
@@ -132,11 +144,11 @@ export declare function callLlmDuplicateReasoning(incomingTitle: string, incomin
  *
  * Algorithm:
  *
- * Tier 1 — BM25 / vector similarity (per candidate):
+ * Tier 1 — lexical or vector similarity (per candidate):
  *   For each active task, compute vector cosine similarity (if embedding is available)
- *   or Jaccard character-trigram similarity as a proxy. This produces a BM25-like score.
+ *   Jaccard over character trigrams, or cosine over embeddings when a provider is loaded.
  *   - score >= DUPLICATE_REJECT_THRESHOLD (0.92): clear match → reject immediately.
- *   - score < BM25_ESCALATE_LOW (0.50): clear different → skip Tier 2 + 3 for this candidate.
+ *   - score < TIER1_ESCALATE_LOW (0.50): clear different → skip Tier 2 + 3 for this candidate.
  *   - score in [0.50, 0.92): ambiguous → collect for Tier-2 Jaccard evaluation.
  *
  * Tier 2 — Jaccard word n-grams (title+description+labels):
@@ -148,7 +160,7 @@ export declare function callLlmDuplicateReasoning(incomingTitle: string, incomin
  *
  * Tier 3 — LLM reasoning (max 1 call per `cleo add`):
  *   Call the daemon provider with both task descriptions and the structured-output schema.
- *   On error/timeout: fall back to Tier-1 BM25 decision for the candidate (never block).
+ *   On error/timeout: fall back to the Tier-1 decision for the candidate (never block).
  *
  * @param title - Title of the task being added.
  * @param description - Description of the task being added (empty string if not provided).
@@ -189,4 +201,45 @@ export declare function buildRejectMessage(candidates: DuplicateCandidate[]): st
  * @returns Array of non-terminal tasks (pending, active, blocked).
  */
 export declare function loadActiveTasks(accessor: DataAccessor): Promise<Task[]>;
+/** Env var overriding {@link DUPLICATE_CHECK_BUDGET_MS}. */
+export declare const DUPLICATE_CHECK_BUDGET_ENV = "CLEO_DUPLICATE_CHECK_BUDGET_MS";
+/**
+ * Resolve the duplicate-detection budget, honouring an operator override.
+ *
+ * @param env - environment to read the override from.
+ * @returns budget in ms; the default when unset or malformed.
+ */
+export declare function resolveDuplicateCheckBudgetMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * {@link checkDuplicates} with a hard deadline and a fail-OPEN result.
+ *
+ * ## Why fail open (T12117 · issue #1244)
+ *
+ * Duplicate detection runs before the insert, so anything that stalls it
+ * doesn't slow the write down — it *loses* it. Reported from the field: three
+ * `cleo add` attempts at 280 s each, none of which created a row, on a host
+ * under memory pressure. No error, no id, no task. A silent write failure is
+ * the worst failure mode a task tracker has, because the agent that filed the
+ * task believes the work is recorded.
+ *
+ * It is also silent in the dangerous direction relative to CLEO's documented
+ * recovery advice. A killed mutation is supposed to mean "query before
+ * retrying — the write has usually landed", which was independently confirmed
+ * true for a timeout-killed write. But these writes had NOT landed, and nothing
+ * in the output distinguishes the two cases. An agent following the contract
+ * correctly reaches the wrong conclusion in one direction or the other.
+ *
+ * So: the row is the product, detection is enrichment. When the budget is
+ * blown, report that on stderr and let the insert proceed. A duplicate that
+ * slips through is recoverable by a human in seconds; a task that was never
+ * created is lost work nobody knows to look for.
+ *
+ * @param args - forwarded verbatim to {@link checkDuplicates}.
+ * @returns the real verdict, or a permissive one when the budget was exceeded.
+ *
+ * @task T12117
+ */
+export declare function checkDuplicatesBounded(...args: Parameters<typeof checkDuplicates>): Promise<DuplicateCheckResult & {
+    timedOut: boolean;
+}>;
 //# sourceMappingURL=duplicate-detector.d.ts.map

package/dist/tasks/duplicate-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duplicate-detector.d.ts","sourceRoot":"","sources":["../../src/tasks/duplicate-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAM9D,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,mFAAmF;AACnF,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAuB/C,gFAAgF;AAChF,eAAO,MAAM,cAAc,IAAI,CAAC;AAShC,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,0DAA0D;IAC1D,YAAY,EAAE,OAAO,CAAC;IACtB,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC;CACnC;AAMD;;;GAGG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;iBAYnC,CAAC;AAEH,kDAAkD;AAClD,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAwE1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAWR;AAuDD;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,CAIR;AA4FD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,aAAa,EAAE,MAAM,EACrB,mBAAmB,EAAE,MAAM,EAC3B,SAAS,EAAE,kBAAkB,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EACxD,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAoGpC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,MAAM,EAAE,EACjB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,CAAC,CA6M/B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAI5E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAMzE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,kBAAkB,EAAE,GAAG,MAAM,CAM3E;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAM7E"}
+{"version":3,"file":"duplicate-detector.d.ts","sourceRoot":"","sources":["../../src/tasks/duplicate-detector.ts"],"names":[],"mappings":"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"}

package/dist/tasks/duplicate-detector.js

@@ -6,7 +6,11 @@
  *
  * Three-tier escalation (T1681):
  *
- *   Tier 1 — BM25 / vector similarity (current: Jaccard trigrams or cosine):
+ *   Tier 1 — lexical OR vector similarity. NOT BM25, despite the historical
+ *     naming: there is no IDF, no term frequency and no length normalisation.
+ *     Two implementations, selected at runtime (see `runDuplicateCheck`):
+ *       - lexical: Jaccard over CHARACTER TRIGRAMS of a title-2x-weighted blob
+ *       - vector:  cosine over embeddings, when an embedding provider is loaded
  *     score >= 0.92 → reject (clear match)
  *     score <  0.50 → insert (clear different)
  *     score in [0.50, 0.92) → escalate to Tier 2
@@ -19,11 +23,11 @@
  *   Tier 3 — LLM reasoning (max 1 call per cleo add):
  *     are_duplicate=true  → reject
  *     are_duplicate=false → insert
- *     LLM error / timeout → fall back to BM25-only decision (never block on error)
+ *     LLM error / timeout → fall back to Tier-1-only decision (never block on error)
  *
- * Thresholds (original T1633 behavior preserved for BM25 clear-match path):
- *   BM25 score >= 0.85 → warning emitted to stderr (non-blocking)
- *   BM25 score >= 0.92 → rejected with E_DUPLICATE_TASK_LIKELY
+ * Thresholds (original T1633 behavior preserved for the Tier-1 clear-match path):
+ *   Tier-1 score >= 0.85 → warning emitted to stderr (non-blocking)
+ *   Tier-1 score >= 0.92 → rejected with E_DUPLICATE_TASK_LIKELY
  *
  * @epic T1627
  * @task T1633
@@ -33,15 +37,15 @@ import { z } from 'zod';
 // ============================================================================
 // Thresholds
 // ============================================================================
-/** BM25 score at which a non-blocking warning is emitted. */
+/** Tier-1 score at which a non-blocking warning is emitted. (Name kept: exported API.) */
 export const DUPLICATE_WARN_THRESHOLD = 0.85;
-/** BM25 score at which task creation is rejected (clear match — no escalation). */
+/** Tier-1 score at which creation is rejected (clear match). (Name kept: exported API.) */
 export const DUPLICATE_REJECT_THRESHOLD = 0.92;
 /**
- * BM25 lower bound for the ambiguous range.
+ * Tier-1 lower bound for the ambiguous range.
  * Scores below this are considered clear-different and skip Jaccard + LLM.
  */
-const BM25_ESCALATE_LOW = 0.5;
+const TIER1_ESCALATE_LOW = 0.5;
 /**
  * Jaccard reject threshold.
  * Scores >= this after Tier-2 escalation cause rejection without calling LLM.
@@ -58,6 +62,29 @@ const MAX_ACTIVE_TASKS_SCAN = 500;
 export const MAX_CANDIDATES = 3;
 /** LLM call timeout in milliseconds. */
 const LLM_TIMEOUT_MS = 15_000;
+/**
+ * Maximum candidates that may be scored with local embeddings (T12117).
+ *
+ * The vector tier used to run inside the per-candidate loop with no bound, so
+ * `cleo add` performed one local model inference **per active task** before
+ * committing the row — O(active tasks) inferences on the write path. In a
+ * project with ~1,000 active tasks that is thousands of inferences to create
+ * one row, which is why `cleo add` was observed taking 180-280 s and failing
+ * outright on a memory-constrained host (issue #1244).
+ *
+ * Candidates beyond this budget fall back to the lexical score, which is the
+ * same fallback already used whenever embeddings are unavailable — so this
+ * bounds cost without introducing a new code path.
+ */
+const MAX_VECTOR_CANDIDATES = 25;
+/**
+ * Wall-clock budget for the whole vector-scoring phase, in milliseconds.
+ *
+ * A second bound beside {@link MAX_VECTOR_CANDIDATES} because the count cap
+ * assumes each inference is fast, and a cold model load is not. Whichever
+ * bound trips first ends the phase.
+ */
+const VECTOR_PHASE_BUDGET_MS = 5_000;
 // ============================================================================
 // LLM structured-output schema (Tier 3)
 // ============================================================================
@@ -79,7 +106,7 @@ export const DuplicateReasoningSchema = z.object({
     suggestion: z.enum(['merge', 'keep-both', 'block-new']),
 });
 // ============================================================================
-// Similarity Primitives — Tier 1 (BM25 proxy)
+// Similarity Primitives — Tier 1 (lexical: character-trigram Jaccard)
 // ============================================================================
 /**
  * Normalise text for comparison: lowercase, collapse whitespace,
@@ -151,7 +178,7 @@ function buildSearchBlob(title, description) {
  *
  * Uses Jaccard similarity over character trigrams of a weighted blob
  * (title 2×, description 1×). This is zero-dependency, deterministic,
- * and symmetrical. Used as the BM25 proxy in Tier 1.
+ * and symmetrical. This is the LEXICAL Tier-1 measure — it is not BM25.
  *
  * @param titleA - First title.
  * @param descA - First description.
@@ -202,7 +229,7 @@ function tokenise(text) {
 }
 /**
  * Build word-level n-gram set from title + description + labels.
- * This differs from the BM25 blob (which uses character trigrams, no labels).
+ * This differs from the Tier-1 lexical blob (character trigrams, no labels).
  *
  * @param title - Task title.
  * @param description - Task description.
@@ -210,7 +237,7 @@ function tokenise(text) {
  * @returns Set of word unigrams + bigrams.
  */
 function buildWordNgramSet(title, description, labels) {
-    // Title carries 2× weight via repetition (matches BM25 weighting)
+    // Title carries 2x weight via repetition (matches the Tier-1 blob weighting)
     const titleTokens = tokenise(title);
     const descTokens = tokenise(description);
     const labelTokens = labels.flatMap((l) => tokenise(l));
@@ -219,7 +246,7 @@ function buildWordNgramSet(title, description, labels) {
 }
 /**
  * Compute Jaccard similarity over word-level n-grams including labels.
- * Used as Tier-2 discriminator when BM25 is ambiguous.
+ * Used as Tier-2 discriminator when the Tier-1 score is ambiguous.
  *
  * @param titleA - First title.
  * @param descA - First description.
@@ -238,24 +265,45 @@ export function computeJaccardWordSimilarity(titleA, descA, labelsA, titleB, des
 // BRAIN-powered Vector Similarity (opportunistic, Tier 1)
 // ============================================================================
 /**
- * Attempt to compute vector-based similarity for a single active task.
- *
- * Embeds the incoming blob and the candidate task's blob, then computes
- * cosine similarity from the dot product (assuming unit-norm vectors from
- * standard embedding models).
+ * Embed the incoming search blob ONCE for the whole duplicate check.
  *
- * Returns `null` when embedding is unavailable (triggers lexical fallback).
+ * Returns `null` when embedding is unavailable, which makes the caller fall
+ * back to the lexical (trigram) measure for every candidate.
  *
  * @param incomingBlob - Normalised search blob for the new task.
- * @param candidateBlob - Normalised search blob for the candidate task.
- * @returns Cosine similarity in [0, 1], or null when unavailable.
+ * @returns The incoming embedding, or `null` when embedding is unavailable.
+ */
+async function embedIncomingOnce(incomingBlob) {
+    try {
+        const { isEmbeddingAvailable, embedText } = await import('../memory/brain-embedding.js');
+        if (!isEmbeddingAvailable())
+            return null;
+        return (await embedText(incomingBlob)) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Cosine similarity between a PRE-COMPUTED incoming vector and a candidate blob.
+ *
+ * The incoming vector is computed once per duplicate check by
+ * {@link embedIncomingOnce} and passed in. It used to be embedded inside this
+ * function, which ran once per candidate — so a store with 1,126 active tasks
+ * embedded the same incoming text 1,126 times per `cleo add`. Only the candidate
+ * is embedded here.
+ *
+ * @param incomingVec - Pre-computed embedding of the incoming blob.
+ * @param candidateBlob - Candidate search blob to embed and compare.
+ * @returns Cosine similarity in [0, 1], or `null` when embedding is unavailable.
  */
-async function tryVectorSimilarity(incomingBlob, candidateBlob) {
+async function tryVectorSimilarity(incomingVec, candidateBlob) {
     try {
         const { isEmbeddingAvailable, embedText } = await import('../memory/brain-embedding.js');
         if (!isEmbeddingAvailable())
             return null;
-        const [vecA, vecB] = await Promise.all([embedText(incomingBlob), embedText(candidateBlob)]);
+        const vecA = incomingVec;
+        const vecB = await embedText(candidateBlob);
         if (!vecA || !vecB || vecA.length !== vecB.length)
             return null;
         // Cosine similarity (assumes unit-norm vectors from embedding model)
@@ -317,7 +365,7 @@ function buildDuplicateUserPrompt(incomingTitle, incomingDescription, candidateT
  *
  * Cost cap: max 1 call per `cleo add` invocation (enforced by the caller via
  * a `llmCallMade` flag). Never throws — returns null on error/timeout so the
- * caller can fall back to BM25-only decision.
+ * caller can fall back to a Tier-1-only decision.
  *
  * @param incomingTitle - Title of the task being added.
  * @param incomingDescription - Description of the task being added.
@@ -331,7 +379,7 @@ export async function callLlmDuplicateReasoning(incomingTitle, incomingDescripti
         const { authHeadersFromSealed } = await import('../llm/credentials.js');
         const { resolveLLMForRole } = await import('../llm/role-resolver.js');
         // T9255: route through the role-based resolver. Duplicate-detection is a
-        // consolidation-tier call (LLM acts as the tie-breaker between BM25 and
+        // consolidation-tier call (LLM acts as the tie-breaker between Tier 1 and
         // Jaccard tiers). The resolver walks `llm.roles.consolidation` →
         // `llm.default` → `llm.daemon` → implicit fallback, preserving the
         // prior `config.llm.daemon.*` defaulting behaviour.
@@ -412,7 +460,7 @@ export async function callLlmDuplicateReasoning(incomingTitle, incomingDescripti
         return validation.data;
     }
     catch {
-        // LLM call errors always fall back to BM25-only decision
+        // LLM call errors always fall back to a Tier-1-only decision
         return null;
     }
 }
@@ -425,11 +473,11 @@ export async function callLlmDuplicateReasoning(incomingTitle, incomingDescripti
  *
  * Algorithm:
  *
- * Tier 1 — BM25 / vector similarity (per candidate):
+ * Tier 1 — lexical or vector similarity (per candidate):
  *   For each active task, compute vector cosine similarity (if embedding is available)
- *   or Jaccard character-trigram similarity as a proxy. This produces a BM25-like score.
+ *   Jaccard over character trigrams, or cosine over embeddings when a provider is loaded.
  *   - score >= DUPLICATE_REJECT_THRESHOLD (0.92): clear match → reject immediately.
- *   - score < BM25_ESCALATE_LOW (0.50): clear different → skip Tier 2 + 3 for this candidate.
+ *   - score < TIER1_ESCALATE_LOW (0.50): clear different → skip Tier 2 + 3 for this candidate.
  *   - score in [0.50, 0.92): ambiguous → collect for Tier-2 Jaccard evaluation.
  *
  * Tier 2 — Jaccard word n-grams (title+description+labels):
@@ -441,7 +489,7 @@ export async function callLlmDuplicateReasoning(incomingTitle, incomingDescripti
  *
  * Tier 3 — LLM reasoning (max 1 call per `cleo add`):
  *   Call the daemon provider with both task descriptions and the structured-output schema.
- *   On error/timeout: fall back to Tier-1 BM25 decision for the candidate (never block).
+ *   On error/timeout: fall back to the Tier-1 decision for the candidate (never block).
  *
  * @param title - Title of the task being added.
  * @param description - Description of the task being added (empty string if not provided).
@@ -473,12 +521,22 @@ export async function checkDuplicates(title, description, accessor, labels, cwd)
             return false;
         }
     })();
-    // ---- Tier 1: BM25 / vector ------------------------------------------------
-    // Candidates that need Tier-2 Jaccard evaluation (BM25 ambiguous range).
-    // Map: candidate → bm25Score
+    // Embed the incoming blob ONCE for the whole check. This used to happen inside
+    // `tryVectorSimilarity`, which runs once per candidate — so a store with 1,126
+    // active tasks embedded the same incoming text 1,126 times per `cleo add`.
+    // `null` here simply means every candidate uses the lexical measure.
+    const incomingVec = embeddingEnabled ? await embedIncomingOnce(incomingBlob) : null;
+    // ---- Tier 1: lexical or vector --------------------------------------------
+    // Candidates that need Tier-2 Jaccard evaluation (Tier-1 ambiguous range).
+    // Map: candidate → tier1Score
     const tier1Ambiguous = [];
-    // Clear-match candidates (bm25 >= DUPLICATE_REJECT_THRESHOLD or >= DUPLICATE_WARN_THRESHOLD)
+    // Clear-match candidates (tier1 >= DUPLICATE_REJECT_THRESHOLD or >= DUPLICATE_WARN_THRESHOLD)
     const clearMatchCandidates = [];
+    // T12117: bound the vector tier. Exceeding either budget degrades the
+    // remaining candidates to the lexical score — the same path taken when
+    // embeddings are unavailable — rather than extending the write.
+    let vectorBudget = MAX_VECTOR_CANDIDATES;
+    const vectorDeadline = Date.now() + VECTOR_PHASE_BUDGET_MS;
     for (const task of activeTasks) {
         // Do not compare a task with itself (e.g. if being re-added after creation)
         if (task.title === title) {
@@ -487,31 +545,38 @@ export async function checkDuplicates(title, description, accessor, labels, cwd)
                 continue; // will be caught by findRecentDuplicate
         }
         const candidateBlob = buildSearchBlob(task.title, task.description ?? '');
-        let bm25Score;
-        if (embeddingEnabled) {
-            const vecScore = await tryVectorSimilarity(incomingBlob, candidateBlob);
-            bm25Score =
+        let tier1Score;
+        // Both bounds apply. #1258 caps the vector phase by COUNT and DEADLINE so a
+        // large store cannot stall a write; this branch additionally passes the
+        // PRE-COMPUTED incoming vector, so the incoming blob is embedded once for
+        // the whole check rather than once per candidate. `incomingVec` is non-null
+        // only when embedding is available, so it subsumes the old
+        // `embeddingEnabled` test.
+        if (incomingVec && vectorBudget > 0 && Date.now() < vectorDeadline) {
+            vectorBudget--;
+            const vecScore = await tryVectorSimilarity(incomingVec, candidateBlob);
+            tier1Score =
                 vecScore ??
                     computeLexicalSimilarity(title, description, task.title, task.description ?? '');
         }
         else {
-            bm25Score = computeLexicalSimilarity(title, description, task.title, task.description ?? '');
+            tier1Score = computeLexicalSimilarity(title, description, task.title, task.description ?? '');
         }
-        if (bm25Score >= DUPLICATE_REJECT_THRESHOLD) {
+        if (tier1Score >= DUPLICATE_REJECT_THRESHOLD) {
             // Clear match — reject without escalating
-            clearMatchCandidates.push({ id: task.id, title: task.title, score: bm25Score });
+            clearMatchCandidates.push({ id: task.id, title: task.title, score: tier1Score });
         }
-        else if (bm25Score >= BM25_ESCALATE_LOW) {
+        else if (tier1Score >= TIER1_ESCALATE_LOW) {
             // Ambiguous — collect for Tier 2
-            tier1Ambiguous.push({ task, bm25Score });
+            tier1Ambiguous.push({ task, tier1Score });
             // Also surface in warn range (>= DUPLICATE_WARN_THRESHOLD) even before Tier 2
-            if (bm25Score >= DUPLICATE_WARN_THRESHOLD) {
-                clearMatchCandidates.push({ id: task.id, title: task.title, score: bm25Score });
+            if (tier1Score >= DUPLICATE_WARN_THRESHOLD) {
+                clearMatchCandidates.push({ id: task.id, title: task.title, score: tier1Score });
             }
         }
-        // bm25Score < BM25_ESCALATE_LOW → clear different, skip
+        // tier1Score < TIER1_ESCALATE_LOW → clear different, skip
     }
-    // If we already have a clear-match reject, return immediately (BM25-only path).
+    // If we already have a clear-match reject, return immediately (Tier-1-only path).
     if (clearMatchCandidates.some((c) => c.score >= DUPLICATE_REJECT_THRESHOLD)) {
         const sorted = clearMatchCandidates
             .filter((c) => c.score >= DUPLICATE_REJECT_THRESHOLD)
@@ -530,7 +595,7 @@ export async function checkDuplicates(title, description, accessor, labels, cwd)
     // Candidates that are still ambiguous after Tier 2 collect for LLM escalation.
     const tier2Ambiguous = [];
     const tier2Candidates = [];
-    for (const { task, bm25Score: _bm25 } of tier1Ambiguous) {
+    for (const { task, tier1Score: _tier1 } of tier1Ambiguous) {
         const jScore = computeJaccardWordSimilarity(title, description, incomingLabels, task.title, task.description ?? '', task.labels ?? []);
         if (jScore >= JACCARD_REJECT_THRESHOLD) {
             // Jaccard says: reject
@@ -592,11 +657,11 @@ export async function checkDuplicates(title, description, accessor, labels, cwd)
                 tier: 'llm',
             };
         }
-        // LLM failed/timed out — fall back to BM25-only decision.
-        // The BM25 score for the top candidate is in [0.5, 0.92), which means
+        // LLM failed/timed out — fall back to a Tier-1-only decision.
+        // The Tier-1 score for the top candidate is in [0.5, 0.92), which means
         // it's in the warn zone only if >= DUPLICATE_WARN_THRESHOLD.
-        const bm25Entry = tier1Ambiguous.find((e) => e.task.id === topCandidate.task.id);
-        const fallbackScore = bm25Entry?.bm25Score ?? topCandidate.jaccardScore;
+        const tier1Entry = tier1Ambiguous.find((e) => e.task.id === topCandidate.task.id);
+        const fallbackScore = tier1Entry?.tier1Score ?? topCandidate.jaccardScore;
         if (fallbackScore >= DUPLICATE_WARN_THRESHOLD) {
             const candidate = {
                 id: topCandidate.task.id,
@@ -612,7 +677,7 @@ export async function checkDuplicates(title, description, accessor, labels, cwd)
             };
         }
     }
-    // ---- Collect any BM25 warn-zone candidates (non-rejecting) ----------------
+    // ---- Collect any Tier-1 warn-zone candidates (non-rejecting) --------------
     const warnCandidates = clearMatchCandidates
         .filter((c) => c.score >= DUPLICATE_WARN_THRESHOLD && c.score < DUPLICATE_REJECT_THRESHOLD)
         .sort((a, b) => b.score - a.score)
@@ -675,4 +740,82 @@ export async function loadActiveTasks(accessor) {
     });
     return tasks;
 }
+/**
+ * Total wall-clock budget for duplicate detection on the write path, in ms.
+ *
+ * Detection is three tiers deep and two of them can call out of process (local
+ * embeddings, then an LLM). Each has its own bound, but "bounded individually"
+ * is not "bounded in aggregate" — and this runs BEFORE the row is inserted.
+ */
+const DUPLICATE_CHECK_BUDGET_MS = 20_000;
+/** Env var overriding {@link DUPLICATE_CHECK_BUDGET_MS}. */
+export const DUPLICATE_CHECK_BUDGET_ENV = 'CLEO_DUPLICATE_CHECK_BUDGET_MS';
+/**
+ * Resolve the duplicate-detection budget, honouring an operator override.
+ *
+ * @param env - environment to read the override from.
+ * @returns budget in ms; the default when unset or malformed.
+ */
+export function resolveDuplicateCheckBudgetMs(env = process.env) {
+    const raw = Number.parseInt(env[DUPLICATE_CHECK_BUDGET_ENV] ?? '', 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : DUPLICATE_CHECK_BUDGET_MS;
+}
+/**
+ * {@link checkDuplicates} with a hard deadline and a fail-OPEN result.
+ *
+ * ## Why fail open (T12117 · issue #1244)
+ *
+ * Duplicate detection runs before the insert, so anything that stalls it
+ * doesn't slow the write down — it *loses* it. Reported from the field: three
+ * `cleo add` attempts at 280 s each, none of which created a row, on a host
+ * under memory pressure. No error, no id, no task. A silent write failure is
+ * the worst failure mode a task tracker has, because the agent that filed the
+ * task believes the work is recorded.
+ *
+ * It is also silent in the dangerous direction relative to CLEO's documented
+ * recovery advice. A killed mutation is supposed to mean "query before
+ * retrying — the write has usually landed", which was independently confirmed
+ * true for a timeout-killed write. But these writes had NOT landed, and nothing
+ * in the output distinguishes the two cases. An agent following the contract
+ * correctly reaches the wrong conclusion in one direction or the other.
+ *
+ * So: the row is the product, detection is enrichment. When the budget is
+ * blown, report that on stderr and let the insert proceed. A duplicate that
+ * slips through is recoverable by a human in seconds; a task that was never
+ * created is lost work nobody knows to look for.
+ *
+ * @param args - forwarded verbatim to {@link checkDuplicates}.
+ * @returns the real verdict, or a permissive one when the budget was exceeded.
+ *
+ * @task T12117
+ */
+export async function checkDuplicatesBounded(...args) {
+    let timer;
+    const budgetMs = resolveDuplicateCheckBudgetMs();
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), budgetMs);
+        // Must not hold the CLI's event loop open on its own.
+        timer.unref();
+    });
+    try {
+        const verdict = await Promise.race([checkDuplicates(...args), timeout]);
+        if (verdict === null) {
+            process.stderr.write(`cleo: duplicate detection exceeded ${budgetMs}ms and was skipped; ` +
+                `creating the task anyway. Run 'cleo find' to check for duplicates.\n`);
+            return {
+                maxScore: 0,
+                candidates: [],
+                shouldReject: false,
+                shouldWarn: false,
+                tier: 'bm25',
+                timedOut: true,
+            };
+        }
+        return { ...verdict, timedOut: false };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 //# sourceMappingURL=duplicate-detector.js.map