agentsmesh 0.32.0 → 0.34.0

package/dist/lessons.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, renameSync, readdirSync, realpathSync, appendFileSync, statSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync, renameSync, readdirSync, realpathSync, appendFileSync } from 'fs';
 import { resolve, dirname, join, relative, sep, basename, extname } from 'path';
 import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
 import { createHash } from 'crypto';
@@ -280,6 +280,23 @@ function todayIso() {
 }
 
 // src/lessons/add-errors.ts
+var EmptyRuleError = class extends Error {
+  code = "EMPTY_RULE";
+  constructor() {
+    super("Lesson rule must not be empty \u2014 pass one imperative sentence.");
+    this.name = "EmptyRuleError";
+  }
+};
+var BroadCommandPatternError = class extends Error {
+  constructor(pattern) {
+    super(
+      `Command pattern ${JSON.stringify(pattern)} matches nearly every command, so it would fire on every recall. Key it on the action instead \u2014 a word-bounded program + subcommand (e.g. "\\bgit commit\\b", "\\brm\\b").`
+    );
+    this.pattern = pattern;
+    this.name = "BroadCommandPatternError";
+  }
+  code = "BROAD_COMMAND_PATTERN";
+};
 var UnknownTopicError = class extends Error {
   constructor(topic) {
     super(`Unknown topic: ${topic}. Pass allowNewTopic + topicSummary to create it.`);
@@ -319,992 +336,1144 @@ var UnrecallableLessonError = class extends Error {
   code = "UNRECALLABLE_LESSON";
 };
 
-// src/lessons/ranking-text.ts
-var K1 = 1.5;
-var B = 0.75;
-var STOP = /* @__PURE__ */ new Set([
-  "the",
-  "a",
-  "an",
-  "to",
-  "of",
-  "in",
-  "and",
-  "or",
-  "for",
-  "is",
-  "on",
-  "at",
-  "with",
-  "be",
-  "as",
-  "it",
-  "that",
-  "this",
-  "its",
-  "must"
-]);
-function tokenize(text) {
-  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2 && !STOP.has(t));
-}
-function queryTerms(query) {
-  const parts = [];
-  if (query.keyword !== void 0) parts.push(query.keyword);
-  if (query.file !== void 0) parts.push(query.file);
-  if (query.command !== void 0) parts.push(query.command);
-  return tokenize(parts.join(" "));
-}
-function buildCorpus(graph) {
-  const docs = [];
-  const df = /* @__PURE__ */ new Map();
-  let total = 0;
-  let n = 0;
-  for (const lesson of Object.values(graph.lessons)) {
-    if (lesson.status !== "active") continue;
-    const toks = tokenize(lesson.rule);
-    n += 1;
-    total += toks.length;
-    docs.push(toks.length);
-    for (const t of new Set(toks)) df.set(t, (df.get(t) ?? 0) + 1);
+// src/lessons/regex-linear/nfa-compile.ts
+var MAX_NFA_STATES = 2e3;
+var Builder = class {
+  states = [];
+  alloc() {
+    if (this.states.length >= MAX_NFA_STATES) {
+      throw new Error(`NFA state limit exceeded (${MAX_NFA_STATES}); pattern expands too large`);
+    }
+    this.states.push({ eps: [], asserts: [], chars: [] });
+    return this.states.length - 1;
   }
-  const N = Math.max(n, 1);
-  const idf = /* @__PURE__ */ new Map();
-  for (const [t, f] of df) idf.set(t, Math.log(1 + (N - f + 0.5) / (f + 0.5)));
-  return { idf, avgdl: total / N || 1 };
+};
+function isNonLineTerminator(c) {
+  return c !== "\n" && c !== "\r" && c !== "\u2028" && c !== "\u2029";
 }
-function bm25(terms, ruleText, corpus) {
-  const toks = tokenize(ruleText);
-  const dl = toks.length || 1;
-  const tf = /* @__PURE__ */ new Map();
-  for (const t of toks) tf.set(t, (tf.get(t) ?? 0) + 1);
-  let score = 0;
-  for (const t of new Set(terms)) {
-    const f = tf.get(t) ?? 0;
-    if (f === 0) continue;
-    const idf = corpus.idf.get(t);
-    score += idf * (f * (K1 + 1)) / (f + K1 * (1 - B + B * dl / corpus.avgdl));
+function compileNode(b, node) {
+  switch (node.k) {
+    case "empty":
+    case "assert": {
+      const s = b.alloc();
+      const e = b.alloc();
+      if (node.k === "assert") b.states[s].asserts.push({ kind: node.kind, target: e });
+      else b.states[s].eps.push(e);
+      return { start: s, end: e };
+    }
+    case "char":
+    case "any":
+    case "class": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const test = node.k === "char" ? (c) => c === node.ch : node.k === "any" ? isNonLineTerminator : node.test;
+      b.states[s].chars.push({ test, target: e });
+      return { start: s, end: e };
+    }
+    case "concat": {
+      if (node.items.length === 0) return compileNode(b, { k: "empty" });
+      let first = null;
+      let prevEnd = -1;
+      for (const item of node.items) {
+        const frag = compileNode(b, item);
+        if (first === null) first = frag;
+        else b.states[prevEnd].eps.push(frag.start);
+        prevEnd = frag.end;
+      }
+      return { start: first.start, end: prevEnd };
+    }
+    case "alt": {
+      const s = b.alloc();
+      const e = b.alloc();
+      for (const opt of node.opts) {
+        const frag = compileNode(b, opt);
+        b.states[s].eps.push(frag.start);
+        b.states[frag.end].eps.push(e);
+      }
+      return { start: s, end: e };
+    }
+    case "opt": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[s].eps.push(frag.start, e);
+      b.states[frag.end].eps.push(e);
+      return { start: s, end: e };
+    }
+    case "star": {
+      const s = b.alloc();
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[s].eps.push(frag.start, e);
+      b.states[frag.end].eps.push(frag.start, e);
+      return { start: s, end: e };
+    }
+    case "plus": {
+      const e = b.alloc();
+      const frag = compileNode(b, node.node);
+      b.states[frag.end].eps.push(frag.start, e);
+      return { start: frag.start, end: e };
+    }
   }
-  return score;
+}
+function compileNfa(ast) {
+  const b = new Builder();
+  const { start, end } = compileNode(b, ast);
+  return { states: b.states, start, accept: end };
 }
 
-// src/lessons/keyword-signal.ts
-var MAX_RECOMMENDED_KEYWORD_TOKENS = 5;
-function isLowSignalKeyword(pattern) {
-  return tokenize(pattern).length > MAX_RECOMMENDED_KEYWORD_TOKENS;
+// src/lessons/regex-linear/nfa.ts
+function wordBoundary(input, pos) {
+  const before = pos > 0 && /[A-Za-z0-9_]/.test(input[pos - 1]);
+  const after = pos < input.length && /[A-Za-z0-9_]/.test(input[pos]);
+  return before !== after;
 }
-function splitRawTokens(pattern) {
-  return pattern.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+function assertHolds(kind, input, pos) {
+  switch (kind) {
+    case "start":
+      return pos === 0;
+    case "end":
+      return pos === input.length;
+    case "wordB":
+      return wordBoundary(input, pos);
+    case "nonWordB":
+      return !wordBoundary(input, pos);
+  }
 }
-function keywordNeedleLosesTokens(pattern) {
-  const raw = splitRawTokens(pattern);
-  if (raw.length < 2) return false;
-  return tokenize(pattern).length !== raw.length;
+function buildMatcher(ast) {
+  const { states, start, accept } = compileNfa(ast);
+  const closure = (set, idx, input, pos, budget) => {
+    const stack = [idx];
+    while (stack.length > 0) {
+      if (budget.remaining <= 0) return;
+      const cur = stack.pop();
+      if (set.has(cur)) continue;
+      set.add(cur);
+      budget.remaining -= 1;
+      for (const t of states[cur].eps) if (!set.has(t)) stack.push(t);
+      for (const a of states[cur].asserts) {
+        if (assertHolds(a.kind, input, pos) && !set.has(a.target)) stack.push(a.target);
+      }
+    }
+  };
+  return {
+    // The input is matched in full (no truncation — truncation would miss suffix
+    // matches and let `$` falsely match an invented endpoint). Work is bounded by
+    // the shared budget instead: when it runs out we report a safe non-match.
+    test(input, budget) {
+      const b = budget ?? { remaining: Number.POSITIVE_INFINITY };
+      if (b.remaining <= 0) return false;
+      let current = /* @__PURE__ */ new Set();
+      for (let pos = 0; pos <= input.length; pos += 1) {
+        closure(current, start, input, pos, b);
+        if (current.has(accept)) return true;
+        if (b.remaining <= 0) return false;
+        if (pos === input.length) break;
+        const ch = input[pos];
+        const next = /* @__PURE__ */ new Set();
+        for (const s of current) {
+          b.remaining -= 1;
+          for (const t of states[s].chars) {
+            if (t.test(ch)) closure(next, t.target, input, pos + 1, b);
+          }
+        }
+        current = next;
+      }
+      return current.has(accept);
+    }
+  };
 }
-function activeTriggerIds(graph) {
-  const ids = /* @__PURE__ */ new Set();
-  for (const lesson of Object.values(graph.lessons)) {
-    if (lesson.status !== "active") continue;
-    for (const t of lesson.triggers) ids.add(t);
+
+// src/lessons/regex-linear/ast.ts
+var UnsupportedRegexError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnsupportedRegexError";
   }
-  return ids;
-}
-function deadFileGlobIds(graph, knownPaths) {
-  const active = activeTriggerIds(graph);
-  const paths = [...knownPaths];
-  const dead = /* @__PURE__ */ new Set();
-  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
-    if (trigger.kind !== "file_glob") continue;
-    if (!active.has(triggerId)) continue;
-    const isMatch = picomatch(trigger.pattern, { dot: true });
-    if (!paths.some((p) => isMatch(p))) dead.add(triggerId);
+};
+
+// src/lessons/regex-linear/parse-helpers.ts
+var MAX_REPEAT = 1e3;
+var isWord = (c) => /[A-Za-z0-9_]/.test(c);
+function expandRepeat(atom, min, max) {
+  const items = [];
+  for (let k = 0; k < min; k += 1) items.push(atom);
+  if (max === Infinity) {
+    items.push({ k: "star", node: atom });
+  } else {
+    for (let k = min; k < max; k += 1) items.push({ k: "opt", node: atom });
   }
-  return dead;
+  if (items.length === 0) return { k: "empty" };
+  return items.length === 1 ? items[0] : { k: "concat", items };
 }
-function collectDeadFileGlobs(graph, findings, knownPaths) {
-  for (const triggerId of deadFileGlobIds(graph, knownPaths)) {
-    findings.push({
-      level: "warning",
-      code: "DEAD_FILE_GLOB",
-      message: `file_glob trigger "${triggerId}" (${graph.triggers[triggerId]?.pattern ?? ""}) matches no file in the working tree \u2014 the lesson is unreachable via this trigger (a rename likely moved the path). Re-point it at the current path, or detach it with \`lessons untrigger\`, or run \`lessons prune --apply\`.`,
-      triggerId
-    });
+function escapeClass(c) {
+  switch (c) {
+    case "d":
+      return (x) => x >= "0" && x <= "9";
+    case "D":
+      return (x) => !(x >= "0" && x <= "9");
+    case "w":
+      return isWord;
+    case "W":
+      return (x) => !isWord(x);
+    case "s":
+      return (x) => /\s/.test(x);
+    case "S":
+      return (x) => !/\s/.test(x);
+    default:
+      return null;
   }
 }
-function fileGlobMatchCount(pattern, knownPaths) {
-  const isMatch = picomatch(pattern, { dot: true });
-  let n = 0;
-  for (const p of knownPaths) if (isMatch(p)) n += 1;
-  return n;
+var HEX2 = /^[0-9a-fA-F]{2}$/;
+var HEX4 = /^[0-9a-fA-F]{4}$/;
+function readUnicodeEscape(src, i, c) {
+  if (c === "x") {
+    const hex2 = src.slice(i, i + 2);
+    return HEX2.test(hex2) ? { ch: String.fromCharCode(parseInt(hex2, 16)), len: 2 } : { ch: "x", len: 0 };
+  }
+  const hex = src.slice(i, i + 4);
+  return HEX4.test(hex) ? { ch: String.fromCharCode(parseInt(hex, 16)), len: 4 } : { ch: "u", len: 0 };
 }
-var RUNNER_ANCHOR = /^\^(pnpm|npm|npx|yarn|bun)\b/;
-function collectRunnerAnchoredPatterns(graph, findings) {
-  const active = activeTriggerIds(graph);
-  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
-    if (trigger.kind !== "command_pattern") continue;
-    if (!active.has(triggerId)) continue;
-    if (!RUNNER_ANCHOR.test(trigger.pattern)) continue;
-    findings.push({
-      level: "warning",
-      code: "RUNNER_ANCHORED_PATTERN",
-      message: `command_pattern trigger "${triggerId}" (${trigger.pattern}) is anchored to one runner \u2014 it won't fire for the same task via another runner (e.g. \`npx\` vs \`pnpm\`). Drop the \`^<runner>\` anchor and key on the task (e.g. \`\\bvitest\\b\`).`,
-      triggerId
-    });
+function readControlEscape(src, i) {
+  const x = src[i];
+  if (x === void 0 || !/[A-Za-z]/.test(x)) {
+    throw new UnsupportedRegexError("\\c must be followed by a letter");
   }
+  return { ch: String.fromCharCode(x.charCodeAt(0) & 31), len: 1 };
 }
-
-// src/lessons/capture-guardrails.ts
-var WIDE_GLOB_MATCH_COUNT = 40;
-var MAX_RECOMMENDED_TRIGGERS = 8;
-function isBroadGlob(pattern) {
-  const p = pattern.trim();
-  if (p === "*" || p === "**") return true;
-  if (!p.includes("**")) return false;
-  const basename5 = p.slice(p.lastIndexOf("/") + 1);
-  return basename5.startsWith("*");
+function classEscapeChar(src, i, e) {
+  if (e === "b") return { ch: "\b", len: 0 };
+  if (e === "c") return readControlEscape(src, i);
+  if (e === "x" || e === "u") return readUnicodeEscape(src, i, e);
+  return { ch: escapeLiteral(e), len: 0 };
 }
-function inspectCapturedLesson(graph, lessonId, knownPaths) {
-  const lesson = graph.lessons[lessonId];
-  if (lesson === void 0) return [];
-  const warnings = [];
-  if (lesson.triggers.length > MAX_RECOMMENDED_TRIGGERS) {
-    warnings.push({
-      code: "OVERSIZED_LESSON_TRIGGERS",
-      message: `Lesson "${lessonId}" has ${lesson.triggers.length} triggers (recommended \u2264 ${MAX_RECOMMENDED_TRIGGERS}); broad trigger sets fire on too many edits and dilute recall \u2014 prefer a few specific triggers.`
-    });
+function escapeLiteral(c) {
+  switch (c) {
+    case "t":
+      return "	";
+    case "n":
+      return "\n";
+    case "r":
+      return "\r";
+    case "f":
+      return "\f";
+    case "v":
+      return "\v";
+    case "0":
+      return "\0";
+    default:
+      return c;
   }
-  const triggers = lesson.triggers.map((id) => graph.triggers[id]).filter((t) => t !== void 0);
-  const broad = triggers.filter((t) => t.kind === "file_glob" && isBroadGlob(t.pattern)).map((t) => t.pattern);
-  if (broad.length > 0) {
-    warnings.push({
-      code: "BROAD_GLOB_TRIGGER",
-      message: `Lesson "${lessonId}" has broad file glob(s) (${broad.join(", ")}) that match large swaths of the tree; prefer a path specific to the lesson.`
-    });
+}
+
+// src/lessons/regex-linear/parse.ts
+function parseRegex(src) {
+  let i = 0;
+  const peek = () => src[i];
+  const eat = () => src[i++];
+  function parseAlt() {
+    const opts = [parseConcat()];
+    while (peek() === "|") {
+      i += 1;
+      opts.push(parseConcat());
+    }
+    return opts.length === 1 ? opts[0] : { k: "alt", opts };
   }
-  if (triggers.length > 0 && triggers.every((t) => t.kind === "keyword")) {
-    warnings.push({
-      code: "KEYWORD_ONLY_LESSON",
-      message: `Lesson "${lessonId}" has only keyword triggers; mandatory --file/--cmd recall surfaces these only when the keyword appears as a path/command token, so it fires less reliably \u2014 add a file_glob or command_pattern trigger for precise recall.`
-    });
+  function parseConcat() {
+    const items = [];
+    while (i < src.length && peek() !== "|" && peek() !== ")") {
+      items.push(parseQuantified());
+    }
+    if (items.length === 0) return { k: "empty" };
+    return items.length === 1 ? items[0] : { k: "concat", items };
   }
-  const lowSignal = triggers.filter((t) => t.kind === "keyword" && isLowSignalKeyword(t.pattern)).map((t) => t.pattern);
-  if (lowSignal.length > 0) {
-    warnings.push({
-      code: "LOW_SIGNAL_KEYWORD",
-      message: `Lesson "${lessonId}" has long keyword trigger(s) (${lowSignal.join(", ")}); recall matches a keyword only as a substring of --keyword or a contiguous token-run in the file/command, so a pattern past ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens rarely fires \u2014 use a short distinctive phrase.`
-    });
+  function parseQuantified() {
+    const atom = parseAtom();
+    const q = peek();
+    if (q === "*" || q === "+" || q === "?") {
+      i += 1;
+      if (peek() === "?") i += 1;
+      return q === "*" ? { k: "star", node: atom } : q === "+" ? { k: "plus", node: atom } : { k: "opt", node: atom };
+    }
+    if (q === "{") {
+      const repeat = tryParseBrace();
+      if (repeat !== null) return expandRepeat(atom, repeat.min, repeat.max);
+    }
+    return atom;
   }
-  const stopworded = triggers.filter((t) => t.kind === "keyword" && keywordNeedleLosesTokens(t.pattern)).map((t) => t.pattern);
-  if (stopworded.length > 0) {
-    warnings.push({
-      code: "STOPWORD_KEYWORD",
-      message: `Lesson "${lessonId}" has keyword trigger(s) containing stopwords/short words (${stopworded.join(", ")}); recall filters them from the pattern but NOT from the file/command text, so the phrase can never match contiguously on the --file/--cmd path \u2014 drop the stopwords (e.g. "state art" instead of "state of the art").`
-    });
+  function tryParseBrace() {
+    const m = /^\{(\d+)(,(\d*)?)?\}/.exec(src.slice(i));
+    if (m === null) return null;
+    i += m[0].length;
+    if (peek() === "?") i += 1;
+    const min = Number(m[1]);
+    const max = m[2] === void 0 ? min : m[3] === "" || m[3] === void 0 ? Infinity : Number(m[3]);
+    if (min > MAX_REPEAT || max !== Infinity && max > MAX_REPEAT) {
+      throw new UnsupportedRegexError(`Repeat count over ${MAX_REPEAT} not supported: {${m[1]}\u2026}`);
+    }
+    return { min, max };
   }
-  if (knownPaths !== void 0) {
-    const dead = deadFileGlobIds(graph, knownPaths);
-    const deadHere = lesson.triggers.filter((id) => dead.has(id)).map((id) => graph.triggers[id]?.pattern).filter((p) => p !== void 0);
-    if (deadHere.length > 0) {
-      warnings.push({
-        code: "DEAD_GLOB",
-        message: `Lesson "${lessonId}" has file_glob trigger(s) (${deadHere.join(", ")}) that match no file in the working tree \u2014 likely a rename. Re-point them at the current path, or the lesson is unreachable via those globs.`
-      });
+  function parseAtom() {
+    const c = peek();
+    if (c === "(") return parseGroup();
+    if (c === "[") return parseClass();
+    if (c === "\\") return parseEscape();
+    if (c === ".") {
+      i += 1;
+      return { k: "any" };
     }
-    const wide = triggers.filter((t) => t.kind === "file_glob" && !isBroadGlob(t.pattern)).filter((t) => fileGlobMatchCount(t.pattern, knownPaths) > WIDE_GLOB_MATCH_COUNT).map((t) => t.pattern);
-    if (wide.length > 0) {
-      warnings.push({
-        code: "WIDE_GLOB_MATCH",
-        message: `Lesson "${lessonId}" has file glob(s) (${wide.join(", ")}) matching more than ${WIDE_GLOB_MATCH_COUNT} files in the working tree; narrow to the file-CLASS where the rule actually applies so it does not fire on unrelated edits.`
-      });
+    if (c === "^") {
+      i += 1;
+      return { k: "assert", kind: "start" };
     }
-  }
-  return warnings;
-}
-
-// src/lessons/capture-near-duplicate.ts
-var NEAR_DUPLICATE_THRESHOLD = 0.6;
-function nearDuplicateWarning(graph, lessonId) {
-  const subject = graph.lessons[lessonId];
-  if (subject === void 0) return null;
-  const subjectTokens = new Set(tokenize(subject.rule));
-  if (subjectTokens.size === 0) return null;
-  let best = null;
-  for (const [id, other] of Object.entries(graph.lessons)) {
-    if (id === lessonId || other.status !== "active") continue;
-    const otherTokens = new Set(tokenize(other.rule));
-    if (otherTokens.size === 0) continue;
-    const score = jaccard(subjectTokens, otherTokens);
-    if (score >= NEAR_DUPLICATE_THRESHOLD && (best === null || score > best.score)) {
-      best = { id, score };
+    if (c === "$") {
+      i += 1;
+      return { k: "assert", kind: "end" };
+    }
+    if (c === void 0 || c === "*" || c === "+" || c === "?" || c === ")") {
+      throw new UnsupportedRegexError(`Unexpected '${c ?? "<end>"}' in pattern`);
     }
+    i += 1;
+    return { k: "char", ch: c };
   }
-  if (best === null) return null;
-  return {
-    code: "NEAR_DUPLICATE_LESSON",
-    message: `Lesson "${lessonId}" closely resembles active lesson "${best.id}" (~${Math.round(best.score * 100)}% token overlap); consider updating "${best.id}" instead of adding a paraphrase (recall would surface both).`
-  };
-}
-function jaccard(a, b) {
-  let intersection = 0;
-  for (const t of a) if (b.has(t)) intersection += 1;
-  return intersection / (a.size + b.size - intersection);
-}
-
-// src/core/errors.ts
-var AgentsMeshError = class extends Error {
-  code;
-  constructor(code, message, options) {
-    super(message, options);
-    this.name = "AgentsMeshError";
-    this.code = code;
+  function parseGroup() {
+    i += 1;
+    if (peek() === "?") {
+      const c2 = src[i + 1];
+      if (c2 === "=" || c2 === "!" || c2 === "<") {
+        if (!(c2 === "<" && /[A-Za-z]/.test(src[i + 2] ?? ""))) {
+          throw new UnsupportedRegexError("Lookaround assertions are not supported");
+        }
+      }
+      if (c2 === ":") i += 2;
+      else if (c2 === "<") {
+        i += 2;
+        while (i < src.length && src[i] !== ">") i += 1;
+        i += 1;
+      }
+    }
+    const inner = parseAlt();
+    if (peek() !== ")") throw new UnsupportedRegexError("Unbalanced group");
+    i += 1;
+    return inner;
   }
-};
-var LockAcquisitionError = class extends AgentsMeshError {
-  lockPath;
-  holder;
-  /** Human-readable lock name surfaced in the message, e.g. "lessons lock". */
-  label;
-  constructor(lockPath, holder, options) {
-    const label = options?.label ?? "lock";
-    super(
-      "AM_LOCK_ACQUISITION_FAILED",
-      `Could not acquire ${label} at ${lockPath}: currently held by ${holder}. Wait for the other process to finish, or remove ${lockPath} manually if you are sure no agentsmesh process is running.`,
-      options
-    );
-    this.name = "LockAcquisitionError";
-    this.lockPath = lockPath;
-    this.holder = holder;
-    this.label = label;
+  function parseEscape() {
+    i += 1;
+    const c = peek();
+    if (c === void 0) throw new UnsupportedRegexError("Trailing backslash");
+    if (/[1-9]/.test(c) || c === "k")
+      throw new UnsupportedRegexError("Backreferences are not supported");
+    i += 1;
+    if (c === "b") return { k: "assert", kind: "wordB" };
+    if (c === "B") return { k: "assert", kind: "nonWordB" };
+    const cls = escapeClass(c);
+    if (cls !== null) return { k: "class", test: cls };
+    if (c === "x" || c === "u" || c === "c") {
+      const { ch, len } = c === "c" ? readControlEscape(src, i) : readUnicodeEscape(src, i, c);
+      i += len;
+      return { k: "char", ch };
+    }
+    return { k: "char", ch: escapeLiteral(c) };
   }
-};
-var FileSystemError = class extends AgentsMeshError {
-  path;
-  errnoCode;
-  constructor(path, message, options) {
-    super("AM_FILESYSTEM", message, options);
-    this.name = "FileSystemError";
-    this.path = path;
-    this.errnoCode = options?.errnoCode;
+  function parseClass() {
+    i += 1;
+    const negate = peek() === "^";
+    if (negate) i += 1;
+    const tests = [];
+    while (i < src.length && peek() !== "]") {
+      tests.push(parseClassMember());
+    }
+    if (peek() !== "]") throw new UnsupportedRegexError("Unterminated character class");
+    i += 1;
+    const base = (c) => tests.some((t) => t(c));
+    return { k: "class", test: negate ? (c) => !base(c) : base };
   }
-};
-
-// src/utils/filesystem/process-lock.ts
-var DEFAULT_STALE_MS = 6e4;
-var DEFAULT_RETRIES = 30;
-var DEFAULT_RETRY_DELAY_MS = 200;
-var YOUNG_LOCK_GRACE_MS = 2e3;
-async function acquireProcessLock(lockPath, opts = {}) {
-  const retries = opts.retries ?? DEFAULT_RETRIES;
-  const delay = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
-  const stale = opts.staleMs ?? DEFAULT_STALE_MS;
-  await mkdir(dirname(lockPath), { recursive: true });
-  let attempt = 0;
-  while (true) {
-    const acquired = await tryAcquire(lockPath);
-    if (acquired) return acquired;
-    const existing = await inspectLock(lockPath);
-    if (existing !== "young" && isStale(existing, stale)) {
-      await rm(lockPath, { recursive: true, force: true }).catch(() => {
-      });
-      continue;
+  function parseClassMember() {
+    let lo;
+    if (peek() === "\\") {
+      i += 1;
+      const e = eat();
+      const cls = escapeClass(e);
+      if (cls !== null) return cls;
+      const r = classEscapeChar(src, i, e);
+      i += r.len;
+      lo = r.ch;
+    } else {
+      lo = eat();
     }
-    if (attempt >= retries) {
-      const holder = existing === "young" ? null : existing;
-      throw new LockAcquisitionError(lockPath, describeHolder(holder), { label: opts.label });
+    if (peek() === "-" && src[i + 1] !== void 0 && src[i + 1] !== "]") {
+      i += 1;
+      let hi;
+      if (peek() === "\\") {
+        i += 1;
+        const e2 = eat();
+        const r = classEscapeChar(src, i, e2);
+        i += r.len;
+        hi = r.ch;
+      } else {
+        hi = eat();
+      }
+      const a = lo.codePointAt(0);
+      const b = hi.codePointAt(0);
+      return (c) => {
+        const p = c.codePointAt(0);
+        return p >= a && p <= b;
+      };
     }
-    attempt++;
-    await sleep(delay);
-  }
-}
-async function tryAcquire(lockPath) {
-  try {
-    await mkdir(lockPath, { recursive: false });
-  } catch (err) {
-    if (err.code === "EEXIST") return null;
-    throw err;
+    return (c) => c === lo;
   }
-  const metadataPath = join(lockPath, "holder.json");
-  const metadata = {
-    pid: process.pid,
-    started: Date.now(),
-    hostname: getHostname()
-  };
-  await writeFile(metadataPath, JSON.stringify(metadata), "utf-8");
-  let released = false;
-  const cleanup = () => {
-    if (released) return;
-    released = true;
-    try {
-      rmSync(lockPath, { recursive: true, force: true });
-    } catch {
-    }
-  };
-  const signalHandler = (signal) => {
-    cleanup();
-    process.kill(process.pid, signal);
-  };
-  process.once("SIGINT", signalHandler);
-  process.once("SIGTERM", signalHandler);
-  process.once("exit", cleanup);
-  return async () => {
-    if (released) return;
-    released = true;
-    process.off("SIGINT", signalHandler);
-    process.off("SIGTERM", signalHandler);
-    process.off("exit", cleanup);
-    await rm(lockPath, { recursive: true, force: true }).catch(() => {
-    });
-  };
+  const ast = parseAlt();
+  if (i !== src.length) throw new UnsupportedRegexError(`Unexpected '${peek()}' at ${i}`);
+  return ast;
 }
-async function inspectLock(lockPath) {
+
+// src/lessons/regex-linear/index.ts
+var cache = /* @__PURE__ */ new Map();
+function compileLinearMatcher(pattern) {
+  const hit = cache.get(pattern);
+  if (hit !== void 0 || cache.has(pattern)) return hit ?? null;
+  let matcher;
   try {
-    const raw = await readFile(join(lockPath, "holder.json"), "utf-8");
-    const parsed = JSON.parse(raw);
-    if (!isLockMetadata(parsed)) return null;
-    return parsed;
+    matcher = buildMatcher(parseRegex(pattern));
   } catch {
-    try {
-      const info = await stat(lockPath);
-      const ageMs = Date.now() - info.mtimeMs;
-      if (ageMs < YOUNG_LOCK_GRACE_MS) return "young";
-    } catch {
-    }
-    return null;
+    matcher = null;
   }
+  cache.set(pattern, matcher);
+  return matcher;
 }
-function isStale(meta, staleMs) {
-  if (!meta) return true;
-  const age = Date.now() - meta.started;
-  if (age > staleMs) return true;
-  if (meta.hostname && meta.hostname !== getHostname()) return false;
-  return !isProcessAlive(meta.pid);
+
+// src/lessons/regex-safety.ts
+var MAX_PATTERN_LENGTH = 1e3;
+function isSafeRegexPattern(pattern) {
+  if (pattern.length > MAX_PATTERN_LENGTH) return false;
+  return compileLinearMatcher(pattern) !== null;
 }
-function isProcessAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === "EPERM";
+function getCommandMatcher(pattern) {
+  if (pattern.length > MAX_PATTERN_LENGTH) return null;
+  return compileLinearMatcher(pattern);
+}
+
+// src/lessons/command-pattern-breadth.ts
+var COMMAND_PROBE_CORPUS = [
+  "git status",
+  'git commit -m "wip"',
+  "pnpm test",
+  "npx vitest run src/x.test.ts",
+  "ls -la",
+  "cat README.md",
+  "rm -rf dist",
+  "mkdir -p build/out",
+  "node scripts/build.js",
+  "docker compose up -d",
+  "curl -s https://example.com",
+  "echo hello > out.txt",
+  "sed -i 's/a/b/' file.txt",
+  "pnpm lint --fix",
+  "python3 -m pytest",
+  "cargo build --release",
+  "make",
+  "npm install --global typescript",
+  "cp a.txt b.txt",
+  "grep -rn TODO src"
+];
+var BROAD_HIT_RATIO = 0.5;
+var PROBE_BUDGET = 1e5;
+function isBroadCommandPattern(pattern) {
+  const matcher = getCommandMatcher(pattern);
+  if (matcher === null) return false;
+  if (matcher.test("", { remaining: PROBE_BUDGET })) return true;
+  let hits = 0;
+  for (const command of COMMAND_PROBE_CORPUS) {
+    if (matcher.test(command, { remaining: PROBE_BUDGET })) hits += 1;
   }
+  return hits > COMMAND_PROBE_CORPUS.length * BROAD_HIT_RATIO;
 }
-function describeHolder(meta) {
-  if (!meta) return "unknown (unreadable lock metadata)";
-  const host = meta.hostname ? `${meta.hostname}:` : "";
-  return `${host}pid ${meta.pid} (running ${Date.now() - meta.started}ms)`;
+
+// src/lessons/ranking-text.ts
+var K1 = 1.5;
+var B = 0.75;
+var STOP = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "to",
+  "of",
+  "in",
+  "and",
+  "or",
+  "for",
+  "is",
+  "on",
+  "at",
+  "with",
+  "be",
+  "as",
+  "it",
+  "that",
+  "this",
+  "its",
+  "must"
+]);
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2 && !STOP.has(t));
 }
-function isLockMetadata(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value;
-  return typeof v.pid === "number" && typeof v.started === "number";
+function queryTerms(query) {
+  const parts = [];
+  if (query.keyword !== void 0) parts.push(query.keyword);
+  if (query.file !== void 0) parts.push(query.file);
+  if (query.command !== void 0) parts.push(query.command);
+  return tokenize(parts.join(" "));
 }
-function getHostname() {
-  return hostname();
+function buildCorpus(graph) {
+  const docs = [];
+  const df = /* @__PURE__ */ new Map();
+  let total = 0;
+  let n = 0;
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    const toks = tokenize(lesson.rule);
+    n += 1;
+    total += toks.length;
+    docs.push(toks.length);
+    for (const t of new Set(toks)) df.set(t, (df.get(t) ?? 0) + 1);
+  }
+  const N = Math.max(n, 1);
+  const idf = /* @__PURE__ */ new Map();
+  for (const [t, f] of df) idf.set(t, Math.log(1 + (N - f + 0.5) / (f + 0.5)));
+  return { idf, avgdl: total / N || 1 };
 }
-function sleep(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+function bm25(terms, ruleText, corpus) {
+  const toks = tokenize(ruleText);
+  const dl = toks.length || 1;
+  const tf = /* @__PURE__ */ new Map();
+  for (const t of toks) tf.set(t, (tf.get(t) ?? 0) + 1);
+  let score = 0;
+  for (const t of new Set(terms)) {
+    const f = tf.get(t) ?? 0;
+    if (f === 0) continue;
+    const idf = corpus.idf.get(t);
+    score += idf * (f * (K1 + 1)) / (f + K1 * (1 - B + B * dl / corpus.avgdl));
+  }
+  return score;
 }
 
-// src/lessons/lessons-lock.ts
-var LESSONS_LOCK_FILENAME = ".lessons.lock";
-function lessonsLockPath(projectRoot) {
-  return resolve(projectRoot, ".agentsmesh/lessons", LESSONS_LOCK_FILENAME);
+// src/lessons/keyword-signal.ts
+var MAX_RECOMMENDED_KEYWORD_TOKENS = 5;
+function isLowSignalKeyword(pattern) {
+  return tokenize(pattern).length > MAX_RECOMMENDED_KEYWORD_TOKENS;
 }
-async function acquireLessonsLock(projectRoot, opts = {}) {
-  const lockPath = lessonsLockPath(projectRoot);
-  await mkdir(dirname(lockPath), { recursive: true });
-  return acquireProcessLock(lockPath, { ...opts, label: "lessons lock" });
+function splitRawTokens(pattern) {
+  return pattern.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+}
+function keywordNeedleLosesTokens(pattern) {
+  const raw = splitRawTokens(pattern);
+  if (raw.length < 2) return false;
+  return tokenize(pattern).length !== raw.length;
 }
 
-// src/lessons/validate-checks.ts
-function collectDanglingRefs(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    for (const topicId of lesson.topics) {
-      if (graph.topics[topicId] === void 0) {
-        findings.push({
-          level: "error",
-          code: "DANGLING_TOPIC",
-          message: `Lesson "${lessonId}" references unknown topic "${topicId}".`,
-          lessonId,
-          topicId
-        });
-      }
-    }
-    for (const triggerId of lesson.triggers) {
-      if (graph.triggers[triggerId] === void 0) {
-        findings.push({
-          level: "error",
-          code: "DANGLING_TRIGGER",
-          message: `Lesson "${lessonId}" references unknown trigger "${triggerId}".`,
-          lessonId,
-          triggerId
-        });
-      }
-    }
-    if (lesson.supersededBy !== void 0 && graph.lessons[lesson.supersededBy] === void 0) {
-      findings.push({
-        level: "error",
-        code: "DANGLING_SUPERSEDER",
-        message: `Lesson "${lessonId}" supersededBy unknown lesson "${lesson.supersededBy}".`,
-        lessonId
-      });
+// src/lessons/trigger-effectiveness.ts
+function ineffectiveTriggers(graph, triggerIds) {
+  const out = [];
+  for (const id of triggerIds) {
+    const trigger = graph.triggers[id];
+    if (trigger === void 0) continue;
+    const reason = ineffectiveReason(trigger.kind, trigger.pattern);
+    if (reason !== null) out.push({ id, kind: trigger.kind, pattern: trigger.pattern, reason });
+  }
+  return out;
+}
+function ineffectiveReason(kind, pattern) {
+  if (kind === "keyword") {
+    if (tokenize(pattern).length === 0) {
+      return "keyword has no matchable token after stopword filtering \u2014 it cannot fire on the mandatory --file/--cmd recall path";
+    }
+    if (keywordNeedleLosesTokens(pattern)) {
+      return "keyword contains stopwords/short words, so its needle can never appear as a contiguous run on the mandatory --file/--cmd recall path";
     }
+    return null;
   }
-}
-function collectDuplicateRefs(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    for (const topicId of firstDuplicates(lesson.topics)) {
-      findings.push({
-        level: "error",
-        code: "DUPLICATE_TOPIC_REF",
-        message: `Lesson "${lessonId}" references topic "${topicId}" more than once.`,
-        lessonId,
-        topicId
-      });
+  if (kind === "command_pattern") {
+    let valid = true;
+    try {
+      new RegExp(pattern);
+    } catch {
+      valid = false;
     }
-    for (const triggerId of firstDuplicates(lesson.triggers)) {
-      findings.push({
-        level: "error",
-        code: "DUPLICATE_TRIGGER_REF",
-        message: `Lesson "${lessonId}" references trigger "${triggerId}" more than once.`,
-        lessonId,
-        triggerId
-      });
+    if (!valid) {
+      return "invalid regex \u2014 recall compiles it with new RegExp and swallows the throw as a non-match, so it never fires";
+    }
+    if (!isSafeRegexPattern(pattern)) {
+      return "regex is outside the provably-linear engine \u2014 recall skips it (ReDoS guard), so it never fires";
     }
+    return null;
   }
+  return null;
 }
-function firstDuplicates(ids) {
-  const seen = /* @__PURE__ */ new Set();
-  const dup = /* @__PURE__ */ new Set();
-  for (const id of ids) {
-    if (seen.has(id)) dup.add(id);
-    else seen.add(id);
+function blockingDeadTriggers(graph, triggerIds) {
+  return ineffectiveTriggers(graph, triggerIds).filter((t) => t.kind !== "command_pattern");
+}
+
+// src/lessons/add-gates.ts
+function assertRuleShape(rule) {
+  const trimmed = rule.trim();
+  if (trimmed.length === 0) throw new EmptyRuleError();
+  if (trimmed.length > MAX_RULE_LENGTH) throw new RuleTooLongError(trimmed.length, MAX_RULE_LENGTH);
+  return trimmed;
+}
+function skipsTriggerGates(input, options) {
+  return options.allowNoTrigger === true || input.scope === "always";
+}
+function countInputTriggers(triggers) {
+  return (triggers.files?.length ?? 0) + (triggers.commands?.length ?? 0) + (triggers.keywords?.length ?? 0);
+}
+function assertTriggerInputs(input, options, existingTriggerCount) {
+  if (!skipsTriggerGates(input, options) && countInputTriggers(input.triggers) === 0 && existingTriggerCount === 0) {
+    throw new NoTriggerError();
+  }
+  if (options.allowNoTrigger !== true) {
+    const broad = (input.triggers.commands ?? []).find(isBroadCommandPattern);
+    if (broad !== void 0) throw new BroadCommandPatternError(broad);
   }
-  return [...dup];
 }
-function collectStatusInvariants(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.status === "superseded" && lesson.supersededBy === void 0) {
-      findings.push({
-        level: "error",
-        code: "SUPERSEDED_WITHOUT_TARGET",
-        message: `Lesson "${lessonId}" has status "superseded" but no supersededBy target.`,
-        lessonId
-      });
-    }
-    if (lesson.status === "active" && lesson.supersededBy !== void 0) {
-      findings.push({
-        level: "error",
-        code: "ACTIVE_WITH_SUPERSEDER",
-        message: `Lesson "${lessonId}" has status "active" but declares supersededBy.`,
-        lessonId
-      });
-    }
+function assertRecallable(graph, resultingTriggers) {
+  const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
+  if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
+    throw new UnrecallableLessonError(blockingDead);
   }
 }
-function collectLifecycleInvariants(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.supersededBy === void 0) continue;
-    if (lesson.supersededBy === lessonId) {
-      findings.push({
-        level: "error",
-        code: "SELF_SUPERSEDED",
-        message: `Lesson "${lessonId}" is superseded by itself.`,
-        lessonId
-      });
-      continue;
-    }
-    const target = graph.lessons[lesson.supersededBy];
-    if (target !== void 0 && target.status !== "active") {
-      findings.push({
-        level: "error",
-        code: "INACTIVE_SUPERSEDER",
-        message: `Lesson "${lessonId}" is superseded by "${lesson.supersededBy}", which is itself ${target.status} \u2014 the chain dead-ends with no live replacement.`,
-        lessonId
-      });
-    }
+
+// src/lessons/glob-breadth.ts
+var WILDCARD = /[*?[\]]/;
+function globNarrowness(pattern) {
+  const segments = pattern.replaceAll("\\", "/").split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (segments.length === 0) return 0;
+  let literal = 0;
+  let globstars = 0;
+  for (const segment of segments) {
+    if (segment === "**") globstars += 1;
+    else if (!WILDCARD.test(segment)) literal += 1;
   }
-  collectSupersedeCycles(graph, findings);
+  return literal / (segments.length + globstars);
 }
-function collectSupersedeCycles(graph, findings) {
-  const reported = /* @__PURE__ */ new Set();
-  for (const startId of Object.keys(graph.lessons)) {
-    const seen = /* @__PURE__ */ new Set();
-    let cur = startId;
-    while (cur !== void 0) {
-      if (seen.has(cur)) {
-        if (cur !== startId || reported.has(cur)) break;
-        reported.add(cur);
-        findings.push({
-          level: "error",
-          code: "SUPERSEDE_CYCLE",
-          message: `Lesson "${startId}" is part of a supersededBy cycle.`,
-          lessonId: startId
-        });
-        break;
-      }
-      seen.add(cur);
-      const next = graph.lessons[cur]?.supersededBy;
-      if (next === cur) break;
-      cur = next;
-    }
+var BROAD_GLOB_NARROWNESS = 0.34;
+function isBroadFileGlob(pattern) {
+  return globNarrowness(pattern) < BROAD_GLOB_NARROWNESS;
+}
+function activeTriggerIds(graph) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    for (const t of lesson.triggers) ids.add(t);
   }
+  return ids;
 }
-function collectReachability(graph, findings) {
-  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.status === "active" && lesson.triggers.length === 0) {
-      findings.push({
-        level: "warning",
-        code: "UNREACHABLE_LESSON",
-        message: `Active lesson "${lessonId}" has no triggers and can never be recalled.`,
-        lessonId
-      });
-    }
+function deadFileGlobIds(graph, knownPaths) {
+  const active = activeTriggerIds(graph);
+  const paths = [...knownPaths];
+  const dead = /* @__PURE__ */ new Set();
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "file_glob") continue;
+    if (!active.has(triggerId)) continue;
+    const isMatch = picomatch(trigger.pattern, { dot: true });
+    if (!paths.some((p) => isMatch(p))) dead.add(triggerId);
   }
+  return dead;
 }
-function collectOrphans(graph, findings) {
-  const referencedTopics = /* @__PURE__ */ new Set();
-  const referencedTriggers = /* @__PURE__ */ new Set();
-  for (const lesson of Object.values(graph.lessons)) {
-    for (const t of lesson.topics) referencedTopics.add(t);
-    for (const t of lesson.triggers) referencedTriggers.add(t);
+function collectDeadFileGlobs(graph, findings, knownPaths) {
+  for (const triggerId of deadFileGlobIds(graph, knownPaths)) {
+    findings.push({
+      level: "warning",
+      code: "DEAD_FILE_GLOB",
+      message: `file_glob trigger "${triggerId}" (${graph.triggers[triggerId]?.pattern ?? ""}) matches no file in the working tree \u2014 the lesson is unreachable via this trigger (a rename likely moved the path). Re-point it at the current path, or detach it with \`lessons untrigger\`, or run \`lessons prune --apply\`.`,
+      triggerId
+    });
   }
-  for (const topicId of Object.keys(graph.topics)) {
-    if (!referencedTopics.has(topicId)) {
-      findings.push({
-        level: "warning",
-        code: "ORPHAN_TOPIC",
-        message: `Topic "${topicId}" is not referenced by any lesson.`,
-        topicId
+}
+function fileGlobMatchCount(pattern, knownPaths) {
+  const isMatch = picomatch(pattern, { dot: true });
+  let n = 0;
+  for (const p of knownPaths) if (isMatch(p)) n += 1;
+  return n;
+}
+var RUNNER_ANCHOR = /^\^(pnpm|npm|npx|yarn|bun)\b/;
+function collectRunnerAnchoredPatterns(graph, findings) {
+  const active = activeTriggerIds(graph);
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "command_pattern") continue;
+    if (!active.has(triggerId)) continue;
+    if (!RUNNER_ANCHOR.test(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "RUNNER_ANCHORED_PATTERN",
+      message: `command_pattern trigger "${triggerId}" (${trigger.pattern}) is anchored to one runner \u2014 it won't fire for the same task via another runner (e.g. \`npx\` vs \`pnpm\`). Drop the \`^<runner>\` anchor and key on the task (e.g. \`\\bvitest\\b\`).`,
+      triggerId
+    });
+  }
+}
+function collectBroadFileGlobs(graph, findings) {
+  const active = activeTriggerIds(graph);
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "file_glob") continue;
+    if (!active.has(triggerId)) continue;
+    if (!isBroadFileGlob(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "BROAD_FILE_GLOB",
+      message: `file_glob trigger "${triggerId}" (${trigger.pattern}) matches most of the repository, so it outranks nothing and crowds the recall budget. Narrow it to the directory or file class the rule is really about, or detach it with \`lessons untrigger\`.`,
+      triggerId
+    });
+  }
+}
+function collectBroadCommandPatterns(graph, findings) {
+  const active = activeTriggerIds(graph);
+  for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind !== "command_pattern") continue;
+    if (!active.has(triggerId)) continue;
+    if (!isBroadCommandPattern(trigger.pattern)) continue;
+    findings.push({
+      level: "warning",
+      code: "BROAD_COMMAND_PATTERN",
+      message: `command_pattern trigger "${triggerId}" (${trigger.pattern}) matches nearly every command, so the lesson fires on every recall. Key it on the action (e.g. \`\\bgit commit\\b\`), or detach it with \`lessons untrigger\`.`,
+      triggerId
+    });
+  }
+}
+
+// src/lessons/capture-guardrails.ts
+var WIDE_GLOB_MATCH_COUNT = 40;
+var MAX_RECOMMENDED_TRIGGERS = 8;
+function isBroadGlob(pattern) {
+  const p = pattern.trim();
+  if (p === "*" || p === "**") return true;
+  if (!p.includes("**")) return false;
+  const basename5 = p.slice(p.lastIndexOf("/") + 1);
+  return basename5.startsWith("*");
+}
+function inspectCapturedLesson(graph, lessonId, knownPaths) {
+  const lesson = graph.lessons[lessonId];
+  if (lesson === void 0) return [];
+  const warnings = [];
+  if (lesson.triggers.length > MAX_RECOMMENDED_TRIGGERS) {
+    warnings.push({
+      code: "OVERSIZED_LESSON_TRIGGERS",
+      message: `Lesson "${lessonId}" has ${lesson.triggers.length} triggers (recommended \u2264 ${MAX_RECOMMENDED_TRIGGERS}); broad trigger sets fire on too many edits and dilute recall \u2014 prefer a few specific triggers.`
+    });
+  }
+  const triggers = lesson.triggers.map((id) => graph.triggers[id]).filter((t) => t !== void 0);
+  const broad = triggers.filter((t) => t.kind === "file_glob" && isBroadGlob(t.pattern)).map((t) => t.pattern);
+  if (broad.length > 0) {
+    warnings.push({
+      code: "BROAD_GLOB_TRIGGER",
+      message: `Lesson "${lessonId}" has broad file glob(s) (${broad.join(", ")}) that match large swaths of the tree; prefer a path specific to the lesson.`
+    });
+  }
+  if (triggers.length > 0 && triggers.every((t) => t.kind === "keyword")) {
+    warnings.push({
+      code: "KEYWORD_ONLY_LESSON",
+      message: `Lesson "${lessonId}" has only keyword triggers; mandatory --file/--cmd recall surfaces these only when the keyword appears as a path/command token, so it fires less reliably \u2014 add a file_glob or command_pattern trigger for precise recall.`
+    });
+  }
+  const lowSignal = triggers.filter((t) => t.kind === "keyword" && isLowSignalKeyword(t.pattern)).map((t) => t.pattern);
+  if (lowSignal.length > 0) {
+    warnings.push({
+      code: "LOW_SIGNAL_KEYWORD",
+      message: `Lesson "${lessonId}" has long keyword trigger(s) (${lowSignal.join(", ")}); recall matches a keyword only as a contiguous token-run in --keyword or the file/command, so a pattern past ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens rarely fires \u2014 use a short distinctive phrase.`
+    });
+  }
+  const stopworded = triggers.filter((t) => t.kind === "keyword" && keywordNeedleLosesTokens(t.pattern)).map((t) => t.pattern);
+  if (stopworded.length > 0) {
+    warnings.push({
+      code: "STOPWORD_KEYWORD",
+      message: `Lesson "${lessonId}" has keyword trigger(s) containing stopwords/short words (${stopworded.join(", ")}); recall filters them from the pattern but NOT from the file/command text, so the phrase can never match contiguously on the --file/--cmd path \u2014 drop the stopwords (e.g. "state art" instead of "state of the art").`
+    });
+  }
+  if (knownPaths !== void 0) {
+    const dead = deadFileGlobIds(graph, knownPaths);
+    const deadHere = lesson.triggers.filter((id) => dead.has(id)).map((id) => graph.triggers[id]?.pattern).filter((p) => p !== void 0);
+    if (deadHere.length > 0) {
+      warnings.push({
+        code: "DEAD_GLOB",
+        message: `Lesson "${lessonId}" has file_glob trigger(s) (${deadHere.join(", ")}) that match no file in the working tree \u2014 likely a rename. Re-point them at the current path, or the lesson is unreachable via those globs.`
       });
     }
-  }
-  for (const triggerId of Object.keys(graph.triggers)) {
-    if (!referencedTriggers.has(triggerId)) {
-      findings.push({
-        level: "warning",
-        code: "ORPHAN_TRIGGER",
-        message: `Trigger "${triggerId}" is not referenced by any lesson.`,
-        triggerId
+    const wide = triggers.filter((t) => t.kind === "file_glob" && !isBroadGlob(t.pattern)).filter((t) => fileGlobMatchCount(t.pattern, knownPaths) > WIDE_GLOB_MATCH_COUNT).map((t) => t.pattern);
+    if (wide.length > 0) {
+      warnings.push({
+        code: "WIDE_GLOB_MATCH",
+        message: `Lesson "${lessonId}" has file glob(s) (${wide.join(", ")}) matching more than ${WIDE_GLOB_MATCH_COUNT} files in the working tree; narrow to the file-CLASS where the rule actually applies so it does not fire on unrelated edits.`
       });
     }
   }
+  return warnings;
 }
 
-// src/lessons/regex-linear/nfa-compile.ts
-var MAX_NFA_STATES = 2e3;
-var Builder = class {
-  states = [];
-  alloc() {
-    if (this.states.length >= MAX_NFA_STATES) {
-      throw new Error(`NFA state limit exceeded (${MAX_NFA_STATES}); pattern expands too large`);
+// src/lessons/capture-near-duplicate.ts
+var NEAR_DUPLICATE_THRESHOLD = 0.6;
+function nearDuplicateWarning(graph, lessonId) {
+  const subject = graph.lessons[lessonId];
+  if (subject === void 0) return null;
+  const subjectTokens = new Set(tokenize(subject.rule));
+  if (subjectTokens.size === 0) return null;
+  let best = null;
+  for (const [id, other] of Object.entries(graph.lessons)) {
+    if (id === lessonId || other.status !== "active") continue;
+    const otherTokens = new Set(tokenize(other.rule));
+    if (otherTokens.size === 0) continue;
+    const score = jaccard(subjectTokens, otherTokens);
+    if (score >= NEAR_DUPLICATE_THRESHOLD && (best === null || score > best.score)) {
+      best = { id, score };
     }
-    this.states.push({ eps: [], asserts: [], chars: [] });
-    return this.states.length - 1;
   }
-};
-function isNonLineTerminator(c) {
-  return c !== "\n" && c !== "\r" && c !== "\u2028" && c !== "\u2029";
+  if (best === null) return null;
+  return {
+    code: "NEAR_DUPLICATE_LESSON",
+    message: `Lesson "${lessonId}" closely resembles active lesson "${best.id}" (~${Math.round(best.score * 100)}% token overlap); consider updating "${best.id}" instead of adding a paraphrase (recall would surface both).`
+  };
 }
-function compileNode(b, node) {
-  switch (node.k) {
-    case "empty":
-    case "assert": {
-      const s = b.alloc();
-      const e = b.alloc();
-      if (node.k === "assert") b.states[s].asserts.push({ kind: node.kind, target: e });
-      else b.states[s].eps.push(e);
-      return { start: s, end: e };
-    }
-    case "char":
-    case "any":
-    case "class": {
-      const s = b.alloc();
-      const e = b.alloc();
-      const test = node.k === "char" ? (c) => c === node.ch : node.k === "any" ? isNonLineTerminator : node.test;
-      b.states[s].chars.push({ test, target: e });
-      return { start: s, end: e };
-    }
-    case "concat": {
-      if (node.items.length === 0) return compileNode(b, { k: "empty" });
-      let first = null;
-      let prevEnd = -1;
-      for (const item of node.items) {
-        const frag = compileNode(b, item);
-        if (first === null) first = frag;
-        else b.states[prevEnd].eps.push(frag.start);
-        prevEnd = frag.end;
-      }
-      return { start: first.start, end: prevEnd };
-    }
-    case "alt": {
-      const s = b.alloc();
-      const e = b.alloc();
-      for (const opt of node.opts) {
-        const frag = compileNode(b, opt);
-        b.states[s].eps.push(frag.start);
-        b.states[frag.end].eps.push(e);
-      }
-      return { start: s, end: e };
-    }
-    case "opt": {
-      const s = b.alloc();
-      const e = b.alloc();
-      const frag = compileNode(b, node.node);
-      b.states[s].eps.push(frag.start, e);
-      b.states[frag.end].eps.push(e);
-      return { start: s, end: e };
-    }
-    case "star": {
-      const s = b.alloc();
-      const e = b.alloc();
-      const frag = compileNode(b, node.node);
-      b.states[s].eps.push(frag.start, e);
-      b.states[frag.end].eps.push(frag.start, e);
-      return { start: s, end: e };
+function jaccard(a, b) {
+  let intersection = 0;
+  for (const t of a) if (b.has(t)) intersection += 1;
+  return intersection / (a.size + b.size - intersection);
+}
+
+// src/core/errors.ts
+var AgentsMeshError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "AgentsMeshError";
+    this.code = code;
+  }
+};
+var LockAcquisitionError = class extends AgentsMeshError {
+  lockPath;
+  holder;
+  /** Human-readable lock name surfaced in the message, e.g. "lessons lock". */
+  label;
+  constructor(lockPath, holder, options) {
+    const label = options?.label ?? "lock";
+    super(
+      "AM_LOCK_ACQUISITION_FAILED",
+      `Could not acquire ${label} at ${lockPath}: currently held by ${holder}. Wait for the other process to finish, or remove ${lockPath} manually if you are sure no agentsmesh process is running.`,
+      options
+    );
+    this.name = "LockAcquisitionError";
+    this.lockPath = lockPath;
+    this.holder = holder;
+    this.label = label;
+  }
+};
+var FileSystemError = class extends AgentsMeshError {
+  path;
+  errnoCode;
+  constructor(path, message, options) {
+    super("AM_FILESYSTEM", message, options);
+    this.name = "FileSystemError";
+    this.path = path;
+    this.errnoCode = options?.errnoCode;
+  }
+};
+
+// src/utils/filesystem/process-lock.ts
+var DEFAULT_STALE_MS = 6 * 60 * 60 * 1e3;
+var DEFAULT_RETRIES = 30;
+var DEFAULT_RETRY_DELAY_MS = 200;
+var YOUNG_LOCK_GRACE_MS = 2e3;
+async function acquireProcessLock(lockPath, opts = {}) {
+  const retries = opts.retries ?? DEFAULT_RETRIES;
+  const delay = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  const stale = opts.staleMs ?? DEFAULT_STALE_MS;
+  await mkdir(dirname(lockPath), { recursive: true });
+  let attempt = 0;
+  while (true) {
+    const acquired = await tryAcquire(lockPath);
+    if (acquired) return acquired;
+    const existing = await inspectLock(lockPath);
+    if (existing !== "young" && isStale(existing, stale)) {
+      await rm(lockPath, { recursive: true, force: true }).catch(() => {
+      });
+      continue;
     }
-    case "plus": {
-      const e = b.alloc();
-      const frag = compileNode(b, node.node);
-      b.states[frag.end].eps.push(frag.start, e);
-      return { start: frag.start, end: e };
+    if (attempt >= retries) {
+      const holder = existing === "young" ? null : existing;
+      throw new LockAcquisitionError(lockPath, describeHolder(holder), { label: opts.label });
     }
+    attempt++;
+    await sleep(delay);
   }
 }
-function compileNfa(ast) {
-  const b = new Builder();
-  const { start, end } = compileNode(b, ast);
-  return { states: b.states, start, accept: end };
-}
-
-// src/lessons/regex-linear/nfa.ts
-function wordBoundary(input, pos) {
-  const before = pos > 0 && /[A-Za-z0-9_]/.test(input[pos - 1]);
-  const after = pos < input.length && /[A-Za-z0-9_]/.test(input[pos]);
-  return before !== after;
-}
-function assertHolds(kind, input, pos) {
-  switch (kind) {
-    case "start":
-      return pos === 0;
-    case "end":
-      return pos === input.length;
-    case "wordB":
-      return wordBoundary(input, pos);
-    case "nonWordB":
-      return !wordBoundary(input, pos);
+async function tryAcquire(lockPath) {
+  try {
+    await mkdir(lockPath, { recursive: false });
+  } catch (err) {
+    if (err.code === "EEXIST") return null;
+    throw err;
   }
-}
-function buildMatcher(ast) {
-  const { states, start, accept } = compileNfa(ast);
-  const closure = (set, idx, input, pos, budget) => {
-    const stack = [idx];
-    while (stack.length > 0) {
-      if (budget.remaining <= 0) return;
-      const cur = stack.pop();
-      if (set.has(cur)) continue;
-      set.add(cur);
-      budget.remaining -= 1;
-      for (const t of states[cur].eps) if (!set.has(t)) stack.push(t);
-      for (const a of states[cur].asserts) {
-        if (assertHolds(a.kind, input, pos) && !set.has(a.target)) stack.push(a.target);
-      }
-    }
+  const metadataPath = join(lockPath, "holder.json");
+  const metadata = {
+    pid: process.pid,
+    started: Date.now(),
+    hostname: getHostname()
   };
-  return {
-    // The input is matched in full (no truncation — truncation would miss suffix
-    // matches and let `$` falsely match an invented endpoint). Work is bounded by
-    // the shared budget instead: when it runs out we report a safe non-match.
-    test(input, budget) {
-      const b = budget ?? { remaining: Number.POSITIVE_INFINITY };
-      if (b.remaining <= 0) return false;
-      let current = /* @__PURE__ */ new Set();
-      for (let pos = 0; pos <= input.length; pos += 1) {
-        closure(current, start, input, pos, b);
-        if (current.has(accept)) return true;
-        if (b.remaining <= 0) return false;
-        if (pos === input.length) break;
-        const ch = input[pos];
-        const next = /* @__PURE__ */ new Set();
-        for (const s of current) {
-          b.remaining -= 1;
-          for (const t of states[s].chars) {
-            if (t.test(ch)) closure(next, t.target, input, pos + 1, b);
-          }
-        }
-        current = next;
-      }
-      return current.has(accept);
+  await writeFile(metadataPath, JSON.stringify(metadata), "utf-8");
+  let released = false;
+  const cleanup = () => {
+    if (released) return;
+    released = true;
+    try {
+      rmSync(lockPath, { recursive: true, force: true });
+    } catch {
     }
   };
+  const signalHandler = (signal) => {
+    cleanup();
+    process.kill(process.pid, signal);
+  };
+  process.once("SIGINT", signalHandler);
+  process.once("SIGTERM", signalHandler);
+  process.once("exit", cleanup);
+  return async () => {
+    if (released) return;
+    released = true;
+    process.off("SIGINT", signalHandler);
+    process.off("SIGTERM", signalHandler);
+    process.off("exit", cleanup);
+    await rm(lockPath, { recursive: true, force: true }).catch(() => {
+    });
+  };
 }
-
-// src/lessons/regex-linear/ast.ts
-var UnsupportedRegexError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "UnsupportedRegexError";
-  }
-};
-
-// src/lessons/regex-linear/parse-helpers.ts
-var MAX_REPEAT = 1e3;
-var isWord = (c) => /[A-Za-z0-9_]/.test(c);
-function expandRepeat(atom, min, max) {
-  const items = [];
-  for (let k = 0; k < min; k += 1) items.push(atom);
-  if (max === Infinity) {
-    items.push({ k: "star", node: atom });
-  } else {
-    for (let k = min; k < max; k += 1) items.push({ k: "opt", node: atom });
+async function inspectLock(lockPath) {
+  try {
+    const raw = await readFile(join(lockPath, "holder.json"), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!isLockMetadata(parsed)) return null;
+    return parsed;
+  } catch {
+    try {
+      const info = await stat(lockPath);
+      const ageMs = Date.now() - info.mtimeMs;
+      if (ageMs < YOUNG_LOCK_GRACE_MS) return "young";
+    } catch {
+    }
+    return null;
   }
-  if (items.length === 0) return { k: "empty" };
-  return items.length === 1 ? items[0] : { k: "concat", items };
 }
-function escapeClass(c) {
-  switch (c) {
-    case "d":
-      return (x) => x >= "0" && x <= "9";
-    case "D":
-      return (x) => !(x >= "0" && x <= "9");
-    case "w":
-      return isWord;
-    case "W":
-      return (x) => !isWord(x);
-    case "s":
-      return (x) => /\s/.test(x);
-    case "S":
-      return (x) => !/\s/.test(x);
-    default:
-      return null;
-  }
+function isStale(meta, staleMs) {
+  if (!meta) return true;
+  const sameHost = !meta.hostname || meta.hostname === getHostname();
+  if (sameHost && !isProcessAlive(meta.pid)) return true;
+  return Date.now() - meta.started > staleMs;
 }
-var HEX2 = /^[0-9a-fA-F]{2}$/;
-var HEX4 = /^[0-9a-fA-F]{4}$/;
-function readUnicodeEscape(src, i, c) {
-  if (c === "x") {
-    const hex2 = src.slice(i, i + 2);
-    return HEX2.test(hex2) ? { ch: String.fromCharCode(parseInt(hex2, 16)), len: 2 } : { ch: "x", len: 0 };
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
   }
-  const hex = src.slice(i, i + 4);
-  return HEX4.test(hex) ? { ch: String.fromCharCode(parseInt(hex, 16)), len: 4 } : { ch: "u", len: 0 };
 }
-function readControlEscape(src, i) {
-  const x = src[i];
-  if (x === void 0 || !/[A-Za-z]/.test(x)) {
-    throw new UnsupportedRegexError("\\c must be followed by a letter");
-  }
-  return { ch: String.fromCharCode(x.charCodeAt(0) & 31), len: 1 };
+function describeHolder(meta) {
+  if (!meta) return "unknown (unreadable lock metadata)";
+  const host = meta.hostname ? `${meta.hostname}:` : "";
+  return `${host}pid ${meta.pid} (running ${Date.now() - meta.started}ms)`;
 }
-function classEscapeChar(src, i, e) {
-  if (e === "b") return { ch: "\b", len: 0 };
-  if (e === "c") return readControlEscape(src, i);
-  if (e === "x" || e === "u") return readUnicodeEscape(src, i, e);
-  return { ch: escapeLiteral(e), len: 0 };
+function isLockMetadata(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.pid === "number" && typeof v.started === "number";
 }
-function escapeLiteral(c) {
-  switch (c) {
-    case "t":
-      return "	";
-    case "n":
-      return "\n";
-    case "r":
-      return "\r";
-    case "f":
-      return "\f";
-    case "v":
-      return "\v";
-    case "0":
-      return "\0";
-    default:
-      return c;
-  }
+function getHostname() {
+  return hostname();
+}
+function sleep(ms) {
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 
-// src/lessons/regex-linear/parse.ts
-function parseRegex(src) {
-  let i = 0;
-  const peek = () => src[i];
-  const eat = () => src[i++];
-  function parseAlt() {
-    const opts = [parseConcat()];
-    while (peek() === "|") {
-      i += 1;
-      opts.push(parseConcat());
+// src/lessons/lessons-lock.ts
+var LESSONS_LOCK_FILENAME = ".lessons.lock";
+function lessonsLockPath(projectRoot) {
+  return resolve(projectRoot, ".agentsmesh/lessons", LESSONS_LOCK_FILENAME);
+}
+async function acquireLessonsLock(projectRoot, opts = {}) {
+  const lockPath = lessonsLockPath(projectRoot);
+  await mkdir(dirname(lockPath), { recursive: true });
+  return acquireProcessLock(lockPath, { ...opts, label: "lessons lock" });
+}
+
+// src/lessons/validate-checks.ts
+function collectDanglingRefs(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    for (const topicId of lesson.topics) {
+      if (graph.topics[topicId] === void 0) {
+        findings.push({
+          level: "error",
+          code: "DANGLING_TOPIC",
+          message: `Lesson "${lessonId}" references unknown topic "${topicId}".`,
+          lessonId,
+          topicId
+        });
+      }
     }
-    return opts.length === 1 ? opts[0] : { k: "alt", opts };
-  }
-  function parseConcat() {
-    const items = [];
-    while (i < src.length && peek() !== "|" && peek() !== ")") {
-      items.push(parseQuantified());
+    for (const triggerId of lesson.triggers) {
+      if (graph.triggers[triggerId] === void 0) {
+        findings.push({
+          level: "error",
+          code: "DANGLING_TRIGGER",
+          message: `Lesson "${lessonId}" references unknown trigger "${triggerId}".`,
+          lessonId,
+          triggerId
+        });
+      }
+    }
+    if (lesson.supersededBy !== void 0 && graph.lessons[lesson.supersededBy] === void 0) {
+      findings.push({
+        level: "error",
+        code: "DANGLING_SUPERSEDER",
+        message: `Lesson "${lessonId}" supersededBy unknown lesson "${lesson.supersededBy}".`,
+        lessonId
+      });
     }
-    if (items.length === 0) return { k: "empty" };
-    return items.length === 1 ? items[0] : { k: "concat", items };
   }
-  function parseQuantified() {
-    const atom = parseAtom();
-    const q = peek();
-    if (q === "*" || q === "+" || q === "?") {
-      i += 1;
-      if (peek() === "?") i += 1;
-      return q === "*" ? { k: "star", node: atom } : q === "+" ? { k: "plus", node: atom } : { k: "opt", node: atom };
+}
+function collectDuplicateRefs(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    for (const topicId of firstDuplicates(lesson.topics)) {
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_TOPIC_REF",
+        message: `Lesson "${lessonId}" references topic "${topicId}" more than once.`,
+        lessonId,
+        topicId
+      });
     }
-    if (q === "{") {
-      const repeat = tryParseBrace();
-      if (repeat !== null) return expandRepeat(atom, repeat.min, repeat.max);
+    for (const triggerId of firstDuplicates(lesson.triggers)) {
+      findings.push({
+        level: "error",
+        code: "DUPLICATE_TRIGGER_REF",
+        message: `Lesson "${lessonId}" references trigger "${triggerId}" more than once.`,
+        lessonId,
+        triggerId
+      });
     }
-    return atom;
   }
-  function tryParseBrace() {
-    const m = /^\{(\d+)(,(\d*)?)?\}/.exec(src.slice(i));
-    if (m === null) return null;
-    i += m[0].length;
-    if (peek() === "?") i += 1;
-    const min = Number(m[1]);
-    const max = m[2] === void 0 ? min : m[3] === "" || m[3] === void 0 ? Infinity : Number(m[3]);
-    if (min > MAX_REPEAT || max !== Infinity && max > MAX_REPEAT) {
-      throw new UnsupportedRegexError(`Repeat count over ${MAX_REPEAT} not supported: {${m[1]}\u2026}`);
-    }
-    return { min, max };
+}
+function firstDuplicates(ids) {
+  const seen = /* @__PURE__ */ new Set();
+  const dup = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    if (seen.has(id)) dup.add(id);
+    else seen.add(id);
   }
-  function parseAtom() {
-    const c = peek();
-    if (c === "(") return parseGroup();
-    if (c === "[") return parseClass();
-    if (c === "\\") return parseEscape();
-    if (c === ".") {
-      i += 1;
-      return { k: "any" };
+  return [...dup];
+}
+function collectStatusInvariants(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status === "superseded" && lesson.supersededBy === void 0) {
+      findings.push({
+        level: "error",
+        code: "SUPERSEDED_WITHOUT_TARGET",
+        message: `Lesson "${lessonId}" has status "superseded" but no supersededBy target.`,
+        lessonId
+      });
     }
-    if (c === "^") {
-      i += 1;
-      return { k: "assert", kind: "start" };
+    if (lesson.status === "active" && lesson.supersededBy !== void 0) {
+      findings.push({
+        level: "error",
+        code: "ACTIVE_WITH_SUPERSEDER",
+        message: `Lesson "${lessonId}" has status "active" but declares supersededBy.`,
+        lessonId
+      });
     }
-    if (c === "$") {
-      i += 1;
-      return { k: "assert", kind: "end" };
+  }
+}
+function collectLifecycleInvariants(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.supersededBy === void 0) continue;
+    if (lesson.supersededBy === lessonId) {
+      findings.push({
+        level: "error",
+        code: "SELF_SUPERSEDED",
+        message: `Lesson "${lessonId}" is superseded by itself.`,
+        lessonId
+      });
+      continue;
     }
-    if (c === void 0 || c === "*" || c === "+" || c === "?" || c === ")") {
-      throw new UnsupportedRegexError(`Unexpected '${c ?? "<end>"}' in pattern`);
+    const target = graph.lessons[lesson.supersededBy];
+    if (target !== void 0 && target.status !== "active") {
+      findings.push({
+        level: "error",
+        code: "INACTIVE_SUPERSEDER",
+        message: `Lesson "${lessonId}" is superseded by "${lesson.supersededBy}", which is itself ${target.status} \u2014 the chain dead-ends with no live replacement.`,
+        lessonId
+      });
     }
-    i += 1;
-    return { k: "char", ch: c };
   }
-  function parseGroup() {
-    i += 1;
-    if (peek() === "?") {
-      const c2 = src[i + 1];
-      if (c2 === "=" || c2 === "!" || c2 === "<") {
-        if (!(c2 === "<" && /[A-Za-z]/.test(src[i + 2] ?? ""))) {
-          throw new UnsupportedRegexError("Lookaround assertions are not supported");
-        }
-      }
-      if (c2 === ":") i += 2;
-      else if (c2 === "<") {
-        i += 2;
-        while (i < src.length && src[i] !== ">") i += 1;
-        i += 1;
+  collectSupersedeCycles(graph, findings);
+}
+function collectSupersedeCycles(graph, findings) {
+  const reported = /* @__PURE__ */ new Set();
+  for (const startId of Object.keys(graph.lessons)) {
+    const seen = /* @__PURE__ */ new Set();
+    let cur = startId;
+    while (cur !== void 0) {
+      if (seen.has(cur)) {
+        if (cur !== startId || reported.has(cur)) break;
+        reported.add(cur);
+        findings.push({
+          level: "error",
+          code: "SUPERSEDE_CYCLE",
+          message: `Lesson "${startId}" is part of a supersededBy cycle.`,
+          lessonId: startId
+        });
+        break;
       }
+      seen.add(cur);
+      const next = graph.lessons[cur]?.supersededBy;
+      if (next === cur) break;
+      cur = next;
     }
-    const inner = parseAlt();
-    if (peek() !== ")") throw new UnsupportedRegexError("Unbalanced group");
-    i += 1;
-    return inner;
   }
-  function parseEscape() {
-    i += 1;
-    const c = peek();
-    if (c === void 0) throw new UnsupportedRegexError("Trailing backslash");
-    if (/[1-9]/.test(c) || c === "k")
-      throw new UnsupportedRegexError("Backreferences are not supported");
-    i += 1;
-    if (c === "b") return { k: "assert", kind: "wordB" };
-    if (c === "B") return { k: "assert", kind: "nonWordB" };
-    const cls = escapeClass(c);
-    if (cls !== null) return { k: "class", test: cls };
-    if (c === "x" || c === "u" || c === "c") {
-      const { ch, len } = c === "c" ? readControlEscape(src, i) : readUnicodeEscape(src, i, c);
-      i += len;
-      return { k: "char", ch };
+}
+function collectReachability(graph, findings) {
+  for (const [lessonId, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status === "active" && lesson.triggers.length === 0) {
+      findings.push({
+        level: "warning",
+        code: "UNREACHABLE_LESSON",
+        message: `Active lesson "${lessonId}" has no triggers and can never be recalled.`,
+        lessonId
+      });
     }
-    return { k: "char", ch: escapeLiteral(c) };
   }
-  function parseClass() {
-    i += 1;
-    const negate = peek() === "^";
-    if (negate) i += 1;
-    const tests = [];
-    while (i < src.length && peek() !== "]") {
-      tests.push(parseClassMember());
-    }
-    if (peek() !== "]") throw new UnsupportedRegexError("Unterminated character class");
-    i += 1;
-    const base = (c) => tests.some((t) => t(c));
-    return { k: "class", test: negate ? (c) => !base(c) : base };
+}
+function collectOrphans(graph, findings) {
+  const referencedTopics = /* @__PURE__ */ new Set();
+  const referencedTriggers = /* @__PURE__ */ new Set();
+  for (const lesson of Object.values(graph.lessons)) {
+    for (const t of lesson.topics) referencedTopics.add(t);
+    for (const t of lesson.triggers) referencedTriggers.add(t);
   }
-  function parseClassMember() {
-    let lo;
-    if (peek() === "\\") {
-      i += 1;
-      const e = eat();
-      const cls = escapeClass(e);
-      if (cls !== null) return cls;
-      const r = classEscapeChar(src, i, e);
-      i += r.len;
-      lo = r.ch;
-    } else {
-      lo = eat();
-    }
-    if (peek() === "-" && src[i + 1] !== void 0 && src[i + 1] !== "]") {
-      i += 1;
-      let hi;
-      if (peek() === "\\") {
-        i += 1;
-        const e2 = eat();
-        const r = classEscapeChar(src, i, e2);
-        i += r.len;
-        hi = r.ch;
-      } else {
-        hi = eat();
-      }
-      const a = lo.codePointAt(0);
-      const b = hi.codePointAt(0);
-      return (c) => {
-        const p = c.codePointAt(0);
-        return p >= a && p <= b;
-      };
+  for (const topicId of Object.keys(graph.topics)) {
+    if (!referencedTopics.has(topicId)) {
+      findings.push({
+        level: "warning",
+        code: "ORPHAN_TOPIC",
+        message: `Topic "${topicId}" is not referenced by any lesson.`,
+        topicId
+      });
     }
-    return (c) => c === lo;
   }
-  const ast = parseAlt();
-  if (i !== src.length) throw new UnsupportedRegexError(`Unexpected '${peek()}' at ${i}`);
-  return ast;
-}
-
-// src/lessons/regex-linear/index.ts
-var cache = /* @__PURE__ */ new Map();
-function compileLinearMatcher(pattern) {
-  const hit = cache.get(pattern);
-  if (hit !== void 0 || cache.has(pattern)) return hit ?? null;
-  let matcher;
-  try {
-    matcher = buildMatcher(parseRegex(pattern));
-  } catch {
-    matcher = null;
+  for (const triggerId of Object.keys(graph.triggers)) {
+    if (!referencedTriggers.has(triggerId)) {
+      findings.push({
+        level: "warning",
+        code: "ORPHAN_TRIGGER",
+        message: `Trigger "${triggerId}" is not referenced by any lesson.`,
+        triggerId
+      });
+    }
   }
-  cache.set(pattern, matcher);
-  return matcher;
-}
-
-// src/lessons/regex-safety.ts
-var MAX_PATTERN_LENGTH = 1e3;
-function isSafeRegexPattern(pattern) {
-  if (pattern.length > MAX_PATTERN_LENGTH) return false;
-  return compileLinearMatcher(pattern) !== null;
-}
-function getCommandMatcher(pattern) {
-  if (pattern.length > MAX_PATTERN_LENGTH) return null;
-  return compileLinearMatcher(pattern);
 }
 
 // src/lessons/validate-quality.ts
@@ -1410,6 +1579,11 @@ function collectFanout(graph, findings) {
     });
   }
 }
+function normalizeRule2(rule) {
+  return rule.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+// src/lessons/validate-keywords.ts
 function collectLowSignalKeywords(graph, findings) {
   const activeTriggerIds2 = /* @__PURE__ */ new Set();
   for (const lesson of Object.values(graph.lessons)) {
@@ -1423,7 +1597,7 @@ function collectLowSignalKeywords(graph, findings) {
     findings.push({
       level: "warning",
       code: "LOW_SIGNAL_KEYWORD",
-      message: `Keyword trigger "${triggerId}" carries more than ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens (${trigger.pattern}); recall matches a keyword only as a substring of --keyword or a contiguous token-run in the file/command, so it rarely fires \u2014 use a short distinctive phrase.`,
+      message: `Keyword trigger "${triggerId}" carries more than ${MAX_RECOMMENDED_KEYWORD_TOKENS} tokens (${trigger.pattern}); recall matches a keyword only as a contiguous token-run in --keyword or the file/command, so it rarely fires \u2014 use a short distinctive phrase.`,
       triggerId
     });
   }
@@ -1448,9 +1622,6 @@ function collectStopwordKeywords(graph, findings) {
     });
   }
 }
-function normalizeRule2(rule) {
-  return rule.trim().replace(/\s+/g, " ").toLowerCase();
-}
 
 // src/lessons/validate.ts
 function validateLessonsGraph(graph, options = {}) {
@@ -1478,6 +1649,8 @@ function validateLessonsGraph(graph, options = {}) {
   collectLowSignalKeywords(graph, findings);
   collectStopwordKeywords(graph, findings);
   collectRunnerAnchoredPatterns(graph, findings);
+  collectBroadCommandPatterns(graph, findings);
+  collectBroadFileGlobs(graph, findings);
   if (options.knownPaths !== void 0) collectDeadFileGlobs(graph, findings, options.knownPaths);
   const ok = findings.every((f) => f.level !== "error");
   return { ok, findings };
@@ -1509,64 +1682,19 @@ async function mutateLessonsGraphLocked(projectRoot, mutator, options = {}) {
         `mutateLessonsGraph: refusing to write \u2014 this change introduces ${errors}. (Pre-existing graph issues are not blocking; run \`agentsmesh lessons validate\` to review and \`lessons untrigger\`/\`prune\` to repair them.)`
       );
     }
-    graph.version = CURRENT_GRAPH_VERSION;
-    saveLessonsGraph(projectRoot, graph);
-    return result;
-  } finally {
-    await release();
-  }
-}
-async function mutateLessonsGraph(projectRoot, mutator, options = {}) {
-  await maybeAutoMigrateLessons(projectRoot);
-  return mutateLessonsGraphLocked(projectRoot, mutator, options);
-}
-
-// src/lessons/trigger-effectiveness.ts
-function ineffectiveTriggers(graph, triggerIds) {
-  const out = [];
-  for (const id of triggerIds) {
-    const trigger = graph.triggers[id];
-    if (trigger === void 0) continue;
-    const reason = ineffectiveReason(trigger.kind, trigger.pattern);
-    if (reason !== null) out.push({ id, kind: trigger.kind, pattern: trigger.pattern, reason });
-  }
-  return out;
-}
-function ineffectiveReason(kind, pattern) {
-  if (kind === "keyword") {
-    if (tokenize(pattern).length === 0) {
-      return "keyword has no matchable token after stopword filtering \u2014 it cannot fire on the mandatory --file/--cmd recall path";
-    }
-    if (keywordNeedleLosesTokens(pattern)) {
-      return "keyword contains stopwords/short words, so its needle can never appear as a contiguous run on the mandatory --file/--cmd recall path";
-    }
-    return null;
-  }
-  if (kind === "command_pattern") {
-    let valid = true;
-    try {
-      new RegExp(pattern);
-    } catch {
-      valid = false;
-    }
-    if (!valid) {
-      return "invalid regex \u2014 recall compiles it with new RegExp and swallows the throw as a non-match, so it never fires";
-    }
-    if (!isSafeRegexPattern(pattern)) {
-      return "regex is outside the provably-linear engine \u2014 recall skips it (ReDoS guard), so it never fires";
-    }
-    return null;
+    graph.version = CURRENT_GRAPH_VERSION;
+    saveLessonsGraph(projectRoot, graph);
+    return result;
+  } finally {
+    await release();
   }
-  return null;
 }
-function blockingDeadTriggers(graph, triggerIds) {
-  return ineffectiveTriggers(graph, triggerIds).filter((t) => t.kind !== "command_pattern");
+async function mutateLessonsGraph(projectRoot, mutator, options = {}) {
+  await maybeAutoMigrateLessons(projectRoot);
+  return mutateLessonsGraphLocked(projectRoot, mutator, options);
 }
 
 // src/lessons/add.ts
-function countInputTriggers(triggers) {
-  return (triggers.files?.length ?? 0) + (triggers.commands?.length ?? 0) + (triggers.keywords?.length ?? 0);
-}
 async function addLesson(projectRoot, input, options = {}) {
   return mutateLessonsGraph(projectRoot, (graph) => addLessonInto(graph, input, options), {
     retries: options.retries
@@ -1574,10 +1702,7 @@ async function addLesson(projectRoot, input, options = {}) {
 }
 function addLessonInto(graph, input, options) {
   const ruleKey = normalizeRule(input.rule);
-  const trimmedRule = input.rule.trim();
-  if (trimmedRule.length > MAX_RULE_LENGTH) {
-    throw new RuleTooLongError(trimmedRule.length, MAX_RULE_LENGTH);
-  }
+  const trimmedRule = assertRuleShape(input.rule);
   const existingId = findExistingLessonByRule(graph, ruleKey);
   const isNewTopic = graph.topics[input.topic] === void 0;
   if (isNewTopic) {
@@ -1587,29 +1712,23 @@ function addLessonInto(graph, input, options) {
     }
     graph.topics[input.topic] = { summary: options.topicSummary };
   }
-  const skipTriggerGates = options.allowNoTrigger === true || input.scope === "always";
-  if (!skipTriggerGates) {
-    const existingTriggers = existingId !== null ? graph.lessons[existingId]?.triggers.length ?? 0 : 0;
-    if (countInputTriggers(input.triggers) === 0 && existingTriggers === 0) {
-      throw new NoTriggerError();
-    }
-  }
+  const existing = existingId !== null ? graph.lessons[existingId] : void 0;
+  assertTriggerInputs(input, options, existing?.triggers.length ?? 0);
   const { triggerIds, newTriggerIds } = mergeTriggers(graph, input.triggers);
-  if (!skipTriggerGates) {
-    const resultingTriggers = existingId !== null ? union(graph.lessons[existingId].triggers, triggerIds) : triggerIds;
-    const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
-    if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
-      throw new UnrecallableLessonError(blockingDead);
-    }
+  if (!skipsTriggerGates(input, options)) {
+    assertRecallable(
+      graph,
+      existing === void 0 ? triggerIds : union(existing.triggers, triggerIds)
+    );
   }
   if (existingId !== null) {
-    const existing = graph.lessons[existingId];
+    const existing2 = graph.lessons[existingId];
     graph.lessons[existingId] = {
-      ...existing,
-      topics: union(existing.topics, [input.topic]),
-      triggers: union(existing.triggers, triggerIds),
-      evidence: union(existing.evidence, input.evidence ?? []),
-      ...existing.rationale === void 0 && input.rationale !== void 0 ? { rationale: input.rationale } : {},
+      ...existing2,
+      topics: union(existing2.topics, [input.topic]),
+      triggers: union(existing2.triggers, triggerIds),
+      evidence: union(existing2.evidence, input.evidence ?? []),
+      ...existing2.rationale === void 0 && input.rationale !== void 0 ? { rationale: input.rationale } : {},
       // Re-capturing a rule with --scope always promotes it to always-on.
       ...input.scope === "always" ? { scope: "always" } : {}
     };
@@ -1702,7 +1821,7 @@ var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING)
 
 Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
 
-**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command>\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
+**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command> --session auto\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always --session auto\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
 
 **Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
 
@@ -1806,26 +1925,6 @@ async function maybeAutoMigrateLessons(projectRoot) {
     throw err;
   }
 }
-function normalizeRecallFile(file, projectRoot) {
-  const forward = file.replaceAll("\\", "/");
-  const direct = relativize(projectRoot, forward);
-  if (!direct.startsWith("../")) return direct;
-  const viaReal = relativize(safeRealpath(projectRoot), safeRealpath(resolve(projectRoot, forward)));
-  return viaReal.startsWith("../") ? direct : viaReal;
-}
-function relativize(root, forward) {
-  const rel = relative(root, resolve(root, forward)).replaceAll("\\", "/");
-  return rel === "" ? forward.replaceAll("\\", "/") : rel;
-}
-function safeRealpath(path) {
-  try {
-    return realpathSync(path);
-  } catch {
-    const parent = dirname(path);
-    if (parent === path) return path;
-    return resolve(safeRealpath(parent), basename(path));
-  }
-}
 
 // src/lessons/keyword-match.ts
 function deriveHaystackTokens(query) {
@@ -1834,14 +1933,16 @@ function deriveHaystackTokens(query) {
   if (query.command !== void 0) parts.push(query.command);
   if (parts.length === 0) return [];
   const out = [];
-  for (const raw of parts.join(" ").split(/[^A-Za-z0-9]+/)) {
-    if (raw.length === 0) continue;
+  for (const raw of splitTokens(parts.join(" "))) {
     out.push(raw.toLowerCase());
     const sub = raw.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").toLowerCase().split(" ").filter((t) => t.length > 0);
     if (sub.length > 1) out.push(...sub);
   }
   return out;
 }
+function splitTokens(text) {
+  return text.split(/[^A-Za-z0-9]+/).filter((t) => t.length > 0);
+}
 function containsRun(needle, hay) {
   if (needle.length === 0) return false;
   for (let i = 0; i + needle.length <= hay.length; i += 1) {
@@ -1857,10 +1958,11 @@ function containsRun(needle, hay) {
   return false;
 }
 function keywordMatches(pattern, query) {
-  if (query.keyword !== void 0 && query.keyword.toLowerCase().includes(pattern.toLowerCase())) {
+  const needle = tokenize(pattern);
+  if (query.keyword !== void 0 && containsRun(needle, splitTokens(query.keyword.toLowerCase()))) {
     return true;
   }
-  return containsRun(tokenize(pattern), deriveHaystackTokens(query));
+  return containsRun(needle, deriveHaystackTokens(query));
 }
 
 // src/lessons/query.ts
@@ -1911,6 +2013,148 @@ function triggerMatches(trigger, query, budget) {
       return keywordMatches(trigger.pattern, query);
   }
 }
+function appendJsonl(path, record, opts) {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}
+`, "utf8");
+  if (statSync(path).size > opts.trimTriggerBytes) capJsonl(path, opts.maxRecords);
+}
+function capJsonl(path, maxRecords) {
+  if (!existsSync(path)) return;
+  const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length <= maxRecords) return;
+  const kept = lines.slice(lines.length - maxRecords);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${kept.join("\n")}
+`, "utf8");
+  renameSync(tmp, path);
+}
+function readJsonl(path) {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (line.trim().length === 0) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/lessons/telemetry.ts
+var MAX_RECALL_LOG_RECORDS = 5e3;
+var RECALL_LOG_TRIM_TRIGGER_BYTES = 2e6;
+var TELEMETRY_ENV = "AGENTSMESH_LESSONS_TELEMETRY";
+var SESSION_ENV = "AGENTSMESH_SESSION_ID";
+function sessionId(env = process.env) {
+  const raw = env[SESSION_ENV];
+  return raw !== void 0 && raw.trim().length > 0 ? raw : void 0;
+}
+function recallLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
+}
+function isTelemetryEnabled(env = process.env) {
+  return env[TELEMETRY_ENV] === "1";
+}
+function appendRecallRecord(projectRoot, record, env = process.env) {
+  if (!isTelemetryEnabled(env)) return;
+  appendJsonl(recallLogPath(projectRoot), record, {
+    maxRecords: MAX_RECALL_LOG_RECORDS,
+    trimTriggerBytes: RECALL_LOG_TRIM_TRIGGER_BYTES
+  });
+}
+
+// src/lessons/cmd-fastpath.ts
+var FASTPATH_DIR = "agentsmesh-lessons-cmdidx";
+function shortHash(value) {
+  let h = 5381;
+  for (let i = 0; i < value.length; i += 1) h = (h << 5) + h + value.charCodeAt(i) >>> 0;
+  return h.toString(36);
+}
+function commandFastpathCachePath(projectRoot) {
+  return join(tmpdir(), FASTPATH_DIR, `${shortHash(resolve(projectRoot))}.json`);
+}
+function currentGraphStamp(projectRoot) {
+  try {
+    const s = statSync(graphFilePath(projectRoot));
+    return { mtimeMs: s.mtimeMs, size: s.size };
+  } catch {
+    return null;
+  }
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function readCache(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const c = parsed;
+    const stamp = c.stamp;
+    if (typeof stamp?.mtimeMs !== "number" || typeof stamp.size !== "number" || !isStringArray(c.commandPatterns) || !isStringArray(c.keywordPatterns)) {
+      return null;
+    }
+    return {
+      stamp: { mtimeMs: stamp.mtimeMs, size: stamp.size },
+      commandPatterns: c.commandPatterns,
+      keywordPatterns: c.keywordPatterns
+    };
+  } catch {
+    return null;
+  }
+}
+function refreshCommandFastpath(projectRoot, graph, preReadStamp) {
+  try {
+    if (preReadStamp === null) return;
+    const stamp = currentGraphStamp(projectRoot);
+    if (stamp === null) return;
+    if (stamp.mtimeMs !== preReadStamp.mtimeMs || stamp.size !== preReadStamp.size) return;
+    const path = commandFastpathCachePath(projectRoot);
+    const existing = readCache(path);
+    if (existing !== null && existing.stamp.mtimeMs === stamp.mtimeMs && existing.stamp.size === stamp.size) {
+      return;
+    }
+    const reachable = /* @__PURE__ */ new Set();
+    for (const lesson of Object.values(graph.lessons)) {
+      if (lesson.status !== "active" || lesson.scope === "always") continue;
+      for (const t of lesson.triggers) reachable.add(t);
+    }
+    const commandPatterns = [];
+    const keywordPatterns = [];
+    for (const [id, trigger] of Object.entries(graph.triggers)) {
+      if (!reachable.has(id)) continue;
+      if (trigger.kind === "command_pattern") commandPatterns.push(trigger.pattern);
+      else if (trigger.kind === "keyword") keywordPatterns.push(trigger.pattern);
+    }
+    const cache2 = { stamp, commandPatterns, keywordPatterns };
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(cache2), "utf8");
+    renameSync(tmp, path);
+  } catch {
+  }
+}
+function normalizeRecallFile(file, projectRoot) {
+  const forward = file.replaceAll("\\", "/");
+  const direct = relativize(projectRoot, forward);
+  if (!direct.startsWith("../")) return direct;
+  const viaReal = relativize(safeRealpath(projectRoot), safeRealpath(resolve(projectRoot, forward)));
+  return viaReal.startsWith("../") ? direct : viaReal;
+}
+function relativize(root, forward) {
+  const rel = relative(root, resolve(root, forward)).replaceAll("\\", "/");
+  return rel === "" ? forward.replaceAll("\\", "/") : rel;
+}
+function safeRealpath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    const parent = dirname(path);
+    if (parent === path) return path;
+    return resolve(safeRealpath(parent), basename(path));
+  }
+}
 
 // src/lessons/ranking-signals.ts
 function buildFanout(graph) {
@@ -1921,6 +2165,15 @@ function buildFanout(graph) {
   }
   return fanout;
 }
+var KEYWORD_NARROWNESS = 0.4;
+function buildNarrowness(graph) {
+  const narrowness = /* @__PURE__ */ new Map();
+  for (const [id, trigger] of Object.entries(graph.triggers)) {
+    if (trigger.kind === "file_glob") narrowness.set(id, globNarrowness(trigger.pattern));
+    else narrowness.set(id, trigger.kind === "keyword" ? KEYWORD_NARROWNESS : 1);
+  }
+  return narrowness;
+}
 function buildTopicCoherence(matches) {
   const topicCount = /* @__PURE__ */ new Map();
   for (const { lesson } of matches) {
@@ -1939,7 +2192,7 @@ function buildTopicCoherence(matches) {
 var DEFAULT_RECALL_LIMIT = 10;
 var DEFAULT_RECALL_MAX_TOKENS = 400;
 var RRF_K = 60;
-var SPECIFICITY_WEIGHT = 3;
+var SPECIFICITY_WEIGHT = 5;
 var TOPIC_COHERENCE_WEIGHT = 2;
 var BM25_WEIGHT = 1;
 var EFFECTIVENESS_WEIGHT = 1;
@@ -1966,12 +2219,15 @@ function rankLessons(graph, query, matches, options = {}) {
   const terms = queryTerms(query);
   const corpus = buildCorpus(graph);
   const fanout = buildFanout(graph);
+  const narrowness = buildNarrowness(graph);
   const coherence = buildTopicCoherence(matches);
   const matchedTriggerIds = collectMatchedTriggerIds(graph, query);
   const scored = matches.map(({ id, lesson }) => {
     const hitTriggers = lesson.triggers.filter((t) => matchedTriggerIds.has(t));
     let specificity = 0;
-    for (const t of hitTriggers) specificity = Math.max(specificity, 1 / fanout.get(t));
+    for (const t of hitTriggers) {
+      specificity = Math.max(specificity, (narrowness.get(t) ?? 1) / fanout.get(t));
+    }
     return {
       id,
       lesson,
@@ -2054,57 +2310,6 @@ function loadRecallConfig(projectRoot) {
     return fallback;
   }
 }
-function appendJsonl(path, record, opts) {
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, `${JSON.stringify(record)}
-`, "utf8");
-  if (statSync(path).size > opts.trimTriggerBytes) capJsonl(path, opts.maxRecords);
-}
-function capJsonl(path, maxRecords) {
-  if (!existsSync(path)) return;
-  const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
-  if (lines.length <= maxRecords) return;
-  const kept = lines.slice(lines.length - maxRecords);
-  const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, `${kept.join("\n")}
-`, "utf8");
-  renameSync(tmp, path);
-}
-function readJsonl(path) {
-  if (!existsSync(path)) return [];
-  const out = [];
-  for (const line of readFileSync(path, "utf8").split("\n")) {
-    if (line.trim().length === 0) continue;
-    try {
-      out.push(JSON.parse(line));
-    } catch {
-    }
-  }
-  return out;
-}
-var MAX_RECALL_LOG_RECORDS = 5e3;
-var RECALL_LOG_TRIM_TRIGGER_BYTES = 2e6;
-var TELEMETRY_ENV = "AGENTSMESH_LESSONS_TELEMETRY";
-var SESSION_ENV = "AGENTSMESH_SESSION_ID";
-function sessionId(env = process.env) {
-  const raw = env[SESSION_ENV];
-  return raw !== void 0 && raw.trim().length > 0 ? raw : void 0;
-}
-function recallLogPath(projectRoot) {
-  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
-}
-function isTelemetryEnabled(env = process.env) {
-  return env[TELEMETRY_ENV] === "1";
-}
-function appendRecallRecord(projectRoot, record, env = process.env) {
-  if (!isTelemetryEnabled(env)) return;
-  appendJsonl(recallLogPath(projectRoot), record, {
-    maxRecords: MAX_RECALL_LOG_RECORDS,
-    trimTriggerBytes: RECALL_LOG_TRIM_TRIGGER_BYTES
-  });
-}
-
-// src/lessons/outcome-log.ts
 function outcomeLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
 }
@@ -2141,48 +2346,116 @@ function loadEffectiveness(projectRoot) {
   return map;
 }
 var SEEN_DIR = "agentsmesh-lessons-seen";
-function openSessionDedup(options = {}) {
-  if (options.disabled === true) return null;
-  const id = options.explicit !== void 0 && options.explicit.trim().length > 0 ? options.explicit.trim() : sessionId(options.env);
-  if (id === void 0) return null;
-  const path = seenPath(id, options.projectRoot);
-  return { sessionId: id, seen: loadSeen(path), path };
-}
-function shortHash(value) {
+function shortHash2(value) {
   let h = 5381;
   for (let i = 0; i < value.length; i += 1) h = (h << 5) + h + value.charCodeAt(i) >>> 0;
   return h.toString(36);
 }
-function seenPath(id, projectRoot) {
+function seenStorePath(id, projectRoot) {
   const safe = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 200);
-  const scoped = projectRoot === void 0 ? safe : `${safe}__${shortHash(resolve(projectRoot))}`;
+  const scoped = projectRoot === void 0 ? safe : `${safe}__${shortHash2(resolve(projectRoot))}`;
   return join(tmpdir(), SEEN_DIR, `${scoped}.json`);
 }
-function loadSeen(path) {
-  if (!existsSync(path)) return /* @__PURE__ */ new Set();
+function readSeenStore(path) {
+  if (!existsSync(path)) return { ids: /* @__PURE__ */ new Set(), stamps: null };
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
-    return new Set(parsed.filter((x) => typeof x === "string"));
+    if (Array.isArray(parsed)) {
+      const ids = new Set(parsed.filter((x) => typeof x === "string"));
+      return { ids, stamps: null };
+    }
+    if (typeof parsed === "object" && parsed !== null) {
+      const seen = parsed.seen;
+      if (typeof seen === "object" && seen !== null) {
+        const stamps = /* @__PURE__ */ new Map();
+        for (const [id, ms] of Object.entries(seen)) {
+          if (typeof ms === "number") stamps.set(id, ms);
+        }
+        const lastAt = parsed.lastAt;
+        return {
+          ids: new Set(stamps.keys()),
+          stamps,
+          ...typeof lastAt === "number" ? { lastAt } : {}
+        };
+      }
+    }
+    return { ids: /* @__PURE__ */ new Set(), stamps: null };
+  } catch {
+    return { ids: /* @__PURE__ */ new Set(), stamps: null };
+  }
+}
+function writeSeenStore(path, data, lastAt) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const body = data instanceof Map ? JSON.stringify({ v: 2, lastAt: lastAt ?? Date.now(), seen: Object.fromEntries(data) }) : JSON.stringify(data);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, body, "utf8");
+    renameSync(tmp, path);
   } catch {
-    return /* @__PURE__ */ new Set();
   }
 }
+var AUTO_SESSION_IDLE_MS = 30 * 60 * 1e3;
+var FUTURE_TOLERANCE_MS = 6e4;
+function stampAgeMs(stamp, now = Date.now()) {
+  if (stamp - now > FUTURE_TOLERANCE_MS) return Number.POSITIVE_INFINITY;
+  return Math.max(0, now - stamp);
+}
+function isIdleSession(stamps, lastAt) {
+  if (stamps === null || stamps.size === 0) return false;
+  let newest = lastAt ?? 0;
+  for (const ms of stamps.values()) if (ms > newest) newest = ms;
+  return stampAgeMs(newest) > AUTO_SESSION_IDLE_MS;
+}
+
+// src/lessons/seen-cache.ts
+function openSessionDedup(options = {}) {
+  if (options.disabled === true) return null;
+  const id = options.explicit !== void 0 && options.explicit.trim().length > 0 ? options.explicit.trim() : sessionId(options.env);
+  if (id === void 0) return null;
+  const path = seenStorePath(id, options.projectRoot);
+  const store = readSeenStore(path);
+  const stale = options.ttlMs !== void 0 && isIdleSession(store.stamps, store.lastAt);
+  const stamps = stale ? null : store.stamps;
+  return {
+    sessionId: id,
+    seen: stale ? /* @__PURE__ */ new Set() : visibleSeen(store.ids, stamps, options.ttlMs),
+    path,
+    stamps,
+    ...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
+  };
+}
+function visibleSeen(ids, stamps, ttlMs) {
+  if (ttlMs === void 0) return ids;
+  if (stamps === null) return /* @__PURE__ */ new Set();
+  const now = Date.now();
+  const fresh = /* @__PURE__ */ new Set();
+  for (const [id, ms] of stamps) if (stampAgeMs(ms, now) <= ttlMs) fresh.add(id);
+  return fresh;
+}
 function filterUnseen(dedup, matches) {
   return matches.filter((m) => !dedup.seen.has(m.id));
 }
 function commitSeen(dedup, returnedIds) {
-  if (returnedIds.length === 0) return;
+  if (returnedIds.length === 0) {
+    if (dedup.ttlMs !== void 0 && dedup.stamps !== null) {
+      writeSeenStore(dedup.path, dedup.stamps);
+    }
+    return;
+  }
+  if (dedup.ttlMs !== void 0 || dedup.stamps !== null) {
+    const now = Date.now();
+    const merged = /* @__PURE__ */ new Map();
+    for (const [id, ms] of dedup.stamps ?? []) {
+      if (dedup.ttlMs === void 0 || now - ms <= dedup.ttlMs) merged.set(id, ms);
+    }
+    for (const id of returnedIds) merged.set(id, now);
+    writeSeenStore(dedup.path, merged);
+    return;
+  }
   const union3 = new Set(dedup.seen);
   for (const id of returnedIds) union3.add(id);
   if (union3.size === dedup.seen.size) return;
-  try {
-    mkdirSync(dirname(dedup.path), { recursive: true });
-    const tmp = `${dedup.path}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify([...union3]), "utf8");
-    renameSync(tmp, dedup.path);
-  } catch {
-  }
+  writeSeenStore(dedup.path, [...union3]);
 }
 
 // src/lessons/recall.ts
@@ -2191,6 +2464,7 @@ async function recallLessons(projectRoot, query, options = {}) {
     await maybeAutoMigrateLessons(projectRoot);
   } catch {
   }
+  const preReadStamp = currentGraphStamp(projectRoot);
   const load = loadLessonsGraphResilient(projectRoot);
   if (load.status === "corrupt") {
     return { lessons: [], totalMatches: 0, suppressed: 0, corrupt: true };
@@ -2200,12 +2474,14 @@ async function recallLessons(projectRoot, query, options = {}) {
   }
   if (load.status === "absent") return { lessons: [], totalMatches: 0, suppressed: 0 };
   const graph = load.graph;
+  refreshCommandFastpath(projectRoot, graph, preReadStamp);
   const matchQuery = query.file === void 0 ? query : { ...query, file: normalizeRecallFile(query.file, projectRoot) };
   const matches = queryLessons(graph, matchQuery);
   const dedup = openSessionDedup({
     explicit: options.sessionId,
     disabled: options.noDedup,
-    projectRoot
+    projectRoot,
+    ...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
   });
   const forRank = dedup === null ? matches : filterUnseen(dedup, matches);
   const cfg = loadRecallConfig(projectRoot);
@@ -2213,8 +2489,10 @@ async function recallLessons(projectRoot, query, options = {}) {
     limit: options.limit ?? cfg.limit,
     maxTokens: options.maxTokens === null ? void 0 : options.maxTokens ?? cfg.maxTokens,
     // Down-rank proven fire-but-fail lessons (empty ⇒ neutral, so recall is
-    // unchanged until the outcome log has real signal). Read from the side-channel.
-    effectiveness: loadEffectiveness(projectRoot)
+    // unchanged until the outcome log has real signal). Read from the side-channel
+    // only when something survived matching+dedup — a no-match recall must not pay
+    // the (up to 2MB) outcome-log read for a ranking of nothing.
+    effectiveness: forRank.length === 0 ? /* @__PURE__ */ new Map() : loadEffectiveness(projectRoot)
   });
   if (dedup !== null)
     commitSeen(
@@ -2566,9 +2844,9 @@ var LINE_REFS = String.raw`L\d+(?:\s*,\s*L\d+)*`;
 var LINE_REF_PATTERNS = [
   new RegExp(String.raw`\s*\bSee\s+${LINE_REFS}\.?`, "g"),
   // " See L128." / " See L140, L149"
-  new RegExp(String.raw`\s*\((?:${LINE_REFS})\)\.?`, "g"),
+  new RegExp(String.raw`\s*\((?:${LINE_REFS})\)`, "g"),
   // " (L174)" / " (L92, L163)"
-  new RegExp(String.raw`\s*\[(?:${LINE_REFS})\]\.?`, "g")
+  new RegExp(String.raw`\s*\[(?:${LINE_REFS})\]`, "g")
   // " [L161, L208]"
 ];
 var ALSO_RELEVANT_PATTERN = /\s*\(also relevant[^)]*\)\s*/g;
@@ -2806,6 +3084,32 @@ function isCoveredByExisting(candidate, existing) {
   }
   return false;
 }
+var OPENER = /^---[ \t]*\r?\n/;
+var CLOSER = /^---[ \t]*\r?$/m;
+function splitFrontmatter(content) {
+  const opener = OPENER.exec(content);
+  if (opener === null) return null;
+  const yamlStart = opener[0].length;
+  const closer = CLOSER.exec(content.slice(yamlStart));
+  if (closer === null) return null;
+  const closeStart = yamlStart + closer.index;
+  const closeEnd = closeStart + closer[0].length;
+  return {
+    yaml: content.slice(yamlStart, closeStart),
+    body: content.slice(closeEnd).trim(),
+    prefix: content.slice(0, closeEnd)
+  };
+}
+function serializeFrontmatter(frontmatter, body) {
+  const keys = Object.keys(frontmatter);
+  if (keys.length === 0) return body;
+  const yamlStr = stringify(frontmatter, { lineWidth: 0 }).trimEnd();
+  return `---
+${yamlStr}
+---
+
+${body}`;
+}
 var LESSONS_CONTRACT_START = "<!-- agentsmesh:lessons-contract:start -->";
 var LESSONS_CONTRACT_END = "<!-- agentsmesh:lessons-contract:end -->";
 function escapeRegExp(value) {
@@ -2818,10 +3122,8 @@ function stripManagedBlock(content, start, end) {
   return content.replace(managedBlockPattern(start, end), "").trim();
 }
 function splitFrontmatterPrefix(content) {
-  if (content.indexOf("---") !== 0) return { prefix: "", body: content.trim() };
-  const close = content.indexOf("---", 3);
-  if (close === -1) return { prefix: "", body: content.trim() };
-  return { prefix: content.slice(0, close + 3), body: content.slice(close + 3).trim() };
+  const split = splitFrontmatter(content);
+  return split === null ? { prefix: "", body: content.trim() } : { prefix: split.prefix, body: split.body };
 }
 function insertAtBodyTop(content, block) {
   const { prefix, body } = splitFrontmatterPrefix(content);
@@ -2835,6 +3137,17 @@ ${placed}` : placed;
 
 // src/targets/projection/lessons-paragraph.ts
 var LEGACY_RAW_FORMS = [
+  // Pre-`--session auto` wording (2026-07): strip sentinel-less copies so a
+  // project scaffolded before the dedup correlator dedups on the next scaffold.
+  `## Lessons (BLOCKING)
+
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
+
+**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command>\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
+
+**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`,
   `## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)
 
 Graph \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit. Manual: the \`lessons\` skill.
@@ -2864,16 +3177,6 @@ ${rule}`, "").replace(rule, ""),
     content
   );
 }
-function serializeFrontmatter(frontmatter, body) {
-  const keys = Object.keys(frontmatter);
-  if (keys.length === 0) return body;
-  const yamlStr = stringify(frontmatter, { lineWidth: 0 }).trimEnd();
-  return `---
-${yamlStr}
----
-
-${body}`;
-}
 
 // src/lessons/skill.ts
 var LESSONS_SKILL_NAME = "lessons";
@@ -2892,14 +3195,18 @@ regression / wrong assumption / surprise and you have not captured (nor stated
 
 ## Recall \u2014 before each edit/command, and at task start
 
-\`agentsmesh lessons query --file <path> --cmd <command>\`, then apply every rule.
-Pure-read commands (read-only) and the query itself are exempt. **keyword-only recall
+\`agentsmesh lessons query --file <path> --cmd <command> --session auto\`, then apply every
+rule. Pure-read commands (read-only) and the query itself are exempt. **keyword-only recall
 for a specific edit is the anti-pattern** \u2014 anchor those to \`--file\`/\`--cmd\`. But at the
 START of a task (or when planning), run \`agentsmesh lessons query --keyword "<the task's
-key terms>" --always\`: that surfaces the conceptual rules no file/command names PLUS the
-universal always-on lessons \u2014 the manual equivalent of the automatic prompt recall on
-hook-capable tools. Author a \`keyword\` trigger beside a \`file_glob\` on conceptual lessons
-so they are reachable both ways. No shell \u2192 MCP \`lessons_query\` (\`file\`/\`command\`/\`keyword\`/\`always\`).
+key terms>" --always --session auto\`: that surfaces the conceptual rules no file/command
+names PLUS the universal always-on lessons \u2014 the manual equivalent of the automatic prompt
+recall on hook-capable tools. **Always pass \`--session auto\`**: it suppresses rules already
+shown this session so repeat recalls stay quiet (without it every recall re-delivers the
+whole matched set); \`--no-dedup\` re-shows everything after a context reset. Author a
+\`keyword\` trigger beside a \`file_glob\` on conceptual lessons so they are reachable both
+ways. No shell \u2192 MCP \`lessons_query\` (\`file\`/\`command\`/\`keyword\`/\`always\`; session dedup
+is on by default there \u2014 \`no_dedup:true\` to re-show).
 
 ## Capture \u2014 Gate Function (before any completion claim)