agentsmesh 0.32.0 → 0.33.0

package/dist/{init-CrZhoNTj.d.ts → init-rvKjGLTB.d.ts}

@@ -469,7 +469,7 @@ declare function toRelPath(projectRoot: string, absolute: string): string;
  * survives generate → import → generate round-trip; only the wording inside each
  * block is tightened for maximum agent compliance.
  */
-declare const LESSONS_PROCEDURAL_RULE = "## Lessons (BLOCKING)\n\nGraph `.agentsmesh/lessons/lessons.json` is canonical; never hand-edit it. Manual: `lessons` skill.\n\n**Recall:** before every file edit or state-changing command, MUST run `agentsmesh lessons query --file <path> --cmd <command>` and obey matches; at task start, ALSO run `agentsmesh lessons query --keyword \"<task terms>\" --always` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.\n\n**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>`.\n\n**Before final:** report `Lesson: captured <id>` or `Lesson: none`. No recall/capture gate = task incomplete. No shell: use `lessons_query` / `lessons_add`.";
+declare const LESSONS_PROCEDURAL_RULE = "## Lessons (BLOCKING)\n\nGraph `.agentsmesh/lessons/lessons.json` is canonical; never hand-edit it. Manual: `lessons` skill.\n\n**Recall:** before every file edit or state-changing command, MUST run `agentsmesh lessons query --file <path> --cmd <command> --session auto` and obey matches; at task start, ALSO run `agentsmesh lessons query --keyword \"<task terms>\" --always --session auto` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.\n\n**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>`.\n\n**Before final:** report `Lesson: captured <id>` or `Lesson: none`. No recall/capture gate = task incomplete. No shell: use `lessons_query` / `lessons_add`.";
 
 interface ScaffoldLessonsResult {
     readonly created: string[];

package/dist/lessons.d.ts

@@ -1,5 +1,5 @@
-import { o as RankedLesson, j as LessonsQuery, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult } from './init-CrZhoNTj.js';
-export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, _ as lessonsLockPath, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-CrZhoNTj.js';
+import { o as RankedLesson, j as LessonsQuery, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult } from './init-rvKjGLTB.js';
+export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, _ as lessonsLockPath, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-rvKjGLTB.js';
 import 'zod';
 
 /**
@@ -34,6 +34,14 @@ interface RecallOptions {
     readonly sessionId?: string;
     /** Force dedup off even when a session correlator is present. */
     readonly noDedup?: boolean;
+    /**
+     * Expire suppressions this long after delivery. Set by callers that have NO
+     * context-reset signal (the MCP server never sees the client compact), so a
+     * lesson dropped from a summarized context cannot stay hidden forever. The
+     * hook path leaves this unset on purpose: it resets on SessionStart
+     * compact/clear, which is the exact signal a wall-clock TTL only approximates.
+     */
+    readonly ttlMs?: number;
 }
 interface RecallResult {
     /** Relevance-ranked, capped lessons (compact metadata lives on each entry). */

package/dist/lessons.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, renameSync, readdirSync, realpathSync, appendFileSync, statSync } from 'fs';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync, renameSync, readdirSync, realpathSync, appendFileSync } from 'fs';
 import { resolve, dirname, join, relative, sep, basename, extname } from 'path';
 import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
 import { createHash } from 'crypto';
@@ -701,7 +701,7 @@ function getHostname() {
   return hostname();
 }
 function sleep(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 
 // src/lessons/lessons-lock.ts
@@ -1702,7 +1702,7 @@ var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING)
 
 Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
 
-**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command>\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
+**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command> --session auto\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always --session auto\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
 
 **Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
 
@@ -1806,26 +1806,6 @@ async function maybeAutoMigrateLessons(projectRoot) {
     throw err;
   }
 }
-function normalizeRecallFile(file, projectRoot) {
-  const forward = file.replaceAll("\\", "/");
-  const direct = relativize(projectRoot, forward);
-  if (!direct.startsWith("../")) return direct;
-  const viaReal = relativize(safeRealpath(projectRoot), safeRealpath(resolve(projectRoot, forward)));
-  return viaReal.startsWith("../") ? direct : viaReal;
-}
-function relativize(root, forward) {
-  const rel = relative(root, resolve(root, forward)).replaceAll("\\", "/");
-  return rel === "" ? forward.replaceAll("\\", "/") : rel;
-}
-function safeRealpath(path) {
-  try {
-    return realpathSync(path);
-  } catch {
-    const parent = dirname(path);
-    if (parent === path) return path;
-    return resolve(safeRealpath(parent), basename(path));
-  }
-}
 
 // src/lessons/keyword-match.ts
 function deriveHaystackTokens(query) {
@@ -1911,6 +1891,148 @@ function triggerMatches(trigger, query, budget) {
       return keywordMatches(trigger.pattern, query);
   }
 }
+function appendJsonl(path, record, opts) {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}
+`, "utf8");
+  if (statSync(path).size > opts.trimTriggerBytes) capJsonl(path, opts.maxRecords);
+}
+function capJsonl(path, maxRecords) {
+  if (!existsSync(path)) return;
+  const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
+  if (lines.length <= maxRecords) return;
+  const kept = lines.slice(lines.length - maxRecords);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${kept.join("\n")}
+`, "utf8");
+  renameSync(tmp, path);
+}
+function readJsonl(path) {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (line.trim().length === 0) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/lessons/telemetry.ts
+var MAX_RECALL_LOG_RECORDS = 5e3;
+var RECALL_LOG_TRIM_TRIGGER_BYTES = 2e6;
+var TELEMETRY_ENV = "AGENTSMESH_LESSONS_TELEMETRY";
+var SESSION_ENV = "AGENTSMESH_SESSION_ID";
+function sessionId(env = process.env) {
+  const raw = env[SESSION_ENV];
+  return raw !== void 0 && raw.trim().length > 0 ? raw : void 0;
+}
+function recallLogPath(projectRoot) {
+  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
+}
+function isTelemetryEnabled(env = process.env) {
+  return env[TELEMETRY_ENV] === "1";
+}
+function appendRecallRecord(projectRoot, record, env = process.env) {
+  if (!isTelemetryEnabled(env)) return;
+  appendJsonl(recallLogPath(projectRoot), record, {
+    maxRecords: MAX_RECALL_LOG_RECORDS,
+    trimTriggerBytes: RECALL_LOG_TRIM_TRIGGER_BYTES
+  });
+}
+
+// src/lessons/cmd-fastpath.ts
+var FASTPATH_DIR = "agentsmesh-lessons-cmdidx";
+function shortHash(value) {
+  let h = 5381;
+  for (let i = 0; i < value.length; i += 1) h = (h << 5) + h + value.charCodeAt(i) >>> 0;
+  return h.toString(36);
+}
+function commandFastpathCachePath(projectRoot) {
+  return join(tmpdir(), FASTPATH_DIR, `${shortHash(resolve(projectRoot))}.json`);
+}
+function currentGraphStamp(projectRoot) {
+  try {
+    const s = statSync(graphFilePath(projectRoot));
+    return { mtimeMs: s.mtimeMs, size: s.size };
+  } catch {
+    return null;
+  }
+}
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function readCache(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const c = parsed;
+    const stamp = c.stamp;
+    if (typeof stamp?.mtimeMs !== "number" || typeof stamp.size !== "number" || !isStringArray(c.commandPatterns) || !isStringArray(c.keywordPatterns)) {
+      return null;
+    }
+    return {
+      stamp: { mtimeMs: stamp.mtimeMs, size: stamp.size },
+      commandPatterns: c.commandPatterns,
+      keywordPatterns: c.keywordPatterns
+    };
+  } catch {
+    return null;
+  }
+}
+function refreshCommandFastpath(projectRoot, graph, preReadStamp) {
+  try {
+    if (preReadStamp === null) return;
+    const stamp = currentGraphStamp(projectRoot);
+    if (stamp === null) return;
+    if (stamp.mtimeMs !== preReadStamp.mtimeMs || stamp.size !== preReadStamp.size) return;
+    const path = commandFastpathCachePath(projectRoot);
+    const existing = readCache(path);
+    if (existing !== null && existing.stamp.mtimeMs === stamp.mtimeMs && existing.stamp.size === stamp.size) {
+      return;
+    }
+    const reachable = /* @__PURE__ */ new Set();
+    for (const lesson of Object.values(graph.lessons)) {
+      if (lesson.status !== "active" || lesson.scope === "always") continue;
+      for (const t of lesson.triggers) reachable.add(t);
+    }
+    const commandPatterns = [];
+    const keywordPatterns = [];
+    for (const [id, trigger] of Object.entries(graph.triggers)) {
+      if (!reachable.has(id)) continue;
+      if (trigger.kind === "command_pattern") commandPatterns.push(trigger.pattern);
+      else if (trigger.kind === "keyword") keywordPatterns.push(trigger.pattern);
+    }
+    const cache2 = { stamp, commandPatterns, keywordPatterns };
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(cache2), "utf8");
+    renameSync(tmp, path);
+  } catch {
+  }
+}
+function normalizeRecallFile(file, projectRoot) {
+  const forward = file.replaceAll("\\", "/");
+  const direct = relativize(projectRoot, forward);
+  if (!direct.startsWith("../")) return direct;
+  const viaReal = relativize(safeRealpath(projectRoot), safeRealpath(resolve(projectRoot, forward)));
+  return viaReal.startsWith("../") ? direct : viaReal;
+}
+function relativize(root, forward) {
+  const rel = relative(root, resolve(root, forward)).replaceAll("\\", "/");
+  return rel === "" ? forward.replaceAll("\\", "/") : rel;
+}
+function safeRealpath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    const parent = dirname(path);
+    if (parent === path) return path;
+    return resolve(safeRealpath(parent), basename(path));
+  }
+}
 
 // src/lessons/ranking-signals.ts
 function buildFanout(graph) {
@@ -2054,57 +2176,6 @@ function loadRecallConfig(projectRoot) {
     return fallback;
   }
 }
-function appendJsonl(path, record, opts) {
-  mkdirSync(dirname(path), { recursive: true });
-  appendFileSync(path, `${JSON.stringify(record)}
-`, "utf8");
-  if (statSync(path).size > opts.trimTriggerBytes) capJsonl(path, opts.maxRecords);
-}
-function capJsonl(path, maxRecords) {
-  if (!existsSync(path)) return;
-  const lines = readFileSync(path, "utf8").split("\n").filter((l) => l.trim().length > 0);
-  if (lines.length <= maxRecords) return;
-  const kept = lines.slice(lines.length - maxRecords);
-  const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, `${kept.join("\n")}
-`, "utf8");
-  renameSync(tmp, path);
-}
-function readJsonl(path) {
-  if (!existsSync(path)) return [];
-  const out = [];
-  for (const line of readFileSync(path, "utf8").split("\n")) {
-    if (line.trim().length === 0) continue;
-    try {
-      out.push(JSON.parse(line));
-    } catch {
-    }
-  }
-  return out;
-}
-var MAX_RECALL_LOG_RECORDS = 5e3;
-var RECALL_LOG_TRIM_TRIGGER_BYTES = 2e6;
-var TELEMETRY_ENV = "AGENTSMESH_LESSONS_TELEMETRY";
-var SESSION_ENV = "AGENTSMESH_SESSION_ID";
-function sessionId(env = process.env) {
-  const raw = env[SESSION_ENV];
-  return raw !== void 0 && raw.trim().length > 0 ? raw : void 0;
-}
-function recallLogPath(projectRoot) {
-  return join(lessonsPaths(projectRoot).base, "recall-log.jsonl");
-}
-function isTelemetryEnabled(env = process.env) {
-  return env[TELEMETRY_ENV] === "1";
-}
-function appendRecallRecord(projectRoot, record, env = process.env) {
-  if (!isTelemetryEnabled(env)) return;
-  appendJsonl(recallLogPath(projectRoot), record, {
-    maxRecords: MAX_RECALL_LOG_RECORDS,
-    trimTriggerBytes: RECALL_LOG_TRIM_TRIGGER_BYTES
-  });
-}
-
-// src/lessons/outcome-log.ts
 function outcomeLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
 }
@@ -2141,48 +2212,116 @@ function loadEffectiveness(projectRoot) {
   return map;
 }
 var SEEN_DIR = "agentsmesh-lessons-seen";
-function openSessionDedup(options = {}) {
-  if (options.disabled === true) return null;
-  const id = options.explicit !== void 0 && options.explicit.trim().length > 0 ? options.explicit.trim() : sessionId(options.env);
-  if (id === void 0) return null;
-  const path = seenPath(id, options.projectRoot);
-  return { sessionId: id, seen: loadSeen(path), path };
-}
-function shortHash(value) {
+function shortHash2(value) {
   let h = 5381;
   for (let i = 0; i < value.length; i += 1) h = (h << 5) + h + value.charCodeAt(i) >>> 0;
   return h.toString(36);
 }
-function seenPath(id, projectRoot) {
+function seenStorePath(id, projectRoot) {
   const safe = id.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 200);
-  const scoped = projectRoot === void 0 ? safe : `${safe}__${shortHash(resolve(projectRoot))}`;
+  const scoped = projectRoot === void 0 ? safe : `${safe}__${shortHash2(resolve(projectRoot))}`;
   return join(tmpdir(), SEEN_DIR, `${scoped}.json`);
 }
-function loadSeen(path) {
-  if (!existsSync(path)) return /* @__PURE__ */ new Set();
+function readSeenStore(path) {
+  if (!existsSync(path)) return { ids: /* @__PURE__ */ new Set(), stamps: null };
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!Array.isArray(parsed)) return /* @__PURE__ */ new Set();
-    return new Set(parsed.filter((x) => typeof x === "string"));
+    if (Array.isArray(parsed)) {
+      const ids = new Set(parsed.filter((x) => typeof x === "string"));
+      return { ids, stamps: null };
+    }
+    if (typeof parsed === "object" && parsed !== null) {
+      const seen = parsed.seen;
+      if (typeof seen === "object" && seen !== null) {
+        const stamps = /* @__PURE__ */ new Map();
+        for (const [id, ms] of Object.entries(seen)) {
+          if (typeof ms === "number") stamps.set(id, ms);
+        }
+        const lastAt = parsed.lastAt;
+        return {
+          ids: new Set(stamps.keys()),
+          stamps,
+          ...typeof lastAt === "number" ? { lastAt } : {}
+        };
+      }
+    }
+    return { ids: /* @__PURE__ */ new Set(), stamps: null };
   } catch {
-    return /* @__PURE__ */ new Set();
+    return { ids: /* @__PURE__ */ new Set(), stamps: null };
   }
 }
+function writeSeenStore(path, data, lastAt) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    const body = data instanceof Map ? JSON.stringify({ v: 2, lastAt: lastAt ?? Date.now(), seen: Object.fromEntries(data) }) : JSON.stringify(data);
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, body, "utf8");
+    renameSync(tmp, path);
+  } catch {
+  }
+}
+var AUTO_SESSION_IDLE_MS = 30 * 60 * 1e3;
+var FUTURE_TOLERANCE_MS = 6e4;
+function stampAgeMs(stamp, now = Date.now()) {
+  if (stamp - now > FUTURE_TOLERANCE_MS) return Number.POSITIVE_INFINITY;
+  return Math.max(0, now - stamp);
+}
+function isIdleSession(stamps, lastAt) {
+  if (stamps === null || stamps.size === 0) return false;
+  let newest = lastAt ?? 0;
+  for (const ms of stamps.values()) if (ms > newest) newest = ms;
+  return stampAgeMs(newest) > AUTO_SESSION_IDLE_MS;
+}
+
+// src/lessons/seen-cache.ts
+function openSessionDedup(options = {}) {
+  if (options.disabled === true) return null;
+  const id = options.explicit !== void 0 && options.explicit.trim().length > 0 ? options.explicit.trim() : sessionId(options.env);
+  if (id === void 0) return null;
+  const path = seenStorePath(id, options.projectRoot);
+  const store = readSeenStore(path);
+  const stale = options.ttlMs !== void 0 && isIdleSession(store.stamps, store.lastAt);
+  const stamps = stale ? null : store.stamps;
+  return {
+    sessionId: id,
+    seen: stale ? /* @__PURE__ */ new Set() : visibleSeen(store.ids, stamps, options.ttlMs),
+    path,
+    stamps,
+    ...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
+  };
+}
+function visibleSeen(ids, stamps, ttlMs) {
+  if (ttlMs === void 0) return ids;
+  if (stamps === null) return /* @__PURE__ */ new Set();
+  const now = Date.now();
+  const fresh = /* @__PURE__ */ new Set();
+  for (const [id, ms] of stamps) if (stampAgeMs(ms, now) <= ttlMs) fresh.add(id);
+  return fresh;
+}
 function filterUnseen(dedup, matches) {
   return matches.filter((m) => !dedup.seen.has(m.id));
 }
 function commitSeen(dedup, returnedIds) {
-  if (returnedIds.length === 0) return;
+  if (returnedIds.length === 0) {
+    if (dedup.ttlMs !== void 0 && dedup.stamps !== null) {
+      writeSeenStore(dedup.path, dedup.stamps);
+    }
+    return;
+  }
+  if (dedup.ttlMs !== void 0 || dedup.stamps !== null) {
+    const now = Date.now();
+    const merged = /* @__PURE__ */ new Map();
+    for (const [id, ms] of dedup.stamps ?? []) {
+      if (dedup.ttlMs === void 0 || now - ms <= dedup.ttlMs) merged.set(id, ms);
+    }
+    for (const id of returnedIds) merged.set(id, now);
+    writeSeenStore(dedup.path, merged);
+    return;
+  }
   const union3 = new Set(dedup.seen);
   for (const id of returnedIds) union3.add(id);
   if (union3.size === dedup.seen.size) return;
-  try {
-    mkdirSync(dirname(dedup.path), { recursive: true });
-    const tmp = `${dedup.path}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify([...union3]), "utf8");
-    renameSync(tmp, dedup.path);
-  } catch {
-  }
+  writeSeenStore(dedup.path, [...union3]);
 }
 
 // src/lessons/recall.ts
@@ -2191,6 +2330,7 @@ async function recallLessons(projectRoot, query, options = {}) {
     await maybeAutoMigrateLessons(projectRoot);
   } catch {
   }
+  const preReadStamp = currentGraphStamp(projectRoot);
   const load = loadLessonsGraphResilient(projectRoot);
   if (load.status === "corrupt") {
     return { lessons: [], totalMatches: 0, suppressed: 0, corrupt: true };
@@ -2200,12 +2340,14 @@ async function recallLessons(projectRoot, query, options = {}) {
   }
   if (load.status === "absent") return { lessons: [], totalMatches: 0, suppressed: 0 };
   const graph = load.graph;
+  refreshCommandFastpath(projectRoot, graph, preReadStamp);
   const matchQuery = query.file === void 0 ? query : { ...query, file: normalizeRecallFile(query.file, projectRoot) };
   const matches = queryLessons(graph, matchQuery);
   const dedup = openSessionDedup({
     explicit: options.sessionId,
     disabled: options.noDedup,
-    projectRoot
+    projectRoot,
+    ...options.ttlMs !== void 0 ? { ttlMs: options.ttlMs } : {}
   });
   const forRank = dedup === null ? matches : filterUnseen(dedup, matches);
   const cfg = loadRecallConfig(projectRoot);
@@ -2213,8 +2355,10 @@ async function recallLessons(projectRoot, query, options = {}) {
     limit: options.limit ?? cfg.limit,
     maxTokens: options.maxTokens === null ? void 0 : options.maxTokens ?? cfg.maxTokens,
     // Down-rank proven fire-but-fail lessons (empty ⇒ neutral, so recall is
-    // unchanged until the outcome log has real signal). Read from the side-channel.
-    effectiveness: loadEffectiveness(projectRoot)
+    // unchanged until the outcome log has real signal). Read from the side-channel
+    // only when something survived matching+dedup — a no-match recall must not pay
+    // the (up to 2MB) outcome-log read for a ranking of nothing.
+    effectiveness: forRank.length === 0 ? /* @__PURE__ */ new Map() : loadEffectiveness(projectRoot)
   });
   if (dedup !== null)
     commitSeen(
@@ -2835,6 +2979,17 @@ ${placed}` : placed;
 
 // src/targets/projection/lessons-paragraph.ts
 var LEGACY_RAW_FORMS = [
+  // Pre-`--session auto` wording (2026-07): strip sentinel-less copies so a
+  // project scaffolded before the dedup correlator dedups on the next scaffold.
+  `## Lessons (BLOCKING)
+
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
+
+**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command>\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
+
+**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`,
   `## Lessons (BLOCKING REQUIREMENT \u2014 MUST run both, no exceptions; the user will check)
 
 Graph \`.agentsmesh/lessons/lessons.json\` is canonical \u2014 never hand-edit. Manual: the \`lessons\` skill.
@@ -2892,14 +3047,18 @@ regression / wrong assumption / surprise and you have not captured (nor stated
 
 ## Recall \u2014 before each edit/command, and at task start
 
-\`agentsmesh lessons query --file <path> --cmd <command>\`, then apply every rule.
-Pure-read commands (read-only) and the query itself are exempt. **keyword-only recall
+\`agentsmesh lessons query --file <path> --cmd <command> --session auto\`, then apply every
+rule. Pure-read commands (read-only) and the query itself are exempt. **keyword-only recall
 for a specific edit is the anti-pattern** \u2014 anchor those to \`--file\`/\`--cmd\`. But at the
 START of a task (or when planning), run \`agentsmesh lessons query --keyword "<the task's
-key terms>" --always\`: that surfaces the conceptual rules no file/command names PLUS the
-universal always-on lessons \u2014 the manual equivalent of the automatic prompt recall on
-hook-capable tools. Author a \`keyword\` trigger beside a \`file_glob\` on conceptual lessons
-so they are reachable both ways. No shell \u2192 MCP \`lessons_query\` (\`file\`/\`command\`/\`keyword\`/\`always\`).
+key terms>" --always --session auto\`: that surfaces the conceptual rules no file/command
+names PLUS the universal always-on lessons \u2014 the manual equivalent of the automatic prompt
+recall on hook-capable tools. **Always pass \`--session auto\`**: it suppresses rules already
+shown this session so repeat recalls stay quiet (without it every recall re-delivers the
+whole matched set); \`--no-dedup\` re-shows everything after a context reset. Author a
+\`keyword\` trigger beside a \`file_glob\` on conceptual lessons so they are reachable both
+ways. No shell \u2192 MCP \`lessons_query\` (\`file\`/\`command\`/\`keyword\`/\`always\`; session dedup
+is on by default there \u2014 \`no_dedup:true\` to re-show).
 
 ## Capture \u2014 Gate Function (before any completion claim)