agentsmesh 0.40.0 → 0.41.0

package/dist/lessons.js

@@ -1,12 +1,14 @@
 import { z } from 'zod';
 import { createHash, randomUUID } from 'crypto';
-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 { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync, renameSync, readdirSync, chmodSync, realpathSync, accessSync, constants, appendFileSync, rmdirSync, unlinkSync, openSync, readSync, closeSync } from 'fs';
+import { resolve, join, relative, sep, dirname, posix, basename, extname } from 'path';
 import picomatch from 'picomatch';
-import { mkdir, rm, writeFile, readFile, stat, lstat, open, rename } from 'fs/promises';
+import { execFile, spawnSync } from 'child_process';
+import { hostname, tmpdir } from 'os';
+import { mkdir, writeFile, rm, readFile, lstat, open, readdir, rmdir, unlink, stat, rename, realpath } from 'fs/promises';
 import { setTimeout } from 'timers/promises';
-import { tmpdir, hostname } from 'os';
+import { promisify } from 'util';
+import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
 
 // src/lessons/graph-schema.ts
 var CURRENT_GRAPH_VERSION = 2;
@@ -52,22 +54,320 @@ var LessonsGraphSchema = z.object({
 function parseGraph(raw) {
   return LessonsGraphSchema.parse(raw);
 }
+function emptyGraph() {
+  return { version: CURRENT_GRAPH_VERSION, lessons: {}, topics: {}, triggers: {} };
+}
+
+// src/lessons/glob-expand.ts
+var MARK = "\0";
+var LED = "
";
+var MAX_EXPANSIONS = 64;
+function fail(reason) {
+  throw new Error(reason);
+}
+function skipClass(s, i) {
+  const end = s.indexOf("]", i + 1);
+  return end === -1 ? i + 1 : end + 1;
+}
+function markLedStars(body) {
+  let out2 = "";
+  let depth = 0;
+  for (let i = 0; i < body.length; ) {
+    const c2 = body[i];
+    if (c2 === "[") {
+      const end = skipClass(body, i);
+      out2 += body.slice(i, end);
+      i = end;
+      continue;
+    }
+    if (c2 === "{") depth += 1;
+    if (c2 === "}" && depth > 0) depth -= 1;
+    const prev = body[i - 1];
+    if (c2 === "*" && prev === "." && depth > 0) fail(".* inside {\u2026} is not supported");
+    const segmentStart = i === 0 || prev === "/";
+    const afterLeadingDot = prev === "." && (i === 1 || body[i - 2] === "/");
+    const led = c2 === "*" && body[i + 1] !== "*" && prev !== "*" && (segmentStart || afterLeadingDot);
+    out2 += led ? LED : c2;
+    i += 1;
+  }
+  return out2;
+}
+function expandBraces(s) {
+  let open2 = -1;
+  for (let i = 0; i < s.length && open2 === -1; ) {
+    if (s[i] === "[") i = skipClass(s, i);
+    else if (s[i] === "}") fail("unbalanced }");
+    else if (s[i] === "{") open2 = i;
+    else i += 1;
+  }
+  if (open2 === -1) return [s];
+  const options = [];
+  let depth = 0;
+  let start = open2 + 1;
+  let close = -1;
+  for (let i = open2 + 1; i < s.length && close === -1; ) {
+    const c2 = s[i];
+    if (c2 === "[") {
+      i = skipClass(s, i);
+      continue;
+    }
+    if (c2 === "{") depth += 1;
+    else if (c2 === "}" && depth > 0) depth -= 1;
+    else if (c2 === "}") close = i;
+    else if (c2 === "," && depth === 0) {
+      options.push(s.slice(start, i));
+      start = i + 1;
+    }
+    i += 1;
+  }
+  if (close === -1) fail("unclosed {");
+  if (options.length === 0)
+    fail("brace groups need a comma, e.g. {a,b} (ranges are not supported)");
+  options.push(s.slice(start, close));
+  const suffixes = expandBraces(s.slice(close + 1));
+  const out2 = [];
+  for (const option of options) {
+    for (const head of expandBraces(option)) {
+      for (const tail of suffixes) {
+        out2.push(s.slice(0, open2) + MARK + head + MARK + tail);
+        if (out2.length > MAX_EXPANSIONS) fail(`more than ${MAX_EXPANSIONS} brace expansions`);
+      }
+    }
+  }
+  return out2;
+}
+
+// src/lessons/glob-parse.ts
+var MAX_GLOB_LENGTH = 256;
+function parseGlob(pattern) {
+  try {
+    return parseOrThrow(pattern);
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+function parseOrThrow(pattern) {
+  if (pattern.length > MAX_GLOB_LENGTH) fail(`longer than ${MAX_GLOB_LENGTH} characters`);
+  if (pattern.includes("\\")) fail("backslash escapes are not supported (use / as separator)");
+  if (/["\u0000-\u001f]/.test(pattern)) fail("quotes and control characters are not supported");
+  if (/[()|]/.test(pattern.replace(/\[[^\]/]*\]/g, ""))) {
+    fail("extglobs and (\u2026)/| groups are not supported (use {a,b})");
+  }
+  if (/[[\]{}]\+/.test(pattern)) fail("+ after a class or brace is a regex quantifier");
+  const negated = pattern.startsWith("!");
+  let body = negated ? pattern.slice(1) : pattern;
+  if (body.startsWith("./")) body = body.slice(2);
+  if (body.startsWith("!") || body.startsWith("./")) fail("use a single leading ! and ./");
+  if (body === "") fail("empty pattern");
+  const fastPath = !negated && (body === "*.*" || body === "**/*.*");
+  if (fastPath) body = `${body.slice(0, -1)}?*`;
+  return { negated, alternatives: expandBraces(markLedStars(body)).map(parseAlternative) };
+}
+function parseAlternative(alt) {
+  const raw = alt.split("/");
+  const out2 = [];
+  raw.forEach((segment, i) => {
+    if (segment.includes("**")) {
+      if (segment !== "**") fail("** must be a whole segment, outside {\u2026} (use * in a segment)");
+      if (out2.at(-1)?.k === "globstar") return;
+      const before = raw[i - 1] ?? "";
+      const trailing = raw.slice(i + 1).every((s) => s === "**");
+      const min1 = trailing && (before.endsWith("*") || before.endsWith(LED));
+      out2.push({ k: "globstar", min1 });
+      return;
+    }
+    const tokens = tokenize(segment, alt);
+    const guarded = segment.includes(LED);
+    const literal = tokens.every((t) => t.k === "lit") ? tokens.map((t) => t.k === "lit" ? t.ch : "").join("") : null;
+    const matchesEmpty = segment !== "" && !guarded && tokens.every((t) => t.k === "star");
+    out2.push({ k: "segment", tokens, literal, guarded, matchesEmpty });
+  });
+  return out2;
+}
+function tokenize(segment, alt) {
+  const tokens = [];
+  for (let i = 0; i < segment.length; i += 1) {
+    const c2 = segment[i];
+    if (c2 === MARK) continue;
+    if (c2 === "*" || c2 === LED) tokens.push({ k: "star" });
+    else if (c2 === "?") tokens.push({ k: "one" });
+    else if (c2 === "[") {
+      const end = segment.indexOf("]", i + 1);
+      if (end === -1) {
+        if (alt.includes("]")) fail("a [...] class cannot span /");
+        tokens.push({ k: "lit", ch: c2 });
+        continue;
+      }
+      tokens.push(parseClass(segment.slice(i + 1, end)));
+      i = end;
+    } else tokens.push({ k: "lit", ch: c2 });
+  }
+  return tokens;
+}
+var CLASS_SPECIAL = /[-*+?.^${}(|)[\]]/;
+function parseClass(body) {
+  if (body === "") fail("empty [] class");
+  if (body.startsWith("!")) fail("[!...] is not a negation here; use [^...]");
+  if (body.includes("[")) fail("POSIX [:classes:] and nested [ are not supported");
+  const negated = body.startsWith("^");
+  const members = negated ? body.slice(1) : body;
+  if (members === "") fail("empty [^] class");
+  const ranges = [];
+  for (let i = 0; i < members.length; i += 1) {
+    const lo = members[i];
+    const hi = members[i + 2];
+    if (members[i + 1] === "-" && hi !== void 0) {
+      if (hi < lo) fail(`class range out of order: ${lo}-${hi}`);
+      ranges.push([lo, hi]);
+      i += 2;
+    } else ranges.push([lo, lo]);
+  }
+  const inSet = (c2) => ranges.some(([lo, hi]) => c2 >= lo && c2 <= hi);
+  const literal = CLASS_SPECIAL.test(body) ? null : `[${body}]`;
+  return { k: "class", test: negated ? (c2) => c2 !== "/" && !inSet(c2) : inSet, literal };
+}
+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/trigger-file-glob.ts
+var ABSOLUTE = /^(?:[A-Za-z]:)?\//;
+var GLOB_CHARS = /[*?[{]/;
+var CODES = {
+  outside: "TRIGGER_FILE_OUTSIDE_PROJECT",
+  root: "TRIGGER_FILE_IS_PROJECT_ROOT",
+  folder: "TRIGGER_FILE_IS_DIRECTORY",
+  unsafe: "UNSAFE_GLOB_PATTERN"
+};
+function problemMessage(given, problem, detail) {
+  switch (problem) {
+    case "outside":
+      return `--trigger-file ${given} points outside the project root. File triggers match project-relative paths, so it would never fire \u2014 pass a glob relative to the project root (e.g. "src/**/*.ts").`;
+    case "root":
+      return `--trigger-file ${given} is the project root itself, and file triggers match files. Pass a glob such as "src/**/*.ts".`;
+    case "folder":
+      return `--trigger-file ${given} is a folder, and file triggers match files. Use ${JSON.stringify(`${detail}/**`)} to match every file in it.`;
+    case "unsafe":
+      return `--trigger-file ${given} is outside the safe glob subset: ${detail}. Use only *, **, ?, [...] and {a,b}.`;
+  }
+}
+var TriggerFileGlobError = class extends Error {
+  constructor(pattern, problem = "outside", detail = "") {
+    super(problemMessage(JSON.stringify(pattern), problem, detail));
+    this.pattern = pattern;
+    this.name = "TriggerFileGlobError";
+    this.code = CODES[problem];
+  }
+  code;
+};
+function sameFolder(a, b) {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+function isFolder(projectRoot, path) {
+  if (GLOB_CHARS.test(path)) return false;
+  return statSync(join(projectRoot, path), { throwIfNoEntry: false })?.isDirectory() === true;
+}
+function projectRelativeGlob(pattern, projectRoot) {
+  const forward = pattern.trim().replaceAll("\\", "/");
+  let rel = forward;
+  if (ABSOLUTE.test(forward)) {
+    const root = projectRoot.replaceAll("\\", "/").replace(/\/+$/, "");
+    rel = forward.startsWith(`${root}/`) || forward === root ? forward.slice(root.length + 1) : normalizeRecallFile(forward, projectRoot);
+    if (ABSOLUTE.test(rel)) {
+      throw new TriggerFileGlobError(
+        pattern,
+        sameFolder(forward, projectRoot) ? "root" : "outside"
+      );
+    }
+  }
+  const normalized = posix.normalize(rel === "" ? "." : rel);
+  if (normalized === ".." || normalized.startsWith("../")) {
+    throw new TriggerFileGlobError(pattern, "outside");
+  }
+  const path = normalized.replace(/\/+$/, "");
+  if (path === "." || path === "") throw new TriggerFileGlobError(pattern, "root");
+  if (path !== normalized || isFolder(projectRoot, path)) {
+    throw new TriggerFileGlobError(pattern, "folder", path);
+  }
+  const unsafe = parseGlob(path);
+  if (typeof unsafe === "string") throw new TriggerFileGlobError(pattern, "unsafe", unsafe);
+  return path;
+}
+
+// src/lessons/add-helpers.ts
 function normalizeRule(rule) {
   return rule.trim().replace(/\s+/g, " ").toLowerCase();
 }
 function union(base, extra) {
-  const out = [...base];
-  for (const item of extra) if (!out.includes(item)) out.push(item);
-  return out;
+  const out2 = [...base];
+  for (const item of extra) if (!out2.includes(item)) out2.push(item);
+  return out2;
+}
+function upsertLesson(before, input, triggerIds) {
+  return {
+    ...before,
+    topics: union(before.topics, [input.topic]),
+    triggers: union(before.triggers, triggerIds),
+    evidence: union(before.evidence, input.evidence ?? []),
+    ...before.rationale === void 0 && input.rationale !== void 0 ? { rationale: input.rationale } : {},
+    ...input.scope === "always" ? { scope: "always" } : {}
+  };
+}
+function describeUpsert(before, after) {
+  const added = (base, next) => next.filter((item) => !base.includes(item));
+  const topics = added(before.topics, after.topics);
+  const triggers = added(before.triggers, after.triggers);
+  const evidence = added(before.evidence, after.evidence);
+  const changes = [];
+  if (after.scope === "always" && before.scope !== "always") changes.push("scope set to always");
+  if (topics.length > 0) changes.push(`topic added: ${topics.join(", ")}`);
+  if (triggers.length > 0) {
+    changes.push(`trigger${triggers.length === 1 ? "" : "s"} attached: ${triggers.join(", ")}`);
+  }
+  if (evidence.length > 0) changes.push(`evidence added: ${evidence.join(", ")}`);
+  if (before.rationale === void 0 && after.rationale !== void 0) {
+    changes.push("rationale added");
+  }
+  return changes;
 }
-function mergeTriggers(graph, spec) {
+function findExistingLessonByRule(graph, ruleKey) {
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    if (normalizeRule(lesson.rule) === ruleKey) return id;
+  }
+  return null;
+}
+function mergeTriggers(graph, spec, projectRoot) {
   const requested = [
-    // Normalize `\` → `/` so a Windows-shaped glob matches: recall relativizes
-    // every `--file` to forward slashes (normalizeRecallFile), so a backslash
-    // pattern stored raw would silently never fire. Normalizing here also lets
-    // a backslash pattern dedupe against the forward-slash node it equals.
+    // Recall matches forward-slash, project-relative paths (normalizeRecallFile),
+    // so a backslash or absolute pattern stored raw would silently never fire.
+    // Normalizing here also dedupes it against the node it equals.
     ...(spec.files ?? []).map(
-      (p) => ({ kind: "file_glob", pattern: p.replaceAll("\\", "/") })
+      (p) => ({
+        kind: "file_glob",
+        pattern: projectRoot === void 0 ? p.replaceAll("\\", "/") : projectRelativeGlob(p, projectRoot)
+      })
     ),
     ...(spec.commands ?? []).map((p) => ({ kind: "command_pattern", pattern: p })),
     ...(spec.keywords ?? []).map((p) => ({ kind: "keyword", pattern: p }))
@@ -123,13 +423,156 @@ function ruleToSlug(rule) {
 function todayIso() {
   return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 }
-var GRAPH_REL_PATH = ".agentsmesh/lessons/lessons.json";
+var UTF8_BOM = "\uFEFF";
+var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".md",
+  ".mdc",
+  ".mdx",
+  ".markdown",
+  ".txt",
+  ".json",
+  ".jsonc",
+  ".yaml",
+  ".yml",
+  ".toml",
+  ".ini",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".ps1",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".ts",
+  ".tsx",
+  ".html",
+  ".css"
+]);
+var TEXT_DOTFILES = /* @__PURE__ */ new Set([
+  ".gitignore",
+  ".cursorignore",
+  ".cursorindexingignore",
+  ".aiignore",
+  ".agentignore",
+  ".clineignore",
+  ".geminiignore",
+  ".codeiumignore",
+  ".continueignore",
+  ".copilotignore",
+  ".windsurfignore",
+  ".junieignore",
+  ".kiroignore",
+  ".rooignore",
+  ".antigravityignore"
+]);
+function shouldNormalizeLineEndings(path) {
+  const ext = extname(path).toLowerCase();
+  if (ext.length > 0) return TEXT_EXTENSIONS.has(ext);
+  const base = basename(path).toLowerCase();
+  return TEXT_DOTFILES.has(base);
+}
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".bmp",
+  ".ico",
+  ".webp",
+  ".avif",
+  ".tiff",
+  ".pdf",
+  ".zip",
+  ".gz",
+  ".tgz",
+  ".bz2",
+  ".xz",
+  ".7z",
+  ".rar",
+  ".jar",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+  ".mp3",
+  ".mp4",
+  ".wav",
+  ".ogg",
+  ".webm",
+  ".mov",
+  ".wasm",
+  ".bin",
+  ".dat",
+  ".db",
+  ".sqlite",
+  ".so",
+  ".dylib",
+  ".dll",
+  ".exe",
+  ".class",
+  ".pyc",
+  // Office and design documents are zip or proprietary containers.
+  ".xlsx",
+  ".xls",
+  ".docx",
+  ".doc",
+  ".pptx",
+  ".ppt",
+  ".odt",
+  ".ods",
+  ".psd",
+  ".ai",
+  ".sketch",
+  ".fig",
+  ".heic",
+  ".heif",
+  // Archives, columnar data, models and compressed payloads.
+  ".tar",
+  ".zst",
+  ".br",
+  ".lz4",
+  ".parquet",
+  ".avro",
+  ".orc",
+  ".pkl",
+  ".npy",
+  ".npz",
+  ".onnx",
+  ".pt",
+  ".safetensors",
+  ".gguf",
+  ".sqlite3",
+  ".avi",
+  ".mkv",
+  ".flac",
+  ".aac",
+  ".m4a",
+  ".ttc"
+]);
+function isBinaryPayloadPath(path) {
+  return BINARY_EXTENSIONS.has(extname(path).toLowerCase());
+}
+function payloadEncodingFor(path) {
+  return isBinaryPayloadPath(path) ? "latin1" : "utf-8";
+}
+function normalizeLineEndings(content) {
+  return content.replace(/\r\n?/g, "\n");
+}
+var EXECUTABLE_SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".sh", ".bash", ".zsh"]);
+function executableModeFor(path) {
+  return EXECUTABLE_SCRIPT_EXTENSIONS.has(extname(path).toLowerCase()) ? 493 : void 0;
+}
+function stripBom(text) {
+  return text.startsWith(UTF8_BOM) ? text.slice(UTF8_BOM.length) : text;
+}
+var LESSONS_GRAPH_PATH = ".agentsmesh/lessons/lessons.json";
 function graphFilePath(projectRoot) {
-  return resolve(projectRoot, GRAPH_REL_PATH);
+  return resolve(projectRoot, LESSONS_GRAPH_PATH);
 }
 function loadLessonsGraph(projectRoot) {
   const raw = readFileSync(graphFilePath(projectRoot), "utf8");
-  return parseGraph(JSON.parse(raw));
+  return parseGraph(JSON.parse(stripBom(raw)));
 }
 function tryLoadLessonsGraph(projectRoot) {
   if (!existsSync(graphFilePath(projectRoot))) return null;
@@ -139,7 +582,7 @@ function loadLessonsGraphResilient(projectRoot) {
   const path = graphFilePath(projectRoot);
   if (!existsSync(path)) return { status: "absent", graph: null };
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const parsed = JSON.parse(stripBom(readFileSync(path, "utf8")));
     const version = parsed?.version;
     if (typeof version === "number" && version > CURRENT_GRAPH_VERSION) {
       return { status: "newer-version", graph: null, version };
@@ -153,11 +596,37 @@ function loadLessonsGraphResilient(projectRoot) {
     };
   }
 }
+var LessonsGraphReadOnlyError = class extends Error {
+  constructor() {
+    super(
+      `${LESSONS_GRAPH_PATH} is read-only, so nothing was saved. Make it writable (chmod u+w ${LESSONS_GRAPH_PATH}) to change lessons.`
+    );
+    this.name = "LessonsGraphReadOnlyError";
+  }
+};
+function fileMode(path) {
+  try {
+    return statSync(path).mode & 511;
+  } catch {
+    return void 0;
+  }
+}
+function isWritable(path) {
+  try {
+    accessSync(path, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function saveLessonsGraph(projectRoot, graph) {
   const path = graphFilePath(projectRoot);
   mkdirSync(dirname(path), { recursive: true });
+  const mode = fileMode(path);
+  if (mode !== void 0 && !isWritable(path)) throw new LessonsGraphReadOnlyError();
   const tmp = `${path}.${process.pid}.tmp`;
   writeFileSync(tmp, serializeGraph(graph), "utf8");
+  if (mode !== void 0) chmodSync(tmp, mode);
   renameSync(tmp, path);
 }
 function serializeGraph(graph) {
@@ -171,9 +640,9 @@ function canonicalize(value) {
     const entries = Object.entries(value).sort(
       ([a], [b]) => a < b ? -1 : 1
     );
-    const out = {};
-    for (const [k, v] of entries) out[k] = canonicalize(v);
-    return out;
+    const out2 = {};
+    for (const [k, v] of entries) out2[k] = canonicalize(v);
+    return out2;
   }
   return value;
 }
@@ -301,6 +770,27 @@ var UnknownTopicError = class extends Error {
   }
   code = "UNKNOWN_TOPIC";
 };
+var InvalidTopicIdError = class extends Error {
+  constructor(topic) {
+    const slug = topic.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    super(
+      `Topic id ${JSON.stringify(topic)} must be kebab-case (lowercase letters, digits and -)` + (slug.length > 0 ? `, e.g. ${JSON.stringify(slug)}.` : ".")
+    );
+    this.topic = topic;
+    this.name = "InvalidTopicIdError";
+  }
+  code = "INVALID_TOPIC_ID";
+};
+var TopicSummaryRequiredError = class extends Error {
+  constructor(topic) {
+    super(
+      `New topic ${JSON.stringify(topic)} needs a one-line summary (--topic-summary on the CLI, topic_summary over MCP).`
+    );
+    this.topic = topic;
+    this.name = "TopicSummaryRequiredError";
+  }
+  code = "TOPIC_SUMMARY_REQUIRED";
+};
 var RuleTooLongError = class extends Error {
   constructor(length, max) {
     super(
@@ -344,8 +834,8 @@ var Builder = class {
     return this.states.length - 1;
   }
 };
-function isNonLineTerminator(c) {
-  return c !== "\n" && c !== "\r" && c !== "\u2028" && c !== "\u2029";
+function isNonLineTerminator(c2) {
+  return c2 !== "\n" && c2 !== "\r" && c2 !== "\u2028" && c2 !== "\u2029";
 }
 function compileNode(b, node) {
   switch (node.k) {
@@ -362,7 +852,7 @@ function compileNode(b, node) {
     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;
+      const test = node.k === "char" ? (c2) => c2 === node.ch : node.k === "any" ? isNonLineTerminator : node.test;
       b.states[s].chars.push({ test, target: e });
       return { start: s, end: e };
     }
@@ -490,7 +980,7 @@ var UnsupportedRegexError = class extends Error {
 
 // src/lessons/regex-linear/parse-helpers.ts
 var MAX_REPEAT = 1e3;
-var isWord = (c) => /[A-Za-z0-9_]/.test(c);
+var isWord = (c2) => /[A-Za-z0-9_]/.test(c2);
 function expandRepeat(atom, min, max) {
   const items = [];
   for (let k = 0; k < min; k += 1) items.push(atom);
@@ -502,8 +992,8 @@ function expandRepeat(atom, min, max) {
   if (items.length === 0) return { k: "empty" };
   return items.length === 1 ? items[0] : { k: "concat", items };
 }
-function escapeClass(c) {
-  switch (c) {
+function escapeClass(c2) {
+  switch (c2) {
     case "d":
       return (x) => x >= "0" && x <= "9";
     case "D":
@@ -522,8 +1012,11 @@ function escapeClass(c) {
 }
 var HEX2 = /^[0-9a-fA-F]{2}$/;
 var HEX4 = /^[0-9a-fA-F]{4}$/;
-function readUnicodeEscape(src, i, c) {
-  if (c === "x") {
+function readUnicodeEscape(src, i, c2) {
+  if (c2 === "u" && src[i] === "{") {
+    throw new UnsupportedRegexError("\\u{\u2026} code point escapes are not supported; use \\uHHHH");
+  }
+  if (c2 === "x") {
     const hex2 = src.slice(i, i + 2);
     return HEX2.test(hex2) ? { ch: String.fromCharCode(parseInt(hex2, 16)), len: 2 } : { ch: "x", len: 0 };
   }
@@ -543,8 +1036,8 @@ function classEscapeChar(src, i, e) {
   if (e === "x" || e === "u") return readUnicodeEscape(src, i, e);
   return { ch: escapeLiteral(e), len: 0 };
 }
-function escapeLiteral(c) {
-  switch (c) {
+function escapeLiteral(c2) {
+  switch (c2) {
     case "t":
       return "	";
     case "n":
@@ -558,7 +1051,7 @@ function escapeLiteral(c) {
     case "0":
       return "\0";
     default:
-      return c;
+      return c2;
   }
 }
 
@@ -610,27 +1103,27 @@ function parseRegex(src) {
     return { min, max };
   }
   function parseAtom() {
-    const c = peek();
-    if (c === "(") return parseGroup();
-    if (c === "[") return parseClass();
-    if (c === "\\") return parseEscape();
-    if (c === ".") {
+    const c2 = peek();
+    if (c2 === "(") return parseGroup();
+    if (c2 === "[") return parseClass2();
+    if (c2 === "\\") return parseEscape();
+    if (c2 === ".") {
       i += 1;
       return { k: "any" };
     }
-    if (c === "^") {
+    if (c2 === "^") {
       i += 1;
       return { k: "assert", kind: "start" };
     }
-    if (c === "$") {
+    if (c2 === "$") {
       i += 1;
       return { k: "assert", kind: "end" };
     }
-    if (c === void 0 || c === "*" || c === "+" || c === "?" || c === ")") {
-      throw new UnsupportedRegexError(`Unexpected '${c ?? "<end>"}' in pattern`);
+    if (c2 === void 0 || c2 === "*" || c2 === "+" || c2 === "?" || c2 === ")") {
+      throw new UnsupportedRegexError(`Unexpected '${c2 ?? "<end>"}' in pattern`);
     }
     i += 1;
-    return { k: "char", ch: c };
+    return { k: "char", ch: c2 };
   }
   function parseGroup() {
     i += 1;
@@ -655,23 +1148,23 @@ function parseRegex(src) {
   }
   function parseEscape() {
     i += 1;
-    const c = peek();
-    if (c === void 0) throw new UnsupportedRegexError("Trailing backslash");
-    if (/[1-9]/.test(c) || c === "k")
+    const c2 = peek();
+    if (c2 === void 0) throw new UnsupportedRegexError("Trailing backslash");
+    if (/[1-9]/.test(c2) || c2 === "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 (c2 === "b") return { k: "assert", kind: "wordB" };
+    if (c2 === "B") return { k: "assert", kind: "nonWordB" };
+    const cls = escapeClass(c2);
     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);
+    if (c2 === "x" || c2 === "u" || c2 === "c") {
+      const { ch, len } = c2 === "c" ? readControlEscape(src, i) : readUnicodeEscape(src, i, c2);
       i += len;
       return { k: "char", ch };
     }
-    return { k: "char", ch: escapeLiteral(c) };
+    return { k: "char", ch: escapeLiteral(c2) };
   }
-  function parseClass() {
+  function parseClass2() {
     i += 1;
     const negate = peek() === "^";
     if (negate) i += 1;
@@ -681,8 +1174,8 @@ function parseRegex(src) {
     }
     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 };
+    const base = (c2) => tests.some((t) => t(c2));
+    return { k: "class", test: negate ? (c2) => !base(c2) : base };
   }
   function parseClassMember() {
     let lo;
@@ -711,12 +1204,12 @@ function parseRegex(src) {
       }
       const a = lo.codePointAt(0);
       const b = hi.codePointAt(0);
-      return (c) => {
-        const p = c.codePointAt(0);
+      return (c2) => {
+        const p = c2.codePointAt(0);
         return p >= a && p <= b;
       };
     }
-    return (c) => c === lo;
+    return (c2) => c2 === lo;
   }
   const ast = parseAlt();
   if (i !== src.length) throw new UnsupportedRegexError(`Unexpected '${peek()}' at ${i}`);
@@ -784,6 +1277,9 @@ function isBroadCommandPattern(pattern) {
   }
   return hits > COMMAND_PROBE_CORPUS.length * BROAD_HIT_RATIO;
 }
+function codePointLength(text) {
+  return [...text].length;
+}
 
 // src/lessons/ranking-text.ts
 var K1 = 1.5;
@@ -810,7 +1306,7 @@ var STOP = /* @__PURE__ */ new Set([
   "its",
   "must"
 ]);
-function tokenize(text) {
+function tokenize2(text) {
   return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 2 && !STOP.has(t));
 }
 function queryTerms(query) {
@@ -818,7 +1314,7 @@ function queryTerms(query) {
   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(" "));
+  return tokenize2(parts.join(" "));
 }
 function buildCorpus(graph) {
   const docs = [];
@@ -827,7 +1323,7 @@ function buildCorpus(graph) {
   let n = 0;
   for (const lesson of Object.values(graph.lessons)) {
     if (lesson.status !== "active") continue;
-    const toks = tokenize(lesson.rule);
+    const toks = tokenize2(lesson.rule);
     n += 1;
     total += toks.length;
     docs.push(toks.length);
@@ -839,7 +1335,7 @@ function buildCorpus(graph) {
   return { idf, avgdl: total / N || 1 };
 }
 function bm25(terms, ruleText, corpus) {
-  const toks = tokenize(ruleText);
+  const toks = tokenize2(ruleText);
   const dl = toks.length || 1;
   const tf = /* @__PURE__ */ new Map();
   for (const t of toks) tf.set(t, (tf.get(t) ?? 0) + 1);
@@ -856,7 +1352,7 @@ function bm25(terms, ruleText, corpus) {
 // src/lessons/keyword-signal.ts
 var MAX_RECOMMENDED_KEYWORD_TOKENS = 5;
 function isLowSignalKeyword(pattern) {
-  return tokenize(pattern).length > MAX_RECOMMENDED_KEYWORD_TOKENS;
+  return tokenize2(pattern).length > MAX_RECOMMENDED_KEYWORD_TOKENS;
 }
 function splitRawTokens(pattern) {
   return pattern.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
@@ -864,23 +1360,23 @@ function splitRawTokens(pattern) {
 function keywordNeedleLosesTokens(pattern) {
   const raw = splitRawTokens(pattern);
   if (raw.length < 2) return false;
-  return tokenize(pattern).length !== raw.length;
+  return tokenize2(pattern).length !== raw.length;
 }
 
 // src/lessons/trigger-effectiveness.ts
 function ineffectiveTriggers(graph, triggerIds) {
-  const out = [];
+  const out2 = [];
   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 });
+    if (reason !== null) out2.push({ id, kind: trigger.kind, pattern: trigger.pattern, reason });
   }
-  return out;
+  return out2;
 }
 function ineffectiveReason(kind, pattern) {
   if (kind === "keyword") {
-    if (tokenize(pattern).length === 0) {
+    if (tokenize2(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)) {
@@ -913,9 +1409,19 @@ function blockingDeadTriggers(graph, triggerIds) {
 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);
+  const length = codePointLength(trimmed);
+  if (length > MAX_RULE_LENGTH) throw new RuleTooLongError(length, MAX_RULE_LENGTH);
   return trimmed;
 }
+function ensureTopic(graph, topic, options) {
+  if (!/^[a-z0-9-]+$/.test(topic)) throw new InvalidTopicIdError(topic);
+  if (graph.topics[topic] !== void 0) return false;
+  if (options.allowNewTopic !== true) throw new UnknownTopicError(topic);
+  const summary = options.topicSummary?.trim() ?? "";
+  if (summary.length === 0) throw new TopicSummaryRequiredError(topic);
+  graph.topics[topic] = { summary };
+  return true;
+}
 function skipsTriggerGates(input, options) {
   return options.allowNoTrigger === true || input.scope === "always";
 }
@@ -931,16 +1437,40 @@ function assertTriggerInputs(input, options, existingTriggerCount) {
     if (broad !== void 0) throw new BroadCommandPatternError(broad);
   }
 }
-function assertRecallable(graph, resultingTriggers) {
-  const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
-  if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
-    throw new UnrecallableLessonError(blockingDead);
-  }
-}
-
+function dropDeadCommandTriggers(graph, merged, options) {
+  if (options.allowNoTrigger === true) return { ...merged, dropped: [] };
+  const dropped = ineffectiveTriggers(graph, merged.triggerIds).filter(
+    (t) => t.kind === "command_pattern"
+  );
+  const dead = new Set(dropped.map((t) => t.id));
+  for (const id of merged.newTriggerIds) if (dead.has(id)) delete graph.triggers[id];
+  return {
+    triggerIds: merged.triggerIds.filter((id) => !dead.has(id)),
+    newTriggerIds: merged.newTriggerIds.filter((id) => !dead.has(id)),
+    dropped
+  };
+}
+function deadCommandWarning(trigger) {
+  return {
+    code: "DEAD_COMMAND_PATTERN",
+    message: `Dropped command trigger ${JSON.stringify(trigger.pattern)} (not saved): ${trigger.reason}.`
+  };
+}
+function assertRecallable(graph, resultingTriggers, dropped) {
+  const blockingDead = blockingDeadTriggers(graph, resultingTriggers);
+  const dead = [...dropped, ...blockingDead];
+  if (dead.length > 0 && blockingDead.length === resultingTriggers.length) {
+    throw new UnrecallableLessonError(dead);
+  }
+}
+
 // src/lessons/glob-breadth.ts
 var WILDCARD = /[*?[\]]/;
+function isNegatedGlob(pattern) {
+  return pattern.startsWith("!");
+}
 function globNarrowness(pattern) {
+  if (isNegatedGlob(pattern)) return 0;
   const segments = pattern.replaceAll("\\", "/").split("/").filter((segment) => segment !== "" && segment !== ".");
   if (segments.length === 0) return 0;
   let literal = 0;
@@ -955,6 +1485,258 @@ var BROAD_GLOB_NARROWNESS = 0.34;
 function isBroadFileGlob(pattern) {
   return globNarrowness(pattern) < BROAD_GLOB_NARROWNESS;
 }
+
+// src/lessons/glob-dp.ts
+var isDotSegment = (s) => s === "." || s === "..";
+function matchSegments(alt, segments, work) {
+  const n = segments.length;
+  let next = new Uint8Array(n + 1);
+  next[n] = 1;
+  for (let i = alt.length - 1; i >= 0; i -= 1) {
+    const seg = alt[i];
+    const cur = new Uint8Array(n + 1);
+    for (let j = n; j >= 0; j -= 1) {
+      if (--work.remaining <= 0) return false;
+      if (seg.k === "globstar") {
+        const eat = j < n && !isDotSegment(segments[j]) && (cur[j + 1] === 1 || next[j + 1] === 1);
+        cur[j] = !seg.min1 && next[j] === 1 || eat ? 1 : 0;
+      } else if (j < n && next[j + 1] === 1) {
+        const text = segments[j];
+        const ok = seg.literal !== null ? text === seg.literal : matchSegment(seg, text, j < n - 1, work);
+        cur[j] = ok ? 1 : 0;
+      }
+    }
+    if (seg.k === "globstar" && i >= 1 && tailMatchesNothing(alt, i + 1)) cur[n] = 1;
+    next = cur;
+  }
+  return next[0] === 1;
+}
+function tailMatchesNothing(alt, from) {
+  const empty = alt[from];
+  const rest = alt[from + 1];
+  if (empty?.k !== "segment" || !empty.matchesEmpty) return false;
+  return rest === void 0 || rest.k === "globstar" && !rest.min1 && from + 2 === alt.length;
+}
+function matchSegment(seg, text, followedBySlash, work) {
+  if (seg.guarded && (isDotSegment(text) || text === "" && !followedBySlash)) return false;
+  const tokens = seg.tokens;
+  const len = text.length;
+  let next = new Uint8Array(len + 1);
+  next[len] = 1;
+  for (let k = tokens.length - 1; k >= 0; k -= 1) {
+    const tok = tokens[k];
+    const cur = new Uint8Array(len + 1);
+    work.remaining -= len + 1;
+    if (work.remaining <= 0) return false;
+    for (let c2 = len; c2 >= 0; c2 -= 1) {
+      cur[c2] = tokenMatches(tok, text, c2, next, cur) ? 1 : 0;
+    }
+    next = cur;
+  }
+  return next[0] === 1;
+}
+function tokenMatches(tok, text, c2, next, cur) {
+  const ch = text[c2];
+  switch (tok.k) {
+    case "star":
+      return next[c2] === 1 || ch !== void 0 && cur[c2 + 1] === 1;
+    case "one":
+      return ch !== void 0 && next[c2 + 1] === 1;
+    case "lit":
+      return ch === tok.ch && next[c2 + 1] === 1;
+    case "class":
+      return ch !== void 0 && tok.test(ch) && next[c2 + 1] === 1 || tok.literal !== null && text.startsWith(tok.literal, c2) && next[c2 + tok.literal.length] === 1;
+  }
+}
+
+// src/lessons/glob-safety.ts
+var MAX_GLOB_PATH_LENGTH = 4096;
+var MATCH_WORK_LIMIT = 2e5;
+var CACHE_LIMIT = 2e3;
+var cache2 = /* @__PURE__ */ new Map();
+function unsafeGlobFinding(triggerId, trigger) {
+  if (trigger.kind !== "file_glob" || trigger.pattern.includes("\\")) return null;
+  const reason = parseGlob(trigger.pattern);
+  if (typeof reason !== "string") return null;
+  return {
+    level: "error",
+    code: "UNSAFE_GLOB_PATTERN",
+    message: `Trigger "${triggerId}" has a file_glob outside the safe glob subset (${trigger.pattern.slice(0, 120)}): ${reason}. Recall treats it as a non-match. Use only *, **, ?, [...] and {a,b}.`,
+    triggerId
+  };
+}
+function getGlobMatcher(pattern) {
+  const hit = cache2.get(pattern);
+  if (hit !== void 0) return hit;
+  if (cache2.size >= CACHE_LIMIT) cache2.clear();
+  const composed = pattern.normalize("NFC");
+  const parsed = parseGlob(composed);
+  const matcher = typeof parsed === "string" ? null : build(composed, parsed);
+  cache2.set(pattern, matcher);
+  return matcher;
+}
+function build(pattern, parsed) {
+  const alts = parsed.alternatives.map(prepare);
+  return {
+    test(rawPath, budget) {
+      const path = rawPath.normalize("NFC");
+      if (path === pattern) return true;
+      if (path === "" || path.length > MAX_GLOB_PATH_LENGTH) return false;
+      const live = alts.filter((a) => mayMatch(a, path));
+      if (live.length === 0) return parsed.negated;
+      const limit = Math.min(MATCH_WORK_LIMIT, budget?.remaining ?? MATCH_WORK_LIMIT);
+      const work = { remaining: limit };
+      const segments = path.split("/");
+      const hit = live.some((a) => matchSegments(a.alt, segments, work));
+      if (budget !== void 0) budget.remaining -= limit - work.remaining;
+      return work.remaining > 0 && hit !== parsed.negated;
+    }
+  };
+}
+function mayMatch({ head, tail }, path) {
+  if (!path.endsWith(tail)) return false;
+  if (head === null) return true;
+  return path.startsWith(head) && (path.length === head.length || path[head.length] === "/");
+}
+function prepare(alt) {
+  const first = alt[0];
+  const last = alt[alt.length - 1];
+  let tail = "";
+  if (last?.k === "segment" && !last.matchesEmpty) {
+    for (let k = last.tokens.length - 1; k >= 0; k -= 1) {
+      const tok = last.tokens[k];
+      if (tok.k !== "lit") break;
+      tail = tok.ch + tail;
+    }
+  }
+  return { alt, head: first?.k === "segment" ? first.literal : null, tail };
+}
+
+// src/lessons/file-glob-liveness.ts
+function missingGlobState(pattern, history) {
+  const matcher = getGlobMatcher(pattern);
+  if (history === null || matcher === null) return "pending";
+  const matchesAny = (paths) => [...paths].some((p) => matcher.test(p));
+  if (matchesAny(history.tracked)) return "live";
+  if (matchesAny(history.renamedAway)) return "dead";
+  if (!picomatch.scan(pattern).isGlob && matchesAny(history.deleted)) return "dead";
+  return "pending";
+}
+var MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+function runGit(cwd, args, timeoutMs) {
+  const r = spawnSync("git", [...args], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: MAX_OUTPUT_BYTES,
+    timeout: timeoutMs,
+    windowsHide: true
+  });
+  const status = r.error === void 0 ? r.status ?? -1 : -1;
+  return { status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+// src/lessons/git-path-history.ts
+var GIT_SCAN_TIMEOUT_MS = 3e3;
+var cache3 = /* @__PURE__ */ new Map();
+function readGitPathHistory(projectRoot) {
+  if (!cache3.has(projectRoot)) cache3.set(projectRoot, scanGitPathHistory(projectRoot));
+  return cache3.get(projectRoot) ?? null;
+}
+var LOG_ARGS = [
+  "log",
+  "HEAD",
+  "--relative",
+  "-M",
+  "--diff-filter=DR",
+  "--name-status",
+  "-z",
+  "--no-color",
+  "--no-show-signature",
+  "--pretty=format:"
+];
+function scanGitPathHistory(projectRoot, timeoutMs = GIT_SCAN_TIMEOUT_MS) {
+  const tracked = runGit(projectRoot, ["ls-files", "-z"], timeoutMs);
+  if (tracked.status !== 0) return null;
+  const log = runGit(projectRoot, LOG_ARGS, timeoutMs);
+  if (log.status !== 0) return null;
+  return {
+    tracked: new Set(tracked.stdout.split("\0").filter(Boolean)),
+    ...parseRemovals(log.stdout)
+  };
+}
+function parseRemovals(out2) {
+  const deleted = /* @__PURE__ */ new Set();
+  const renamedAway = /* @__PURE__ */ new Set();
+  const tokens = out2.split("\0");
+  for (let i = 0; i < tokens.length; i += 1) {
+    const status = tokens[i] ?? "";
+    const path = tokens[i + 1] ?? "";
+    if (status.startsWith("D")) {
+      if (path !== "") deleted.add(path);
+      i += 1;
+    } else if (status.startsWith("R")) {
+      if (path !== "") renamedAway.add(path);
+      i += 2;
+    }
+  }
+  return { deleted, renamedAway };
+}
+var BASE_REL = ".agentsmesh/lessons";
+function lessonsPaths(projectRoot) {
+  const base = join(projectRoot, BASE_REL);
+  return {
+    base,
+    graph: join(base, "lessons.json"),
+    config: join(base, "config.json"),
+    journal: join(base, "journal.md"),
+    index: join(base, "index.yaml"),
+    topicsDir: join(base, "topics")
+  };
+}
+function toRelPath(projectRoot, absolute) {
+  return relative(projectRoot, absolute).split(sep).join("/");
+}
+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> --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>\`.
+
+**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
+
+// src/lessons/project-files.ts
+var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
+var MAX_FILES = 2e5;
+function projectFilesOf(paths, gitHistory) {
+  return Object.assign(new Set(paths), { gitHistory });
+}
+function gitHistoryOf(paths) {
+  return paths.gitHistory?.() ?? null;
+}
+function listProjectFiles(projectRoot, maxFiles = MAX_FILES) {
+  const out2 = /* @__PURE__ */ new Set();
+  try {
+    const stack = [projectRoot];
+    while (stack.length > 0) {
+      const dir = stack.pop();
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          if (!SKIP_DIRS.has(entry.name)) stack.push(join(dir, entry.name));
+        } else if (entry.isFile()) {
+          out2.add(toRelPath(projectRoot, join(dir, entry.name)));
+          if (out2.size > maxFiles) return null;
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+  return projectFilesOf(out2, () => readGitPathHistory(projectRoot));
+}
+
+// src/lessons/validate-liveness.ts
 function activeTriggerIds(graph) {
   const ids = /* @__PURE__ */ new Set();
   for (const lesson of Object.values(graph.lessons)) {
@@ -963,32 +1745,42 @@ function activeTriggerIds(graph) {
   }
   return ids;
 }
-function deadFileGlobIds(graph, knownPaths) {
-  const active = activeTriggerIds(graph);
+function fileGlobLiveness(graph, knownPaths, triggerIds) {
+  const active = triggerIds === void 0 ? activeTriggerIds(graph) : new Set(triggerIds);
   const paths = [...knownPaths];
-  const dead = /* @__PURE__ */ new Set();
+  const missing = [];
   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);
+    if (trigger.kind !== "file_glob" || !active.has(triggerId)) continue;
+    const matcher = getGlobMatcher(trigger.pattern);
+    if (matcher === null) continue;
+    if (!paths.some((p) => matcher.test(p))) missing.push([triggerId, trigger.pattern]);
   }
-  return dead;
+  const dead = /* @__PURE__ */ new Set();
+  const pending = /* @__PURE__ */ new Set();
+  if (missing.length === 0) return { dead, pending };
+  const history = gitHistoryOf(knownPaths);
+  for (const [triggerId, pattern] of missing) {
+    const state = missingGlobState(pattern, history);
+    if (state === "dead") dead.add(triggerId);
+    else if (state === "pending") pending.add(triggerId);
+  }
+  return { dead, pending };
 }
 function collectDeadFileGlobs(graph, findings, knownPaths) {
-  for (const triggerId of deadFileGlobIds(graph, knownPaths)) {
+  for (const triggerId of fileGlobLiveness(graph, knownPaths).dead) {
     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\`.`,
+      message: `file_glob trigger "${triggerId}" (${graph.triggers[triggerId]?.pattern ?? ""}) matches no file, and git history shows its path was renamed or deleted \u2014 the lesson is unreachable via this trigger. Re-point it at the current path, or detach it with \`lessons untrigger\`, or run \`lessons prune --apply\`.`,
       triggerId
     });
   }
 }
 function fileGlobMatchCount(pattern, knownPaths) {
-  const isMatch = picomatch(pattern, { dot: true });
+  const matcher = getGlobMatcher(pattern);
+  if (matcher === null) return 0;
   let n = 0;
-  for (const p of knownPaths) if (isMatch(p)) n += 1;
+  for (const p of knownPaths) if (matcher.test(p)) n += 1;
   return n;
 }
 var RUNNER_ANCHOR = /^\^(pnpm|npm|npx|yarn|bun)\b/;
@@ -1040,10 +1832,10 @@ 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 === "*" || p === "**" || isNegatedGlob(p)) return true;
   if (!p.includes("**")) return false;
-  const basename5 = p.slice(p.lastIndexOf("/") + 1);
-  return basename5.startsWith("*");
+  const basename6 = p.slice(p.lastIndexOf("/") + 1);
+  return basename6.startsWith("*");
 }
 function inspectCapturedLesson(graph, lessonId, knownPaths) {
   const lesson = graph.lessons[lessonId];
@@ -1084,12 +1876,19 @@ function inspectCapturedLesson(graph, lessonId, knownPaths) {
     });
   }
   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);
+    const { dead, pending } = fileGlobLiveness(graph, knownPaths, lesson.triggers);
+    const deadHere = patternsIn(graph, lesson.triggers, dead);
     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.`
+        message: `Lesson "${lessonId}" has file_glob trigger(s) (${deadHere.join(", ")}) that match no file, and git history shows the path was renamed or deleted \u2014 likely a rename. Re-point them at the current path, or the lesson is unreachable via those globs.`
+      });
+    }
+    const pendingHere = patternsIn(graph, lesson.triggers, pending);
+    if (pendingHere.length > 0) {
+      warnings.push({
+        code: "PENDING_GLOB",
+        message: `Lesson "${lessonId}" has file_glob trigger(s) (${pendingHere.join(", ")}) whose path does not exist yet \u2014 the trigger will fire once it does, so it is kept. If the path is a typo, re-point it.`
       });
     }
     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);
@@ -1102,18 +1901,21 @@ function inspectCapturedLesson(graph, lessonId, knownPaths) {
   }
   return warnings;
 }
+function patternsIn(graph, ids, keep) {
+  return ids.filter((id) => keep.has(id)).map((id) => graph.triggers[id]?.pattern).filter((p) => p !== void 0);
+}
 
 // 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));
+  const subjectTokens = new Set(tokenize2(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));
+    const otherTokens = new Set(tokenize2(other.rule));
     if (otherTokens.size === 0) continue;
     const score = jaccard(subjectTokens, otherTokens);
     if (score >= NEAR_DUPLICATE_THRESHOLD && (best === null || score > best.score)) {
@@ -1131,6 +1933,26 @@ function jaccard(a, b) {
   for (const t of a) if (b.has(t)) intersection += 1;
   return intersection / (a.size + b.size - intersection);
 }
+var LEFTOVER = /\.(?:\d+\.tmp|[\w-]+\.stale)$/;
+var LEFTOVER_AGE_MS = 6e4;
+function sweepLessonsLeftovers(projectRoot, now = Date.now()) {
+  const dir = lessonsPaths(projectRoot).base;
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (!LEFTOVER.test(name)) continue;
+    const path = join(dir, name);
+    try {
+      if (now - statSync(path).mtimeMs > LEFTOVER_AGE_MS)
+        rmSync(path, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
 
 // src/core/errors.ts
 var AgentsMeshError = class extends Error {
@@ -1169,62 +1991,375 @@ var FileSystemError = class extends AgentsMeshError {
     this.errnoCode = options?.errnoCode;
   }
 };
+var execFileAsync = promisify(execFile);
+var PS_TIMEOUT_MS = 2e3;
+var self;
+async function processIdentity(pid, platform = process.platform) {
+  if (!Number.isInteger(pid) || pid <= 0 || platform === "win32") return null;
+  try {
+    return platform === "linux" ? await linuxIdentity(pid) : await psIdentity(pid);
+  } catch {
+    return null;
+  }
+}
+function selfIdentity() {
+  self ??= processIdentity(process.pid);
+  return self;
+}
+function linuxStartIdentity(stat3, bootId) {
+  const start = stat3.slice(stat3.lastIndexOf(")") + 2).split(" ")[19];
+  const boot = bootId.trim();
+  if (start === void 0 || !/^\d+$/.test(start) || boot === "") return null;
+  return `${boot}:${start}`;
+}
+async function linuxIdentity(pid) {
+  const [stat3, bootId] = await Promise.all([
+    readFile(`/proc/${pid}/stat`, "utf-8"),
+    readFile("/proc/sys/kernel/random/boot_id", "utf-8")
+  ]);
+  return linuxStartIdentity(stat3, bootId);
+}
+async function psIdentity(pid) {
+  const { stdout } = await execFileAsync("ps", ["-o", "lstart=", "-p", String(pid)], {
+    env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+    timeout: PS_TIMEOUT_MS
+  });
+  const start = stdout.trim();
+  return start === "" ? null : start;
+}
+var TRANSIENT_CODES = /* @__PURE__ */ new Set(["EPERM", "EACCES", "EBUSY"]);
+var ATTEMPTS = 5;
+var BASE_DELAY_MS = 25;
+var pause = new Int32Array(new SharedArrayBuffer(4));
+function isTransientFsError(err) {
+  const code = err?.code;
+  return typeof code === "string" && TRANSIENT_CODES.has(code);
+}
+async function retryTransient(op) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await op();
+    } catch (err) {
+      if (!isTransientFsError(err) || attempt >= ATTEMPTS) throw err;
+      await setTimeout(BASE_DELAY_MS * 2 ** (attempt - 1));
+    }
+  }
+}
+function retryTransientSync(op) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return op();
+    } catch (err) {
+      if (!isTransientFsError(err) || attempt >= ATTEMPTS) throw err;
+      Atomics.wait(pause, 0, 0, BASE_DELAY_MS * 2 ** (attempt - 1));
+    }
+  }
+}
+var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY", "EEXIST"]);
+async function renameWithRetry(from, to, options = {}) {
+  const attempts = options.attempts ?? 5;
+  const delayMs = options.delayMs ?? 50;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await rename(from, to);
+      return;
+    } catch (err) {
+      const code = err.code;
+      const transient = code !== void 0 && TRANSIENT_RENAME_CODES.has(code);
+      if (!transient || attempt >= attempts - 1) throw err;
+      await setTimeout(delayMs * 2 ** attempt);
+    }
+  }
+}
+var HOLDER_FILE = "holder.json";
+var OWNER_PREFIX = "owner-";
+var YOUNG_LOCK_GRACE_MS = 2e3;
+var PID_REUSE_PROBE_AFTER_MS = 2e3;
+function ownerPath(lockPath, token) {
+  return join(lockPath, `${OWNER_PREFIX}${token}`);
+}
+function holderPath(lockPath) {
+  return join(lockPath, HOLDER_FILE);
+}
+function errorCode(err) {
+  return err?.code;
+}
+var LockPathNotFolderError = class extends Error {
+  constructor(lockPath) {
+    super(
+      `${lockPath.replaceAll("\\", "/")} is a file, but agentsmesh keeps its lock there as a folder. Delete it and run the command again.`
+    );
+    this.name = "LockPathNotFolderError";
+  }
+};
+async function ownerTokens(dir) {
+  try {
+    const entries = await readdir(dir);
+    return entries.filter((e) => e.startsWith(OWNER_PREFIX)).map((e) => e.slice(OWNER_PREFIX.length));
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return null;
+    if (errorCode(err) === "ENOTDIR") throw new LockPathNotFolderError(dir);
+    throw err;
+  }
+}
+async function readHolderRaw(dir) {
+  return readFile(holderPath(dir), "utf-8").catch(() => null);
+}
+function holderToken(raw) {
+  return raw === null ? void 0 : parseMetadata(raw)?.token;
+}
+async function inspectLock(lockPath) {
+  const tokens = await ownerTokens(lockPath);
+  if (tokens === null) return { kind: "gone" };
+  const raw = await readHolderRaw(lockPath);
+  const meta = raw === null ? null : parseMetadata(raw);
+  const [only] = tokens;
+  if (meta && tokens.length === 1 && only !== void 0 && meta.token === only) {
+    return { kind: "held", token: only, meta };
+  }
+  if (meta && raw !== null && tokens.length === 0 && meta.token === void 0) {
+    return { kind: "legacy", meta, raw };
+  }
+  const age = await dirAgeMs(lockPath);
+  if (age === null) return { kind: "gone" };
+  const young = age < YOUNG_LOCK_GRACE_MS && age >= -3e5;
+  return young ? { kind: "young" } : { kind: "orphan", tokens, raw };
+}
+async function isStale(meta, staleMs, cache4) {
+  const age = Date.now() - meta.started;
+  if (age > staleMs || age < -3e5) return true;
+  if (meta.hostname && meta.hostname !== hostname()) return false;
+  if (!isProcessAlive(meta.pid)) return true;
+  if (meta.procStart === void 0 || age < PID_REUSE_PROBE_AFTER_MS) return false;
+  return pidReused(meta.pid, meta.procStart, cache4);
+}
+function describeHolder(state) {
+  if (state.kind !== "held" && state.kind !== "legacy") return "unknown (unreadable lock metadata)";
+  const { meta } = state;
+  const host = meta.hostname ? `${meta.hostname}:` : "";
+  return `${host}pid ${meta.pid} (running ${Math.max(0, Date.now() - meta.started)}ms)`;
+}
+async function dirAgeMs(lockPath) {
+  try {
+    return Date.now() - (await stat(lockPath)).mtimeMs;
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return null;
+    throw err;
+  }
+}
+function pidReused(pid, recorded, cache4) {
+  const key = `${pid}:${recorded}`;
+  let verdict = cache4.get(key);
+  if (!verdict) {
+    verdict = processIdentity(pid).then((current) => current !== null && current !== recorded);
+    cache4.set(key, verdict);
+  }
+  return verdict;
+}
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return errorCode(err) === "EPERM";
+  }
+}
+function parseMetadata(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof value !== "object" || value === null) return null;
+  const v = value;
+  if (typeof v.pid !== "number" || typeof v.started !== "number") return null;
+  const optionalText = (x) => x === void 0 || typeof x === "string";
+  const textOk = [v.hostname, v.token, v.procStart].every(optionalText);
+  return textOk ? value : null;
+}
+
+// src/utils/filesystem/process-lock-ops.ts
+async function tryAcquire(lockPath, meta) {
+  try {
+    await mkdir(lockPath);
+  } catch (err) {
+    if (errorCode(err) === "EEXIST") return false;
+    throw err;
+  }
+  const owner = ownerPath(lockPath, meta.token);
+  let writingHolder = false;
+  try {
+    await mkdir(owner);
+    if ((await ownerTokens(lockPath))?.length !== 1) return await backOff(lockPath, owner);
+    writingHolder = true;
+    await writeFile(holderPath(lockPath), JSON.stringify(meta), { encoding: "utf-8", flag: "wx" });
+  } catch (err) {
+    const code = errorCode(err);
+    if (code === "ENOENT" || code === "EEXIST") return backOff(lockPath, owner);
+    if (writingHolder) await rm(holderPath(lockPath), { force: true }).catch(() => {
+    });
+    await backOff(lockPath, owner);
+    throw err;
+  }
+  if (existsSync(owner)) return true;
+  await teardown(lockPath, [meta.token]);
+  return false;
+}
+function releaseOwnedSync(lockPath, token) {
+  try {
+    rmdirSync(ownerPath(lockPath, token));
+  } catch {
+    return;
+  }
+  try {
+    if (holderToken(readFileSync(holderPath(lockPath), "utf-8")) === token) {
+      unlinkSync(holderPath(lockPath));
+    }
+  } catch {
+  }
+  try {
+    rmdirSync(lockPath);
+  } catch {
+  }
+}
+async function evict(lockPath, state) {
+  if (state.kind === "held") return evictOwners(lockPath, [state.token]);
+  if (state.kind === "orphan" && state.tokens.length > 0) {
+    return evictOwners(lockPath, state.tokens);
+  }
+  if (state.kind === "legacy" || state.kind === "orphan") return dropUnowned(lockPath, state.raw);
+}
+async function evictOwners(lockPath, tokens) {
+  const removed = [];
+  for (const token of tokens) {
+    if (await removeOwner(lockPath, token)) removed.push(token);
+  }
+  if (removed.length > 0) await teardown(lockPath, removed);
+}
+async function removeOwner(lockPath, token) {
+  try {
+    await retryTransient(() => rmdir(ownerPath(lockPath, token)));
+    return true;
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return false;
+    throw err;
+  }
+}
+async function teardown(lockPath, tokens) {
+  const token = holderToken(await readHolderRaw(lockPath));
+  if (token !== void 0 && tokens.includes(token)) {
+    await unlink(holderPath(lockPath)).catch(() => {
+    });
+  }
+  await rmdir(lockPath).catch(() => {
+  });
+}
+async function dropUnowned(lockPath, judgedRaw) {
+  const aside = `${lockPath}.${randomUUID()}.stale`;
+  try {
+    await renameWithRetry(lockPath, aside);
+  } catch (err) {
+    if (errorCode(err) === "ENOENT") return;
+    throw err;
+  }
+  const owners = await ownerTokens(aside);
+  if (owners?.length !== 0 || await readHolderRaw(aside) !== judgedRaw) {
+    return putBack(aside, lockPath);
+  }
+  try {
+    await rm(aside, { recursive: true, force: true });
+  } catch (err) {
+    await putBack(aside, lockPath);
+    throw err;
+  }
+}
+async function putBack(aside, lockPath) {
+  await rename(aside, lockPath).catch(() => {
+  });
+}
+async function backOff(lockPath, owner) {
+  await rmdir(owner).catch(() => {
+  });
+  await rmdir(lockPath).catch(() => {
+  });
+  return false;
+}
 
 // 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;
+var MAX_IMMEDIATE_RETRIES = 100;
+var MAX_TRANSIENT_ERRORS = 5;
 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;
+  const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
   await mkdir(dirname(lockPath), { recursive: true });
+  const procStart = await selfIdentity();
+  const probes = /* @__PURE__ */ new Map();
   let attempt = 0;
+  let immediate = 0;
+  const waitingSince = Date.now();
+  let noticed = false;
+  let transient = 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 });
+    let state;
+    try {
+      const holder = newHolder(procStart);
+      if (await tryAcquire(lockPath, holder)) return holdLock(lockPath, holder.token);
+      state = await inspectLock(lockPath);
+      transient = 0;
+    } catch (err) {
+      if (!isTransientFsError(err) || ++transient >= MAX_TRANSIENT_ERRORS) throw err;
+      await setTimeout(lockRetryDelayMs(transient, opts));
+      continue;
+    }
+    if (immediate < MAX_IMMEDIATE_RETRIES && await clearedNow(lockPath, state, staleMs, probes)) {
+      immediate++;
       continue;
     }
     if (attempt >= retries) {
-      const holder = existing === "young" ? null : existing;
-      throw new LockAcquisitionError(lockPath, describeHolder(holder), { label: opts.label });
+      throw new LockAcquisitionError(lockPath, describeHolder(state), { label: opts.label });
     }
     attempt++;
-    await setTimeout(delay);
+    immediate = 0;
+    if (!noticed && opts.onWait && Date.now() - waitingSince >= (opts.waitNoticeMs ?? 2e3)) {
+      noticed = true;
+      opts.onWait(describeHolder(state));
+    }
+    await setTimeout(lockRetryDelayMs(attempt, opts));
   }
 }
-async function tryAcquire(lockPath) {
-  try {
-    await mkdir(lockPath, { recursive: false });
-  } catch (err) {
-    if (err.code === "EEXIST") return null;
-    throw err;
-  }
-  const metadataPath = join(lockPath, "holder.json");
-  const metadata = {
+function lockRetryDelayMs(attempt, opts, random = Math.random) {
+  const base = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+  const cap = Math.max(base, opts.maxRetryDelayMs ?? base);
+  const delay = Math.min(cap, base * 2 ** (attempt - 1));
+  return opts.jitter ? delay * (0.5 + random() * 0.5) : delay;
+}
+async function clearedNow(lockPath, state, staleMs, probes) {
+  if (state.kind === "gone") return true;
+  if (state.kind === "young") return false;
+  if (state.kind !== "orphan" && !await isStale(state.meta, staleMs, probes)) return false;
+  await evict(lockPath, state);
+  return true;
+}
+function newHolder(procStart) {
+  return {
     pid: process.pid,
     started: Date.now(),
-    hostname: getHostname()
+    hostname: hostname(),
+    token: randomUUID(),
+    ...procStart === null ? {} : { procStart }
   };
-  try {
-    await writeFile(metadataPath, JSON.stringify(metadata), "utf-8");
-  } catch (error) {
-    await rm(lockPath, { recursive: true, force: true }).catch(() => {
-    });
-    throw error;
-  }
+}
+function holdLock(lockPath, token) {
   let released = false;
   const cleanup = () => {
     if (released) return;
     released = true;
-    try {
-      rmSync(lockPath, { recursive: true, force: true });
-    } catch {
-    }
+    releaseOwnedSync(lockPath, token);
   };
   const signalHandler = (signal) => {
     cleanup();
@@ -1233,70 +2368,109 @@ async function tryAcquire(lockPath) {
   process.once("SIGINT", signalHandler);
   process.once("SIGTERM", signalHandler);
   process.once("exit", cleanup);
-  return async () => {
+  const release = 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(() => {
+    await evictOwners(lockPath, [token]).catch(() => {
     });
   };
+  const isHeld = async () => !released && existsSync(ownerPath(lockPath, token));
+  return Object.assign(release, { isHeld });
 }
-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;
-  }
-}
-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;
+
+// src/utils/output/color.ts
+function noColorRequested() {
+  const value = process.env.NO_COLOR;
+  return value !== void 0 && value !== "";
+}
+function forceColorRequested() {
+  const value = process.env.FORCE_COLOR;
+  if (value === void 0) return void 0;
+  return value !== "0" && value !== "false";
+}
+function colorEnabled(stream = process.stdout) {
+  const forced = forceColorRequested();
+  if (forced !== void 0) return forced;
+  if (noColorRequested()) return false;
+  return stream.isTTY === true;
 }
-function isProcessAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === "EPERM";
+
+// src/utils/output/logger.ts
+var C = {
+  green: "\x1B[32m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m",
+  reset: "\x1B[0m"
+};
+function outStream() {
+  return process.stdout;
+}
+function out(text) {
+  outStream().write(text);
+}
+function c(code, text, stream) {
+  return colorEnabled(stream) ? `${code}${text}${C.reset}` : text;
+}
+var logger = {
+  info(msg) {
+    out(c(C.cyan, msg, outStream()) + "\n");
+  },
+  warn(msg) {
+    process.stderr.write(c(C.yellow, "\u26A0 ", process.stderr) + msg + "\n");
+  },
+  error(msg) {
+    process.stderr.write(c(C.red, "\u2717 ", process.stderr) + msg + "\n");
+  },
+  success(msg) {
+    out(c(C.green, "\u2713 ", outStream()) + msg + "\n");
+  },
+  debug(msg) {
+    if (process.env.AGENTSMESH_DEBUG === "1") {
+      out(c(C.cyan, "[debug] ", outStream()) + msg + "\n");
+    }
   }
-}
-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 isLockMetadata(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value;
-  return typeof v.pid === "number" && typeof v.started === "number";
-}
-function getHostname() {
-  return hostname();
-}
+};
 
 // src/lessons/lessons-lock.ts
 var LESSONS_LOCK_FILENAME = ".lessons.lock";
+var LESSONS_LOCK_OPTIONS = Object.freeze({
+  retries: 500,
+  retryDelayMs: 25,
+  maxRetryDelayMs: 250,
+  jitter: true,
+  staleMs: 6e4
+});
 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" });
+  return acquireProcessLock(lessonsLockPath(projectRoot), {
+    retries: opts.retries ?? LESSONS_LOCK_OPTIONS.retries,
+    retryDelayMs: opts.retryDelayMs ?? LESSONS_LOCK_OPTIONS.retryDelayMs,
+    maxRetryDelayMs: opts.maxRetryDelayMs ?? LESSONS_LOCK_OPTIONS.maxRetryDelayMs,
+    jitter: opts.jitter ?? LESSONS_LOCK_OPTIONS.jitter,
+    staleMs: opts.staleMs ?? LESSONS_LOCK_OPTIONS.staleMs,
+    label: "lessons lock",
+    waitNoticeMs: opts.waitNoticeMs,
+    onWait: opts.onWait ?? ((holder) => logger.warn(
+      `Waiting for the lessons lock, held by ${holder}; a lock older than ${LESSONS_LOCK_OPTIONS.staleMs / 1e3} s is taken over.`
+    ))
+  });
+}
+var LessonsLockLostError = class extends Error {
+  constructor() {
+    super(
+      `lost the lessons lock while writing (the process was paused longer than the ${LESSONS_LOCK_OPTIONS.staleMs / 1e3} s stale window?); nothing was saved \u2014 retry the command`
+    );
+    this.name = "LessonsLockLostError";
+  }
+};
+async function assertLessonsLockHeld(lock) {
+  if (!await lock.isHeld()) throw new LessonsLockLostError();
 }
 
 // src/lessons/validate-checks.ts
@@ -1500,6 +2674,8 @@ function collectDuplicateRules(graph, findings) {
 }
 function collectInvalidTriggerPatterns(graph, findings) {
   for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
+    const globFinding = unsafeGlobFinding(triggerId, trigger);
+    if (globFinding !== null) findings.push(globFinding);
     if (trigger.kind !== "command_pattern") continue;
     try {
       new RegExp(trigger.pattern);
@@ -1507,7 +2683,7 @@ function collectInvalidTriggerPatterns(graph, findings) {
       findings.push({
         level: "error",
         code: "INVALID_TRIGGER_PATTERN",
-        message: `Trigger "${triggerId}" has an invalid command_pattern regex (${trigger.pattern}): ${err instanceof Error ? err.message : String(err)}.`,
+        message: `Trigger "${triggerId}" has an invalid command_pattern regex (${trigger.pattern}): ${regexSyntaxReason(err)}.`,
         triggerId
       });
       continue;
@@ -1516,12 +2692,16 @@ function collectInvalidTriggerPatterns(graph, findings) {
       findings.push({
         level: "error",
         code: "UNSAFE_TRIGGER_PATTERN",
-        message: `Trigger "${triggerId}" has a command_pattern regex outside the provably-linear subset (${trigger.pattern}): it can backtrack catastrophically (e.g. a quantified group like (a+)+ or (a|aa)+, adjacent repetition like a+a+, or a backreference/lookaround). Rewrite using a linear pattern.`,
+        message: `Trigger "${triggerId}" has a command_pattern regex the linear matcher cannot run (${trigger.pattern}). It does not support backreferences (\\1, \\k<name>), lookarounds ((?=x), (?!x), (?<=x), (?<!x)), or patterns too large to run, such as (a{1000}){10}. Nested quantifiers such as (a+)+ are fine. Rewrite the pattern without the unsupported part.`,
         triggerId
       });
     }
   }
 }
+function regexSyntaxReason(err) {
+  const text = err instanceof Error ? err.message : String(err);
+  return text.replace(/^Invalid regular expression: \/[\s\S]*\/[a-z]*: /, "");
+}
 function collectBackslashGlobPatterns(graph, findings) {
   for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
     if (trigger.kind !== "file_glob") continue;
@@ -1620,7 +2800,7 @@ function collectStopwordKeywords(graph, findings) {
   for (const [triggerId, trigger] of Object.entries(graph.triggers)) {
     if (trigger.kind !== "keyword") continue;
     if (!active.has(triggerId)) continue;
-    if (tokenize(trigger.pattern).length !== 0 && !keywordNeedleLosesTokens(trigger.pattern)) {
+    if (tokenize2(trigger.pattern).length !== 0 && !keywordNeedleLosesTokens(trigger.pattern)) {
       continue;
     }
     findings.push({
@@ -1667,9 +2847,17 @@ function validateLessonsGraph(graph, options = {}) {
 }
 
 // src/lessons/mutate.ts
-function emptyGraph() {
-  return { version: CURRENT_GRAPH_VERSION, lessons: {}, topics: {}, triggers: {} };
-}
+var LessonsWriteRefusedError = class extends Error {
+  findings;
+  constructor(findings) {
+    const errors = findings.map((f) => `${f.code}: ${f.message.replace(/[.\s]+$/, "")}`).join("; ");
+    super(
+      `Refused to save the lessons graph: this change would add ${errors}. Nothing was written.`
+    );
+    this.name = "LessonsWriteRefusedError";
+    this.findings = findings;
+  }
+};
 function findingKey(f) {
   return `${f.code}|${f.triggerId ?? ""}|${f.lessonId ?? ""}`;
 }
@@ -1679,6 +2867,7 @@ function errorSignatures(report) {
 async function mutateLessonsGraphLocked(projectRoot, mutator, options = {}) {
   const release = await acquireLessonsLock(projectRoot, { retries: options.retries });
   try {
+    sweepLessonsLeftovers(projectRoot);
     const graph = tryLoadLessonsGraph(projectRoot) ?? emptyGraph();
     const baseline = errorSignatures(validateLessonsGraph(graph));
     const result = await mutator(graph);
@@ -1687,12 +2876,10 @@ async function mutateLessonsGraphLocked(projectRoot, mutator, options = {}) {
       (f) => f.level === "error" && !baseline.has(findingKey(f))
     );
     if (introduced.length > 0) {
-      const errors = introduced.map((f) => `${f.code}: ${f.message}`).join("; ");
-      throw new Error(
-        `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.)`
-      );
+      throw new LessonsWriteRefusedError(introduced);
     }
     graph.version = CURRENT_GRAPH_VERSION;
+    await assertLessonsLockHeld(release);
     saveLessonsGraph(projectRoot, graph);
     return result;
   } finally {
@@ -1706,50 +2893,41 @@ async function mutateLessonsGraph(projectRoot, mutator, options = {}) {
 
 // src/lessons/add.ts
 async function addLesson(projectRoot, input, options = {}) {
-  return mutateLessonsGraph(projectRoot, (graph) => addLessonInto(graph, input, options), {
-    retries: options.retries
-  });
+  return mutateLessonsGraph(
+    projectRoot,
+    (graph) => addLessonInto(graph, input, { ...options, projectRoot }),
+    { retries: options.retries }
+  );
 }
 function addLessonInto(graph, input, options) {
   const ruleKey = normalizeRule(input.rule);
   const trimmedRule = assertRuleShape(input.rule);
   const existingId = findExistingLessonByRule(graph, ruleKey);
-  const isNewTopic = graph.topics[input.topic] === void 0;
-  if (isNewTopic) {
-    if (options.allowNewTopic !== true) throw new UnknownTopicError(input.topic);
-    if (options.topicSummary === void 0 || options.topicSummary.length === 0) {
-      throw new Error(`addLesson: new topic "${input.topic}" requires topicSummary.`);
-    }
-    graph.topics[input.topic] = { summary: options.topicSummary };
-  }
+  const isNewTopic = ensureTopic(graph, input.topic, options);
   const existing = existingId !== null ? graph.lessons[existingId] : void 0;
   assertTriggerInputs(input, options, existing?.triggers.length ?? 0);
-  const { triggerIds, newTriggerIds } = mergeTriggers(graph, input.triggers);
+  const merged = mergeTriggers(graph, input.triggers, options.projectRoot);
+  const { triggerIds, newTriggerIds, dropped } = dropDeadCommandTriggers(graph, merged, options);
   if (!skipsTriggerGates(input, options)) {
-    assertRecallable(
-      graph,
-      existing === void 0 ? triggerIds : union(existing.triggers, triggerIds)
-    );
+    const resulting = existing === void 0 ? triggerIds : union(existing.triggers, triggerIds);
+    assertRecallable(graph, resulting, dropped);
   }
-  if (existingId !== null) {
-    const existing2 = graph.lessons[existingId];
-    graph.lessons[existingId] = {
-      ...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" } : {}
-    };
+  const droppedWarnings = dropped.map(deadCommandWarning);
+  if (existingId !== null && existing !== void 0) {
+    const updated = upsertLesson(existing, input, triggerIds);
+    graph.lessons[existingId] = updated;
     return {
       id: existingId,
       isNewLesson: false,
       isNewTopic,
       newTriggerIds,
+      changes: describeUpsert(existing, updated),
       // Near-duplicate detection is meaningless on an upsert (the lesson IS the
       // match), so only DEAD_GLOB/hygiene warnings apply here.
-      warnings: inspectCapturedLesson(graph, existingId, options.knownPaths)
+      warnings: [
+        ...inspectCapturedLesson(graph, existingId, options.knownPaths),
+        ...droppedWarnings
+      ]
     };
   }
   const id = makeLessonId(graph, input.topic, ruleKey);
@@ -1757,29 +2935,26 @@ function addLessonInto(graph, input, options) {
     rule: trimmedRule,
     topics: [input.topic],
     triggers: triggerIds,
-    evidence: input.evidence === void 0 ? [] : [...input.evidence],
+    evidence: [...new Set(input.evidence ?? [])],
     status: "active",
     createdAt: input.createdAt ?? todayIso(),
     ...input.rationale === void 0 ? {} : { rationale: input.rationale },
     ...input.scope === "always" ? { scope: "always" } : {}
   };
-  const warnings = inspectCapturedLesson(graph, id, options.knownPaths);
   const nearDup = nearDuplicateWarning(graph, id);
   return {
     id,
     isNewLesson: true,
     isNewTopic,
     newTriggerIds,
-    warnings: nearDup === null ? warnings : [...warnings, nearDup]
+    changes: [],
+    warnings: [
+      ...inspectCapturedLesson(graph, id, options.knownPaths),
+      ...nearDup === null ? [] : [nearDup],
+      ...droppedWarnings
+    ]
   };
 }
-function findExistingLessonByRule(graph, ruleKey) {
-  for (const [id, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.status !== "active") continue;
-    if (normalizeRule(lesson.rule) === ruleKey) return id;
-  }
-  return null;
-}
 
 // src/lessons/import-legacy-merge.ts
 async function mergeLegacy(projectRoot, paths, specs, summaryByTopic, options) {
@@ -1812,43 +2987,74 @@ async function mergeLegacy(projectRoot, paths, specs, summaryByTopic, options) {
     triggerCount: addedTriggers.size
   };
 }
-var BASE_REL = ".agentsmesh/lessons";
-function lessonsPaths(projectRoot) {
-  const base = join(projectRoot, BASE_REL);
-  return {
-    base,
-    graph: join(base, "lessons.json"),
-    config: join(base, "config.json"),
-    journal: join(base, "journal.md"),
-    index: join(base, "index.yaml"),
-    topicsDir: join(base, "topics")
-  };
+async function canonicalizePath(path) {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    const parent = dirname(path);
+    if (parent === path) return resolve(path);
+    return join(await canonicalizePath(parent), basename(path));
+  }
 }
-function toRelPath(projectRoot, absolute) {
-  return relative(projectRoot, absolute).split(sep).join("/");
+function isPathInside(target, root) {
+  return target === root || target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+var display = (path) => path.replaceAll("\\", "/");
+async function assertPathInsideRoot(root, target) {
+  const rootAbs = resolve(root);
+  const targetAbs = resolve(target);
+  if (!isPathInside(targetAbs, rootAbs)) {
+    throw new Error(`Unsafe filesystem path: ${display(target)} is outside ${display(rootAbs)}`);
+  }
+  let realTarget;
+  let realRoot;
+  try {
+    [realTarget, realRoot] = await Promise.all([
+      canonicalizePath(targetAbs),
+      canonicalizePath(rootAbs)
+    ]);
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(
+      `Unsafe filesystem path: ${display(target)} could not be resolved (${detail})`,
+      { cause }
+    );
+  }
+  if (isPathInside(realTarget, realRoot)) return;
+  throw new Error(
+    `Unsafe filesystem path: ${display(target)} resolves to ${display(realTarget)} outside ${display(realRoot)}`
+  );
 }
-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> --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>\`.
-
-**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
 
-// src/lessons/import-legacy.ts
-var LessonsGraphExistsError = class extends Error {
-  code = "LESSONS_GRAPH_EXISTS";
-  constructor() {
-    super("importLegacyLessons: a non-empty lessons.json already exists; pass force to overwrite.");
-    this.name = "LessonsGraphExistsError";
+// src/lessons/import-legacy-read.ts
+var LESSONS_DIR = ".agentsmesh/lessons";
+var LegacyTopicPathError = class extends Error {
+  code = "LEGACY_TOPIC_PATH_OUTSIDE";
+  constructor(file) {
+    super(
+      `Legacy topic file path is outside .agentsmesh/lessons/: ${file}. Refusing to migrate (legacy artifacts left intact).`
+    );
+    this.name = "LegacyTopicPathError";
   }
 };
-async function importLegacyLessons(projectRoot, options) {
-  const paths = lessonsPaths(projectRoot);
-  const indexRaw = readFileSync(paths.index, "utf8");
-  const index = LegacyIndexSchema.parse(parse(indexRaw));
+async function resolveLegacyTopicPath(projectRoot, file) {
+  const forward = file.replaceAll("\\", "/");
+  const normalized = posix.normalize(forward);
+  const relative3 = !/^[A-Za-z]:/.test(forward) && !forward.startsWith("/") && normalized.startsWith(`${LESSONS_DIR}/`);
+  if (!relative3) throw new LegacyTopicPathError(file);
+  const target = join(projectRoot, normalized);
+  try {
+    await assertPathInsideRoot(join(projectRoot, LESSONS_DIR), target);
+  } catch {
+    throw new LegacyTopicPathError(file);
+  }
+  return target;
+}
+async function readLegacySource(projectRoot, migratedAt) {
+  const index = LegacyIndexSchema.parse(
+    parse(readFileSync(lessonsPaths(projectRoot).index, "utf8"))
+  );
   const topics = {};
   const triggersById = /* @__PURE__ */ new Map();
   const triggerIdByKey = /* @__PURE__ */ new Map();
@@ -1859,14 +3065,15 @@ async function importLegacyLessons(projectRoot, options) {
     topics[cluster.topic] = { summary: cluster.summary };
     summaryByTopic.set(cluster.topic, cluster.summary);
     const clusterTriggerIds = collectClusterTriggerIds(cluster, triggersById, triggerIdByKey);
-    const topicFile = join(projectRoot, cluster.file);
+    const topicFile = await resolveLegacyTopicPath(projectRoot, cluster.file);
     if (!existsSync(topicFile)) {
       throw new Error(
-        `importLegacyLessons: declared topic file is missing: ${cluster.file}. Refusing to migrate (legacy artifacts left intact).`
+        `Legacy topic file is missing: ${cluster.file}. Refusing to migrate (legacy artifacts left intact).`
       );
     }
-    const topicMarkdown = readFileSync(topicFile, "utf8");
-    for (const { index: ruleIndex, body, evidence } of parseRulesSection(topicMarkdown)) {
+    for (const { index: ruleIndex, body, evidence } of parseRulesSection(
+      readFileSync(topicFile, "utf8")
+    )) {
       const lessonEvidence = [
         `legacy:${cluster.file}#rule-${ruleIndex}`,
         ...evidence.map((e) => `legacy:${e}`)
@@ -1877,7 +3084,7 @@ async function importLegacyLessons(projectRoot, options) {
         triggers: clusterTriggerIds,
         evidence: lessonEvidence,
         status: "active",
-        createdAt: options.migratedAt
+        createdAt: migratedAt
       };
       specs.push({
         rule: body,
@@ -1888,22 +3095,43 @@ async function importLegacyLessons(projectRoot, options) {
           keywords: cluster.triggers.keywords
         },
         evidence: lessonEvidence,
-        createdAt: options.migratedAt
+        createdAt: migratedAt
       });
     }
   }
-  if (options.merge === true)
+  return { topics, triggers: Object.fromEntries(triggersById), lessons, specs, summaryByTopic };
+}
+
+// src/lessons/import-legacy.ts
+var LessonsGraphExistsError = class extends Error {
+  code = "LESSONS_GRAPH_EXISTS";
+  constructor() {
+    super(
+      "A non-empty lessons.json already exists. Pass --force to overwrite it, or --merge to add the legacy lessons to it."
+    );
+    this.name = "LessonsGraphExistsError";
+  }
+};
+async function importLegacyLessons(projectRoot, options) {
+  const paths = lessonsPaths(projectRoot);
+  if (options.merge === true) {
+    const { specs, summaryByTopic } = await readLegacySource(projectRoot, options.migratedAt);
     return mergeLegacy(projectRoot, paths, specs, summaryByTopic, options);
-  const triggers = Object.fromEntries(triggersById.entries());
-  await mutateLessonsGraphLocked(projectRoot, (g) => {
+  }
+  const { topics, lessons, triggers } = await mutateLessonsGraphLocked(projectRoot, async (g) => {
+    if (options.requireAbsentGraph === true && existsSync(paths.graph)) {
+      throw new LessonsGraphExistsError();
+    }
     const populated = Object.keys(g.lessons).length > 0 || Object.keys(g.topics).length > 0 || Object.keys(g.triggers).length > 0;
     if (options.force !== true && populated) {
       throw new LessonsGraphExistsError();
     }
+    const source = await readLegacySource(projectRoot, options.migratedAt);
     g.version = CURRENT_GRAPH_VERSION;
-    g.lessons = lessons;
-    g.topics = topics;
-    g.triggers = triggers;
+    g.lessons = source.lessons;
+    g.topics = source.topics;
+    g.triggers = source.triggers;
+    return source;
   });
   const deletedPaths = options.deleteLegacy === false ? [] : deleteLegacyArtifacts(paths.base);
   return {
@@ -1911,7 +3139,7 @@ async function importLegacyLessons(projectRoot, options) {
     deletedPaths,
     topicCount: Object.keys(topics).length,
     lessonCount: Object.keys(lessons).length,
-    triggerCount: triggersById.size
+    triggerCount: Object.keys(triggers).length
   };
 }
 
@@ -1921,7 +3149,7 @@ async function maybeAutoMigrateLessons(projectRoot) {
   const paths = lessonsPaths(projectRoot);
   if (!existsSync(paths.index)) return false;
   try {
-    await importLegacyLessons(projectRoot, { migratedAt: todayIso() });
+    await importLegacyLessons(projectRoot, { migratedAt: todayIso(), requireAbsentGraph: true });
     return true;
   } catch (err) {
     if (err instanceof LessonsGraphExistsError) return false;
@@ -1973,10 +3201,53 @@ function writeSeenStore(path, data, lastAt) {
     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);
+    retryTransientSync(() => renameSync(tmp, path));
   } catch {
   }
 }
+function removeSeenStore(path) {
+  try {
+    rmSync(path, { force: true, recursive: true });
+  } catch {
+  }
+}
+var LOCK_WAIT_MS = 2e3;
+var LOCK_STALE_MS = 1e4;
+var pause2 = new Int32Array(new SharedArrayBuffer(4));
+function lockIsStale(lock) {
+  try {
+    return Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS;
+  } catch {
+    return false;
+  }
+}
+function takeLock(lock) {
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (; ; ) {
+    try {
+      mkdirSync(dirname(lock), { recursive: true });
+      mkdirSync(lock);
+      return true;
+    } catch (err) {
+      if (err.code !== "EEXIST" && !isTransientFsError(err)) {
+        return false;
+      }
+    }
+    if (lockIsStale(lock)) removeSeenStore(lock);
+    else if (Date.now() >= deadline) return false;
+    else Atomics.wait(pause2, 0, 0, 5);
+  }
+}
+function updateSeenStore(path, update) {
+  const lock = `${path}.lock`;
+  const locked = takeLock(lock);
+  try {
+    const next = update(readSeenStore(path));
+    if (next !== null) writeSeenStore(path, next.data);
+  } finally {
+    if (locked) removeSeenStore(lock);
+  }
+}
 
 // src/lessons/keyword-match.ts
 function deriveHaystackTokens(query) {
@@ -1984,13 +3255,13 @@ function deriveHaystackTokens(query) {
   if (query.file !== void 0) parts.push(query.file);
   if (query.command !== void 0) parts.push(query.command);
   if (parts.length === 0) return [];
-  const out = [];
+  const out2 = [];
   for (const raw of splitTokens(parts.join(" "))) {
-    out.push(raw.toLowerCase());
+    out2.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);
+    if (sub.length > 1) out2.push(...sub);
   }
-  return out;
+  return out2;
 }
 function splitTokens(text) {
   return text.split(/[^A-Za-z0-9]+/).filter((t) => t.length > 0);
@@ -2010,7 +3281,7 @@ function containsRun(needle, hay) {
   return false;
 }
 function keywordMatches(pattern, query) {
-  const needle = tokenize(pattern);
+  const needle = tokenize2(pattern);
   if (query.keyword !== void 0 && containsRun(needle, splitTokens(query.keyword.toLowerCase()))) {
     return true;
   }
@@ -2019,6 +3290,7 @@ function keywordMatches(pattern, query) {
 
 // src/lessons/query.ts
 var COMMAND_MATCH_BUDGET = 5e6;
+var GLOB_MATCH_BUDGET = 2e6;
 function queryLessons(graph, query) {
   if (query.file === void 0 && query.command === void 0 && query.keyword === void 0) {
     return [];
@@ -2041,9 +3313,12 @@ function collectMatchedTriggersByKind(graph, query) {
     command_pattern: /* @__PURE__ */ new Set(),
     keyword: /* @__PURE__ */ new Set()
   };
-  const budget = { remaining: COMMAND_MATCH_BUDGET };
+  const budgets = {
+    command: { remaining: COMMAND_MATCH_BUDGET },
+    glob: { remaining: GLOB_MATCH_BUDGET }
+  };
   for (const [id, trigger] of Object.entries(graph.triggers)) {
-    if (triggerMatches(trigger, query, budget)) byKind[trigger.kind].add(id);
+    if (triggerMatches(trigger, query, budgets)) byKind[trigger.kind].add(id);
   }
   return byKind;
 }
@@ -2051,47 +3326,121 @@ function collectMatchedTriggerIds(graph, query) {
   const { file_glob, command_pattern, keyword } = collectMatchedTriggersByKind(graph, query);
   return /* @__PURE__ */ new Set([...file_glob, ...command_pattern, ...keyword]);
 }
-function triggerMatches(trigger, query, budget) {
+function triggerMatches(trigger, query, budgets) {
   switch (trigger.kind) {
-    case "file_glob":
+    case "file_glob": {
       if (query.file === void 0) return false;
-      return picomatch(trigger.pattern, { dot: true })(query.file);
+      const matcher = getGlobMatcher(trigger.pattern);
+      return matcher !== null && matcher.test(query.file, budgets.glob);
+    }
     case "command_pattern": {
       if (query.command === void 0) return false;
       const matcher = getCommandMatcher(trigger.pattern);
-      return matcher !== null && matcher.test(query.command, budget);
+      return matcher !== null && matcher.test(query.command, budgets.command);
     }
     case "keyword":
       return keywordMatches(trigger.pattern, query);
   }
 }
+function commandCouldMatch(commandPatterns, keywordPatterns, command) {
+  const budget = { remaining: COMMAND_MATCH_BUDGET };
+  const query = { command };
+  return commandPatterns.some((p) => {
+    const matcher = getCommandMatcher(p);
+    return matcher !== null && matcher.test(command, budget);
+  }) || keywordPatterns.some((p) => keywordMatches(p, query));
+}
 function appendJsonl(path, record, opts) {
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, `${JSON.stringify(record)}
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const lead = endsWithoutNewline(path) ? "\n" : "";
+    appendFileSync(path, `${lead}${JSON.stringify(record)}
 `, "utf8");
-  if (statSync(path).size > opts.trimTriggerBytes) capJsonl(path, opts.maxRecords);
+    if (statSync(path).size > opts.trimTriggerBytes) {
+      capJsonl(path, opts.maxRecords, opts.trimTriggerBytes / 2);
+    }
+  } catch {
+  }
 }
-function capJsonl(path, maxRecords) {
+function endsWithoutNewline(path) {
+  let fd;
+  try {
+    const size = statSync(path).size;
+    if (size === 0) return false;
+    fd = openSync(path, "r");
+    const last = Buffer.alloc(1);
+    readSync(fd, last, 0, 1, size - 1);
+    return last[0] !== 10;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== void 0) closeSync(fd);
+  }
+}
+function capJsonl(path, maxRecords, maxBytes = Infinity) {
   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 kept = [];
+  let bytes = 0;
+  for (let i = lines.length - 1; i >= 0 && kept.length < maxRecords; i -= 1) {
+    const size = Buffer.byteLength(lines[i]) + 1;
+    if (size > maxBytes) continue;
+    if (bytes + size > maxBytes) break;
+    bytes += size;
+    kept.push(lines[i]);
+  }
+  if (kept.length === lines.length) return;
   const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, `${kept.join("\n")}
+  writeFileSync(tmp, kept.length === 0 ? "" : `${kept.reverse().join("\n")}
 `, "utf8");
   renameSync(tmp, path);
 }
-function readJsonl(path) {
-  if (!existsSync(path)) return [];
-  const out = [];
-  for (const line of readFileSync(path, "utf8").split("\n")) {
+function readTail(path, maxBytes) {
+  const size = maxBytes === void 0 ? 0 : statSync(path).size;
+  if (maxBytes === void 0 || size <= maxBytes) return readFileSync(path, "utf8");
+  const fd = openSync(path, "r");
+  try {
+    const tail = Buffer.alloc(maxBytes);
+    readSync(fd, tail, 0, maxBytes, size - maxBytes);
+    const text = tail.toString("utf8");
+    return text.slice(text.indexOf("\n") + 1);
+  } finally {
+    closeSync(fd);
+  }
+}
+function readJsonl(path, isRecord2, opts = {}) {
+  let text;
+  try {
+    text = readTail(path, opts.maxBytes);
+  } catch {
+    return [];
+  }
+  const out2 = [];
+  for (const line of text.split("\n")) {
     if (line.trim().length === 0) continue;
     try {
-      out.push(JSON.parse(line));
+      const value = JSON.parse(line);
+      if (isRecord2(value)) out2.push(value);
     } catch {
     }
   }
-  return out;
+  return out2;
+}
+
+// src/utils/types/guards.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/lessons/log-record-guards.ts
+var isStr = (v) => typeof v === "string";
+var isNum = (v) => typeof v === "number" && Number.isFinite(v);
+var optional = (v, check) => v === void 0 || check(v);
+function isOutcomeEvent(v) {
+  if (!isRecord(v) || !isStr(v.ts) || !isStr(v.contextKey)) return false;
+  if (!optional(v.session, isStr)) return false;
+  if (v.kind === "delivered") return isStr(v.lessonId) && optional(v.rank, isNum);
+  return v.kind === "failure" && optional(v.errorClass, isStr);
 }
 
 // src/lessons/telemetry.ts
@@ -2106,21 +3455,26 @@ function sessionId(env = process.env) {
 function recallLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
 }
-function configTelemetry(projectRoot) {
+function configFlag(projectRoot, key) {
   const path = lessonsPaths(projectRoot).config;
-  if (!existsSync(path)) return false;
+  if (!existsSync(path)) return void 0;
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    return typeof parsed === "object" && parsed !== null && parsed.telemetry === true;
+    const parsed = JSON.parse(stripBom(readFileSync(path, "utf8")));
+    if (typeof parsed !== "object" || parsed === null) return void 0;
+    const value = parsed[key];
+    return typeof value === "boolean" ? value : void 0;
   } catch {
-    return false;
+    return void 0;
   }
 }
+function envOverride(raw) {
+  const value = raw?.trim().toLowerCase();
+  if (value === "1" || value === "true" || value === "yes" || value === "on") return true;
+  if (value === "0" || value === "false" || value === "no" || value === "off") return false;
+  return void 0;
+}
 function isTelemetryEnabled(env = process.env, projectRoot) {
-  const raw = env[TELEMETRY_ENV];
-  if (raw === "1") return true;
-  if (raw === "0") return false;
-  return projectRoot !== void 0 && configTelemetry(projectRoot);
+  return envOverride(env[TELEMETRY_ENV]) ?? (projectRoot !== void 0 && configFlag(projectRoot, "telemetry") === true);
 }
 function appendRecallRecord(projectRoot, record, env = process.env) {
   if (!isTelemetryEnabled(env, projectRoot)) return;
@@ -2150,15 +3504,15 @@ 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)) {
+    const c2 = parsed;
+    const stamp = c2.stamp;
+    if (typeof stamp?.mtimeMs !== "number" || typeof stamp.size !== "number" || !isStringArray(c2.commandPatterns) || !isStringArray(c2.keywordPatterns)) {
       return null;
     }
     return {
       stamp: { mtimeMs: stamp.mtimeMs, size: stamp.size },
-      commandPatterns: c.commandPatterns,
-      keywordPatterns: c.keywordPatterns
+      commandPatterns: c2.commandPatterns,
+      keywordPatterns: c2.keywordPatterns
     };
   } catch {
     return null;
@@ -2187,34 +3541,14 @@ function refreshCommandFastpath(projectRoot, graph, preReadStamp) {
       if (trigger.kind === "command_pattern") commandPatterns.push(trigger.pattern);
       else if (trigger.kind === "keyword") keywordPatterns.push(trigger.pattern);
     }
-    const cache2 = { stamp, commandPatterns, keywordPatterns };
+    const cache4 = { stamp, commandPatterns, keywordPatterns };
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(cache2), "utf8");
+    writeFileSync(tmp, JSON.stringify(cache4), "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/lexical-retrieval.ts
 var LEXICAL_LIMIT = 3;
@@ -2235,14 +3569,14 @@ function matchLessons(graph, query) {
   return { matches: [...triggered, ...lexical], lexicalCount: lexical.length };
 }
 function lexicalCandidates(graph, keyword, excludeIds) {
-  const terms = [...new Set(tokenize(keyword))];
+  const terms = [...new Set(tokenize2(keyword))];
   if (terms.length < LEXICAL_MIN_TERMS) return [];
   const excluded = new Set(excludeIds);
   const corpus = buildCorpus(graph);
   const scored = [];
   for (const [id, lesson] of Object.entries(graph.lessons)) {
     if (lesson.status !== "active" || lesson.scope === "always" || excluded.has(id)) continue;
-    const ruleTerms = new Set(tokenize(lesson.rule));
+    const ruleTerms = new Set(tokenize2(lesson.rule));
     let shared = 0;
     for (const t of terms) if (!GENERIC.has(t) && ruleTerms.has(t)) shared += 1;
     if (shared < LEXICAL_MIN_TERMS) continue;
@@ -2363,32 +3697,39 @@ function rankLessons(graph, query, matches, options = {}) {
   return applyCaps(ranked, options);
 }
 function applyCaps(ranked, options) {
-  let out = ranked;
-  if (options.limit !== void 0 && options.limit >= 0) out = out.slice(0, options.limit);
-  if (options.maxTokens !== void 0 && out.length > 0) {
-    const budgeted = [out[0]];
-    let used = estTokens(out[0].lesson.rule);
-    for (const row of out.slice(1)) {
+  let out2 = ranked;
+  if (options.limit !== void 0 && options.limit >= 0) out2 = out2.slice(0, options.limit);
+  if (options.maxTokens !== void 0 && out2.length > 0) {
+    const budgeted = [out2[0]];
+    let used = estTokens(out2[0].lesson.rule);
+    for (const row of out2.slice(1)) {
       const cost = estTokens(row.lesson.rule);
       if (used + cost > options.maxTokens) break;
       used += cost;
       budgeted.push(row);
     }
-    out = budgeted;
+    out2 = budgeted;
   }
-  return out;
+  return out2;
 }
 function defaultLessonsConfig() {
   return {
     recallLimit: DEFAULT_RECALL_LIMIT,
     recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
     autoPrune: false,
-    telemetry: false
+    telemetry: false,
+    outcomeLog: true
   };
 }
+var MAX_RECALL_LIMIT = 50;
+var MAX_RECALL_MAX_TOKENS = 8e3;
 function positiveInt(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
 }
+function clamped(value, ceiling) {
+  const n = positiveInt(value);
+  return n === null ? null : Math.min(n, ceiling);
+}
 function loadRecallConfig(projectRoot) {
   const fallback = {
     limit: DEFAULT_RECALL_LIMIT,
@@ -2397,32 +3738,126 @@ function loadRecallConfig(projectRoot) {
   const path = lessonsPaths(projectRoot).config;
   if (!existsSync(path)) return fallback;
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const parsed = JSON.parse(stripBom(readFileSync(path, "utf8")));
     if (typeof parsed !== "object" || parsed === null) return fallback;
     const cfg = parsed;
     return {
-      limit: positiveInt(cfg.recallLimit) ?? fallback.limit,
-      maxTokens: positiveInt(cfg.recallMaxTokens) ?? fallback.maxTokens
+      limit: clamped(cfg.recallLimit, MAX_RECALL_LIMIT) ?? fallback.limit,
+      maxTokens: clamped(cfg.recallMaxTokens, MAX_RECALL_MAX_TOKENS) ?? fallback.maxTokens
     };
   } catch {
     return fallback;
   }
 }
+var GLOBAL_VALUE_FLAGS = /* @__PURE__ */ new Map([
+  [
+    "git",
+    ["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--super-prefix", "--config-env"]
+  ],
+  ["npm", ["--prefix", "-w", "--workspace", "--userconfig", "--cache", "--loglevel"]],
+  ["pnpm", ["-C", "--dir", "-F", "--filter", "--loglevel", "--reporter"]],
+  ["yarn", ["--cwd"]],
+  ["npx", ["-p", "--package", "-c", "--call"]],
+  ["bun", ["--cwd", "--config"]],
+  ["bunx", ["-p", "--package"]],
+  ["make", ["-C", "--directory", "-f", "--file", "--makefile", "-I", "--include-dir"]],
+  ["docker", ["-H", "--host", "--context", "-c", "--config", "-l", "--log-level"]],
+  [
+    "kubectl",
+    ["-n", "--namespace", "--context", "--kubeconfig", "--cluster", "--user", "-s", "--server"]
+  ],
+  ["cargo", ["-C", "--config", "-Z", "--color"]],
+  ["go", ["-C"]]
+]);
+var SHELL_SETUP = /* @__PURE__ */ new Set([
+  "cd",
+  "pushd",
+  "popd",
+  "export",
+  "set",
+  "unset",
+  "source",
+  ".",
+  "[",
+  "[[",
+  "test",
+  "true",
+  "false",
+  ":"
+]);
+var SHELL_PREFIX = /* @__PURE__ */ new Set(["if", "then", "else", "elif", "do", "while", "until", "!", "time"]);
+var BLOCK_SYNTAX = /* @__PURE__ */ new Set(["for", "case", "select", "function", "done", "fi", "esac"]);
+var ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+var SUBCOMMAND = /^[A-Za-z][A-Za-z0-9_-]*(?::[A-Za-z0-9_-]+)*$/;
+function splitSegments(command) {
+  const out2 = [];
+  let cur = "";
+  let quote = null;
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i];
+    const next = command[i + 1];
+    if (quote !== null) {
+      cur += ch;
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      quote = ch;
+      cur += ch;
+    } else if (ch === "\\" && next !== void 0) {
+      cur += ch + next;
+      i += 1;
+    } else if (ch === ";" || ch === "\n" || ch === "|" || ch === "&" && next === "&") {
+      out2.push(cur);
+      cur = "";
+      if (ch !== ";" && ch !== "\n" && (next === ch || next === "&")) i += 1;
+    } else {
+      cur += ch;
+    }
+  }
+  out2.push(cur);
+  return out2;
+}
+function programName(word) {
+  return posix.basename(word.replaceAll("\\", "/")) || word;
+}
+function subcommandOf(program, args) {
+  const valueFlags = GLOBAL_VALUE_FLAGS.get(program);
+  let i = 0;
+  while (valueFlags !== void 0 && i < args.length && /^-./.test(args[i])) {
+    const flag = args[i];
+    i += flag !== "--" && !flag.includes("=") && valueFlags.includes(flag) ? 2 : 1;
+    if (flag === "--") break;
+  }
+  const next = args[i];
+  return next !== void 0 && SUBCOMMAND.test(next) ? { subcommand: next, gapped: i > 0 } : { gapped: false };
+}
+function segmentClass(segment) {
+  const words = segment.replace(/^[\s({]+/, "").replace(/[\s)}]+$/, "").split(/\s+/).filter((w) => w.length > 0);
+  while (words.length > 0 && SHELL_PREFIX.has(words[0])) words.shift();
+  const first = words[0];
+  if (first === void 0 || first.startsWith("#") || BLOCK_SYNTAX.has(first)) return null;
+  while (words.length > 0 && ASSIGNMENT.test(words[0])) words.shift();
+  if (words.length === 0) return null;
+  const program = programName(words[0]);
+  return { program, ...subcommandOf(program, words.slice(1)) };
+}
+function commandClass(command) {
+  let setup = null;
+  for (const segment of splitSegments(command.replace(/\\\r?\n/g, " "))) {
+    const cls = segmentClass(segment);
+    if (cls === null) continue;
+    if (!SHELL_SETUP.has(cls.program)) return cls;
+    setup ??= { program: cls.program, gapped: false };
+  }
+  return setup;
+}
 
 // src/lessons/context-key.ts
 function normalizeCommand(command) {
-  const words = command.trim().split(/\s+/);
-  let start = 0;
-  while (start < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[start])) start += 1;
-  const rest = words.slice(start);
-  const programIdx = rest.findIndex(isBareWord);
-  if (programIdx === -1) return rest[0] ?? "";
-  const program = rest[programIdx];
-  const next = rest[programIdx + 1];
-  return next !== void 0 && isBareWord(next) ? `${program} ${next}` : program;
-}
-function isBareWord(w) {
-  return w.length > 0 && !w.startsWith("-") && !w.includes("/") && !/^["'`]/.test(w);
+  const cls = commandClass(command);
+  if (cls === null) return "";
+  return cls.subcommand === void 0 ? cls.program : `${cls.program} ${cls.subcommand}`;
 }
 function contextKey(input, projectRoot) {
   if (input.file !== void 0 && input.file.length > 0) {
@@ -2461,40 +3896,114 @@ function recordRecallTelemetry(projectRoot, graph, query, matches, lessons, opti
     ...session !== void 0 ? { session } : {}
   });
 }
-function outcomeLogPath(projectRoot) {
-  return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
+
+// src/lessons/action-match.ts
+function queryFromContextKey(key) {
+  if (key.startsWith("file:")) return { file: key.slice("file:".length) };
+  if (key.startsWith("cmd:") && key.length > "cmd:".length)
+    return { command: key.slice("cmd:".length) };
+  return null;
 }
-function readOutcomeLog(projectRoot) {
-  return readJsonl(outcomeLogPath(projectRoot));
+function createActionMatcher(graph) {
+  const seen = /* @__PURE__ */ new Map();
+  return (lessonId, contextKey2) => {
+    let byKey = seen.get(lessonId);
+    if (byKey === void 0) {
+      byKey = /* @__PURE__ */ new Map();
+      seen.set(lessonId, byKey);
+    }
+    let hit = byKey.get(contextKey2);
+    if (hit === void 0) {
+      hit = matchesOwnTrigger(graph, lessonId, contextKey2);
+      byKey.set(contextKey2, hit);
+    }
+    return hit;
+  };
 }
-function scopeKey(ev) {
-  return `${ev.session ?? ""}\0${ev.contextKey}`;
+function matchesOwnTrigger(graph, lessonId, contextKey2) {
+  const query = queryFromContextKey(contextKey2);
+  const lesson = graph.lessons[lessonId];
+  if (query === null || lesson === void 0) return false;
+  const triggers = lesson.triggers.map((id) => graph.triggers[id]).filter((t) => t !== void 0);
+  const patterns = (kind) => triggers.filter((t) => t.kind === kind).map((t) => t.pattern);
+  if ("command" in query) {
+    return commandCouldMatch(patterns("command_pattern"), patterns("keyword"), query.command);
+  }
+  return patterns("file_glob").some((p) => getGlobMatcher(p)?.test(query.file) ?? false) || patterns("keyword").some((p) => keywordMatches(p, query));
 }
-function effectiveness(events) {
-  const lastFailure = /* @__PURE__ */ new Map();
-  events.forEach((ev, i) => {
-    if (ev.kind === "failure") lastFailure.set(scopeKey(ev), i);
+
+// src/lessons/effectiveness.ts
+var INEFFECTIVE_MIN_DELIVERIES = 3;
+var MISS_WINDOW_MS = 30 * 60 * 1e3;
+function failuresBySession(events) {
+  const out2 = /* @__PURE__ */ new Map();
+  events.forEach((ev, index) => {
+    const at = Date.parse(ev.ts);
+    if (ev.kind !== "failure" || ev.session === void 0 || !Number.isFinite(at)) return;
+    const list = out2.get(ev.session) ?? [];
+    list.push({ index, at, contextKey: ev.contextKey });
+    out2.set(ev.session, list);
   });
-  const out = /* @__PURE__ */ new Map();
-  events.forEach((ev, i) => {
+  return out2;
+}
+function impeachingFailure(ev, index, failures, matches) {
+  const at = Date.parse(ev.ts);
+  if (ev.session === void 0 || !Number.isFinite(at)) return void 0;
+  return failures.get(ev.session)?.find(
+    (f) => f.index > index && f.at >= at && f.at - at <= MISS_WINDOW_MS && matches(ev.lessonId, f.contextKey)
+  );
+}
+function effectiveness(events, graph) {
+  const failures = failuresBySession(events);
+  const matches = createActionMatcher(graph);
+  const acc = /* @__PURE__ */ new Map();
+  events.forEach((ev, index) => {
     if (ev.kind !== "delivered") return;
-    const cur = out.get(ev.lessonId) ?? { delivered: 0, missed: 0 };
+    const cur = acc.get(ev.lessonId) ?? { delivered: 0, missed: 0, actions: /* @__PURE__ */ new Set() };
+    acc.set(ev.lessonId, cur);
     cur.delivered += 1;
-    const lf = lastFailure.get(scopeKey(ev));
-    if (lf !== void 0 && lf > i) cur.missed += 1;
-    out.set(ev.lessonId, cur);
+    const hit = impeachingFailure(ev, index, failures, matches);
+    if (hit === void 0) return;
+    cur.missed += 1;
+    cur.actions.add(hit.contextKey);
   });
-  return out;
+  const out2 = /* @__PURE__ */ new Map();
+  for (const [id, a] of acc) {
+    out2.set(id, {
+      delivered: a.delivered,
+      missed: a.missed,
+      failingActions: [...a.actions].sort()
+    });
+  }
+  return out2;
 }
 function effectivenessScore(o) {
   return o.delivered === 0 ? 1 : 1 - o.missed / o.delivered;
 }
-function loadEffectiveness(projectRoot) {
-  const map = /* @__PURE__ */ new Map();
-  for (const [id, o] of effectiveness(readOutcomeLog(projectRoot))) {
-    map.set(id, effectivenessScore(o));
+function effectivenessScores(events, graph) {
+  const out2 = /* @__PURE__ */ new Map();
+  for (const [id, o] of effectiveness(events, graph)) {
+    if (o.delivered >= INEFFECTIVE_MIN_DELIVERIES) out2.set(id, effectivenessScore(o));
   }
-  return map;
+  return out2;
+}
+
+// src/lessons/outcome-log.ts
+var OUTCOME_LOG_TRIM_TRIGGER_BYTES = 2e6;
+function outcomeLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
+}
+function readOutcomeLog(projectRoot) {
+  return readJsonl(outcomeLogPath(projectRoot), isOutcomeEvent, {
+    maxBytes: OUTCOME_LOG_TRIM_TRIGGER_BYTES
+  });
+}
+function loadEffectiveness(projectRoot, graph, lessonIds) {
+  const all = readOutcomeLog(projectRoot);
+  const events = lessonIds === void 0 ? all : all.filter((e) => e.kind !== "delivered" || lessonIds.has(e.lessonId));
+  const kinds = new Set(events.map((e) => e.kind));
+  if (!kinds.has("delivered") || !kinds.has("failure")) return /* @__PURE__ */ new Map();
+  return effectivenessScores(events, graph);
 }
 var AUTO_SESSION_IDLE_MS = 30 * 60 * 1e3;
 var FUTURE_TOLERANCE_MS = 6e4;
@@ -2523,7 +4032,8 @@ function openSessionDedup(options = {}) {
     seen: stale ? /* @__PURE__ */ new Set() : visibleSeen(store.ids, stamps, options.ttlMs),
     path,
     stamps,
-    ...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
+    ...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {},
+    ...stale ? { resetAt: Date.now() } : {}
   };
 }
 function visibleSeen(ids, stamps, ttlMs) {
@@ -2538,27 +4048,26 @@ function filterUnseen(dedup, matches) {
   return matches.filter((m) => !dedup.seen.has(m.id));
 }
 function commitSeen(dedup, returnedIds) {
-  if (returnedIds.length === 0) {
-    if (dedup.ttlMs !== void 0 && dedup.stamps !== null) {
-      writeSeenStore(dedup.path, dedup.stamps);
+  updateSeenStore(dedup.path, (latest) => {
+    const store = dedup.resetAt !== void 0 && (latest.lastAt ?? 0) <= dedup.resetAt ? EMPTY : latest;
+    if (returnedIds.length === 0) {
+      return dedup.ttlMs !== void 0 && store.stamps !== null ? { data: store.stamps } : null;
     }
-    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);
+    if (dedup.ttlMs !== void 0 || store.stamps !== null) {
+      const now = Date.now();
+      const merged = /* @__PURE__ */ new Map();
+      for (const [id, ms] of store.stamps ?? []) {
+        if (dedup.ttlMs === void 0 || now - ms <= dedup.ttlMs) merged.set(id, ms);
+      }
+      for (const id of returnedIds) merged.set(id, now);
+      return { data: merged };
     }
-    for (const id of returnedIds) merged.set(id, now);
-    writeSeenStore(dedup.path, merged);
-    return;
-  }
-  const union2 = new Set(dedup.seen);
-  for (const id of returnedIds) union2.add(id);
-  if (union2.size === dedup.seen.size) return;
-  writeSeenStore(dedup.path, [...union2]);
+    const union2 = new Set(store.ids);
+    for (const id of returnedIds) union2.add(id);
+    return union2.size === store.ids.size ? null : { data: [...union2] };
+  });
 }
+var EMPTY = { ids: /* @__PURE__ */ new Set(), stamps: null };
 
 // src/lessons/recall.ts
 async function recallLessons(projectRoot, query, options = {}) {
@@ -2594,7 +4103,7 @@ async function recallLessons(projectRoot, query, options = {}) {
     // 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)
+    effectiveness: forRank.length === 0 ? /* @__PURE__ */ new Map() : loadEffectiveness(projectRoot, graph, new Set(forRank.map((m) => m.id)))
   });
   if (dedup !== null)
     commitSeen(
@@ -2634,7 +4143,7 @@ function planPrune(graph, options = {}) {
   const removedDeadGlobs = [];
   const unreachableLessons = [];
   if (options.knownPaths !== void 0) {
-    const dead = deadFileGlobIds(graph, options.knownPaths);
+    const { dead } = fileGlobLiveness(graph, options.knownPaths);
     if (dead.size > 0) {
       for (const [id, kept] of keptByLesson) {
         const deadInLesson = kept.filter((t) => dead.has(t));
@@ -2658,7 +4167,14 @@ function planPrune(graph, options = {}) {
     for (const topic of lesson.topics) referencedTopics.add(topic);
   }
   const removedTopicIds = Object.keys(graph.topics).filter((t) => !referencedTopics.has(t)).sort();
-  return { removedTriggerIds, removedTopicIds, trimmedLessons, removedDeadGlobs, unreachableLessons, cap };
+  return {
+    removedTriggerIds,
+    removedTopicIds,
+    trimmedLessons,
+    removedDeadGlobs,
+    unreachableLessons,
+    cap
+  };
 }
 function applyPruneToGraph(graph, plan) {
   for (const trim of [...plan.trimmedLessons, ...plan.removedDeadGlobs ?? []]) {
@@ -2683,15 +4199,7 @@ function isEmptyPrunePlan(plan) {
 
 // src/lessons/auto-prune.ts
 function isAutoPruneEnabled(projectRoot) {
-  const path = lessonsPaths(projectRoot).config;
-  if (!existsSync(path)) return false;
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof parsed !== "object" || parsed === null) return false;
-    return parsed.autoPrune === true;
-  } catch {
-    return false;
-  }
+  return configFlag(projectRoot, "autoPrune") === true;
 }
 async function maybeAutoPrune(projectRoot, knownPaths) {
   if (!isAutoPruneEnabled(projectRoot)) return null;
@@ -2743,28 +4251,6 @@ function recordCapture(projectRoot, triggerKinds, result, env = process.env) {
     env
   );
 }
-var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
-var MAX_FILES = 2e5;
-function listProjectFiles(projectRoot) {
-  const out = /* @__PURE__ */ new Set();
-  try {
-    const stack = [projectRoot];
-    while (stack.length > 0) {
-      const dir = stack.pop();
-      for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        if (entry.isDirectory()) {
-          if (!SKIP_DIRS.has(entry.name)) stack.push(join(dir, entry.name));
-        } else if (entry.isFile()) {
-          out.add(toRelPath(projectRoot, join(dir, entry.name)));
-          if (out.size > MAX_FILES) return out;
-        }
-      }
-    }
-  } catch {
-    return null;
-  }
-  return out;
-}
 
 // src/lessons/capture.ts
 async function captureLesson(projectRoot, input, options = {}) {
@@ -2794,19 +4280,17 @@ async function mergeLessons(projectRoot, loserId, keeperId, options = {}) {
 }
 function mergeInto(graph, loserId, keeperId) {
   if (loserId === keeperId) {
-    throw new Error(`mergeLessons: cannot merge lesson "${loserId}" into itself.`);
+    throw new Error(`Cannot merge lesson "${loserId}" into itself.`);
   }
   const loser = graph.lessons[loserId];
-  if (loser === void 0) throw new Error(`mergeLessons: unknown lesson "${loserId}".`);
+  if (loser === void 0) throw new Error(`Unknown lesson "${loserId}".`);
   const keeper = graph.lessons[keeperId];
-  if (keeper === void 0) throw new Error(`mergeLessons: unknown lesson "${keeperId}".`);
+  if (keeper === void 0) throw new Error(`Unknown lesson "${keeperId}".`);
   if (keeper.status !== "active") {
-    throw new Error(`mergeLessons: keeper "${keeperId}" is not active (status: ${keeper.status}).`);
+    throw new Error(`Keeper "${keeperId}" is not active (status: ${keeper.status}).`);
   }
   if (loser.status !== "active") {
-    throw new Error(
-      `mergeLessons: loser "${loserId}" is already ${loser.status}; nothing to merge.`
-    );
+    throw new Error(`Loser "${loserId}" is already ${loser.status}; nothing to merge.`);
   }
   graph.lessons[keeperId] = {
     ...keeper,
@@ -2830,10 +4314,10 @@ var LINE_REF_PATTERNS = [
 ];
 var ALSO_RELEVANT_PATTERN = /\s*\(also relevant[^)]*\)\s*/g;
 function stripLegacyMarkers(rule) {
-  let out = rule;
-  for (const pattern of LINE_REF_PATTERNS) out = out.replace(pattern, "");
-  out = out.replace(ALSO_RELEVANT_PATTERN, " ");
-  return out.trim();
+  let out2 = rule;
+  for (const pattern of LINE_REF_PATTERNS) out2 = out2.replace(pattern, "");
+  out2 = out2.replace(ALSO_RELEVANT_PATTERN, " ");
+  return out2.trim();
 }
 function applyStrip(graph) {
   const changedIds = [];
@@ -2859,14 +4343,43 @@ async function stripMarkersInGraph(projectRoot, options = {}) {
   });
   return { changedIds, changedCount: changedIds.length };
 }
-var RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
-var RECALL_HOOK_TOOL_MATCHER = "Edit|Write|Bash";
+var LOCAL_FIRST = "npx --no --offline agentsmesh";
+var BARE = "agentsmesh";
+var DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "optionalDependencies"];
+function agentsmeshInvocation(projectRoot) {
+  return dependsOnAgentsmesh(projectRoot) ? LOCAL_FIRST : BARE;
+}
+function dependsOnAgentsmesh(projectRoot) {
+  try {
+    const manifest = JSON.parse(
+      readFileSync(join(projectRoot, "package.json"), "utf8")
+    );
+    return DEPENDENCY_FIELDS.some((field) => manifest?.[field]?.agentsmesh !== void 0);
+  } catch {
+    return false;
+  }
+}
+
+// src/lessons/recall-hook-scaffold.ts
+var RECALL_SUBCOMMAND = "lessons hook";
+var RECALL_HOOK_COMMAND = `agentsmesh ${RECALL_SUBCOMMAND}`;
+var RECALL_HOOK_TOOL_MATCHER = "Edit|Write|NotebookEdit|Bash|PowerShell";
+var MANAGED_COMMAND = new RegExp(`^(?:npx(?: --?[\\w-]+)* )?${RECALL_HOOK_COMMAND}$`);
+function recallHookCommand(projectRoot) {
+  return `${agentsmeshInvocation(projectRoot)} ${RECALL_SUBCOMMAND}`;
+}
+function isManagedRecallCommand(command) {
+  return typeof command === "string" && MANAGED_COMMAND.test(command.trim());
+}
+function isManaged(item) {
+  return item instanceof YAMLMap && isManagedRecallCommand(item.get("command"));
+}
 var RECALL_EVENTS = [
   { event: "PreToolUse", matcher: RECALL_HOOK_TOOL_MATCHER },
   { event: "UserPromptSubmit", matcher: "*" },
-  // Capture-on-failure nudge (see capture-nudge.ts). BEST-EFFORT: only Claude
-  // Code's passthrough hooks emit it; whitelist targets drop it without warning
-  // (BEST_EFFORT_HOOK_EVENTS). PostToolUse is success-only, so failures need this.
+  // Capture-on-failure nudge (see capture-nudge.ts). BEST-EFFORT: targets with
+  // no failure event drop it without warning (BEST_EFFORT_HOOK_EVENTS).
+  // PostToolUse is success-only, so failures need this.
   { event: "PostToolUseFailure", matcher: "*" },
   // Reset recall dedup after a context compaction/clear (see hook.ts SessionStart).
   // BEST-EFFORT: targets that can't represent SessionStart just keep dedup as-is.
@@ -2876,32 +4389,39 @@ var RETIRED_EVENTS = ["PostToolUse"];
 function removeEvent(doc, event) {
   const existing = doc.get(event);
   if (!(existing instanceof YAMLSeq)) return false;
-  const kept = existing.items.filter(
-    (item) => !(item instanceof YAMLMap && item.get("command") === RECALL_HOOK_COMMAND)
-  );
+  const kept = existing.items.filter((item) => !isManaged(item));
   if (kept.length === existing.items.length) return false;
   if (kept.length === 0) doc.delete(event);
   else existing.items = kept;
   return true;
 }
-function injectEvent(doc, event, matcher) {
+function upsertEvent(doc, event, matcher, command) {
   const existing = doc.get(event);
   const seq = existing instanceof YAMLSeq ? existing : new YAMLSeq();
-  const present = seq.items.some(
-    (item) => item instanceof YAMLMap && item.get("command") === RECALL_HOOK_COMMAND
-  );
-  if (present) return false;
-  seq.add(doc.createNode({ matcher, type: "command", command: RECALL_HOOK_COMMAND }));
-  doc.set(event, seq);
-  return true;
+  const [first, ...extra] = seq.items.filter(isManaged);
+  if (first === void 0) {
+    seq.add(doc.createNode({ matcher, type: "command", command }));
+    doc.set(event, seq);
+    return true;
+  }
+  let changed = extra.length > 0;
+  if (changed) seq.items = seq.items.filter((item) => !extra.includes(item));
+  const desired = { matcher, type: "command", command };
+  for (const [key, value] of Object.entries(desired)) {
+    if (first.get(key) === value) continue;
+    first.set(key, value);
+    changed = true;
+  }
+  return changed;
 }
 function injectRecallHook(projectRoot) {
   const path = join(projectRoot, ".agentsmesh", "hooks.yaml");
   if (!existsSync(path)) return false;
   const doc = parseDocument(readFileSync(path, "utf8"));
+  const command = recallHookCommand(projectRoot);
   let changed = false;
   for (const { event, matcher } of RECALL_EVENTS) {
-    if (injectEvent(doc, event, matcher)) changed = true;
+    if (upsertEvent(doc, event, matcher, command)) changed = true;
   }
   for (const event of RETIRED_EVENTS) {
     if (removeEvent(doc, event)) changed = true;
@@ -2909,165 +4429,117 @@ function injectRecallHook(projectRoot) {
   if (changed) writeFileSync(path, String(doc), "utf8");
   return changed;
 }
-
-// src/lessons/merge-driver-setup.ts
-var LESSONS_MERGE_DRIVER = "agentsmesh-lessons";
-var LESSONS_GITATTRIBUTES_ENTRY = `.agentsmesh/lessons/lessons.json merge=${LESSONS_MERGE_DRIVER}`;
-var UTF8_BOM = "\uFEFF";
-var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".md",
-  ".mdc",
-  ".mdx",
-  ".markdown",
-  ".txt",
-  ".json",
-  ".jsonc",
-  ".yaml",
-  ".yml",
-  ".toml",
-  ".ini",
-  ".sh",
-  ".bash",
-  ".zsh",
-  ".ps1",
-  ".js",
-  ".mjs",
-  ".cjs",
-  ".ts",
-  ".tsx",
-  ".html",
-  ".css"
-]);
-var TEXT_DOTFILES = /* @__PURE__ */ new Set([
-  ".gitignore",
-  ".cursorignore",
-  ".cursorindexingignore",
-  ".aiignore",
-  ".agentignore",
-  ".clineignore",
-  ".geminiignore",
-  ".codeiumignore",
-  ".continueignore",
-  ".copilotignore",
-  ".windsurfignore",
-  ".junieignore",
-  ".kiroignore",
-  ".rooignore",
-  ".antigravityignore"
-]);
-function shouldNormalizeLineEndings(path) {
-  const ext = extname(path).toLowerCase();
-  if (ext.length > 0) return TEXT_EXTENSIONS.has(ext);
-  const base = basename(path).toLowerCase();
-  return TEXT_DOTFILES.has(base);
+function commandProgram(command) {
+  const m = /^\s*(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(command);
+  return m?.[1] ?? m?.[2] ?? m?.[3] ?? "";
 }
-var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".bmp",
-  ".ico",
-  ".webp",
-  ".avif",
-  ".tiff",
-  ".pdf",
-  ".zip",
-  ".gz",
-  ".tgz",
-  ".bz2",
-  ".xz",
-  ".7z",
-  ".rar",
-  ".jar",
-  ".woff",
-  ".woff2",
-  ".ttf",
-  ".otf",
-  ".eot",
-  ".mp3",
-  ".mp4",
-  ".wav",
-  ".ogg",
-  ".webm",
-  ".mov",
-  ".wasm",
-  ".bin",
-  ".dat",
-  ".db",
-  ".sqlite",
-  ".so",
-  ".dylib",
-  ".dll",
-  ".exe",
-  ".class",
-  ".pyc",
-  // Office and design documents are zip or proprietary containers.
-  ".xlsx",
-  ".xls",
-  ".docx",
-  ".doc",
-  ".pptx",
-  ".ppt",
-  ".odt",
-  ".ods",
-  ".psd",
-  ".ai",
-  ".sketch",
-  ".fig",
-  ".heic",
-  ".heif",
-  // Archives, columnar data, models and compressed payloads.
-  ".tar",
-  ".zst",
-  ".br",
-  ".lz4",
-  ".parquet",
-  ".avro",
-  ".orc",
-  ".pkl",
-  ".npy",
-  ".npz",
-  ".onnx",
-  ".pt",
-  ".safetensors",
-  ".gguf",
-  ".sqlite3",
-  ".avi",
-  ".mkv",
-  ".flac",
-  ".aac",
-  ".m4a",
-  ".ttc"
-]);
-function isBinaryPayloadPath(path) {
-  return BINARY_EXTENSIONS.has(extname(path).toLowerCase());
+function isTransientBinDir(dir) {
+  const parts = dir.split(/[\\/]+/).filter((p) => p !== "");
+  const [parent, last] = parts.slice(-2);
+  return parts.includes("_npx") || parent === "node_modules" && last === ".bin";
 }
-function payloadEncodingFor(path) {
-  return isBinaryPayloadPath(path) ? "latin1" : "utf-8";
+function commandLauncherExists(command, env = process.env, platform = process.platform) {
+  const program = commandProgram(command);
+  if (program === "") return false;
+  if (program.includes("/") || program.includes("\\")) return existsSync(program);
+  const win = platform === "win32";
+  const exts = win ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")] : [""];
+  const dirs = (env.PATH ?? env.Path ?? "").split(win ? ";" : ":").filter((d) => d !== "" && !isTransientBinDir(d));
+  return dirs.some((dir) => exts.some((ext) => existsSync(join(dir, program + ext))));
 }
-function normalizeLineEndings(content) {
-  return content.replace(/\r\n?/g, "\n");
+function localBinExists(fromDir, name) {
+  for (let dir = resolve(fromDir); ; dir = dirname(dir)) {
+    const bin = join(dir, "node_modules", ".bin");
+    if (existsSync(join(bin, name)) || existsSync(join(bin, `${name}.cmd`))) return true;
+    if (dirname(dir) === dir) return false;
+  }
 }
-var EXECUTABLE_SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".sh", ".bash", ".zsh"]);
-function executableModeFor(path) {
-  return EXECUTABLE_SCRIPT_EXTENSIONS.has(extname(path).toLowerCase()) ? 493 : void 0;
+
+// src/lessons/merge-driver-setup.ts
+var LESSONS_MERGE_DRIVER = "agentsmesh-lessons";
+var LESSONS_GITATTRIBUTES_ENTRY = `${LESSONS_GRAPH_PATH} merge=${LESSONS_MERGE_DRIVER}`;
+var DRIVER_KEY = `merge.${LESSONS_MERGE_DRIVER}.driver`;
+var NAME_KEY = `merge.${LESSONS_MERGE_DRIVER}.name`;
+var DRIVER_NAME = "agentsmesh lessons union";
+function lessonsMergeDriverCommand(invocation) {
+  return `${invocation.replaceAll("\\", "/")} lessons merge-driver %O %A %B`;
+}
+var NPX_INVOCATION = "npx --no --offline agentsmesh";
+var NPX_COMMAND = lessonsMergeDriverCommand(NPX_INVOCATION);
+var BARE_COMMAND = lessonsMergeDriverCommand("agentsmesh");
+var OWN_COMMANDS = /* @__PURE__ */ new Set([BARE_COMMAND, NPX_COMMAND]);
+function launchable(command, env) {
+  const npxMissing = command === NPX_COMMAND && !commandLauncherExists(NPX_COMMAND, env);
+  return npxMissing && commandLauncherExists(BARE_COMMAND, env) ? BARE_COMMAND : command;
+}
+function configValue(git, root, key) {
+  const r = git(root, ["config", "--get", key]);
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+function launchProblem(git, projectRoot, command, env) {
+  if (!commandLauncherExists(command, env)) {
+    return `\`${commandProgram(command)}\` is not installed on PATH (npx and package-script bin folders do not count), so git could not start the driver; install agentsmesh globally or as a project devDependency`;
+  }
+  if (command !== NPX_COMMAND) return null;
+  const top = git(projectRoot, ["rev-parse", "--show-toplevel"]);
+  const repoRoot = top.status === 0 ? top.stdout.trim() : projectRoot;
+  if (localBinExists(repoRoot, "agentsmesh") || commandLauncherExists("agentsmesh", env)) {
+    return null;
+  }
+  return `git runs the driver from the repository root (${repoRoot.replaceAll("\\", "/")}), where \`${NPX_INVOCATION}\` cannot find agentsmesh; add agentsmesh to the devDependencies of the root package.json and install, or install agentsmesh globally`;
 }
-var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY", "EEXIST"]);
-async function renameWithRetry(from, to, options = {}) {
-  const attempts = options.attempts ?? 5;
-  const delayMs = options.delayMs ?? 50;
-  for (let attempt = 0; ; attempt++) {
-    try {
-      await rename(from, to);
-      return;
-    } catch (err) {
-      const code = err.code;
-      const transient = code !== void 0 && TRANSIENT_RENAME_CODES.has(code);
-      if (!transient || attempt >= attempts - 1) throw err;
-      await setTimeout(delayMs * 2 ** attempt);
+function ensureLessonsMergeDriver(projectRoot, options = {}) {
+  const git = options.git ?? runGit;
+  const env = options.env ?? process.env;
+  const command = launchable(
+    lessonsMergeDriverCommand(options.invocation ?? agentsmeshInvocation(projectRoot)),
+    env
+  );
+  const attr = git(projectRoot, ["check-attr", "merge", "--", LESSONS_GRAPH_PATH]);
+  if (attr.status !== 0 || !attr.stdout.trim().endsWith(`: merge: ${LESSONS_MERGE_DRIVER}`)) {
+    return { status: "skipped", command };
+  }
+  const existing = configValue(git, projectRoot, DRIVER_KEY);
+  if (existing !== null && existing !== command && !OWN_COMMANDS.has(existing)) {
+    return { status: "custom", command, existing };
+  }
+  const reason = existing === command ? null : launchProblem(git, projectRoot, command, env);
+  if (reason !== null) return { status: "failed", command, reason };
+  const writes = [];
+  if (existing !== command) writes.push([DRIVER_KEY, command]);
+  if (configValue(git, projectRoot, NAME_KEY) === null) writes.push([NAME_KEY, DRIVER_NAME]);
+  for (const [key, value] of writes) {
+    const r = git(projectRoot, ["config", "--local", key, value]);
+    if (r.status !== 0) {
+      const detail = r.stderr.trim() || `exit ${r.status}`;
+      const reason2 = `git config failed (${detail}); run: git config ${DRIVER_KEY} "${command}"`;
+      return { status: "failed", command, reason: reason2 };
     }
   }
+  if (existing === command) return { status: "unchanged", command };
+  return { status: existing === null ? "configured" : "updated", command };
+}
+var RECALL_HOOK_TEAM_HINT = "Lessons recall hooks call a global agentsmesh: teammates without a global install will not get lesson recall; add agentsmesh as a devDependency and re-run 'agentsmesh init --lessons'.";
+function recallHookTeamHint(projectRoot) {
+  const wired = wiredRecallCommands(projectRoot);
+  if (wired.length === 0) return null;
+  const expected = recallHookCommand(projectRoot);
+  const stale = wired.find((command) => command !== expected);
+  if (stale !== void 0) {
+    return `Lessons recall hooks run \`${stale}\`, but this project now calls \`${expected}\`; re-run 'agentsmesh init --lessons' to update them.`;
+  }
+  if (!existsSync(join(projectRoot, "package.json"))) return null;
+  return expected === RECALL_HOOK_COMMAND ? RECALL_HOOK_TEAM_HINT : null;
+}
+function wiredRecallCommands(projectRoot) {
+  try {
+    const hooks = parse(
+      readFileSync(join(projectRoot, ".agentsmesh", "hooks.yaml"), "utf8")
+    );
+    return Object.values(hooks ?? {}).filter(Array.isArray).flat().map((entry) => entry?.command).filter(isManagedRecallCommand).map((command) => command.trim());
+  } catch {
+    return [];
+  }
 }
 
 // src/utils/filesystem/fs.ts
@@ -3313,7 +4785,8 @@ At least one _effective_ trigger is required (or \`--scope always\` for a univer
 the capture is rejected (\`UNRECALLABLE_LESSON\`); prefer \`--trigger-file\`. No shell \u2192 MCP \`lessons_query\`,
 \`lessons_add\`, \`lessons_topics\`, \`lessons_show\`, \`lessons_deprecate\`. Run
 \`agentsmesh lessons --help\` for every subcommand and flag: query, add, topics, show,
-deprecate, merge, untrigger, strip-markers, prune, journal, validate, stats, import-md.
+deprecate, merge, untrigger, strip-markers, prune, journal, validate, resolve, stats, import-md.
+A git merge conflict in \`lessons.json\` \u2192 run \`agentsmesh lessons resolve\`; never hand-edit it.
 
 ### Rationalization Prevention \u2014 these excuses mean STOP
 
@@ -3357,11 +4830,14 @@ async function scaffoldLessons(projectRoot) {
   const gitignoreUpdated = await ensureGitignoreEntries(projectRoot, [
     toRelPath(projectRoot, recallLogPath(projectRoot)),
     toRelPath(projectRoot, captureLogPath(projectRoot)),
-    toRelPath(projectRoot, outcomeLogPath(projectRoot))
+    toRelPath(projectRoot, outcomeLogPath(projectRoot)),
+    `${toRelPath(projectRoot, lessonsLockPath(projectRoot))}/`,
+    `${toRelPath(projectRoot, paths.base)}/*.tmp`
   ]);
   const gitattributesUpdated = await ensureGitattributesEntries(projectRoot, [
     LESSONS_GITATTRIBUTES_ENTRY
   ]);
+  const mergeDriver = ensureLessonsMergeDriver(projectRoot);
   return {
     created,
     updated,
@@ -3369,7 +4845,9 @@ async function scaffoldLessons(projectRoot) {
     rootRuleUpdated,
     gitignoreUpdated,
     gitattributesUpdated,
-    recallHookInjected
+    recallHookInjected,
+    mergeDriver,
+    recallHookTeamHint: recallHookTeamHint(projectRoot)
   };
 }
 function seedLessonsSkill(projectRoot, created, updated, skipped) {