@causyne/agent 1.10.12 → 1.10.17

package/src/planCache.js

@@ -2,7 +2,6 @@ import fs from 'fs';
 import path from 'path';
 import crypto from 'crypto';
 import { causyneHome } from './utils/paths.js';
-
 // Agentic Plan Caching.
 //
 // THE WASTE THIS ATTACKS. The agent rediscovers the same approach from scratch
@@ -32,10 +31,9 @@ import { causyneHome } from './utils/paths.js';
 // WHAT IS STORED. Tool names, a short whitelisted action token, and whether the
 // step worked. No paths, no arguments, no file contents, no command lines. A
 // procedure, not a transcript.
-
 const PLAN_DIR = path.join(causyneHome(), 'plans');
 const PLAN_FILE = path.join(PLAN_DIR, 'index.json');
-
+const METRICS_FILE = path.join(PLAN_DIR, 'metrics.json');
 /** Two plans must overlap this much on keywords before one is offered for the other. */
 // Tuned against the asymmetry, not for elegance. A false positive costs a few
 // tokens of clearly-labelled prior art the model is told to verify. A false
@@ -43,47 +41,57 @@ const PLAN_FILE = path.join(PLAN_DIR, 'index.json');
 // ended a real run at the daily ceiling. Archetype is already a hard gate, so
 // the remaining risk is "same archetype, different task", and that is cheap.
 const MATCH_THRESHOLD = 0.38;
-
 /** Ceiling on retained templates. Pruned by usefulness, not by age alone. */
 const MAX_PLANS = 200;
-
 /** A plan longer than this is a transcript, not a procedure. */
 const MAX_STEPS = 24;
-
 /** Keywords kept per plan. Enough to discriminate, short enough to stay cheap. */
 const MAX_KEYWORDS = 12;
-
+/** Exact keyword-set hits stay O(1); fuzzy matching is a bounded fallback. */
+const RECENT_LOOKUP_WINDOW = 32;
+const MIN_LOOKUPS_BEFORE_DISABLE = 20;
+const MIN_PLANS_BEFORE_DISABLE = 10;
+const MIN_HEALTHY_HIT_RATE = 0.10;
+const DISABLE_COOLDOWN_MS = 5 * 60 * 1000;
+const SEED_FAILURE_CLASSES = new Set([
+    'not_found', 'permission', 'timeout', 'network', 'rate_limited',
+    'invalid_args', 'syntax', 'exit_nonzero', 'failed'
+]);
+const METRICS_FLUSH_INTERVAL = 10;
+let plansCache = null;
+let plansMtimeMs = -1;
+let exactIndex = new Map();
+let metricsCache = null;
+let dirtyMetricEvents = 0;
 /**
  * Words that carry no intent. Deliberately small: an aggressive list throws
  * away the domain nouns that make two tasks comparable.
  * @type {ReadonlySet<string>}
  */
 const STOPWORDS = new Set([
-  'the', 'a', 'an', 'and', 'or', 'but', 'for', 'to', 'of', 'in', 'on', 'at',
-  'is', 'are', 'be', 'was', 'were', 'do', 'does', 'did', 'can', 'could',
-  'with', 'from', 'into', 'then', 'this', 'that', 'it', 'its', 'as', 'by',
-  'please', 'just', 'now', 'my', 'me', 'you', 'your', 'i',
-  // Generic creation verbs. Every task has one, so they inflate the union
-  // without discriminating between tasks — the exact shape that made
-  // "buat pena 3D di Blender" and "bikin pulpen 3D di blender" score 0.40
-  // when they describe the same job. `build`, `fix`, `debug` and `render` are
-  // deliberately NOT here: those DO separate tasks inside one archetype.
-  'make', 'create', 'creating', 'made', 'generate',
-  // Indonesian — the owner writes in both, and a mixed-language prompt must
-  // key the same way whichever language framed it.
-  'dan', 'atau', 'yang', 'untuk', 'dari', 'ke', 'di', 'itu', 'ini', 'dengan',
-  'tolong', 'saya', 'aku', 'kamu', 'adalah', 'pada', 'juga', 'agar', 'jadi',
-  'buat', 'bikin', 'membuat', 'lalu', 'kemudian', 'terus', 'dulu', 'saja',
-  'sekarang', 'harus', 'bisa', 'sudah', 'belum', 'akan', 'mau', 'coba'
+    'the', 'a', 'an', 'and', 'or', 'but', 'for', 'to', 'of', 'in', 'on', 'at',
+    'is', 'are', 'be', 'was', 'were', 'do', 'does', 'did', 'can', 'could',
+    'with', 'from', 'into', 'then', 'this', 'that', 'it', 'its', 'as', 'by',
+    'please', 'just', 'now', 'my', 'me', 'you', 'your', 'i',
+    // Generic creation verbs. Every task has one, so they inflate the union
+    // without discriminating between tasks — the exact shape that made
+    // "buat pena 3D di Blender" and "bikin pulpen 3D di blender" score 0.40
+    // when they describe the same job. `build`, `fix`, `debug` and `render` are
+    // deliberately NOT here: those DO separate tasks inside one archetype.
+    'make', 'create', 'creating', 'made', 'generate',
+    // Indonesian — the owner writes in both, and a mixed-language prompt must
+    // key the same way whichever language framed it.
+    'dan', 'atau', 'yang', 'untuk', 'dari', 'ke', 'di', 'itu', 'ini', 'dengan',
+    'tolong', 'saya', 'aku', 'kamu', 'adalah', 'pada', 'juga', 'agar', 'jadi',
+    'buat', 'bikin', 'membuat', 'lalu', 'kemudian', 'terus', 'dulu', 'saja',
+    'sekarang', 'harus', 'bisa', 'sudah', 'belum', 'akan', 'mau', 'coba'
 ]);
-
 // HONEST LIMIT. Matching is LEXICAL. A task cached in English and re-asked in
 // Indonesian (or the reverse) will miss, because Jaccard cannot know that
 // "pen" and "pena" are the same object. That is a deliberate trade: this path
 // is deterministic, instant, and works on a machine with no embedding model
 // provisioned. Cortex is the semantic route and already carries embeddings;
 // these two compose rather than compete.
-
 /**
  * One executed step, reduced to what is reusable.
  *
@@ -99,7 +107,6 @@ const STOPWORDS = new Set([
  * @property {string}  [why] Failure CLASS when ok is false. A closed vocabulary,
  *                           never the error text.
  */
-
 /**
  * @typedef {Object} PlanTemplate
  * @property {string}     id
@@ -111,46 +118,225 @@ const STOPWORDS = new Set([
  * @property {number}     createdAt
  * @property {number}     updatedAt
  */
-
 /**
  * @typedef {Object} PlanMatch
  * @property {PlanTemplate} template
  * @property {number}       similarity
+ * @property {'exact'|'fuzzy'} matchType
+ * @property {{keywordCount: number, lookupMs: number}} telemetry
  */
-
 function ensureDir() {
-  if (!fs.existsSync(PLAN_DIR)) fs.mkdirSync(PLAN_DIR, { recursive: true, mode: 0o700 });
+    if (!fs.existsSync(PLAN_DIR))
+        fs.mkdirSync(PLAN_DIR, { recursive: true, mode: 0o700 });
+}
+/** @returns {string} */
+function planSignature(archetype, keywords) {
+    return `${String(archetype || '')}\u0000${[...new Set(keywords || [])].sort().join('\u0001')}`;
+}
+function rebuildIndex(plans) {
+    exactIndex = new Map();
+    for (const template of plans) {
+        const signature = planSignature(template.archetype, template.keywords);
+        const current = exactIndex.get(signature);
+        if (!current || (template.wins || 0) > (current.wins || 0)) {
+            exactIndex.set(signature, template);
+        }
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isPlanStep(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.tool === 'string'
+        && typeof value.note === 'string'
+        && typeof value.ok === 'boolean'
+        && (value.why === undefined
+            || (typeof value.why === 'string' && SEED_FAILURE_CLASSES.has(value.why)));
+}
+function isPlanTemplate(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.id === 'string'
+        && typeof value.archetype === 'string'
+        && Array.isArray(value.keywords)
+        && value.keywords.every((keyword) => typeof keyword === 'string')
+        && Array.isArray(value.steps)
+        && value.steps.every(isPlanStep)
+        && typeof value.uses === 'number'
+        && Number.isFinite(value.uses)
+        && typeof value.wins === 'number'
+        && Number.isFinite(value.wins)
+        && typeof value.createdAt === 'number'
+        && Number.isFinite(value.createdAt)
+        && typeof value.updatedAt === 'number'
+        && Number.isFinite(value.updatedAt);
 }
-
-/**
- * @returns {PlanTemplate[]}
- */
 function readAll() {
-  try {
-    if (!fs.existsSync(PLAN_FILE)) return [];
-    const parsed = JSON.parse(fs.readFileSync(PLAN_FILE, 'utf8'));
-    return Array.isArray(parsed) ? parsed : [];
-  } catch (e) {
-    return []; // a corrupt cache degrades to a cold one, never to a failed task
-  }
+    try {
+        if (!fs.existsSync(PLAN_FILE)) {
+            plansCache = [];
+            plansMtimeMs = -1;
+            rebuildIndex(plansCache);
+            return plansCache;
+        }
+        const mtimeMs = fs.statSync(PLAN_FILE).mtimeMs;
+        if (plansCache && mtimeMs === plansMtimeMs)
+            return plansCache;
+        const parsed = JSON.parse(fs.readFileSync(PLAN_FILE, 'utf8'));
+        plansCache = Array.isArray(parsed) ? parsed.filter(isPlanTemplate) : [];
+        plansMtimeMs = mtimeMs;
+        rebuildIndex(plansCache);
+        return plansCache;
+    }
+    catch (e) {
+        plansCache = [];
+        plansMtimeMs = -1;
+        rebuildIndex(plansCache);
+        return plansCache; // a corrupt cache degrades to a cold one, never to a failed task
+    }
 }
-
 /**
  * @param {PlanTemplate[]} plans
  * @returns {boolean}
  */
 function writeAll(plans) {
-  try {
-    ensureDir();
-    const temp = `${PLAN_FILE}.tmp_${process.pid}`;
-    fs.writeFileSync(temp, JSON.stringify(plans, null, 2), { mode: 0o600 });
-    fs.renameSync(temp, PLAN_FILE); // atomic: a torn write would erase the cache
+    try {
+        ensureDir();
+        const temp = `${PLAN_FILE}.tmp_${process.pid}`;
+        fs.writeFileSync(temp, JSON.stringify(plans, null, 2), { mode: 0o600 });
+        fs.renameSync(temp, PLAN_FILE); // atomic: a torn write would erase the cache
+        plansCache = plans;
+        plansMtimeMs = fs.statSync(PLAN_FILE).mtimeMs;
+        rebuildIndex(plans);
+        return true;
+    }
+    catch (e) {
+        return false; // losing the cache must never fail the task
+    }
+}
+function defaultMetrics() {
+    return {
+        version: 1,
+        lookups: 0,
+        hits: 0,
+        exactHits: 0,
+        fuzzyHits: 0,
+        misses: 0,
+        bypassed: 0,
+        records: 0,
+        totalLookupMs: 0,
+        maxLookupMs: 0,
+        totalRecordMs: 0,
+        recent: [],
+        disabledUntil: 0,
+        lastLookupAt: 0,
+        lastRecordAt: 0
+    };
+}
+const METRIC_NUMBER_FIELDS = [
+    'lookups', 'hits', 'exactHits', 'fuzzyHits', 'misses', 'bypassed', 'records',
+    'totalLookupMs', 'maxLookupMs', 'totalRecordMs', 'disabledUntil',
+    'lastLookupAt', 'lastRecordAt'
+];
+function normalizeMetrics(value) {
+    const metrics = defaultMetrics();
+    if (!isRecord(value))
+        return metrics;
+    for (const key of METRIC_NUMBER_FIELDS) {
+        const candidate = value[key];
+        if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate >= 0) {
+            metrics[key] = candidate;
+        }
+    }
+    if (Array.isArray(value.recent)) {
+        metrics.recent = value.recent
+            .filter((entry) => entry === 0 || entry === 1)
+            .slice(-RECENT_LOOKUP_WINDOW);
+    }
+    return metrics;
+}
+function readMetrics() {
+    if (metricsCache)
+        return metricsCache;
+    try {
+        if (!fs.existsSync(METRICS_FILE)) {
+            metricsCache = defaultMetrics();
+            return metricsCache;
+        }
+        const parsed = JSON.parse(fs.readFileSync(METRICS_FILE, 'utf8'));
+        metricsCache = normalizeMetrics(parsed);
+    }
+    catch (e) {
+        metricsCache = defaultMetrics();
+    }
+    return metricsCache;
+}
+function writeMetrics(force = false) {
+    if (!metricsCache || (!force && dirtyMetricEvents < METRICS_FLUSH_INTERVAL))
+        return false;
+    try {
+        ensureDir();
+        const temp = `${METRICS_FILE}.tmp_${process.pid}`;
+        fs.writeFileSync(temp, JSON.stringify(metricsCache, null, 2), { mode: 0o600 });
+        fs.renameSync(temp, METRICS_FILE);
+        dirtyMetricEvents = 0;
+        return true;
+    }
+    catch (e) {
+        return false;
+    }
+}
+function recentHitRate(metrics) {
+    if (!metrics.recent.length)
+        return 0;
+    return metrics.recent.reduce((sum, value) => sum + value, 0) / metrics.recent.length;
+}
+function shouldTemporarilyDisable(metrics, planCount, now) {
+    if (metrics.disabledUntil > now)
+        return true;
+    if (metrics.disabledUntil > 0 && metrics.disabledUntil <= now) {
+        metrics.disabledUntil = 0;
+        metrics.recent = [];
+    }
+    if (planCount < MIN_PLANS_BEFORE_DISABLE || metrics.recent.length < MIN_LOOKUPS_BEFORE_DISABLE) {
+        return false;
+    }
+    if (recentHitRate(metrics) >= MIN_HEALTHY_HIT_RATE)
+        return false;
+    metrics.disabledUntil = now + DISABLE_COOLDOWN_MS;
+    writeMetrics(true);
     return true;
-  } catch (e) {
-    return false; // losing the cache must never fail the task
-  }
 }
-
+function recordLookupTelemetry({ hit, matchType = null, durationMs, bypassed = false }) {
+    const metrics = readMetrics();
+    const now = Date.now();
+    metrics.lastLookupAt = now;
+    if (bypassed) {
+        metrics.bypassed += 1;
+    }
+    else {
+        metrics.lookups += 1;
+        metrics.totalLookupMs += durationMs;
+        metrics.maxLookupMs = Math.max(metrics.maxLookupMs, durationMs);
+        metrics.recent.push(hit ? 1 : 0);
+        if (metrics.recent.length > RECENT_LOOKUP_WINDOW)
+            metrics.recent.shift();
+        if (hit) {
+            metrics.hits += 1;
+            if (matchType === 'exact')
+                metrics.exactHits += 1;
+            if (matchType === 'fuzzy')
+                metrics.fuzzyHits += 1;
+        }
+        else {
+            metrics.misses += 1;
+        }
+    }
+    dirtyMetricEvents += 1;
+    writeMetrics(false);
+}
 /**
  * Intent keywords, computed without a model.
  *
@@ -158,15 +344,13 @@ function writeAll(plans) {
  * @returns {string[]} unique, lowercase, order not significant
  */
 export function extractKeywords(text) {
-  const words = String(text || '')
-    .toLowerCase()
-    .replace(/[^\p{L}\p{N}\s_-]/gu, ' ')
-    .split(/\s+/)
-    .filter((w) => w.length >= 3 && w.length <= 24 && !STOPWORDS.has(w) && !/^\d+$/.test(w));
-
-  return [...new Set(words)].slice(0, MAX_KEYWORDS);
+    const words = String(text || '')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length >= 3 && w.length <= 24 && !STOPWORDS.has(w) && !/^\d+$/.test(w));
+    return [...new Set(words)].slice(0, MAX_KEYWORDS);
 }
-
 /**
  * Jaccard overlap. Symmetric, bounded 0..1, and cheap enough to run against
  * every stored plan without anyone noticing.
@@ -176,15 +360,16 @@ export function extractKeywords(text) {
  * @returns {number}
  */
 export function similarity(a, b) {
-  const left = new Set(a || []);
-  const right = new Set(b || []);
-  if (left.size === 0 || right.size === 0) return 0;
-
-  let shared = 0;
-  for (const word of left) if (right.has(word)) shared++;
-  return shared / (left.size + right.size - shared);
+    const left = new Set(a || []);
+    const right = new Set(b || []);
+    if (left.size === 0 || right.size === 0)
+        return 0;
+    let shared = 0;
+    for (const word of left)
+        if (right.has(word))
+            shared++;
+    return shared / (left.size + right.size - shared);
 }
-
 /**
  * Reduce a tool call to a reusable step.
  *
@@ -198,26 +383,24 @@ export function similarity(a, b) {
  * @returns {PlanStep}
  */
 export function toStep(tool, args, ok, result) {
-  const SAFE_KEYS = ['action', 'verb', 'mode', 'operation', 'kind', 'type'];
-  let note = '';
-
-  for (const key of SAFE_KEYS) {
-    const value = args && args[key];
-    if (typeof value === 'string' && value) {
-      note = value.toLowerCase().replace(/[^a-z0-9_.-]/g, '').slice(0, 32);
-      if (note) break;
+    const SAFE_KEYS = ['action', 'verb', 'mode', 'operation', 'kind', 'type'];
+    let note = '';
+    for (const key of SAFE_KEYS) {
+        const value = isRecord(args) ? args[key] : undefined;
+        if (typeof value === 'string' && value) {
+            note = value.toLowerCase().replace(/[^a-z0-9_.-]/g, '').slice(0, 32);
+            if (note)
+                break;
+        }
     }
-  }
-
-  /** @type {PlanStep} */
-  const step = { tool: String(tool || '').slice(0, 64), note, ok: Boolean(ok) };
-  if (!step.ok) {
-    const why = failureClass(result);
-    if (why) step.why = why;
-  }
-  return step;
+    const step = { tool: String(tool || '').slice(0, 64), note, ok: Boolean(ok) };
+    if (!step.ok) {
+        const why = failureClass(result);
+        if (why)
+            step.why = why;
+    }
+    return step;
 }
-
 /**
  * Why a step failed, as a CLASS rather than as a message.
  *
@@ -234,57 +417,103 @@ export function toStep(tool, args, ok, result) {
  * @returns {string} one of the classes below, or '' when nothing matched
  */
 export function failureClass(result) {
-  if (!result) return '';
-  const text = [result.error, result.message, result.stderr, result.reason]
-    .filter((v) => typeof v === 'string')
-    .join(' ')
-    .toLowerCase()
-    .slice(0, 500);
-  if (!text) return typeof result.exitCode === 'number' && result.exitCode !== 0 ? 'exit_nonzero' : '';
-
-  if (/not found|no such file|enoent|command not found|cannot find/.test(text)) return 'not_found';
-  if (/permission|denied|eacces|eperm|unauthor|forbidden/.test(text)) return 'permission';
-  if (/timed? ?out|etimedout|deadline/.test(text)) return 'timeout';
-  if (/econnrefused|enotfound|network|dns|socket|offline/.test(text)) return 'network';
-  if (/rate limit|429|quota|budget/.test(text)) return 'rate_limited';
-  if (/invalid|malformed|schema|required (property|field)|bad request|400/.test(text)) return 'invalid_args';
-  if (/syntax ?error|parse error|unexpected token/.test(text)) return 'syntax';
-  if (/exit code|non-?zero|exited with/.test(text)) return 'exit_nonzero';
-  return 'failed';
+    if (!result)
+        return '';
+    const source = isRecord(result) ? result : {};
+    const text = [source.error, source.message, source.stderr, source.reason]
+        .filter((v) => typeof v === 'string')
+        .join(' ')
+        .toLowerCase()
+        .slice(0, 500);
+    if (!text)
+        return typeof source.exitCode === 'number' && source.exitCode !== 0 ? 'exit_nonzero' : '';
+    if (/not found|no such file|enoent|command not found|cannot find/.test(text))
+        return 'not_found';
+    if (/permission|denied|eacces|eperm|unauthor|forbidden/.test(text))
+        return 'permission';
+    if (/timed? ?out|etimedout|deadline/.test(text))
+        return 'timeout';
+    if (/econnrefused|enotfound|network|dns|socket|offline/.test(text))
+        return 'network';
+    if (/rate limit|429|quota|budget/.test(text))
+        return 'rate_limited';
+    if (/invalid|malformed|schema|required (property|field)|bad request|400/.test(text))
+        return 'invalid_args';
+    if (/syntax ?error|parse error|unexpected token/.test(text))
+        return 'syntax';
+    if (/exit code|non-?zero|exited with/.test(text))
+        return 'exit_nonzero';
+    return 'failed';
 }
-
 /**
  * The best stored plan for this request, if one is close enough.
  *
- * @param   {{prompt: string, archetype?: string}} query
+ * @param   {{prompt: string, archetype?: string, allowFuzzy?: boolean}} query
  * @returns {PlanMatch|null}
  */
 export function lookupPlan(query) {
-  const keywords = extractKeywords(query?.prompt);
-  if (keywords.length === 0) return null;
-
-  const archetype = String(query?.archetype || '');
-  let best = null;
-
-  for (const template of readAll()) {
-    // Archetype is a hard gate, not a score. A "build a 3D scene" plan sharing
-    // three words with "debug the build" is not a plan for it.
-    if (archetype && template.archetype && template.archetype !== archetype) continue;
-
-    const score = similarity(keywords, template.keywords);
-    if (score < MATCH_THRESHOLD) continue;
-
-    // Ties break on demonstrated usefulness, so a plan that has actually worked
-    // outranks one that merely matched before.
-    const winRate = template.uses > 0 ? template.wins / template.uses : 0;
-    const ranked = score + winRate * 0.1;
-    if (!best || ranked > best.ranked) best = { template, similarity: score, ranked };
-  }
-
-  if (!best) return null;
-  return { template: best.template, similarity: best.similarity };
+    const startedAt = performance.now();
+    const keywords = extractKeywords(query?.prompt);
+    if (keywords.length === 0) {
+        recordLookupTelemetry({ hit: false, durationMs: performance.now() - startedAt });
+        return null;
+    }
+    const archetype = String(query?.archetype || '');
+    const plans = readAll();
+    const now = Date.now();
+    if (shouldTemporarilyDisable(readMetrics(), plans.length, now)) {
+        recordLookupTelemetry({ hit: false, durationMs: performance.now() - startedAt, bypassed: true });
+        return null;
+    }
+    const exact = exactIndex.get(planSignature(archetype, keywords));
+    if (exact) {
+        const durationMs = performance.now() - startedAt;
+        recordLookupTelemetry({ hit: true, matchType: 'exact', durationMs });
+        return {
+            template: exact,
+            similarity: 1,
+            matchType: 'exact',
+            telemetry: { keywordCount: keywords.length, lookupMs: durationMs }
+        };
+    }
+    // Low-confidence task classification is not enough evidence for fuzzy reuse.
+    // Exact matches remain safe; broader reuse waits until the task shape is at
+    // least medium confidence, avoiding the accuracy loss reported for aggressive
+    // fuzzy thresholds in APC Table 6.
+    if (query?.allowFuzzy === false) {
+        const durationMs = performance.now() - startedAt;
+        recordLookupTelemetry({ hit: false, durationMs });
+        return null;
+    }
+    let best = null;
+    for (const template of plans) {
+        // Archetype is a hard gate, not a score. A "build a 3D scene" plan sharing
+        // three words with "debug the build" is not a plan for it.
+        if (archetype && template.archetype && template.archetype !== archetype)
+            continue;
+        const score = similarity(keywords, template.keywords);
+        if (score < MATCH_THRESHOLD)
+            continue;
+        // Ties break on demonstrated usefulness, so a plan that has actually worked
+        // outranks one that merely matched before.
+        const winRate = template.uses > 0 ? template.wins / template.uses : 0;
+        const ranked = score + winRate * 0.1;
+        if (!best || ranked > best.ranked)
+            best = { template, similarity: score, ranked };
+    }
+    const durationMs = performance.now() - startedAt;
+    if (!best) {
+        recordLookupTelemetry({ hit: false, durationMs });
+        return null;
+    }
+    recordLookupTelemetry({ hit: true, matchType: 'fuzzy', durationMs });
+    return {
+        template: best.template,
+        similarity: best.similarity,
+        matchType: 'fuzzy',
+        telemetry: { keywordCount: keywords.length, lookupMs: durationMs }
+    };
 }
-
 /**
  * Store or reinforce the procedure a task actually followed.
  *
@@ -292,46 +521,108 @@ export function lookupPlan(query) {
  * @returns {PlanTemplate|null} the stored template, or null when there was nothing worth storing
  */
 export function recordPlan(outcome) {
-  const steps = Array.isArray(outcome?.steps) ? outcome.steps.slice(0, MAX_STEPS) : [];
-  // A one-step task teaches nothing a fresh model would not do anyway.
-  if (steps.length < 2) return null;
-
-  const keywords = extractKeywords(outcome?.prompt);
-  if (keywords.length === 0) return null;
-
-  const plans = readAll();
-  const archetype = String(outcome?.archetype || '');
-
-  const existing = plans.find(
-    (t) => t.archetype === archetype && similarity(keywords, t.keywords) >= 0.8
-  );
-
-  if (existing) {
-    existing.steps = steps;              // the newest working route wins
-    existing.uses += 1;
-    existing.wins += 1;
-    existing.updatedAt = Date.now();
+    const startedAt = performance.now();
+    const steps = Array.isArray(outcome?.steps)
+        ? outcome.steps.filter(isPlanStep).slice(0, MAX_STEPS)
+        : [];
+    // A one-step task teaches nothing a fresh model would not do anyway.
+    if (steps.length < 2)
+        return null;
+    const keywords = extractKeywords(outcome?.prompt);
+    if (keywords.length === 0)
+        return null;
+    const plans = readAll();
+    const archetype = String(outcome?.archetype || '');
+    const existing = plans.find((t) => t.archetype === archetype && similarity(keywords, t.keywords) >= 0.8);
+    if (existing) {
+        existing.steps = steps; // the newest working route wins
+        existing.uses += 1;
+        existing.wins += 1;
+        existing.updatedAt = Date.now();
+        writeAll(prune(plans));
+        const metrics = readMetrics();
+        metrics.records += 1;
+        metrics.totalRecordMs += performance.now() - startedAt;
+        metrics.lastRecordAt = Date.now();
+        dirtyMetricEvents += 1;
+        writeMetrics(false);
+        return existing;
+    }
+    const template = {
+        id: `p_${Date.now().toString(36)}_${crypto.randomBytes(3).toString('hex')}`,
+        archetype,
+        keywords,
+        steps,
+        uses: 1,
+        wins: 1,
+        createdAt: Date.now(),
+        updatedAt: Date.now()
+    };
+    plans.push(template);
     writeAll(prune(plans));
-    return existing;
-  }
-
-  /** @type {PlanTemplate} */
-  const template = {
-    id: `p_${Date.now().toString(36)}_${crypto.randomBytes(3).toString('hex')}`,
-    archetype,
-    keywords,
-    steps,
-    uses: 1,
-    wins: 1,
-    createdAt: Date.now(),
-    updatedAt: Date.now()
-  };
-
-  plans.push(template);
-  writeAll(prune(plans));
-  return template;
+    const metrics = readMetrics();
+    metrics.records += 1;
+    metrics.totalRecordMs += performance.now() - startedAt;
+    metrics.lastRecordAt = Date.now();
+    dirtyMetricEvents += 1;
+    writeMetrics(false);
+    return template;
+}
+/**
+ * Pre-populate a cold cache from user-supplied, argument-free plan samples.
+ * Only tool names, short action labels and closed-vocabulary outcomes survive;
+ * paths, prompts passed to tools and command lines have no field to enter.
+ */
+export function prewarmPlans(samples) {
+    if (!Array.isArray(samples))
+        return { accepted: 0, rejected: 1, errors: ['Expected a JSON array'] };
+    const errors = [];
+    let accepted = 0;
+    for (const [index, sample] of samples.slice(0, 100).entries()) {
+        const sampleRecord = isRecord(sample) ? sample : {};
+        const prompt = typeof sampleRecord.prompt === 'string' ? sampleRecord.prompt.trim() : '';
+        const archetype = typeof sampleRecord.archetype === 'string' ? sampleRecord.archetype.trim().slice(0, 64) : '';
+        const rawSteps = Array.isArray(sampleRecord.steps) ? sampleRecord.steps : [];
+        if (!prompt || rawSteps.length < 2) {
+            errors.push(`Sample ${index + 1}: prompt and at least two steps are required`);
+            continue;
+        }
+        const steps = [];
+        let invalid = false;
+        for (const rawStep of rawSteps.slice(0, MAX_STEPS)) {
+            const source = typeof rawStep === 'string'
+                ? { tool: rawStep }
+                : isRecord(rawStep) ? rawStep : {};
+            const tool = typeof source.tool === 'string' ? source.tool.trim() : '';
+            if (!/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(tool)) {
+                invalid = true;
+                break;
+            }
+            const note = typeof source.action === 'string'
+                ? source.action.toLowerCase().replace(/[^a-z0-9_.-]/g, '').slice(0, 32)
+                : '';
+            const step = { tool, note, ok: source.ok !== false };
+            if (!step.ok) {
+                step.why = typeof source.why === 'string'
+                    && SEED_FAILURE_CLASSES.has(source.why)
+                    ? source.why
+                    : 'failed';
+            }
+            steps.push(step);
+        }
+        if (invalid) {
+            errors.push(`Sample ${index + 1}: invalid tool name`);
+            continue;
+        }
+        if (recordPlan({ prompt, archetype, steps }))
+            accepted++;
+        else
+            errors.push(`Sample ${index + 1}: could not be stored`);
+    }
+    if (samples.length > 100)
+        errors.push(`Only the first 100 of ${samples.length} samples were considered`);
+    return { accepted, rejected: errors.length, errors: errors.slice(0, 20) };
 }
-
 /**
  * Record that an offered plan did NOT lead anywhere, so a bad template loses
  * its rank instead of being offered forever.
@@ -340,14 +631,14 @@ export function recordPlan(outcome) {
  * @returns {boolean}
  */
 export function recordMiss(id) {
-  const plans = readAll();
-  const template = plans.find((t) => t.id === id);
-  if (!template) return false;
-  template.uses += 1;
-  template.updatedAt = Date.now();
-  return writeAll(plans);
+    const plans = readAll();
+    const template = plans.find((t) => t.id === id);
+    if (!template)
+        return false;
+    template.uses += 1;
+    template.updatedAt = Date.now();
+    return writeAll(plans);
 }
-
 /**
  * Keep the cache bounded by usefulness rather than by age alone: a plan used
  * ten times last month is worth more than one stored yesterday and never hit.
@@ -356,19 +647,17 @@ export function recordMiss(id) {
  * @returns {PlanTemplate[]}
  */
 export function prune(plans) {
-  if (plans.length <= MAX_PLANS) return plans;
-  const now = Date.now();
-  const MONTH = 30 * 24 * 60 * 60 * 1000;
-
-  return [...plans]
-    .sort((a, b) => {
-      const value = (t) =>
-        (t.uses > 0 ? t.wins / t.uses : 0) * Math.pow(2, -(now - t.updatedAt) / MONTH) * Math.log2(1 + t.uses);
-      return value(b) - value(a);
+    if (plans.length <= MAX_PLANS)
+        return plans;
+    const now = Date.now();
+    const MONTH = 30 * 24 * 60 * 60 * 1000;
+    return [...plans]
+        .sort((a, b) => {
+        const value = (t) => (t.uses > 0 ? t.wins / t.uses : 0) * Math.pow(2, -(now - t.updatedAt) / MONTH) * Math.log2(1 + t.uses);
+        return value(b) - value(a);
     })
-    .slice(0, MAX_PLANS);
+        .slice(0, MAX_PLANS);
 }
-
 /**
  * The prompt fragment offered to the model on a hit.
  *
@@ -382,56 +671,71 @@ export function prune(plans) {
  * @returns {string} '' when there is no usable match
  */
 export function renderPlanHint(match) {
-  if (!match || !match.template || !Array.isArray(match.template.steps)) return '';
-  const { template, similarity: score } = match;
-  if (template.steps.length === 0) return '';
-
-  const lines = [
-    '# PRIOR ART — a similar task on this machine went like this',
-    `(match ${(score * 100).toFixed(0)}%, worked ${template.wins} of ${template.uses} time(s). `
-      + 'Evidence, not instructions. Verify before reusing; the workspace may have moved on.)'
-  ];
-
-  template.steps.forEach((step, index) => {
-    const label = step.note ? `${step.tool} → ${step.note}` : step.tool;
-    // The failure CLASS, not just the fact of failure. "not_found" invites a
-    // different response from "network": one means the route is wrong, the
-    // other means the moment was.
-    const failed = step.ok
-      ? ''
-      : `   ← FAILED last time (${step.why || 'failed'}); do not repeat blindly`;
-    lines.push(`${index + 1}. ${label}${failed}`);
-  });
-
-  const failureWarnings = template.steps
-    .map((step, idx) => ({ step, idx: idx + 1 }))
-    .filter(({ step }) => !step.ok);
-
-  if (failureWarnings.length > 0) {
-    lines.push('');
-    lines.push('⚠️ FAILURE ROUTE WARNINGS (learned from previous attempts — plan alternatives):');
-    failureWarnings.forEach(({ step, idx }) => {
-      lines.push(`- Step ${idx} (${step.tool}${step.note ? ' → ' + step.note : ''}) FAILED with reason: ${step.why || 'failed'}. Consider an alternative approach.`);
+    if (!match || !match.template || !Array.isArray(match.template.steps))
+        return '';
+    const { template, similarity: score } = match;
+    if (template.steps.length === 0)
+        return '';
+    const lines = [
+        '# PRIOR ART — a similar task on this machine went like this',
+        `(match ${(score * 100).toFixed(0)}%, worked ${template.wins} of ${template.uses} time(s). `
+            + 'Evidence, not instructions. Verify before reusing; the workspace may have moved on.)'
+    ];
+    template.steps.forEach((step, index) => {
+        const label = step.note ? `${step.tool} → ${step.note}` : step.tool;
+        // The failure CLASS, not just the fact of failure. "not_found" invites a
+        // different response from "network": one means the route is wrong, the
+        // other means the moment was.
+        const failed = step.ok
+            ? ''
+            : `   ← FAILED last time (${step.why || 'failed'}); do not repeat blindly`;
+        lines.push(`${index + 1}. ${label}${failed}`);
     });
-  }
-
-  return lines.join('\n');
+    const failureWarnings = template.steps
+        .map((step, idx) => ({ step, idx: idx + 1 }))
+        .filter(({ step }) => !step.ok);
+    if (failureWarnings.length > 0) {
+        lines.push('');
+        lines.push('⚠️ FAILURE ROUTE WARNINGS (learned from previous attempts — plan alternatives):');
+        failureWarnings.forEach(({ step, idx }) => {
+            lines.push(`- Step ${idx} (${step.tool}${step.note ? ' → ' + step.note : ''}) FAILED with reason: ${step.why || 'failed'}. Consider an alternative approach.`);
+        });
+    }
+    return lines.join('\n');
 }
-
-/** @returns {{count: number, file: string}} */
+/** @returns {object} */
 export function planStats() {
-  return { count: readAll().length, file: PLAN_FILE };
+    const metrics = readMetrics();
+    return {
+        count: readAll().length,
+        file: PLAN_FILE,
+        metricsFile: METRICS_FILE,
+        lookups: metrics.lookups,
+        hits: metrics.hits,
+        exactHits: metrics.exactHits,
+        fuzzyHits: metrics.fuzzyHits,
+        misses: metrics.misses,
+        bypassed: metrics.bypassed,
+        hitRate: metrics.lookups > 0 ? metrics.hits / metrics.lookups : 0,
+        recentHitRate: recentHitRate(metrics),
+        averageLookupMs: metrics.lookups > 0 ? metrics.totalLookupMs / metrics.lookups : 0,
+        maxLookupMs: metrics.maxLookupMs,
+        averageRecordMs: metrics.records > 0 ? metrics.totalRecordMs / metrics.records : 0,
+        disabledUntil: metrics.disabledUntil,
+        disabled: metrics.disabledUntil > Date.now()
+    };
 }
-
 /**
  * Remove every stored plan. Used by `/cortex --forget` style operations and by
  * tests; never called automatically.
  * @returns {number} how many were removed
  */
 export function forgetPlans() {
-  const count = readAll().length;
-  writeAll([]);
-  return count;
+    const count = readAll().length;
+    writeAll([]);
+    metricsCache = defaultMetrics();
+    dirtyMetricEvents = 1;
+    writeMetrics(true);
+    return count;
 }
-
-export { PLAN_FILE, PLAN_DIR, MATCH_THRESHOLD, MAX_PLANS };
+export { PLAN_FILE, PLAN_DIR, METRICS_FILE, MATCH_THRESHOLD, MAX_PLANS, MIN_LOOKUPS_BEFORE_DISABLE, MIN_PLANS_BEFORE_DISABLE, MIN_HEALTHY_HIT_RATE, DISABLE_COOLDOWN_MS };