agentsmesh 0.40.0 → 0.41.0

package/dist/index.js

@@ -1,15 +1,15 @@
-import { z } from 'zod';
-import { stringify, parse, parseDocument, YAMLSeq, YAMLMap, isMap, Document, isSeq, isScalar, Scalar, Pair } from 'yaml';
-import { readFileSync, existsSync, mkdirSync, writeFileSync, constants, rmSync, renameSync, readdirSync, realpathSync, statSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, constants, rmSync, readdirSync, statSync, chmodSync, renameSync, accessSync, realpathSync, rmdirSync, unlinkSync } from 'fs';
 import { join, resolve, relative, sep, dirname, basename, extname, win32, posix } from 'path';
-import { mkdir, access, readdir, rm, readFile, writeFile, stat, lstat, open, realpath, rename, mkdtemp, cp } from 'fs/promises';
+import { stringify, parse, parseDocument, YAMLSeq, isMap, Document, isSeq, YAMLMap, isScalar, Scalar, Pair } from 'yaml';
+import { z } from 'zod';
+import { access, readdir, mkdir, readFile, rm, writeFile, lstat, open, stat, realpath, rmdir, unlink, rename, mkdtemp, cp } from 'fs/promises';
 import { setTimeout } from 'timers/promises';
 import { createHash, randomUUID } from 'crypto';
-import picomatch2 from 'picomatch';
+import picomatch from 'picomatch';
 import { parse as parse$1, stringify as stringify$1 } from 'smol-toml';
 import { Buffer } from 'buffer';
 import { homedir, hostname, tmpdir } from 'os';
-import { execFile } from 'child_process';
+import { execFile, spawnSync } from 'child_process';
 import { fileURLToPath, pathToFileURL, URL as URL$1 } from 'url';
 import { promisify } from 'util';
 import * as tar from 'tar';
@@ -24,6 +24,104 @@ var __export = (target34, all) => {
   for (var name in all)
     __defProp(target34, name, { get: all[name], enumerable: true });
 };
+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;
+  }
+}
+var LOCAL_FIRST, BARE, DEPENDENCY_FIELDS;
+var init_cli_invocation = __esm({
+  "src/lessons/cli-invocation.ts"() {
+    LOCAL_FIRST = "npx --no --offline agentsmesh";
+    BARE = "agentsmesh";
+    DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "optionalDependencies"];
+  }
+});
+function recallHookCommand(projectRoot) {
+  return `${agentsmeshInvocation(projectRoot)} ${RECALL_SUBCOMMAND}`;
+}
+function isRecallHookCommand(command) {
+  return typeof command === "string" && command.includes(RECALL_HOOK_COMMAND);
+}
+function isManagedRecallCommand(command) {
+  return typeof command === "string" && MANAGED_COMMAND.test(command.trim());
+}
+function isManaged(item) {
+  return item instanceof YAMLMap && isManagedRecallCommand(item.get("command"));
+}
+function removeEvent(doc, event) {
+  const existing = doc.get(event);
+  if (!(existing instanceof YAMLSeq)) return false;
+  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 upsertEvent(doc, event, matcher, command) {
+  const existing = doc.get(event);
+  const seq = existing instanceof YAMLSeq ? existing : new YAMLSeq();
+  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 (upsertEvent(doc, event, matcher, command)) changed = true;
+  }
+  for (const event of RETIRED_EVENTS) {
+    if (removeEvent(doc, event)) changed = true;
+  }
+  if (changed) writeFileSync(path, String(doc), "utf8");
+  return changed;
+}
+var RECALL_SUBCOMMAND, RECALL_HOOK_COMMAND, RECALL_HOOK_TOOL_MATCHER, MANAGED_COMMAND, RECALL_EVENTS, RETIRED_EVENTS;
+var init_recall_hook_scaffold = __esm({
+  "src/lessons/recall-hook-scaffold.ts"() {
+    init_cli_invocation();
+    RECALL_SUBCOMMAND = "lessons hook";
+    RECALL_HOOK_COMMAND = `agentsmesh ${RECALL_SUBCOMMAND}`;
+    RECALL_HOOK_TOOL_MATCHER = "Edit|Write|NotebookEdit|Bash|PowerShell";
+    MANAGED_COMMAND = new RegExp(`^(?:npx(?: --?[\\w-]+)* )?${RECALL_HOOK_COMMAND}$`);
+    RECALL_EVENTS = [
+      { event: "PreToolUse", matcher: RECALL_HOOK_TOOL_MATCHER },
+      { event: "UserPromptSubmit", matcher: "*" },
+      // 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.
+      { event: "SessionStart", matcher: "*" }
+    ];
+    RETIRED_EVENTS = ["PostToolUse"];
+  }
+});
 function capabilityLevel(capability) {
   return typeof capability === "string" ? capability : capability.level;
 }
@@ -183,6 +281,7 @@ var init_target_descriptor_schema = __esm({
       emitScopedSettings: z.function().optional(),
       mergeGeneratedOutputContent: z.function().optional(),
       postProcessHookOutputs: z.function().optional(),
+      hookContextEvents: z.array(z.string()).optional(),
       preservesManualActivation: z.boolean().optional()
     }).passthrough();
     targetDescriptorSchema = targetDescriptorSchemaBase.superRefine((value, ctx) => {
@@ -578,61 +677,6 @@ var init_guards = __esm({
   "src/utils/types/guards.ts"() {
   }
 });
-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)
-  );
-  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) {
-  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;
-}
-function injectRecallHook(projectRoot) {
-  const path = join(projectRoot, ".agentsmesh", "hooks.yaml");
-  if (!existsSync(path)) return false;
-  const doc = parseDocument(readFileSync(path, "utf8"));
-  let changed = false;
-  for (const { event, matcher } of RECALL_EVENTS) {
-    if (injectEvent(doc, event, matcher)) changed = true;
-  }
-  for (const event of RETIRED_EVENTS) {
-    if (removeEvent(doc, event)) changed = true;
-  }
-  if (changed) writeFileSync(path, String(doc), "utf8");
-  return changed;
-}
-var RECALL_HOOK_COMMAND, RECALL_HOOK_TOOL_MATCHER, RECALL_EVENTS, RETIRED_EVENTS;
-var init_recall_hook_scaffold = __esm({
-  "src/lessons/recall-hook-scaffold.ts"() {
-    RECALL_HOOK_COMMAND = "agentsmesh lessons hook";
-    RECALL_HOOK_TOOL_MATCHER = "Edit|Write|Bash";
-    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.
-      { 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.
-      { event: "SessionStart", matcher: "*" }
-    ];
-    RETIRED_EVENTS = ["PostToolUse"];
-  }
-});
 
 // src/core/hook-types.ts
 function isBestEffortHookEvent(event, entries) {
@@ -960,8 +1004,10 @@ function executableModeFor(path) {
 }
 function normalizeTextPayload(path, content) {
   if (!shouldNormalizeLineEndings(path)) return content;
-  const withoutBom = content.startsWith(UTF8_BOM) ? content.slice(UTF8_BOM.length) : content;
-  return normalizeLineEndings(withoutBom);
+  return normalizeLineEndings(stripBom(content));
+}
+function stripBom(text) {
+  return text.startsWith(UTF8_BOM) ? text.slice(UTF8_BOM.length) : text;
 }
 var UTF8_BOM, TEXT_EXTENSIONS, TEXT_DOTFILES, BINARY_EXTENSIONS, EXECUTABLE_SCRIPT_EXTENSIONS;
 var init_fs_text_encoding = __esm({
@@ -2161,6 +2207,15 @@ var init_constants = __esm({
   }
 });
 
+// src/targets/catalog/ignore-output.ts
+function ignoreOutput(path) {
+  return (canonical) => canonical.ignore.length === 0 ? [] : [{ path, content: canonical.ignore.join("\n") }];
+}
+var init_ignore_output = __esm({
+  "src/targets/catalog/ignore-output.ts"() {
+  }
+});
+
 // src/targets/aider/generator.ts
 function buildAiderConventions(canonical) {
   const root = canonical.rules.find((rule) => rule.root);
@@ -2190,11 +2245,7 @@ function generateAgents(canonical) {
     content: serializeProjectedAgentSkill(agent)
   }));
 }
-function generateIgnore(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: AIDER_IGNORE, content: canonical.ignore.join("\n") }];
-}
-var generateMcp, generatePermissions;
+var generateIgnore, generateMcp, generatePermissions;
 var init_generator = __esm({
   "src/targets/aider/generator.ts"() {
     init_no_outputs();
@@ -2203,6 +2254,8 @@ var init_generator = __esm({
     init_projected_agent_skill();
     init_command_skill();
     init_constants();
+    init_ignore_output();
+    generateIgnore = ignoreOutput(AIDER_IGNORE);
     generateMcp = NO_OUTPUTS;
     generatePermissions = NO_OUTPUTS;
   }
@@ -3731,7 +3784,7 @@ var init_importer = __esm({
   }
 });
 function globFilter(files, pattern) {
-  const isMatch = picomatch2(pattern, OPTIONS);
+  const isMatch = picomatch(pattern, OPTIONS);
   return files.filter((file) => isMatch(file));
 }
 var OPTIONS;
@@ -7096,10 +7149,6 @@ function generateAgents4(canonical) {
     content: serializeAntigravityAgent(agent)
   }));
 }
-function generateIgnore3(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: ANTIGRAVITY_IGNORE_FILE, content: canonical.ignore.join("\n") }];
-}
 function renderAntigravityGlobalInstructions(canonical) {
   const root = canonical.rules.find((rule) => rule.root);
   const nonRootRules = canonical.rules.filter((rule) => {
@@ -7114,7 +7163,7 @@ function generateHooks2(canonical) {
   if (Object.keys(hooks).length === 0) return [];
   return [{ path: ANTIGRAVITY_HOOKS_FILE, content: JSON.stringify(hooks, null, 2) }];
 }
-var generatePermissions3;
+var generateIgnore3, generatePermissions3;
 var init_generator4 = __esm({
   "src/targets/antigravity/generator.ts"() {
     init_no_outputs();
@@ -7123,6 +7172,8 @@ var init_generator4 = __esm({
     init_hooks_format2();
     init_agents_format();
     init_constants5();
+    init_ignore_output();
+    generateIgnore3 = ignoreOutput(ANTIGRAVITY_IGNORE_FILE);
     generatePermissions3 = NO_OUTPUTS;
   }
 });
@@ -8716,16 +8767,14 @@ function generateHooks3(canonical) {
   const content = JSON.stringify({ hooks: claudeHooks }, null, 2);
   return [{ path: CLAUDE_SETTINGS, content }];
 }
-function generateIgnore5(canonical) {
-  if (!canonical.ignore || canonical.ignore.length === 0) return [];
-  const content = canonical.ignore.join("\n");
-  return [{ path: CLAUDE_IGNORE, content }];
-}
+var generateIgnore5;
 var init_generator6 = __esm({
   "src/targets/claude-code/generator.ts"() {
     init_markdown();
     init_constants7();
     init_hooks_format2();
+    init_ignore_output();
+    generateIgnore5 = ignoreOutput(CLAUDE_IGNORE);
   }
 });
 function ruleSectionTitle(rule) {
@@ -10544,11 +10593,7 @@ function generateMcp5(canonical) {
   if (!canonical.mcp || Object.keys(canonical.mcp.mcpServers).length === 0) return [];
   return [{ path: CODEBUFF_MCP_FILE, content: serializeCodebuffMcp(canonical.mcp) }];
 }
-function generateIgnore7(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: CODEBUFF_IGNORE_FILE, content: canonical.ignore.join("\n") }];
-}
-var generateAgents8, generateHooks5, generatePermissions6;
+var generateIgnore7, generateAgents8, generateHooks5, generatePermissions6;
 var init_generator8 = __esm({
   "src/targets/codebuff/generator.ts"() {
     init_no_outputs();
@@ -10558,6 +10603,8 @@ var init_generator8 = __esm({
     init_nested_rules();
     init_mcp_format2();
     init_constants9();
+    init_ignore_output();
+    generateIgnore7 = ignoreOutput(CODEBUFF_IGNORE_FILE);
     generateAgents8 = NO_OUTPUTS;
     generateHooks5 = NO_OUTPUTS;
     generatePermissions6 = NO_OUTPUTS;
@@ -13070,53 +13117,37 @@ var init_mcp_generator = __esm({
   }
 });
 
-// src/targets/copilot/hook-entry.ts
-function hasHookCommand2(entry) {
-  return hasHookCommand(entry);
-}
-var init_hook_entry = __esm({
-  "src/targets/copilot/hook-entry.ts"() {
-    init_hook_command();
-  }
-});
-
 // src/targets/copilot/hook-format.ts
-function mapHookEvent(event) {
-  switch (event) {
-    case "PreToolUse":
-      return "preToolUse";
-    case "PostToolUse":
-      return "postToolUse";
-    case "Notification":
-      return "notification";
-    case "UserPromptSubmit":
-      return "userPromptSubmitted";
-    default:
-      return null;
-  }
+function copilotHookGroups(hooks) {
+  return Object.entries(hooks ?? {}).flatMap(([event, entries]) => {
+    const copilotEvent = CANONICAL_TO_COPILOT.get(event);
+    if (!copilotEvent || !Array.isArray(entries)) return [];
+    const kept = entries.filter(
+      (entry) => typeof entry === "object" && entry !== null && hasHookCommand(entry)
+    );
+    return kept.length > 0 ? [{ event, copilotEvent, entries: kept }] : [];
+  });
+}
+function wrapperScriptName(event, index) {
+  return `${event.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase()}-${index}.sh`;
 }
 function buildCopilotHooksObject(hooks) {
-  if (!hooks) return null;
-  const result2 = Object.fromEntries(
-    Object.entries(hooks).flatMap(([event, entries]) => {
-      const mappedEvent = mapHookEvent(event);
-      if (!mappedEvent || !Array.isArray(entries)) return [];
-      const mappedEntries = entries.filter(
-        (entry) => typeof entry === "object" && entry !== null && hasHookCommand2(entry)
-      ).map((entry, index) => {
-        const safePhase = event.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase();
+  const groups = copilotHookGroups(hooks);
+  if (groups.length === 0) return null;
+  return Object.fromEntries(
+    groups.map(({ event, copilotEvent, entries }) => [
+      copilotEvent,
+      entries.map((entry, index) => {
         const hook = {
           type: "command",
-          bash: `./scripts/${safePhase}-${index}.sh`
+          bash: `./scripts/${wrapperScriptName(event, index)}`
         };
         if (entry.matcher && entry.matcher !== "*") hook.matcher = entry.matcher;
         if (entry.timeout !== void 0) hook.timeoutSec = Math.ceil(entry.timeout / 1e3);
         return hook;
-      });
-      return mappedEntries.length > 0 ? [[mappedEvent, mappedEntries]] : [];
-    })
+      })
+    ])
   );
-  return Object.keys(result2).length > 0 ? result2 : null;
 }
 function generateHooks8(canonical) {
   const hooks = buildCopilotHooksObject(canonical.hooks);
@@ -13128,10 +13159,24 @@ function generateHooks8(canonical) {
     }
   ];
 }
+var COPILOT_HOOK_CONTEXT_EVENTS, CANONICAL_TO_COPILOT;
 var init_hook_format = __esm({
   "src/targets/copilot/hook-format.ts"() {
     init_constants32();
-    init_hook_entry();
+    init_hook_command();
+    COPILOT_HOOK_CONTEXT_EVENTS = [
+      "SessionStart",
+      "PostToolUse",
+      "PostToolUseFailure"
+    ];
+    CANONICAL_TO_COPILOT = /* @__PURE__ */ new Map([
+      ["PreToolUse", "preToolUse"],
+      ["PostToolUse", "postToolUse"],
+      ["PostToolUseFailure", "postToolUseFailure"],
+      ["Notification", "notification"],
+      ["UserPromptSubmit", "userPromptSubmitted"],
+      ["SessionStart", "sessionStart"]
+    ]);
   }
 });
 function ruleSlug2(source) {
@@ -13237,18 +13282,7 @@ var init_generator12 = __esm({
   }
 });
 function mapCopilotHookEvent(event) {
-  switch (event) {
-    case "preToolUse":
-      return "PreToolUse";
-    case "postToolUse":
-      return "PostToolUse";
-    case "notification":
-      return "Notification";
-    case "userPromptSubmitted":
-      return "UserPromptSubmit";
-    default:
-      return null;
-  }
+  return COPILOT_TO_CANONICAL.get(event) ?? null;
 }
 function extractMatcher(comment) {
   if (typeof comment !== "string") return "*";
@@ -13336,11 +13370,16 @@ async function importHooks(projectRoot, results, options = {}) {
     feature: "hooks"
   });
 }
+var COPILOT_TO_CANONICAL;
 var init_hook_parser = __esm({
   "src/targets/copilot/hook-parser.ts"() {
     init_canonical_paths();
     init_fs();
     init_constants32();
+    init_hook_format();
+    COPILOT_TO_CANONICAL = new Map(
+      [...CANONICAL_TO_COPILOT].map(([canonical, copilot]) => [copilot, canonical])
+    );
   }
 });
 async function importSkills2(projectRoot, results, normalize, skillsDirRel = COPILOT_SKILLS_DIR) {
@@ -13577,7 +13616,7 @@ function lintCommands4(canonical) {
 }
 function lintHooks9(canonical) {
   if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
-  const supported = ["PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit"];
+  const supported = [...CANONICAL_TO_COPILOT.keys()];
   const diagnostics = unsupportedHookEventNames(canonical.hooks, supported).map(
     (event) => createUnsupportedHookWarning(event, "copilot", supported, {
       unsupportedBy: "Copilot hooks"
@@ -13600,11 +13639,9 @@ function lintHooks9(canonical) {
 var init_lint10 = __esm({
   "src/targets/copilot/lint.ts"() {
     init_helpers();
+    init_hook_format();
   }
 });
-function safePhaseName(phase) {
-  return phase.replace(/[^a-zA-Z0-9]/g, "-").toLowerCase();
-}
 function toRepoRelative(projectRoot, sourcePath) {
   const repoRelative = relative(projectRoot, sourcePath).replace(/\\/g, "/");
   if (!repoRelative || repoRelative.startsWith("../")) return null;
@@ -13632,9 +13669,6 @@ async function buildAssetOutput(projectRoot, command, hooksDirRel) {
     rewrittenCommand: rewriteWrapperCommand(command, repoRelative)
   };
 }
-function wrapperPath(event, index, hooksDirRel) {
-  return `${hooksDirRel}/scripts/${safePhaseName(event)}-${index}.sh`;
-}
 function safeShellLine2(value) {
   return value.replace(/[\r\n]+/g, " ");
 }
@@ -13649,15 +13683,13 @@ function buildWrapper(command, matcher) {
   ].join("\n");
 }
 async function addHookScriptAssets(projectRoot, canonical, outputs, hooksDirRel = COPILOT_HOOKS_DIR) {
-  if (!canonical.hooks) return outputs;
+  const groups = copilotHookGroups(canonical.hooks);
+  if (groups.length === 0) return outputs;
   const wrapperOutputs = [];
   const assetOutputs = /* @__PURE__ */ new Map();
-  for (const [event, entries] of Object.entries(canonical.hooks)) {
-    if (!Array.isArray(entries)) continue;
-    let index = 0;
-    for (const entry of entries) {
-      if (!hasHookCommand2(entry)) continue;
-      const scriptPath = wrapperPath(event, index, hooksDirRel);
+  for (const { event, entries } of groups) {
+    for (const [index, entry] of entries.entries()) {
+      const scriptPath = `${hooksDirRel}/scripts/${wrapperScriptName(event, index)}`;
       let command = entry.command;
       const asset = await buildAssetOutput(projectRoot, entry.command, hooksDirRel);
       if (asset) {
@@ -13671,7 +13703,6 @@ async function addHookScriptAssets(projectRoot, canonical, outputs, hooksDirRel
         'set -eu\nHOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"\n'
       );
       wrapperOutputs.push({ path: scriptPath, content: wrapper });
-      index++;
     }
   }
   return [...outputs, ...wrapperOutputs, ...assetOutputs.values()];
@@ -13681,7 +13712,7 @@ var init_hook_assets = __esm({
   "src/targets/copilot/hook-assets.ts"() {
     init_fs();
     init_constants32();
-    init_hook_entry();
+    init_hook_format();
     SCRIPT_PREFIX_RE = /^(?<prefix>\s*(?:(?:bash|sh|zsh)\s+)?)["']?(?<path>(?:\.\.\/|\.\/|[^/\s"'`]+\/)[^\s"'`]+)["']?(?<suffix>(?:\s.*)?)$/;
   }
 });
@@ -13999,6 +14030,7 @@ var init_copilot2 = __esm({
     init_command_prompt();
     init_lint10();
     init_hook_assets();
+    init_hook_format();
     init_scope_extras2();
     init_importer_spec2();
     init_capabilities6();
@@ -14129,6 +14161,7 @@ var init_copilot2 = __esm({
         permissions: lintPermissions7
       },
       postProcessHookOutputs: async (projectRoot, canonical, outputs) => addHookScriptAssets(projectRoot, canonical, [...outputs]),
+      hookContextEvents: COPILOT_HOOK_CONTEXT_EVENTS,
       mergeGeneratedOutputContent: mergeCopilotMcpJson,
       project: project7,
       globalSupport: {
@@ -14216,11 +14249,6 @@ function generatePermissions8(canonical) {
   });
   return [{ path: CRUSH_CONFIG_FILE, content: JSON.stringify(crushConfig, null, 2) }];
 }
-function generateIgnore9(canonical) {
-  if (!canonical.ignore || canonical.ignore.length === 0) return [];
-  const content = canonical.ignore.join("\n");
-  return [{ path: CRUSH_IGNORE, content }];
-}
 function buildCrushHooksFromCanonical(canonical) {
   if (!canonical.hooks) return {};
   const result2 = {};
@@ -14238,7 +14266,7 @@ function buildCrushHooksFromCanonical(canonical) {
   }
   return result2;
 }
-var generateRules12;
+var generateRules12, generateIgnore9;
 var init_generator13 = __esm({
   "src/targets/crush/generator.ts"() {
     init_managed_blocks();
@@ -14247,7 +14275,9 @@ var init_generator13 = __esm({
     init_command_skill();
     init_constants12();
     init_config_format();
+    init_ignore_output();
     generateRules12 = (canonical) => embeddedRootRule(canonical, CRUSH_TARGET, CRUSH_ROOT_FILE);
+    generateIgnore9 = ignoreOutput(CRUSH_IGNORE);
   }
 });
 async function importFromCrush(projectRoot, options = {}) {
@@ -14783,7 +14813,7 @@ function cursorHooksToCanonical(hooks) {
   }
   return result2;
 }
-var CANONICAL_TO_CURSOR, CURSOR_TO_CANONICAL;
+var CANONICAL_TO_CURSOR, CURSOR_HOOK_CONTEXT_EVENTS, CURSOR_TO_CANONICAL;
 var init_hook_format2 = __esm({
   "src/targets/cursor/hook-format.ts"() {
     init_hook_types();
@@ -14791,6 +14821,7 @@ var init_hook_format2 = __esm({
     CANONICAL_TO_CURSOR = {
       PreToolUse: "preToolUse",
       PostToolUse: "postToolUse",
+      PostToolUseFailure: "postToolUseFailure",
       UserPromptSubmit: "beforeSubmitPrompt",
       SubagentStart: "subagentStart",
       SubagentStop: "subagentStop",
@@ -14799,6 +14830,11 @@ var init_hook_format2 = __esm({
       SessionEnd: "sessionEnd",
       PreCompact: "preCompact"
     };
+    CURSOR_HOOK_CONTEXT_EVENTS = [
+      "SessionStart",
+      "PostToolUse",
+      "PostToolUseFailure"
+    ];
     CURSOR_TO_CANONICAL = new Map(
       Object.entries(CANONICAL_TO_CURSOR).map(([canonical, cursor]) => [cursor, canonical])
     );
@@ -14807,7 +14843,7 @@ var init_hook_format2 = __esm({
 
 // src/targets/cursor/generator/hooks.ts
 function generateHooks10(canonical) {
-  if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
+  if (!canonical.hooks) return [];
   const cursorHooks = toCursorHooks(canonical.hooks);
   if (Object.keys(cursorHooks).length === 0) return [];
   const content = JSON.stringify({ version: 1, hooks: cursorHooks }, null, 2);
@@ -14821,14 +14857,12 @@ var init_hooks3 = __esm({
 });
 
 // src/targets/cursor/generator/ignore.ts
-function generateIgnore10(canonical) {
-  if (!canonical.ignore || canonical.ignore.length === 0) return [];
-  const content = canonical.ignore.join("\n");
-  return [{ path: CURSOR_IGNORE, content }];
-}
+var generateIgnore10;
 var init_ignore = __esm({
   "src/targets/cursor/generator/ignore.ts"() {
     init_constants13();
+    init_ignore_output();
+    generateIgnore10 = ignoreOutput(CURSOR_IGNORE);
   }
 });
 
@@ -15524,6 +15558,7 @@ var init_cursor2 = __esm({
     init_linter13();
     init_import_map_builders();
     init_lint12();
+    init_hook_format2();
     target13 = {
       name: "cursor",
       primaryRootInstructionPath: CURSOR_GENERAL_RULE,
@@ -15645,6 +15680,7 @@ var init_cursor2 = __esm({
         permissions: "native"
       },
       emptyImportMessage: "No Cursor config found (AGENTS.md or .cursor/rules/*.mdc; with --global: ~/.cursor/{rules/*.mdc,AGENTS.md,mcp.json,hooks.json,cursorignore,skills/,agents/,commands/} and legacy ~/.agentsmesh-exports/cursor/user-rules.md).",
+      hookContextEvents: CURSOR_HOOK_CONTEXT_EVENTS,
       lintRules: lintRules13,
       lint: {
         commands: lintCommands6,
@@ -16906,25 +16942,127 @@ var init_skills3 = __esm({
   }
 });
 
-// src/targets/gemini-cli/generator/settings.ts
-function mapHookEvent2(event) {
-  switch (event) {
-    case "PreToolUse":
-      return "BeforeTool";
-    case "PostToolUse":
-      return "AfterTool";
-    case "Notification":
-      return "Notification";
-    case "SubagentStart":
-      return "BeforeAgent";
-    case "SubagentStop":
-      return "AfterAgent";
-    case "SessionStart":
-      return "SessionStart";
-    default:
-      return null;
+// src/targets/gemini-cli/hook-map.ts
+function geminiHookEvent(event) {
+  return CANONICAL_TO_GEMINI.get(event) ?? null;
+}
+function mapGeminiHookEvent(event) {
+  return GEMINI_TO_CANONICAL.get(event) ?? null;
+}
+function splitNames(list, separator) {
+  return list.split(separator).map((name) => name.trim()).filter((name) => name.length > 0);
+}
+function toGeminiMatcher(geminiEvent, matcher) {
+  if (!TOOL_EVENTS.has(geminiEvent) || !NAME_LIST.test(matcher)) return matcher;
+  const tools = unique(
+    splitNames(matcher, /[|,]/).flatMap((name) => CANONICAL_TO_GEMINI_TOOLS.get(name) ?? [name])
+  );
+  return tools.length > 0 ? `^(?:${tools.join("|")})$` : matcher;
+}
+function fromGeminiMatcher(geminiEvent, matcher) {
+  if (!TOOL_EVENTS.has(geminiEvent)) return matcher;
+  const list = ANCHORED_LIST.exec(matcher)?.[1] ?? matcher;
+  if (!NAME_LIST.test(list) || list.includes(",")) return matcher;
+  return unique(
+    splitNames(list, /\|/).map((name) => GEMINI_TO_CANONICAL_TOOLS.get(name) ?? name)
+  ).join("|");
+}
+var GEMINI_HOOK_CONTEXT_EVENTS, CANONICAL_TO_GEMINI, GEMINI_TO_CANONICAL, TOOL_EVENTS, CANONICAL_TO_GEMINI_TOOLS, GEMINI_TO_CANONICAL_TOOLS, NAME_LIST, ANCHORED_LIST, unique;
+var init_hook_map = __esm({
+  "src/targets/gemini-cli/hook-map.ts"() {
+    GEMINI_HOOK_CONTEXT_EVENTS = [
+      "UserPromptSubmit",
+      "SessionStart",
+      "PostToolUse"
+    ];
+    CANONICAL_TO_GEMINI = /* @__PURE__ */ new Map([
+      ["PreToolUse", "BeforeTool"],
+      ["PostToolUse", "AfterTool"],
+      ["Notification", "Notification"],
+      // BeforeAgent fires after the user submits a prompt and carries `prompt`.
+      ["UserPromptSubmit", "BeforeAgent"],
+      // Older mapping, kept so existing SubagentStart hooks still reach Gemini.
+      ["SubagentStart", "BeforeAgent"],
+      ["SubagentStop", "AfterAgent"],
+      ["SessionStart", "SessionStart"]
+    ]);
+    GEMINI_TO_CANONICAL = new Map([
+      ...[...CANONICAL_TO_GEMINI].map(([canonical, gemini]) => [gemini, canonical]),
+      // BeforeAgent is shared with SubagentStart; import it as the prompt event.
+      ["BeforeAgent", "UserPromptSubmit"],
+      // Legacy lowercase names.
+      ["preToolUse", "PreToolUse"],
+      ["postToolUse", "PostToolUse"],
+      ["notification", "Notification"]
+    ]);
+    TOOL_EVENTS = /* @__PURE__ */ new Set(["BeforeTool", "AfterTool"]);
+    CANONICAL_TO_GEMINI_TOOLS = /* @__PURE__ */ new Map([
+      ["Bash", ["run_shell_command"]],
+      ["PowerShell", ["run_shell_command"]],
+      ["Edit", ["replace"]],
+      ["MultiEdit", ["replace"]],
+      ["Write", ["write_file"]],
+      ["NotebookEdit", []],
+      ["Read", ["read_file", "read_many_files"]],
+      ["Grep", ["grep_search"]],
+      ["Glob", ["glob"]],
+      ["LS", ["list_directory"]],
+      ["WebFetch", ["web_fetch"]],
+      ["WebSearch", ["google_web_search"]],
+      ["TodoWrite", ["write_todos"]]
+    ]);
+    GEMINI_TO_CANONICAL_TOOLS = /* @__PURE__ */ new Map([
+      ["run_shell_command", "Bash"],
+      ["replace", "Edit"],
+      ["write_file", "Write"],
+      ["read_file", "Read"],
+      ["read_many_files", "Read"],
+      ["grep_search", "Grep"],
+      ["search_file_content", "Grep"],
+      ["glob", "Glob"],
+      ["list_directory", "LS"],
+      ["web_fetch", "WebFetch"],
+      ["google_web_search", "WebSearch"],
+      ["write_todos", "TodoWrite"]
+    ]);
+    NAME_LIST = /^[\w\s,|-]+$/;
+    ANCHORED_LIST = /^\^\(\?:(.*)\)\$$/;
+    unique = (values) => [...new Set(values)];
+  }
+});
+
+// src/targets/gemini-cli/generator/hooks.ts
+function buildGeminiHooks(hooks) {
+  const result2 = {};
+  for (const [event, entries] of Object.entries(hooks ?? {})) {
+    const geminiEvent = geminiHookEvent(event);
+    if (!geminiEvent || !Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (typeof entry !== "object" || entry === null || !hasHookCommand(entry)) continue;
+      const list = result2[geminiEvent] ??= [];
+      list.push({
+        matcher: typeof entry.matcher === "string" ? toGeminiMatcher(geminiEvent, entry.matcher) : entry.matcher,
+        hooks: [
+          {
+            name: `${geminiEvent}-${list.length + 1}`,
+            type: "command",
+            command: getHookCommand(entry),
+            timeout: entry.timeout
+          }
+        ]
+      });
+    }
   }
+  return Object.keys(result2).length > 0 ? result2 : null;
 }
+var init_hooks4 = __esm({
+  "src/targets/gemini-cli/generator/hooks.ts"() {
+    init_hook_command();
+    init_hook_map();
+  }
+});
+
+// src/targets/gemini-cli/generator/settings.ts
 function generateGeminiSettingsFiles(canonical, enabledFeatures) {
   const settings = {};
   let hasAnyNativeSettings = false;
@@ -16936,29 +17074,10 @@ function generateGeminiSettingsFiles(canonical, enabledFeatures) {
     settings.experimental = { enableAgents: true };
     hasAnyNativeSettings = true;
   }
-  if (enabledFeatures.has("hooks") && canonical.hooks) {
-    const hookEntries = Object.entries(canonical.hooks).flatMap(([event, entries]) => {
-      const mappedEvent = mapHookEvent2(event);
-      if (!mappedEvent || !Array.isArray(entries)) return [];
-      const mappedEntries = entries.filter(
-        (entry) => typeof entry === "object" && entry !== null && hasHookCommand(entry)
-      ).map((entry, index) => ({
-        matcher: entry.matcher,
-        hooks: [
-          {
-            name: `${mappedEvent}-${index + 1}`,
-            type: "command",
-            command: getHookCommand(entry),
-            timeout: entry.timeout
-          }
-        ]
-      }));
-      return mappedEntries.length > 0 ? [[mappedEvent, mappedEntries]] : [];
-    });
-    if (hookEntries.length > 0) {
-      settings.hooks = Object.fromEntries(hookEntries);
-      hasAnyNativeSettings = true;
-    }
+  const hooks = enabledFeatures.has("hooks") ? buildGeminiHooks(canonical.hooks) : null;
+  if (hooks) {
+    settings.hooks = hooks;
+    hasAnyNativeSettings = true;
   }
   if (hasAnyNativeSettings) {
     settings.context = { fileName: [GEMINI_ROOT, GEMINI_COMPAT_AGENTS] };
@@ -16968,19 +17087,18 @@ function generateGeminiSettingsFiles(canonical, enabledFeatures) {
 }
 var init_settings2 = __esm({
   "src/targets/gemini-cli/generator/settings.ts"() {
-    init_hook_command();
     init_constants33();
+    init_hooks4();
   }
 });
 
 // src/targets/gemini-cli/generator/ignore.ts
-function generateIgnore13(canonical) {
-  if (!canonical.ignore || canonical.ignore.length === 0) return [];
-  return [{ path: GEMINI_IGNORE, content: canonical.ignore.join("\n") }];
-}
+var generateIgnore13;
 var init_ignore2 = __esm({
   "src/targets/gemini-cli/generator/ignore.ts"() {
     init_constants33();
+    init_ignore_output();
+    generateIgnore13 = ignoreOutput(GEMINI_IGNORE);
   }
 });
 
@@ -17259,27 +17377,6 @@ var init_layout6 = __esm({
     };
   }
 });
-function mapGeminiHookEvent(event) {
-  switch (event) {
-    case "BeforeTool":
-    case "preToolUse":
-      return "PreToolUse";
-    case "AfterTool":
-    case "postToolUse":
-      return "PostToolUse";
-    case "Notification":
-    case "notification":
-      return "Notification";
-    case "BeforeAgent":
-      return "SubagentStart";
-    case "AfterAgent":
-      return "SubagentStop";
-    case "SessionStart":
-      return "SessionStart";
-    default:
-      return null;
-  }
-}
 function parseFlexibleFrontmatter(content) {
   const yamlOpen = content.indexOf("---");
   const tomlOpen = content.indexOf("+++");
@@ -17353,7 +17450,7 @@ async function importGeminiSettings(projectRoot, results) {
           (entry) => entry.hooks.filter(
             (hook) => hook !== null && typeof hook === "object" && hasHookCommand(hook)
           ).map((hook) => ({
-            matcher: entry.matcher,
+            matcher: fromGeminiMatcher(event, entry.matcher),
             command: getHookCommand(hook),
             type: "command",
             timeout: typeof hook.timeout === "number" ? hook.timeout : void 0
@@ -17363,7 +17460,7 @@ async function importGeminiSettings(projectRoot, results) {
           const legacyMapped = value.filter(
             (entry) => entry !== null && typeof entry === "object" && typeof entry.matcher === "string" && hasHookCommand(entry)
           ).map((entry) => ({
-            matcher: entry.matcher,
+            matcher: fromGeminiMatcher(event, entry.matcher),
             command: getHookCommand(entry),
             type: "command"
           }));
@@ -17392,7 +17489,7 @@ var init_format_helpers_settings = __esm({
     init_hook_command();
     init_fs();
     init_constants33();
-    init_format_helpers_shared();
+    init_hook_map();
   }
 });
 async function importGeminiIgnore(projectRoot, results) {
@@ -17888,14 +17985,7 @@ function lintPermissions10(canonical, options) {
 }
 function lintHooks12(canonical) {
   if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
-  const supported = [
-    "PreToolUse",
-    "PostToolUse",
-    "Notification",
-    "SubagentStart",
-    "SubagentStop",
-    "SessionStart"
-  ];
+  const supported = [...CANONICAL_TO_GEMINI.keys()];
   return unsupportedHookEventNames(canonical.hooks, supported).map(
     (event) => createUnsupportedHookWarning(event, "gemini-cli", supported)
   );
@@ -17903,6 +17993,7 @@ function lintHooks12(canonical) {
 var init_lint15 = __esm({
   "src/targets/gemini-cli/lint.ts"() {
     init_helpers();
+    init_hook_map();
   }
 });
 
@@ -17939,6 +18030,7 @@ var init_gemini_cli2 = __esm({
     init_import_map_builders();
     init_lint15();
     init_scoped_settings_emit();
+    init_hook_map();
     init_settings();
     target16 = {
       name: "gemini-cli",
@@ -17989,6 +18081,7 @@ var init_gemini_cli2 = __esm({
         permissions: lintPermissions10
       },
       emitScopedSettings: emitScopedGeminiSettings,
+      hookContextEvents: GEMINI_HOOK_CONTEXT_EVENTS,
       mergeGeneratedOutputContent(existing, pending, newContent, resolvedPath) {
         const base = pending?.content ?? existing;
         if (base !== null && resolvedPath === GEMINI_SETTINGS) {
@@ -18081,14 +18174,10 @@ function generateAgents17(canonical) {
     content: serializeProjectedAgentSkill(agent)
   }));
 }
-function generateIgnore14(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: GOOSE_IGNORE, content: canonical.ignore.join("\n") }];
-}
 function generateHooks12(canonical) {
   return buildWrappedCommandHooks(canonical, GOOSE_HOOKS_FILE);
 }
-var generateRules17, generatePermissions12;
+var generateRules17, generateIgnore14, generatePermissions12;
 var init_generator20 = __esm({
   "src/targets/goose/generator.ts"() {
     init_managed_blocks();
@@ -18098,7 +18187,9 @@ var init_generator20 = __esm({
     init_command_skill();
     init_wrapped_command_hooks();
     init_constants16();
+    init_ignore_output();
     generateRules17 = (canonical) => embeddedRootRule(canonical, GOOSE_TARGET, GOOSE_ROOT_FILE);
+    generateIgnore14 = ignoreOutput(GOOSE_IGNORE);
     generatePermissions12 = NO_OUTPUTS;
   }
 });
@@ -19003,10 +19094,6 @@ function generateAgents18(canonical) {
     };
   });
 }
-function generateIgnore16(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: JUNIE_IGNORE, content: canonical.ignore.join("\n") }];
-}
 function generateSkills17(canonical) {
   return generateEmbeddedSkills(canonical, JUNIE_SKILLS_DIR);
 }
@@ -19018,6 +19105,7 @@ function renderJunieGlobalInstructions(canonical) {
   });
   return appendEmbeddedRulesBlock(root?.body.trim() ?? "", nonRootRules);
 }
+var generateIgnore16;
 var init_generator22 = __esm({
   "src/targets/junie/generator.ts"() {
     init_mcp_servers();
@@ -19025,7 +19113,9 @@ var init_generator22 = __esm({
     init_managed_blocks();
     init_markdown();
     init_constants18();
+    init_ignore_output();
     init_global_config2();
+    generateIgnore16 = ignoreOutput(JUNIE_IGNORE);
   }
 });
 
@@ -19441,10 +19531,6 @@ function generateMcp15(canonical) {
     }
   ];
 }
-function generateIgnore17(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: KILO_CODE_IGNORE, content: canonical.ignore.join("\n") }];
-}
 function generatePermissions15(canonical) {
   if (!canonical.permissions) return [];
   const { allow, deny } = canonical.permissions;
@@ -19459,11 +19545,14 @@ function generatePermissions15(canonical) {
 function generateSkills18(canonical) {
   return generateEmbeddedSkills(canonical, KILO_CODE_SKILLS_DIR);
 }
+var generateIgnore17;
 var init_generator23 = __esm({
   "src/targets/kilo-code/generator.ts"() {
     init_embedded_skill();
     init_markdown();
     init_constants19();
+    init_ignore_output();
+    generateIgnore17 = ignoreOutput(KILO_CODE_IGNORE);
   }
 });
 var kiloNonRootRuleMapper, kiloCommandMapper, kiloAgentMapper;
@@ -21208,11 +21297,7 @@ function buildKiroAgentOutputs(canonical, rules = []) {
 function generateAgents21(canonical) {
   return buildKiroAgentOutputs(canonical);
 }
-function generateIgnore18(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: KIRO_IGNORE, content: canonical.ignore.join("\n") }];
-}
-var generatePermissions17;
+var generateIgnore18, generatePermissions17;
 var init_generator25 = __esm({
   "src/targets/kiro/generator.ts"() {
     init_no_outputs();
@@ -21221,6 +21306,8 @@ var init_generator25 = __esm({
     init_markdown();
     init_hook_format3();
     init_constants21();
+    init_ignore_output();
+    generateIgnore18 = ignoreOutput(KIRO_IGNORE);
     generatePermissions17 = NO_OUTPUTS;
   }
 });
@@ -23863,10 +23950,6 @@ function generateMcp19(canonical) {
   const content = JSON.stringify({ mcpServers: canonical.mcp.mcpServers }, null, 2);
   return [{ path: QWEN_SETTINGS, content }];
 }
-function generateIgnore21(canonical) {
-  if (!canonical.ignore || canonical.ignore.length === 0) return [];
-  return [{ path: QWEN_IGNORE, content: canonical.ignore.join("\n") }];
-}
 function generateHooks18(canonical) {
   if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
   const hooks = buildClaudeHooksObjectFromCanonical(canonical);
@@ -23884,11 +23967,14 @@ function generatePermissions21(canonical) {
   if (ask.length > 0) permissions.ask = ask;
   return [{ path: QWEN_SETTINGS, content: JSON.stringify({ permissions }, null, 2) }];
 }
+var generateIgnore21;
 var init_generator29 = __esm({
   "src/targets/qwen-code/generator.ts"() {
     init_markdown();
     init_hooks_format2();
     init_constants25();
+    init_ignore_output();
+    generateIgnore21 = ignoreOutput(QWEN_IGNORE);
   }
 });
 
@@ -25586,10 +25672,6 @@ function generateMcp23(canonical) {
     }
   ];
 }
-function generateIgnore24(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: TRAE_IGNORE, content: canonical.ignore.join("\n") }];
-}
 function generateHooks20(canonical) {
   if (!canonical.hooks) return [];
   const hooks = {};
@@ -25610,12 +25692,15 @@ function generateHooks20(canonical) {
   if (Object.keys(hooks).length === 0) return [];
   return [{ path: TRAE_HOOKS_FILE, content: JSON.stringify({ version: 1, hooks }, null, 2) }];
 }
+var generateIgnore24;
 var init_generator33 = __esm({
   "src/targets/trae/generator.ts"() {
     init_embedded_skill();
     init_markdown();
     init_hook_command();
     init_constants29();
+    init_ignore_output();
+    generateIgnore24 = ignoreOutput(TRAE_IGNORE);
   }
 });
 
@@ -26322,11 +26407,7 @@ function generateMcp24(canonical, ctx) {
   const content = JSON.stringify({ mcpServers: canonical.mcp.mcpServers }, null, 2);
   return [{ path, content }];
 }
-function generateIgnore25(canonical) {
-  if (canonical.ignore.length === 0) return [];
-  return [{ path: WARP_IGNORE_FILE, content: canonical.ignore.join("\n") }];
-}
-var generateRules31, generatePermissions24, generateHooks21;
+var generateRules31, generatePermissions24, generateHooks21, generateIgnore25;
 var init_generator34 = __esm({
   "src/targets/warp/generator.ts"() {
     init_managed_blocks();
@@ -26335,9 +26416,11 @@ var init_generator34 = __esm({
     init_projected_agent_skill();
     init_command_skill();
     init_constants30();
+    init_ignore_output();
     generateRules31 = (canonical) => embeddedRootRule(canonical, WARP_TARGET, WARP_ROOT_FILE);
     generatePermissions24 = NO_OUTPUTS;
     generateHooks21 = NO_OUTPUTS;
+    generateIgnore25 = ignoreOutput(WARP_IGNORE_FILE);
   }
 });
 
@@ -26962,13 +27045,12 @@ var init_rules4 = __esm({
 });
 
 // src/targets/windsurf/generator/ignore.ts
-function generateIgnore26(canonical) {
-  if (!canonical.ignore || canonical.ignore.length === 0) return [];
-  return [{ path: CODEIUM_IGNORE, content: canonical.ignore.join("\n") }];
-}
+var generateIgnore26;
 var init_ignore3 = __esm({
   "src/targets/windsurf/generator/ignore.ts"() {
     init_constants34();
+    init_ignore_output();
+    generateIgnore26 = ignoreOutput(CODEIUM_IGNORE);
   }
 });
 
@@ -27034,7 +27116,7 @@ function canonicalHookEventName(event) {
   if (KNOWN_CANONICAL_HOOK_EVENTS.includes(event)) return event;
   return WINDSURF_TO_CANONICAL.get(event) ?? null;
 }
-var KNOWN_CANONICAL_HOOK_EVENTS, WINDSURF_TO_CANONICAL;
+var KNOWN_CANONICAL_HOOK_EVENTS, WINDSURF_HOOK_CONTEXT_EVENTS, WINDSURF_TO_CANONICAL;
 var init_hook_events = __esm({
   "src/targets/windsurf/hook-events.ts"() {
     init_hook_types();
@@ -27047,6 +27129,7 @@ var init_hook_events = __esm({
       "SubagentStop",
       ...BEST_EFFORT_HOOK_EVENTS
     ];
+    WINDSURF_HOOK_CONTEXT_EVENTS = [];
     WINDSURF_TO_CANONICAL = new Map(
       KNOWN_CANONICAL_HOOK_EVENTS.map((event) => [windsurfEventName(event), event])
     );
@@ -27072,12 +27155,12 @@ function toWindsurfHooks(hooks) {
   return result2;
 }
 function generateHooks22(canonical) {
-  if (!canonical.hooks || Object.keys(canonical.hooks).length === 0) return [];
+  if (!canonical.hooks) return [];
   const hooks = toWindsurfHooks(canonical.hooks);
   if (Object.keys(hooks).length === 0) return [];
   return [{ path: WINDSURF_HOOKS_FILE, content: JSON.stringify({ hooks }, null, 2) }];
 }
-var init_hooks4 = __esm({
+var init_hooks5 = __esm({
   "src/targets/windsurf/generator/hooks.ts"() {
     init_hook_command();
     init_constants34();
@@ -27129,7 +27212,7 @@ var init_generator35 = __esm({
     init_workflows();
     init_agents4();
     init_mcp4();
-    init_hooks4();
+    init_hooks5();
     init_skills4();
     init_permissions6();
   }
@@ -27248,7 +27331,7 @@ async function parseHooks(hooksPath, onParseError) {
   return result2;
 }
 var VALID_TYPES;
-var init_hooks5 = __esm({
+var init_hooks6 = __esm({
   "src/canonical/features/hooks.ts"() {
     init_syntax_error();
     init_fs();
@@ -27329,7 +27412,7 @@ var WILDCARD_MATCHER;
 var init_importer_hooks2 = __esm({
   "src/targets/windsurf/importer-hooks.ts"() {
     init_canonical_paths();
-    init_hooks5();
+    init_hooks6();
     init_fs();
     init_constants34();
     init_hook_events();
@@ -27630,6 +27713,7 @@ var init_windsurf2 = __esm({
     init_merge14();
     init_linter32();
     init_lint31();
+    init_hook_events();
     init_import_map_builders();
     init_conversions();
     init_projected_agent_skill();
@@ -27761,6 +27845,7 @@ var init_windsurf2 = __esm({
       },
       emptyImportMessage: "No Windsurf config found (.windsurfrules, .windsurf/rules, .windsurfignore, or .codeiumignore).",
       supportsConversion: { agents: true },
+      hookContextEvents: WINDSURF_HOOK_CONTEXT_EVENTS,
       lintRules: lintRules32,
       lint: {
         commands: lintCommands10,
@@ -28905,6 +28990,23 @@ var init_builtin_targets = __esm({
   }
 });
 
+// src/targets/catalog/recall-hook-targets.ts
+init_recall_hook_scaffold();
+init_builtin_targets();
+init_registry();
+function withTargetRecallHooks(canonical, target34) {
+  const descriptor34 = getBuiltinTargetDefinition(target34) ?? getDescriptor(target34);
+  const contextEvents = descriptor34?.hookContextEvents;
+  if (contextEvents === void 0 || canonical.hooks === null) return canonical;
+  const hooks = {};
+  for (const [event, entries] of Object.entries(canonical.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    const kept = contextEvents.includes(event) ? entries : entries.filter((entry) => !isRecallHookCommand(entry?.command));
+    if (kept.length > 0) hooks[event] = kept;
+  }
+  return { ...canonical, hooks };
+}
+
 // src/core/generate/engine.ts
 init_builtin_targets();
 init_registry();
@@ -29807,11 +29909,12 @@ async function generateHooksFeature(results, targets, canonical, projectRoot, sc
     const gen = resolveTargetFeatureGenerator(target34, "hooks", config, scope) ?? getDescriptor(target34)?.generators.generateHooks;
     if (!gen) continue;
     const ctx = featureContext(target34, "hooks", scope);
-    let outputs = [...gen(canonical, ctx)];
+    const projected = withTargetRecallHooks(canonical, target34);
+    let outputs = [...gen(projected, ctx)];
     const descriptor34 = getBuiltinTargetDefinition(target34) ?? getDescriptor(target34);
     const post = descriptor34?.postProcessHookOutputs;
     if (post) {
-      outputs = [...await post(projectRoot, canonical, outputs)];
+      outputs = [...await post(projectRoot, projected, outputs)];
     }
     const options = outputMergeOptions(target34);
     for (const out2 of outputs) {
@@ -29824,7 +29927,7 @@ async function generateScopedSettingsFeature(results, targets, canonical, projec
     const descriptor34 = getBuiltinTargetDefinition(target34) ?? getDescriptor(target34);
     const emit = descriptor34?.emitScopedSettings;
     if (!emit) continue;
-    const outputs = emit(canonical, scope, enabledFeatures);
+    const outputs = emit(withTargetRecallHooks(canonical, target34), scope, enabledFeatures);
     if (outputs.length === 0) continue;
     const options = outputMergeOptions(target34);
     for (const out2 of outputs) {
@@ -29867,7 +29970,12 @@ async function generate(ctx) {
     const descriptor34 = getBuiltinTargetDefinition(target34) ?? getDescriptor(target34);
     const scopeExtras = descriptor34?.globalSupport?.scopeExtras;
     if (scopeExtras) {
-      const extras = await scopeExtras(canonical, projectRoot, scope, enabledFeatures);
+      const extras = await scopeExtras(
+        withTargetRecallHooks(canonical, target34),
+        projectRoot,
+        scope,
+        enabledFeatures
+      );
       await emitScopeExtras(results, target34, extras, projectRoot);
     }
   }
@@ -31174,7 +31282,7 @@ async function parsePermissions(permissionsPath, onParseError) {
 }
 
 // src/canonical/load/loader.ts
-init_hooks5();
+init_hooks6();
 
 // src/canonical/features/ignore.ts
 init_fs();
@@ -31223,10 +31331,10 @@ function ruleSlug4(r) {
 function mergeByKey(base, overlay, key) {
   return [...new Map([...base, ...overlay].map((item) => [key(item), item])).values()];
 }
-function mergeCanonicalFiles(base, overlay) {
+function mergeCanonicalFiles(base, overlay, options = {}) {
   const mcp = mergeMcp7(base.mcp, overlay.mcp);
   const permissions = mergePermissions2(base.permissions, overlay.permissions);
-  const hooks = mergeHooks5(base.hooks, overlay.hooks);
+  const hooks = options.hooks === "combine" ? combineHooks(base.hooks, overlay.hooks) : overrideHooks(base.hooks, overlay.hooks);
   const ignore = mergeUniqueStrings(base.ignore, overlay.ignore);
   return {
     rules: mergeByKey(base.rules, overlay.rules, ruleSlug4),
@@ -31265,17 +31373,31 @@ function mergeUniqueStrings(base, overlay) {
   }
   return merged;
 }
-function mergeHooks5(base, overlay) {
+function overrideHooks(base, overlay) {
   if (!base && !overlay) return null;
   const result2 = {};
-  const keys = /* @__PURE__ */ new Set([...Object.keys(base ?? {}), ...Object.keys(overlay ?? {})]);
-  for (const k of keys) {
+  for (const k of hookEvents(base, overlay)) {
     const o = overlay?.[k];
-    const b = base?.[k];
-    result2[k] = o !== void 0 && o.length > 0 ? o : b ?? [];
+    result2[k] = o !== void 0 && o.length > 0 ? o : base?.[k] ?? [];
+  }
+  return result2;
+}
+function combineHooks(first, then) {
+  if (!first && !then) return null;
+  const result2 = {};
+  for (const k of hookEvents(first, then)) {
+    const kept = first?.[k] ?? [];
+    const defined = new Set(kept.map(hookKey));
+    result2[k] = [...kept, ...(then?.[k] ?? []).filter((entry) => !defined.has(hookKey(entry)))];
   }
   return result2;
 }
+function hookEvents(a, b) {
+  return [.../* @__PURE__ */ new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})])];
+}
+function hookKey(entry) {
+  return JSON.stringify([entry.type ?? "command", entry.matcher, entry.command]);
+}
 
 // src/config/resolve/native-format-detector.ts
 init_fs();
@@ -32046,7 +32168,7 @@ function gateExtendElevatedArtifacts(canonical, ext) {
   });
 }
 init_mcp();
-init_hooks5();
+init_hooks6();
 
 // src/install/pack/pack-reader.ts
 init_fs();
@@ -32133,7 +32255,7 @@ async function loadPacksCanonical(abDir) {
     const canonical = await loadPackCanonical(packDir);
     const filtered = filterCanonicalByFeatures(canonical, meta.features);
     const picked = applyExtendPick(filtered, meta.features, meta.pick, meta.name);
-    merged = mergeCanonicalFiles(merged, picked);
+    merged = mergeCanonicalFiles(merged, picked, { hooks: "combine" });
   }
   return merged;
 }
@@ -32184,9 +32306,10 @@ async function loadCanonicalWithExtends(config, configDir, options = {}, canonic
     merged = mergeCanonicalFiles(merged, picked);
   }
   const packsCanonical = await loadPacksCanonical(canonicalDir);
-  merged = mergeCanonicalFiles(merged, packsCanonical);
+  merged = mergeCanonicalFiles(merged, packsCanonical, { hooks: "combine" });
   const localCanonical = await loadCanonicalFiles(canonicalDir);
   merged = mergeCanonicalFiles(merged, localCanonical);
+  merged = { ...merged, hooks: combineHooks(merged.hooks, packsCanonical.hooks) };
   return { canonical: merged, resolvedExtends };
 }
 
@@ -32465,6 +32588,9 @@ function lintRuleScopeInversion(input) {
   }
   return out2;
 }
+
+// src/lessons/graph-store.ts
+init_fs_text_encoding();
 var CURRENT_GRAPH_VERSION = 2;
 var VersionSchema = z.union([z.literal(1), z.literal(2)]);
 var MAX_RULE_LENGTH = 2e3;
@@ -32508,25 +32634,54 @@ var LessonsGraphSchema = z.object({
 function parseGraph(raw) {
   return LessonsGraphSchema.parse(raw);
 }
+function emptyGraph() {
+  return { version: CURRENT_GRAPH_VERSION, lessons: {}, topics: {}, triggers: {} };
+}
 
 // src/lessons/graph-store.ts
-var GRAPH_REL_PATH = ".agentsmesh/lessons/lessons.json";
+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;
   return loadLessonsGraph(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) {
@@ -32570,9 +32725,76 @@ Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Man
 **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\`.`;
+var MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+function runGit2(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 cache = /* @__PURE__ */ new Map();
+function readGitPathHistory(projectRoot) {
+  if (!cache.has(projectRoot)) cache.set(projectRoot, scanGitPathHistory(projectRoot));
+  return cache.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 = runGit2(projectRoot, ["ls-files", "-z"], timeoutMs);
+  if (tracked.status !== 0) return null;
+  const log = runGit2(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 };
+}
+
+// src/lessons/project-files.ts
 var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
 var MAX_FILES = 2e5;
-function listProjectFiles(projectRoot) {
+function projectFilesOf(paths2, gitHistory) {
+  return Object.assign(new Set(paths2), { gitHistory });
+}
+function gitHistoryOf(paths2) {
+  return paths2.gitHistory?.() ?? null;
+}
+function listProjectFiles(projectRoot, maxFiles = MAX_FILES) {
   const out2 = /* @__PURE__ */ new Set();
   try {
     const stack = [projectRoot];
@@ -32583,14 +32805,14 @@ function listProjectFiles(projectRoot) {
           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 > MAX_FILES) return out2;
+          if (out2.size > maxFiles) return null;
         }
       }
     }
   } catch {
     return null;
   }
-  return out2;
+  return projectFilesOf(out2, () => readGitPathHistory(projectRoot));
 }
 
 // src/lessons/validate-checks.ts
@@ -32767,6 +32989,265 @@ function collectOrphans(graph, findings) {
     }
   }
 }
+
+// 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 rel2 = relative(root, resolve(root, forward)).replaceAll("\\", "/");
+  return rel2 === "" ? forward.replaceAll("\\", "/") : rel2;
+}
+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 rel2 = forward;
+  if (ABSOLUTE.test(forward)) {
+    const root = projectRoot.replaceAll("\\", "/").replace(/\/+$/, "");
+    rel2 = forward.startsWith(`${root}/`) || forward === root ? forward.slice(root.length + 1) : normalizeRecallFile(forward, projectRoot);
+    if (ABSOLUTE.test(rel2)) {
+      throw new TriggerFileGlobError(
+        pattern,
+        sameFolder(forward, projectRoot) ? "root" : "outside"
+      );
+    }
+  }
+  const normalized = posix.normalize(rel2 === "" ? "." : rel2);
+  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();
 }
@@ -32775,14 +33256,50 @@ function union(base, extra) {
   for (const item of extra) if (!out2.includes(item)) out2.push(item);
   return out2;
 }
-function mergeTriggers(graph, spec) {
+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 findExistingLessonByRule(graph, ruleKey2) {
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active") continue;
+    if (normalizeRule(lesson.rule) === ruleKey2) 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 }))
@@ -32839,6 +33356,132 @@ function todayIso() {
   return (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 }
 
+// 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/regex-linear/nfa-compile.ts
 var MAX_NFA_STATES = 2e3;
 var Builder = class {
@@ -33030,6 +33673,9 @@ function escapeClass(c2) {
 var HEX2 = /^[0-9a-fA-F]{2}$/;
 var HEX4 = /^[0-9a-fA-F]{4}$/;
 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 };
@@ -33119,7 +33765,7 @@ function parseRegex(src) {
   function parseAtom() {
     const c2 = peek();
     if (c2 === "(") return parseGroup2();
-    if (c2 === "[") return parseClass();
+    if (c2 === "[") return parseClass2();
     if (c2 === "\\") return parseEscape();
     if (c2 === ".") {
       i += 1;
@@ -33178,7 +33824,7 @@ function parseRegex(src) {
     }
     return { k: "char", ch: escapeLiteral(c2) };
   }
-  function parseClass() {
+  function parseClass2() {
     i += 1;
     const negate = peek() === "^";
     if (negate) i += 1;
@@ -33231,17 +33877,17 @@ function parseRegex(src) {
 }
 
 // src/lessons/regex-linear/index.ts
-var cache = /* @__PURE__ */ new Map();
+var cache3 = /* @__PURE__ */ new Map();
 function compileLinearMatcher(pattern) {
-  const hit = cache.get(pattern);
-  if (hit !== void 0 || cache.has(pattern)) return hit ?? null;
+  const hit = cache3.get(pattern);
+  if (hit !== void 0 || cache3.has(pattern)) return hit ?? null;
   let matcher;
   try {
     matcher = buildMatcher(parseRegex(pattern));
   } catch {
     matcher = null;
   }
-  cache.set(pattern, matcher);
+  cache3.set(pattern, matcher);
   return matcher;
 }
 
@@ -33282,6 +33928,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);
@@ -33289,7 +33937,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;
@@ -33298,12 +33946,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;
@@ -33384,7 +34036,11 @@ function collectTriggerSetCollisions(graph, findings) {
 
 // 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;
@@ -33435,6 +34091,15 @@ function isBroadCommandPattern(pattern) {
   }
   return hits > COMMAND_PROBE_CORPUS.length * BROAD_HIT_RATIO;
 }
+function missingGlobState(pattern, history) {
+  const matcher = getGlobMatcher(pattern);
+  if (history === null || matcher === null) return "pending";
+  const matchesAny = (paths2) => [...paths2].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";
+}
 
 // src/lessons/validate-liveness.ts
 function activeTriggerIds(graph) {
@@ -33445,32 +34110,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 paths2 = [...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 = picomatch2(trigger.pattern, { dot: true });
-    if (!paths2.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 (!paths2.some((p) => matcher.test(p))) missing.push([triggerId, trigger.pattern]);
+  }
+  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;
+  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 = picomatch2(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/;
@@ -33542,7 +34217,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) {
@@ -33550,7 +34225,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 = [];
@@ -33559,7 +34234,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);
@@ -33571,7 +34246,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);
@@ -33588,7 +34263,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);
@@ -33596,7 +34271,7 @@ 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/validate-keywords.ts
@@ -33619,7 +34294,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({
@@ -33667,7 +34342,6 @@ function validateLessonsGraph(graph, options = {}) {
 
 // src/core/lint/shared/lessons.ts
 var LESSONS_TARGET = "lessons";
-var GRAPH_REL = ".agentsmesh/lessons/lessons.json";
 var ROOT_RULE_REL = ".agentsmesh/rules/_root.md";
 var LESSONS_HEADING = /^## Lessons \(/m;
 function lintLessonsSubsystem(projectRoot, scope) {
@@ -33682,7 +34356,7 @@ function lintLessonsSubsystem(projectRoot, scope) {
     return [
       diag(
         "error",
-        GRAPH_REL,
+        LESSONS_GRAPH_PATH,
         `lessons.json failed to load: ${err instanceof Error ? err.message : String(err)}`
       )
     ];
@@ -33690,7 +34364,7 @@ function lintLessonsSubsystem(projectRoot, scope) {
   const knownPaths = listProjectFiles(projectRoot) ?? void 0;
   const report = validateLessonsGraph(graph, { knownPaths });
   for (const finding of report.findings) {
-    out2.push(diag(finding.level, GRAPH_REL, `[${finding.code}] ${finding.message}`));
+    out2.push(diag(finding.level, LESSONS_GRAPH_PATH, `[${finding.code}] ${finding.message}`));
   }
   const rootRuleAbs = join(projectRoot, ROOT_RULE_REL);
   const rootRuleBody = existsSync(rootRuleAbs) ? readFileSync(rootRuleAbs, "utf8") : "";
@@ -33712,8 +34386,8 @@ function diag(level, file, message) {
 // src/core/lint/linter.ts
 var EXCLUDE_DIRS = ["node_modules", ".git", "dist", "coverage", ".agentsmesh"];
 function isExcludedProjectPath(rel2) {
-  const posix8 = rel2.replaceAll("\\", "/");
-  return EXCLUDE_DIRS.some((d) => posix8.includes(`/${d}/`) || posix8.startsWith(`${d}/`));
+  const posix11 = rel2.replaceAll("\\", "/");
+  return EXCLUDE_DIRS.some((d) => posix11.includes(`/${d}/`) || posix11.startsWith(`${d}/`));
 }
 async function getProjectFiles(projectRoot) {
   const all = await readDirRecursive(projectRoot);
@@ -34106,14 +34780,22 @@ async function findUntrackedManagedDirFiles(args) {
   return [...found].sort();
 }
 
+// src/lessons/conflict-markers.ts
+function hasConflictMarkers(text) {
+  return /^(?:<{7}|>{7})(?: |\r?$)/m.test(text);
+}
+
 // src/core/check/lock-sync.ts
+init_fs();
 async function checkLockSync(opts) {
   const { config, configDir, canonicalDir, rootBase, scope = "project" } = opts;
   const lock = await readLock(canonicalDir);
   if (lock === null) {
+    const text = await readFileSafe(join(canonicalDir, ".lock"));
     return {
       inSync: false,
       hasLock: false,
+      lockConflict: text !== null && hasConflictMarkers(text),
       canonicalDrift: false,
       outputDrift: false,
       modified: [],
@@ -34183,6 +34865,7 @@ async function checkLockSync(opts) {
   return {
     inSync,
     hasLock: true,
+    lockConflict: false,
     canonicalDrift,
     outputDrift,
     modified,
@@ -34458,6 +35141,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(
@@ -34488,6 +35192,9 @@ var UnrecallableLessonError = class extends Error {
   }
   code = "UNRECALLABLE_LESSON";
 };
+function codePointLength(text) {
+  return [...text].length;
+}
 
 // src/lessons/trigger-effectiveness.ts
 function ineffectiveTriggers(graph, triggerIds) {
@@ -34502,7 +35209,7 @@ function ineffectiveTriggers(graph, triggerIds) {
 }
 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)) {
@@ -34535,9 +35242,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";
 }
@@ -34553,10 +35270,30 @@ function assertTriggerInputs(input, options, existingTriggerCount) {
     if (broad !== void 0) throw new BroadCommandPatternError(broad);
   }
 }
-function assertRecallable(graph, resultingTriggers) {
+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);
-  if (resultingTriggers.length > 0 && blockingDead.length === resultingTriggers.length) {
-    throw new UnrecallableLessonError(blockingDead);
+  const dead = [...dropped, ...blockingDead];
+  if (dead.length > 0 && blockingDead.length === resultingTriggers.length) {
+    throw new UnrecallableLessonError(dead);
   }
 }
 
@@ -34565,7 +35302,7 @@ 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 basename78 = p.slice(p.lastIndexOf("/") + 1);
   return basename78.startsWith("*");
@@ -34609,12 +35346,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);
@@ -34627,18 +35371,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)) {
@@ -34656,63 +35403,375 @@ 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/utils/filesystem/process-lock.ts
 init_errors();
+var execFileAsync2 = 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(stat7, bootId) {
+  const start = stat7.slice(stat7.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 [stat7, bootId] = await Promise.all([
+    readFile(`/proc/${pid}/stat`, "utf-8"),
+    readFile("/proc/sys/kernel/random/boot_id", "utf-8")
+  ]);
+  return linuxStartIdentity(stat7, bootId);
+}
+async function psIdentity(pid) {
+  const { stdout } = await execFileAsync2("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;
+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));
+    }
+  }
+}
+
+// src/utils/filesystem/process-lock-ops.ts
+init_rename_retry();
+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 cap2 = Math.max(base, opts.maxRetryDelayMs ?? base);
+  const delay = Math.min(cap2, 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();
@@ -34721,76 +35780,69 @@ 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(() => {
     });
   };
-}
-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;
-}
-function isProcessAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === "EPERM";
-  }
-}
-function 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();
+  const isHeld = async () => !released && existsSync(ownerPath(lockPath, token));
+  return Object.assign(release, { isHeld });
 }
 
 // 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/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 ?? ""}`;
 }
@@ -34800,6 +35852,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 result2 = await mutator(graph);
@@ -34808,12 +35861,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 result2;
   } finally {
@@ -34827,50 +35878,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 ruleKey2 = normalizeRule(input.rule);
   const trimmedRule = assertRuleShape(input.rule);
   const existingId = findExistingLessonByRule(graph, ruleKey2);
-  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, ruleKey2);
@@ -34878,29 +35920,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, ruleKey2) {
-  for (const [id, lesson] of Object.entries(graph.lessons)) {
-    if (lesson.status !== "active") continue;
-    if (normalizeRule(lesson.rule) === ruleKey2) return id;
-  }
-  return null;
-}
 
 // src/lessons/import-legacy-merge.ts
 async function mergeLegacy(projectRoot, paths2, specs, summaryByTopic, options) {
@@ -34933,19 +35972,33 @@ async function mergeLegacy(projectRoot, paths2, specs, summaryByTopic, options)
     triggerCount: addedTriggers.size
   };
 }
-
-// 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";
+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 paths2 = lessonsPaths(projectRoot);
-  const indexRaw = readFileSync(paths2.index, "utf8");
-  const index = LegacyIndexSchema.parse(parse(indexRaw));
+async function resolveLegacyTopicPath(projectRoot, file) {
+  const forward = file.replaceAll("\\", "/");
+  const normalized = posix.normalize(forward);
+  const relative27 = !/^[A-Za-z]:/.test(forward) && !forward.startsWith("/") && normalized.startsWith(`${LESSONS_DIR}/`);
+  if (!relative27) throw new LegacyTopicPathError(file);
+  const target34 = join(projectRoot, normalized);
+  try {
+    await assertPathInsideRoot(join(projectRoot, LESSONS_DIR), target34);
+  } catch {
+    throw new LegacyTopicPathError(file);
+  }
+  return target34;
+}
+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();
@@ -34956,14 +36009,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}`)
@@ -34974,7 +36028,7 @@ async function importLegacyLessons(projectRoot, options) {
         triggers: clusterTriggerIds,
         evidence: lessonEvidence,
         status: "active",
-        createdAt: options.migratedAt
+        createdAt: migratedAt
       };
       specs.push({
         rule: body,
@@ -34985,22 +36039,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 paths2 = lessonsPaths(projectRoot);
+  if (options.merge === true) {
+    const { specs, summaryByTopic } = await readLegacySource(projectRoot, options.migratedAt);
     return mergeLegacy(projectRoot, paths2, 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(paths2.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(paths2.base);
   return {
@@ -35008,7 +36083,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
   };
 }
 
@@ -35018,13 +36093,14 @@ async function maybeAutoMigrateLessons(projectRoot) {
   const paths2 = lessonsPaths(projectRoot);
   if (!existsSync(paths2.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;
     throw err;
   }
 }
+new Int32Array(new SharedArrayBuffer(4));
 
 // src/lessons/keyword-match.ts
 function deriveHaystackTokens(query) {
@@ -35058,7 +36134,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;
   }
@@ -35067,6 +36143,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 [];
@@ -35089,9 +36166,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;
 }
@@ -35099,21 +36179,29 @@ 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 picomatch2(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);
   }
 }
 
+// src/lessons/telemetry.ts
+init_fs_text_encoding();
+
+// src/lessons/log-record-guards.ts
+init_guards();
+
 // src/lessons/telemetry.ts
 function recallLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
@@ -35250,14 +36338,20 @@ function applyCaps(ranked, options) {
   }
   return out2;
 }
+
+// src/lessons/recall-config.ts
+init_fs_text_encoding();
 function defaultLessonsConfig() {
   return {
     recallLimit: DEFAULT_RECALL_LIMIT,
     recallMaxTokens: DEFAULT_RECALL_MAX_TOKENS,
     autoPrune: false,
-    telemetry: false
+    telemetry: false,
+    outcomeLog: true
   };
 }
+
+// src/lessons/outcome-log.ts
 function outcomeLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
 }
@@ -35273,19 +36367,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,
@@ -35340,9 +36432,123 @@ async function stripMarkersInGraph(projectRoot, options = {}) {
 }
 init_recall_hook_scaffold();
 
+// src/lessons/merge-driver-setup.ts
+init_cli_invocation();
+function commandProgram(command) {
+  const m = /^\s*(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(command);
+  return m?.[1] ?? m?.[2] ?? m?.[3] ?? "";
+}
+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 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 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;
+  }
+}
+
 // 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 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`;
+}
+function ensureLessonsMergeDriver(projectRoot, options = {}) {
+  const git = options.git ?? runGit2;
+  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 };
+}
+
+// src/lessons/recall-hook-hint.ts
+init_recall_hook_scaffold();
+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/gitattributes.ts
 init_fs();
@@ -35483,7 +36689,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
 
@@ -35527,11 +36734,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, paths2.base)}/*.tmp`
   ]);
   const gitattributesUpdated = await ensureGitattributesEntries(projectRoot, [
     LESSONS_GITATTRIBUTES_ENTRY
   ]);
+  const mergeDriver = ensureLessonsMergeDriver(projectRoot);
   return {
     created,
     updated,
@@ -35539,7 +36749,9 @@ async function scaffoldLessons(projectRoot) {
     rootRuleUpdated,
     gitignoreUpdated,
     gitattributesUpdated,
-    recallHookInjected
+    recallHookInjected,
+    mergeDriver,
+    recallHookTeamHint: recallHookTeamHint(projectRoot)
   };
 }
 function seedLessonsSkill(projectRoot, created, updated, skipped) {