pi-mega-compact 0.21.8 → 0.21.10

package/src/extractive-salvage.ts

@@ -0,0 +1,212 @@
+/**
+ * extractive-salvage.ts — file-path policy + skeleton salvage for extractive.ts.
+ *
+ * Extracted from extractive.ts (A1/A2 sprint) to keep that file under the
+ * 300-line src/ soft limit. Pure functions only — no I/O, no logging.
+ *
+ * DESIGN (A1): blocklist, not allowlist. The old `INTERESTING_EXT` allowlist
+ * (rs/ts/tsx/js/json/md) silently produced content-free summaries for every
+ * other language — a .go/.py/.c project got a 34-token skeleton. An allowlist
+ * has to be *right* about ~40 ecosystems to be useful and fails closed (drops
+ * real work) when it is wrong; a NOISE blocklist only has to be right about the
+ * small, stable set of binary/generated/asset extensions and fails open (an
+ * unknown extension is surfaced, which is the safe direction for a summary).
+ */
+
+import type { EngineMessage } from "./types.js";
+
+// ---- File path policy ------------------------------------------------------
+
+/**
+ * Generic extension capture: any 1–6 char ALPHABETIC extension. Path
+ * character class is unchanged from the original FILE_PATH_RE so existing
+ * matching behaviour (quotes/backticks/whitespace as delimiters) is preserved.
+ * Alphabetic-only is deliberate: every real source/config extension is alpha
+ * (c..tsx, tsconfig.json), while an alphanumeric class matches version strings
+ * ("GLM-4.7", "v0.21.9", "Node 18.2") as "files" and spams Key files.
+ */
+export const FILE_PATH_RE = /(?:^|\s)([^\s"`']+\.([A-Za-z]{1,6}))\b/g;
+
+/** Same policy, single-match, for inferCurrentWork (also excludes ':'). */
+export const CURRENT_WORK_PATH_RE = /(?:^|\s)([^\s"`':]+\.([A-Za-z]{1,6}))\b/m;
+
+/**
+ * Binary / generated / asset / vendored extensions that carry no summary value.
+ * Deliberately small and stable. Note `md`, `json`, `toml`, `yaml`, `sql`, `css`
+ * and `html` are NOT noise — they are hand-edited source in most repos.
+ */
+export const NOISE_EXT = new Set([
+  // lockfiles & logs
+  "lock", "log", "sum",
+  // images & media
+  "png", "jpg", "jpeg", "gif", "webp", "svg", "ico", "bmp", "tiff",
+  "mp3", "mp4", "mov", "wav", "webm", "avi",
+  // fonts
+  "woff", "woff2", "ttf", "otf", "eot",
+  // archives & binaries
+  "zip", "gz", "tgz", "bz2", "xz", "7z", "rar", "tar",
+  "exe", "dll", "so", "dylib", "bin", "o", "a", "obj", "class", "pyc", "pyo",
+  "wasm", "node", "jar", "war", "deb", "rpm", "dmg", "iso", "img",
+  // generated / build artifacts
+  "map", "min", "lockb", "snap", "cache", "tmp", "temp", "swp", "bak", "orig",
+  // data blobs & databases
+  "pdf", "db", "sqlite", "sqlite3", "pack", "idx", "pem", "key", "crt",
+]);
+
+/** Directory fragments whose files are never "key files" for a summary. */
+const NOISE_DIR_RE = /(?:^|\/)(?:node_modules|\.git|dist|build|coverage|vendor|target|__pycache__|\.venv|venv)(?:\/|$)/;
+
+/**
+ * TLD-shaped extensions: `example.com`, `github.com`, `npm.cmd` are domains and
+ * launchers, not code. (QA lens 1 finding, 2026-08-19.) Conservative list only —
+ * no real source extension lives here (.go/.rs/.ts stay interesting).
+ */
+const TLD_EXT = new Set([
+  "com", "org", "net", "io", "gov", "edu", "biz", "info", "dev", "app",
+  "page", "xyz", "site", "online", "cloud", "me", "co", "us", "uk", "de",
+  "fr", "jp", "cn", "nl", "se", "eu", "int", "mil", "cmd",
+]);
+
+/** True when a matched path is worth surfacing in a summary. */
+export function isInterestingPath(filePath: string, ext: string): boolean {
+  const lowerExt = ext.toLowerCase();
+  if (NOISE_EXT.has(lowerExt)) return false;
+  if (TLD_EXT.has(lowerExt)) return false; // bare domains, not code
+  if (/^(?:https?|ftp):\/\//i.test(filePath) || filePath.toLowerCase().startsWith("www.")) return false;
+  if (NOISE_DIR_RE.test(filePath)) return false;
+  // `app.min.js` / `bundle.min.css` style double extensions.
+  if (/\.min\.[A-Za-z0-9]{1,6}$/.test(filePath)) return false;
+  if (/\.map$/.test(filePath)) return false;
+  // Prose abbreviations ("e.g", "i.e", "U.S"): a single-char base with no slash
+  // and no digit is never a filename. ("a.c" is rare collateral; "q1.py" and
+  // "src/a.ts" survive — digit / slash both exempt.)
+  const base = filePath.slice(0, filePath.lastIndexOf("."));
+  if (!filePath.includes("/") && !/\d/.test(filePath) && base.length <= 1) return false;
+  return true;
+}
+
+// ---- Path collection -------------------------------------------------------
+
+const MAX_KEY_FILES = 5;
+const MAX_FILES = 10;
+const FRESHNESS_WINDOW = 10;
+
+/** All interesting file paths mentioned in a blob of text. */
+export function extractFilePaths(text: string): string[] {
+  const paths: string[] = [];
+  for (const m of text.matchAll(FILE_PATH_RE)) {
+    if (isInterestingPath(m[1], m[2])) paths.push(m[1]);
+  }
+  return paths;
+}
+
+/** Most-mentioned paths within the recency window (behaviour unchanged). */
+export function collectKeyFiles(messages: EngineMessage[]): string[] {
+  const recent = messages.slice(-FRESHNESS_WINDOW);
+  const pathFreq = new Map<string, number>();
+  for (const m of recent) {
+    for (const p of extractFilePaths(m.text)) {
+      pathFreq.set(p, (pathFreq.get(p) ?? 0) + 1);
+    }
+  }
+  return [...pathFreq.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, MAX_KEY_FILES)
+    .map(([p]) => p);
+}
+
+/** Paths written/edited by tools (extension-agnostic; behaviour unchanged). */
+export function extractFilesModified(tools: EngineMessage[]): string[] {
+  const files = new Set<string>();
+  for (const m of tools) {
+    if (!m.toolName) continue;
+    const name = m.toolName.toLowerCase();
+    if (name === "write" || name === "edit" || name === "notebookedit") {
+      const input = m.input ?? m.text;
+      const pathMatch = input.match(/["']?(\/[^\s"']+\.\w+)["']?/);
+      if (pathMatch) files.add(pathMatch[1]);
+    }
+    if (name === "bash") {
+      const cmd = m.input ?? m.text;
+      if (cmd.includes("git add") || cmd.includes("git commit") || cmd.includes("git diff")) {
+        for (const p of extractFilePaths(cmd)) files.add(p);
+      }
+    }
+  }
+  return [...files].slice(0, MAX_FILES);
+}
+
+// ---- Placeholder user turns (A2b) ------------------------------------------
+
+/**
+ * Content-free user turns. Extremely common in resumed sessions; taking them
+ * verbatim as "User requests" is what produced the three "• resume" bullets.
+ */
+const PLACEHOLDER_RE =
+  /^(?:resume|continue|go on|go ahead|proceed|next|yes|yeah|yep|y|ok|okay|k|sure|thanks|thank you|ty|done|please continue|carry on)\W*$/i;
+
+export function isPlaceholderRequest(text: string): boolean {
+  return PLACEHOLDER_RE.test(text.trim());
+}
+
+// ---- Skeleton salvage (A2c) ------------------------------------------------
+
+const MAX_SALVAGE_LINES = 5;
+const SALVAGE_LINE_LEN = 120;
+
+/**
+ * A "skeleton" summary is the scope line and nothing else — no files, no current
+ * work, no decisions, no pending items, and no *substantive* user request. That
+ * is ~34 tokens of zero information and is what breaks a resumed session.
+ *
+ * NOTE: `recentUser` is treated as empty when it holds only placeholders. The
+ * incident summary DID have three "• resume" bullets, so a plain
+ * `recentUser.length === 0` test would never have fired on the very case this
+ * salvage exists for.
+ */
+export function isSkeletonSummary(parts: {
+  recentUser: string[];
+  keyFiles: string[];
+  currentWork: string | undefined;
+  decisions: string[];
+  pending: string[];
+}): boolean {
+  const hasRealRequest = parts.recentUser.some((r) => !isPlaceholderRequest(r));
+  return (
+    !hasRealRequest &&
+    parts.keyFiles.length === 0 &&
+    !parts.currentWork &&
+    parts.decisions.length === 0 &&
+    parts.pending.length === 0
+  );
+}
+
+/**
+ * Last-resort content: the first meaningful line of the most recent assistant
+ * and tool messages. Deterministic (pure scan, newest-first, then re-ordered
+ * oldest-first for reading). Returns [] when there is genuinely nothing.
+ */
+export function buildSalvageDigest(messages: EngineMessage[]): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (let i = messages.length - 1; i >= 0 && out.length < MAX_SALVAGE_LINES; i--) {
+    const m = messages[i];
+    if (m.role !== "assistant" && m.role !== "tool") continue;
+    const raw = m.text || m.output || m.input || "";
+    const line = raw
+      .split("\n")
+      .map((l) => l.trim())
+      .find((l) => l.length > 0);
+    if (!line) continue;
+    const label = m.role === "tool" ? `${m.toolName ?? "tool"}: ` : "";
+    const entry = truncateLine(`${label}${line}`, SALVAGE_LINE_LEN);
+    if (seen.has(entry)) continue;
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out.reverse();
+}
+
+function truncateLine(s: string, maxLen: number): string {
+  return s.length <= maxLen ? s : s.slice(0, maxLen - 1) + "…";
+}

package/src/extractive.ts

@@ -10,14 +10,24 @@
 
 import type { EngineMessage } from "./types.js";
 import { estimateBlockTokens } from "./tokens.js";
+import {
+  CURRENT_WORK_PATH_RE,
+  isInterestingPath,
+  isPlaceholderRequest,
+  isSkeletonSummary,
+  buildSalvageDigest,
+  collectKeyFiles,
+  extractFilesModified,
+} from "./extractive-salvage.js";
 
 // ---- Limits ----------------------------------------------------------------
 
 const MAX_RECENT_USER = 3;
 const MAX_DECISIONS = 5;
-const MAX_FILES = 10;
 const MAX_PENDING = 5;
 const MAX_TOPIC_LINES = 12;
+/** Cap for the merged keyFiles ∪ filesModified "Key files" line (A2a). */
+const MAX_SUMMARY_FILES = 8;
 
 // ---- Truncation helper -----------------------------------------------------
 
@@ -57,9 +67,27 @@ function buildTopicSummary(
   currentWork: string | undefined,
   keyFiles: string[],
   pending: string[],
+  filesModified: string[],
+  decisions: string[],
 ): string {
   const lines: string[] = [];
 
+  // A2a: files captured from write/edit tool inputs are extracted
+  // extension-agnostically but never reached the summary. Fold them in so work
+  // outside the recency window (and outside the path regex) is still reported.
+  // Drop an absolute path when a kept relative path already names the SAME file.
+  // Only MULTI-COMPONENT relative paths fold ("engine/mesh.go" absorbs
+  // "/proj/engine/mesh.go"); a bare basename ("mesh.go") is never folded into an
+  // absolute path, since "/proj/other/x/mesh.go" may be a genuinely different
+  // file (QA lens 1 finding: the naive endsWith dropped different directories).
+  const combined = [...keyFiles, ...filesModified];
+  const allFiles = [...new Set(combined)].filter((p) => {
+    if (!p.startsWith("/")) return true;
+    return !combined.some(
+      (r) => r !== p && !r.startsWith("/") && r.includes("/") && p.endsWith("/" + r),
+    );
+  }).slice(0, MAX_SUMMARY_FILES);
+
   // Scope line
   const users = messages.filter((m) => m.role === "user");
   const assistants = messages.filter((m) => m.role === "assistant");
@@ -79,8 +107,8 @@ function buildTopicSummary(
   // Current work
   if (currentWork) lines.push(`Current work: ${currentWork}`);
 
-  // Key files
-  if (keyFiles.length) lines.push(`Key files: ${keyFiles.join(", ")}.`);
+  // Key files (keyFiles ∪ filesModified)
+  if (allFiles.length) lines.push(`Key files: ${allFiles.join(", ")}.`);
 
   // Pending work
   if (pending.length) {
@@ -88,42 +116,52 @@ function buildTopicSummary(
     for (const p of pending) lines.push(`  • ${p}`);
   }
 
+  // A2c: a scope-line-only summary carries zero information and strands a
+  // resumed session. Salvage the tail of the conversation instead. The line cap
+  // is raised ONLY here: the salvage block is bounded at 5 lines + 1 header, and
+  // a skeleton by definition contributed just the 1 scope line, so the worst
+  // case is 7 lines — still well under the normal 12-line budget.
+  const skeleton = isSkeletonSummary({ recentUser, keyFiles: allFiles, currentWork, decisions, pending });
+  if (skeleton) {
+    const digest = buildSalvageDigest(messages);
+    if (digest.length) {
+      lines.push("Recent activity:");
+      for (const d of digest) lines.push(`  • ${d}`);
+    }
+    return lines.join("\n");
+  }
+
   // Cap total length
   return lines.slice(0, MAX_TOPIC_LINES).join("\n");
 }
 
-// ---- File path extraction --------------------------------------------------
-
-const INTERESTING_EXT = new Set(["rs", "ts", "tsx", "js", "json", "md"]);
-const FILE_PATH_RE = /(?:^|\s)([^\s"`']+\.(rs|ts|tsx|js|json|md|py|sh|sql|toml|yaml|yml|css|html))\b/g;
-
-function extractFilePaths(text: string): string[] {
-  const paths: string[] = [];
-  for (const m of text.matchAll(FILE_PATH_RE)) {
-    const filePath = m[1];
-    const ext = m[2];
-    const basename = filePath.split("/").pop() ?? filePath;
-    if (basename === "node_modules" || filePath.includes("node_modules/")) continue;
-    if (INTERESTING_EXT.has(ext)) paths.push(filePath);
-  }
-  return paths;
-}
-
-// ---- Recent user requests (existing logic, kept) ---------------------------
+// ---- Recent user requests --------------------------------------------------
 
+/**
+ * A2b: skip content-free "resume"/"continue" turns and look further back to
+ * fill the quota, so a resumed session surfaces its real requests. Falls back
+ * to the placeholders when EVERY user turn is one (an honest "• resume" beats
+ * an empty section).
+ */
 function collectRecentUserRequests(
   messages: EngineMessage[],
   limit: number,
 ): string[] {
-  const requests: string[] = [];
-  for (let i = messages.length - 1; i >= 0 && requests.length < limit; i--) {
-    if (messages[i].role === "user") {
-      let snippet = messages[i].text.split("\n").slice(0, 3).join(" ");
-      snippet = snippet.replace(/^.+\nProcessed\$?\s*/i, "").replace(/\n/g, " ");
-      requests.push(truncate(snippet, 200));
+  const substantive: string[] = [];
+  const placeholders: string[] = [];
+  for (let i = messages.length - 1; i >= 0 && substantive.length < limit; i--) {
+    if (messages[i].role !== "user") continue;
+    let snippet = messages[i].text.split("\n").slice(0, 3).join(" ");
+    snippet = snippet.replace(/^.+\nProcessed\$?\s*/i, "").replace(/\n/g, " ");
+    const cleaned = truncate(snippet, 200);
+    if (!cleaned.trim()) continue;
+    if (isPlaceholderRequest(cleaned)) {
+      if (placeholders.length < limit) placeholders.push(cleaned);
+      continue;
     }
+    substantive.push(cleaned);
   }
-  return requests.reverse();
+  return (substantive.length ? substantive : placeholders).reverse();
 }
 
 // ---- Pending work (existing logic, kept) -----------------------------------
@@ -149,10 +187,9 @@ function inferCurrentWork(messages: EngineMessage[]): string | undefined {
   for (let i = messages.length - 1; i >= 0; i--) {
     const m = messages[i];
     if (m.role !== "assistant") continue;
-    const path = m.text.match(
-      /(?:^|\s)([^\s"`':]+\.(rs|ts|tsx|js|json|md|py|toml|yaml|yml|sql))\b/m,
-    );
-    if (path) {
+    // A1: same language-agnostic policy as extractFilePaths.
+    const path = m.text.match(CURRENT_WORK_PATH_RE);
+    if (path && isInterestingPath(path[1], path[2])) {
       const line = m.text.split("\n").slice(0, 2).join(" ");
       return truncate(line, 200);
     }
@@ -190,29 +227,6 @@ function extractDecisions(messages: EngineMessage[]): string[] {
   return [...new Set(decisions)];
 }
 
-// ---- Files modified --------------------------------------------------------
-
-function extractFilesModified(tools: EngineMessage[]): string[] {
-  const files = new Set<string>();
-  for (const m of tools) {
-    if (!m.toolName) continue;
-    const name = m.toolName.toLowerCase();
-    if (name === "write" || name === "edit" || name === "notebookedit") {
-      // Extract file path from input payload
-      const input = m.input ?? m.text;
-      const pathMatch = input.match(/["']?(\/[^\s"']+\.\w+)["']?/);
-      if (pathMatch) files.add(pathMatch[1]);
-    }
-    if (name === "bash") {
-      const cmd = m.input ?? m.text;
-      if (cmd.includes("git add") || cmd.includes("git commit") || cmd.includes("git diff")) {
-        for (const p of extractFilePaths(cmd)) files.add(p);
-      }
-    }
-  }
-  return [...files].slice(0, MAX_FILES);
-}
-
 // ---- Public API ------------------------------------------------------------
 
 /**
@@ -243,29 +257,10 @@ export function extractiveSummarize(messages: EngineMessage[]): ExtractiveSummar
   const filesModified = extractFilesModified(toolMsgs);
 
   const topicSummary = buildTopicSummary(
-    safe, tools, recentUser, currentWork, keyFiles, pending,
+    safe, tools, recentUser, currentWork, keyFiles, pending, filesModified, keyDecisions,
   );
 
   const tokenEstimate = estimateBlockTokens(topicSummary);
 
   return { topicSummary, keyDecisions, nextSteps: pending, filesModified, tokenEstimate };
 }
-
-// ---- Key files (existing logic from compact.ts, moved here) ----------------
-
-const MAX_KEY_FILES = 5;
-const FRESHNESS_WINDOW = 10;
-
-function collectKeyFiles(messages: EngineMessage[]): string[] {
-  const recent = messages.slice(-FRESHNESS_WINDOW);
-  const pathFreq = new Map<string, number>();
-  for (const m of recent) {
-    for (const p of extractFilePaths(m.text)) {
-      pathFreq.set(p, (pathFreq.get(p) ?? 0) + 1);
-    }
-  }
-  return [...pathFreq.entries()]
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, MAX_KEY_FILES)
-    .map(([p]) => p);
-}

package/src/vector-cortex/dedup-attr/rollup.ts

@@ -91,6 +91,10 @@ export function computeDedupTierRollup(
     if (ev.type !== "dedup_audit") continue;
     const ts = Date.parse(ev.ts);
     if (Number.isNaN(ts) || ts < windowStart || ts > windowEnd) continue;
+    // "skipped" (degenerate-match guard declined a collapse) is a decision, but
+    // NOT a tier catch — it is attributed to no tier below. Excluding it from the
+    // denominator keeps l0Share + l1Share + l2Share summing to 1 over the window.
+    if (ev.status === "skipped") continue;
     total += 1;
     switch (ev.tier) {
       case "L0":

package/src/vectorStore/add-degenerate.ts

@@ -0,0 +1,64 @@
+/**
+ * add-degenerate.ts — the L1/L2 degenerate-match decliner bound to one add().
+ *
+ * Split out of add.ts to keep it under the 300-line src/ soft limit (the same
+ * sibling-helper pattern as add-l0.ts / add-l1.ts). The PREDICATE lives in
+ * src/dedup/degenerate.ts alongside the other dedup primitives; what lives here
+ * is only the cascade-side glue: the telemetry the decision emits and the
+ * boolean the two call sites branch on.
+ *
+ * See src/dedup/degenerate.ts for the incident (2026-08-19) this guards against.
+ */
+import type { StoredCheckpoint } from "../store.js";
+import { shouldSkipDegenerateMatch } from "../dedup/degenerate.js";
+import type { DegenerateGuardTunables } from "../dedup/degenerate.js";
+import type { DedupAuditRecorder } from "./dedup-audit.js";
+import type { VectorStore } from "./class.js";
+import type { AddInput } from "./types.js";
+
+/** Declines one fuzzy-tier match; true ⇒ treat the match as if it never happened. */
+export type DegenerateDecliner = (
+	tier: "L1" | "L2",
+	matched: StoredCheckpoint,
+	similarity?: number,
+) => boolean;
+
+/**
+ * Build the decliner for one add() cascade.
+ *
+ * Returns a predicate the L1/L2 call sites use as a one-line guard. When it
+ * returns true it has ALREADY recorded the declined decision (monitoring event +
+ * `skipped` audit line + the live `onTier` detail), so the caller only has to
+ * fall through. When the umbrella flag is off it always returns false and emits
+ * nothing — byte-identical to the pre-guard cascade.
+ */
+export function degenerateDecliner(args: {
+	store: VectorStore;
+	input: AddInput;
+	/** This candidate's content hash — blocks declining an exact-content match. */
+	contentHash: string;
+	cfg: DegenerateGuardTunables;
+	audit: DedupAuditRecorder;
+	/** Cascade start time, for the latency field on the monitoring event. */
+	t0: number;
+}): DegenerateDecliner {
+	const { store, input, contentHash, cfg, audit, t0 } = args;
+	const candidate = { ...input, contentHash };
+	return (tier, matched, similarity) => {
+		if (!shouldSkipDegenerateMatch(matched, candidate, cfg)) return false;
+		// Reported as `mark_only`: a tier matched but policy declined to collapse —
+		// exactly the existing MARK_ONLY shape, with a distinct reason string so the
+		// dashboard can tell a guard decline from an operator-configured MARK_ONLY.
+		store.record(
+			tier,
+			"mark_only",
+			"degenerateGuard",
+			Date.now() - t0,
+			similarity,
+			matched.checkpointId,
+		);
+		audit.skipped(tier, matched.checkpointId, "degenerateGuard", similarity);
+		input.onTier?.({ tier, status: "passed", detail: "degenerateGuard" });
+		return true;
+	};
+}

package/src/vectorStore/add.ts

@@ -38,6 +38,7 @@ import {
 	bumpDedupStats,
 } from "../store/sqlite.js";
 import { computeRegionHash } from "./hash.js";
+import { degenerateDecliner } from "./add-degenerate.js";
 import { runL0Tier, computeSummaryHash } from "./add-l0.js";
 import { findL1Duplicate } from "./add-l1.js";
 import { dedupAuditRecorder } from "./dedup-audit.js";
@@ -86,9 +87,23 @@ export function addCheckpoint(store: VectorStore, input: AddInput): AddResult {
 	// Tracks whether a tier matched while in MARK_ONLY (record-but-don't-collapse),
 	// and which tier.
 	let markOnly: "L0" | "L1" | "L2" | null = null;
+	// Content digest for this candidate (also consumed by the L0 tier below).
+	const digest = computeContentDigest(input.regionText);
+	// Degenerate-match guard (incident 2026-08-19): declines a fuzzy-tier collapse
+	// onto a content-free skeleton when the incoming region is richer, so the
+	// skeleton stops absorbing every future compaction. Returns true (having
+	// already recorded the decision) ⇒ the caller treats the match as a non-match.
+	// Flag-off ⇒ always false ⇒ byte-identical predecessor. See add-degenerate.ts.
+	const declineDegenerate = degenerateDecliner({
+		store,
+		input,
+		contentHash: digest.contentHash,
+		cfg,
+		audit,
+		t0,
+	});
 
 	// L0 exact-match tier (contentHash / regionHash / summaryHash) — see add-l0.ts.
-	const digest = computeContentDigest(input.regionText);
 	const bloom = openBloom(store.stateDir);
 	const summaryHash = computeSummaryHash(input.topicSummary);
 	const l0 = runL0Tier({
@@ -113,7 +128,10 @@ export function addCheckpoint(store: VectorStore, input: AddInput): AddResult {
 	onTier?.({ tier: "L1", status: "scanning" });
 	if (cfg.L1_ENABLED) {
 		const l1 = findL1Duplicate(store, sessionId, input.regionText, all);
-		if (l1 && !cfg.MARK_ONLY_L1) {
+		// Guard first: a declined match must not collapse and must not be recorded
+		// as a MARK_ONLY hit either — it is a non-match for the rest of the cascade.
+		const l1Declined = l1 !== undefined && declineDegenerate("L1", l1);
+		if (l1 && !l1Declined && !cfg.MARK_ONLY_L1) {
 			l1.timestamp = input.timestamp;
 			upsertCheckpoint(l1, store.stateDir);
 			bumpDedupStats(true, store.stateDir);
@@ -124,7 +142,7 @@ export function addCheckpoint(store: VectorStore, input: AddInput): AddResult {
 			onTier?.({ tier: "L1", status: "deduped", detail: "l1MinHash" });
 			return r;
 		}
-		if (l1 && cfg.MARK_ONLY_L1) markOnly = "L1";
+		if (l1 && !l1Declined && cfg.MARK_ONLY_L1) markOnly = "L1";
 	}
 	onTier?.({ tier: "L1", status: "passed" });
 
@@ -152,7 +170,13 @@ export function addCheckpoint(store: VectorStore, input: AddInput): AddResult {
 			},
 			{ checkpoint: all[0], sim: -1 },
 		);
-		if (!timedOut && nearest.sim >= simThreshold) {
+		// A declined match falls through to the "store a fresh checkpoint" path; the
+		// guard already audited the decision, so the near-miss emit below is skipped.
+		const l2Declined =
+			!timedOut &&
+			nearest.sim >= simThreshold &&
+			declineDegenerate("L2", nearest.checkpoint, nearest.sim);
+		if (!timedOut && !l2Declined && nearest.sim >= simThreshold) {
 			if (!cfg.MARK_ONLY_L2) {
 				// Near-identical — update timestamp on existing checkpoint
 				nearest.checkpoint.timestamp = input.timestamp;
@@ -190,7 +214,7 @@ export function addCheckpoint(store: VectorStore, input: AddInput): AddResult {
 		// Near-miss: how close did we come to collapsing? Only emitted when the
 		// scan actually completed and scored a candidate — a timed-out scan has no
 		// honest best to report.
-		if (!timedOut && nearest.sim >= 0) {
+		if (!timedOut && !l2Declined && nearest.sim >= 0) {
 			audit.passed("L2", nearest.checkpoint.checkpointId, nearest.sim);
 		}
 	}

package/src/vectorStore/dedup-audit.ts

@@ -51,8 +51,8 @@ export interface DedupAuditEvent {
 	sessionId: string;
 	/** Which layer produced the decision ("new" = nothing collapsed). */
 	tier: "L0" | "L1" | "L2" | "new";
-	/** What the layer decided. */
-	status: "deduped" | "passed" | "stored";
+	/** What the layer decided. `skipped` = matched but policy declined to collapse. */
+	status: "deduped" | "passed" | "stored" | "skipped";
 	/** Checkpoint the region collapsed onto, or the nearest one scored. */
 	matchedEntry?: string;
 	/** Checkpoint created, when the outcome was a new write. */
@@ -129,6 +129,20 @@ export interface DedupAuditRecorder {
 		matchedEntry: string,
 		similarity: number,
 	): void;
+	/**
+	 * A tier MATCHED but policy declined the collapse (degenerate-match guard).
+	 *
+	 * Distinct from `passed`: the threshold WAS cleared, so this line is how an
+	 * operator sees that a skeleton checkpoint was prevented from absorbing richer
+	 * content — the signal for "the store is healing". `similarity` is carried only
+	 * where the tier scored one (L2 does, L1 does not).
+	 */
+	skipped(
+		tier: "L0" | "L1" | "L2",
+		matchedEntry: string,
+		dedupReason: string,
+		similarity?: number,
+	): void;
 	/** Final outcome: nothing collapsed, a new checkpoint was written. */
 	stored(storedEntry: string, dedupReason: string, tokenEstimate: number): void;
 }
@@ -161,6 +175,15 @@ export function dedupAuditRecorder(
 				matchedEntry,
 				similarity,
 			}),
+		skipped: (tier, matchedEntry, dedupReason, similarity) =>
+			emitDedupAudit(ctx, {
+				...base,
+				tier,
+				status: "skipped",
+				matchedEntry,
+				dedupReason,
+				...(similarity === undefined ? {} : { similarity }),
+			}),
 		stored: (storedEntry, dedupReason, tokenEstimate) =>
 			emitDedupAudit(ctx, {
 				...base,