pi-mega-compact 0.21.9 → 0.21.10

package/dist/src/vectorStore/add-degenerate.js

@@ -0,0 +1,25 @@
+import { shouldSkipDegenerateMatch } from "../dedup/degenerate.js";
+/**
+ * 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) {
+    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/dist/src/vectorStore/add.js

@@ -27,6 +27,7 @@ import { lshBands } from "../dedup/l1-lsh.js";
 import { openBloom, saveBloom } from "../store/bloom.js";
 import { listCheckpoints, nextCheckpointId, upsertCheckpoint, loadSessionState, saveSessionState, upsertMinhashSignature, insertLshBuckets, addTokensSaved, 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";
@@ -67,8 +68,22 @@ export function addCheckpoint(store, input) {
     // Tracks whether a tier matched while in MARK_ONLY (record-but-don't-collapse),
     // and which tier.
     let markOnly = null;
-    // L0 exact-match tier (contentHash / regionHash / summaryHash) — see add-l0.ts.
+    // 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 bloom = openBloom(store.stateDir);
     const summaryHash = computeSummaryHash(input.topicSummary);
     const l0 = runL0Tier({
@@ -94,7 +109,10 @@ export function addCheckpoint(store, input) {
     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);
@@ -105,7 +123,7 @@ export function addCheckpoint(store, input) {
             onTier?.({ tier: "L1", status: "deduped", detail: "l1MinHash" });
             return r;
         }
-        if (l1 && cfg.MARK_ONLY_L1)
+        if (l1 && !l1Declined && cfg.MARK_ONLY_L1)
             markOnly = "L1";
     }
     onTier?.({ tier: "L1", status: "passed" });
@@ -131,7 +149,12 @@ export function addCheckpoint(store, input) {
             const sim = cosineSimilarity(embedding, cp.embedding);
             return sim > best.sim ? { checkpoint: cp, sim } : best;
         }, { 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;
@@ -164,7 +187,7 @@ export function addCheckpoint(store, input) {
         // 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/dist/src/vectorStore/dedup-audit.js

@@ -69,6 +69,14 @@ export function dedupAuditRecorder(ctx, scope) {
             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,
             tier: "new",

package/dist/vector-cortex/dedup-attr/rollup.js

@@ -49,6 +49,11 @@ export function computeDedupTierRollup(events, windowMs, now) {
         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/dist/vectorStore/dedup-audit.js

@@ -69,6 +69,14 @@ export function dedupAuditRecorder(ctx, scope) {
             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,
             tier: "new",

package/extensions/dashboard-server/routes-dedup-attribution.ts

@@ -59,7 +59,17 @@ function parseAuditLine(line: string): DedupAuditEvent | null {
   const tier = obj.tier;
   const status = obj.status;
   if (tier !== "L0" && tier !== "L1" && tier !== "L2" && tier !== "new") return null;
-  if (status !== "deduped" && status !== "passed" && status !== "stored") return null;
+  // "skipped" = a tier matched but the degenerate-match guard declined to
+  // collapse. Accepted so the line is not silently dropped from the tail; the
+  // rollup below counts only deduped/passed, so tier catch-share math is
+  // unchanged by its presence.
+  if (
+    status !== "deduped" &&
+    status !== "passed" &&
+    status !== "stored" &&
+    status !== "skipped"
+  )
+    return null;
   // sessionId is never read by the rollup; a parsed line may omit richer fields.
   return { type: "dedup_audit", ts: obj.ts, tier, status, sessionId: "" };
 }

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -228,6 +228,12 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			boolDirect("MEGACOMPACT_MARK_ONLY_L1", "Mark Only L1", "L1 runs but does not collapse", false),
 			boolDirect("MEGACOMPACT_MARK_ONLY_L2", "Mark Only L2", "L2 runs but does not collapse", false),
 			boolDirect("MEGACOMPACT_MINILM", "MiniLM Embedder", "Use MiniLM instead of trigram", false),
+			boolDirect(
+				"MEGACOMPACT_DEDUP_DEGENERATE_GUARD",
+				"Degenerate Match Guard",
+				"Decline an L1/L2 collapse when the MATCHED stored checkpoint is a content-free skeleton (a ~30-40 token structural summary) and the incoming region is richer. Without this, one degenerate checkpoint absorbs every later compaction forever and the store can never heal. OFF = byte-identical pre-guard cascade. Calibrated by the two Degenerate floors under Dedup Thresholds.",
+				true,
+			),
 			boolDirect(
 				"MEGACOMPACT_DEDUP_AUDIT",
 				"Dedup Audit Trail",
@@ -242,6 +248,8 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 			num("MEGACOMPACT_L2_THRESHOLD", "L2 Cosine Threshold", "L2 semantic dedup firing point", 0.85, 0, 1),
 			num("MEGACOMPACT_L1_JACCARD", "L1 Jaccard Threshold", "L1 MinHash near-dup threshold", 0.8, 0, 1),
 			num("MEGACOMPACT_DEDUP_SIM", "Dedup Similarity", "Legacy content-similarity fallback", 0.9, 0, 1),
+			num("MEGACOMPACT_DEDUP_DEGEN_MIN_TOKENS", "Degenerate Min Tokens", "Absolute token floor below which a stored summary counts as a degenerate skeleton (Degenerate Match Guard)", 48, 0, 10000, "tokens"),
+			num("MEGACOMPACT_DEDUP_DEGEN_MIN_PCT", "Degenerate Min Percent", "Relative floor as a fraction of the summary's original region size; a summary under max(min-tokens, pct x original) is degenerate", 0.005, 0, 1),
 			num("MEGACOMPACT_RECALL_MIN_COSINE", "Recall Min Cosine (same-repo)", "3WF-3 same-repo floor the 3-source validator applies to the top winner (cross-repo 0.90 stays separate)", 0.12, 0, 1),
 			num("MEGACOMPACT_MMR_LAMBDA", "MMR Lambda", "Maximal Marginal Relevance diversity", 0.5, 0, 1),
 			num("MEGACOMPACT_SEMDEDUP_COSINE", "SemDeDup Cosine", "Offline SemDeDup pair threshold", 0.95, 0, 1),

package/extensions/mega-events/context-handler/liveTrim.ts

@@ -170,8 +170,12 @@ export function buildLiveTrimView(
 			// (rt.lastCheckpointId) instead of ran.result.checkpointId, which is
 			// dedup-volatile: on a re-compact that dedups onto a DIFFERENT existing
 			// checkpoint, result.checkpointId is the matched id (engine.ts:188) while
-			// lastCheckpointId is only updated on a genuinely new checkpoint
-			// (compact.ts:100-104). Keying on result.checkpointId would make
+			// lastCheckpointId was, pre-C1, only updated on a genuinely new checkpoint.
+			// C1 (v0.21.10) now stamps lastCheckpointId on the dedup path too (see
+			// compact/run.ts) — it means "the checkpoint backing this epoch" — so this
+			// key and the D.2/D.3 comparison agree in both directions and the `??`
+			// fallbacks below are now only for the truly-no-checkpoint edge case.
+			// Keying on result.checkpointId directly would still make
 			// trimCache.checkpointId != rt.lastCheckpointId forever after that
 			// dedup fire, disabling replay for the rest of the epoch (the
 			// alternating cache-miss that 0.8.6 meant to fix). Prefer the stable

package/extensions/mega-events/context-handler.ts

@@ -219,8 +219,14 @@ export function registerContextHandler(
 
 		// Debounce so we don't fire on every context event past threshold.
 		// (Replay already returned above — only fresh compacts reach this point.)
+		// C2 (v0.21.10): EXEMPT headroom-triggered fires, matching the thrash-guard
+		// exemption above. pi's own overflow recovery (400 → compact → immediate
+		// retry) re-fires a context event <2s after our last fire; debouncing it
+		// returned the RAW untrimmed view, so input + output reserve still blew the
+		// window → 400 → "recovery failed after one compact-and-retry attempt".
+		// An overflowed session is unrecoverable; a re-fire is merely wasteful.
 		const now = Date.now();
-		if (now < runtime.debounceUntil) {
+		if (now < runtime.debounceUntil && !gate.headroomExceeded) {
 			runtime.diagCtxDebounce++;
 			return tailResult() ?? undefined;
 		}

package/extensions/mega-pipeline/compact/run.ts

@@ -109,10 +109,20 @@ function doCompact(
 	runtime.pulsing = false;
 
 	if (result.skipped) return { skipped: true };
-	if (!result.deduped) {
-		runtime.rt.persistedThisSession = true;
-		runtime.rt.lastCheckpointId = result.checkpointId;
-	}
+	// C1 (v0.21.10): lastCheckpointId tracks "the checkpoint backing this epoch",
+	// so it is stamped on BOTH paths — a matched-dedup checkpoint backs this epoch
+	// just as much as a freshly created one. Previously the dedup path left it
+	// undefined, so a runtime session whose every compaction deduped (common after
+	// a process restart, when checkpoints persist but `rt` is rebuilt) never set it
+	// → liveTrim's trimCache fell back to result.checkpointId (the matched id) →
+	// `trimCache.checkpointId === rt.lastCheckpointId` was `"chkpt_001" !== undefined`
+	// → the D.2/D.3 replay NEVER matched and the full pipeline re-ran on every
+	// context event (liveTrimReplays: 0, "comp lag warn"). A later fire matching a
+	// DIFFERENT checkpoint now changes the key once (one cache regeneration), then
+	// replays stabilise. `persistedThisSession` keeps its narrower meaning ("we
+	// wrote NEW state this session") and stays gated on !deduped.
+	if (!result.deduped) runtime.rt.persistedThisSession = true;
+	runtime.rt.lastCheckpointId = result.checkpointId;
 	runtime.rt.lastCompactedFrom = result.compactedFrom;
 	runtime.rt.lastCompactedTokens = result.tokenEstimate;
 	runtime.rt.dedupAttempts++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.21.9",
+  "version": "0.21.10",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/config/dedup.ts

@@ -66,6 +66,18 @@ export interface DedupConfigShape {
   L2_COSINE_CODE: number | null;
   L2_COSINE_PROSE: number | null;
   L1_JACCARD: number; // MinHash/LSH near-dup verification
+  /**
+   * Degenerate-match guard (incident 2026-08-19). ON declines an L1/L2 collapse
+   * when the MATCHED stored checkpoint is a content-free skeleton and the
+   * incoming candidate is richer, so a degenerate checkpoint can no longer
+   * absorb every future compaction forever. OFF is byte-identical to the
+   * pre-guard cascade. See src/dedup/degenerate.ts.
+   */
+  DEDUP_DEGENERATE_GUARD: boolean;
+  /** Absolute token floor under which a stored summary counts as degenerate. */
+  DEDUP_DEGEN_MIN_TOKENS: number;
+  /** Relative floor as a fraction of the summary's original region size. */
+  DEDUP_DEGEN_MIN_PCT: number;
   DEDUP_SIM: number; // legacy content-similarity fallback
   MMR_LAMBDA: number; // retrieval diversity
   SEMDEDUP_COSINE: number; // offline SemDeDup pair threshold
@@ -123,6 +135,9 @@ export function loadDedupConfig(): DedupConfigShape {
     L2_COSINE_CODE: envNumOrNull("MEGACOMPACT_L2_THRESHOLD_CODE"),
     L2_COSINE_PROSE: envNumOrNull("MEGACOMPACT_L2_THRESHOLD_PROSE"),
     L1_JACCARD: envNum("MEGACOMPACT_L1_JACCARD", 0.8),
+    DEDUP_DEGENERATE_GUARD: envBool("MEGACOMPACT_DEDUP_DEGENERATE_GUARD", true),
+    DEDUP_DEGEN_MIN_TOKENS: envNum("MEGACOMPACT_DEDUP_DEGEN_MIN_TOKENS", 48),
+    DEDUP_DEGEN_MIN_PCT: envNum("MEGACOMPACT_DEDUP_DEGEN_MIN_PCT", 0.005),
     DEDUP_SIM: envNum("MEGACOMPACT_DEDUP_SIM", 0.9),
     MMR_LAMBDA: envNum("MEGACOMPACT_MMR_LAMBDA", 0.5),
     SEMDEDUP_COSINE: envNum("MEGACOMPACT_SEMDEDUP_COSINE", 0.95),

package/src/dedup/degenerate.ts

@@ -0,0 +1,125 @@
+/**
+ * degenerate.ts — the degenerate-checkpoint predicate + the L1/L2 collapse guard.
+ *
+ * WHY THIS EXISTS (incident 2026-08-19). A defect in the summarizer could emit a
+ * DEGENERATE summary: a ~30-40 token structural skeleton with no informational
+ * content, e.g.
+ *
+ *   "Conversation: 64 messages (5 user, 29 assistant, 27 tool). Tools: bash, edit, read."
+ *
+ * Once such a checkpoint landed in the store it became an absorbing state. Every
+ * later compaction produced a structurally identical skeleton, so L1 MinHash and
+ * L2 cosine (0.872 against a 0.85 threshold) matched it EVERY time — each add()
+ * returned `deduped: true`, discarded the incoming content, and only bumped the
+ * stored skeleton's timestamp. The store could never heal, even after the
+ * summarizer was fixed, because a rich new summary that happened to match the
+ * skeleton would still be swallowed by it.
+ *
+ * THE GUARD. When L1 or L2 finds a match, we ask whether the MATCHED (stored)
+ * checkpoint is degenerate and the incoming candidate is RICHER. If both hold, we
+ * decline the collapse and let the cascade continue as if nothing matched — so a
+ * fresh, informative checkpoint is written and the skeleton stops absorbing.
+ *
+ * Direction matters: only "poor stored ← rich incoming" is unblocked. Two equal
+ * skeletons still collapse (dedup is doing its job), and a rich stored
+ * checkpoint absorbing a poor incoming one is left alone — that is ordinary
+ * dedup, not the pathology.
+ *
+ * PREVENT-PI-004: pure arithmetic over already-loaded fields. No IO, no network.
+ */
+import type { StoredCheckpoint } from "../store.js";
+
+/** The tunables the guard reads (thread from DedupConfigShape). */
+export interface DegenerateGuardTunables {
+	/** Umbrella flag. OFF ⇒ the guard never fires (byte-identical predecessor). */
+	readonly DEDUP_DEGENERATE_GUARD: boolean;
+	/** Absolute token floor below which a stored summary is structural, not informational. */
+	readonly DEDUP_DEGEN_MIN_TOKENS: number;
+	/** Relative floor as a fraction of the ORIGINAL region the summary stands in for. */
+	readonly DEDUP_DEGEN_MIN_PCT: number;
+}
+
+/** The two fields the predicate scores. Kept structural so tests need no full row. */
+export interface DegenerateSubject {
+	tokenEstimate?: number;
+	originalTokenEstimate?: number;
+}
+
+/**
+ * The effective token floor for a checkpoint: the larger of the absolute floor
+ * and `MIN_PCT × originalTokenEstimate`.
+ *
+ * A missing / zero / non-finite `originalTokenEstimate` contributes nothing, so
+ * the absolute floor applies alone — direct add() callers and pre-v0.4 rows that
+ * never recorded the original region size are judged on absolute size only,
+ * never accidentally deemed degenerate by a 0-valued percentage term.
+ */
+export function degenerateFloor(
+	subject: DegenerateSubject,
+	tunables: DegenerateGuardTunables,
+): number {
+	const orig = subject.originalTokenEstimate;
+	const relative =
+		typeof orig === "number" && Number.isFinite(orig) && orig > 0
+			? orig * tunables.DEDUP_DEGEN_MIN_PCT
+			: 0;
+	return Math.max(tunables.DEDUP_DEGEN_MIN_TOKENS, relative);
+}
+
+/**
+ * Is this stored checkpoint a degenerate (content-free) summary?
+ *
+ * Calibration against the incident data:
+ *  - skeleton: tokenEstimate 34, original ≈19166 → 34 < max(48, 95.8) → TRUE
+ *  - normal:   tokenEstimate 2000, original 70000 → 2000 > max(48, 350) → FALSE
+ *
+ * The relative term is what makes this scale: a 34-token summary of a 900-token
+ * region is a legitimate 26× compression, while the same 34 tokens standing in
+ * for 19k is a skeleton.
+ */
+export function isDegenerateCheckpoint(
+	subject: DegenerateSubject,
+	tunables: DegenerateGuardTunables,
+): boolean {
+	const tokens = subject.tokenEstimate ?? 0;
+	return tokens < degenerateFloor(subject, tunables);
+}
+
+/**
+ * Should an L1/L2 match be DECLINED because it would collapse richer incoming
+ * content onto a degenerate stored checkpoint?
+ *
+ * Returns true only when all four hold:
+ *   1. the umbrella flag is ON,
+ *   2. the matched (stored) checkpoint is degenerate,
+ *   3. the candidate is strictly richer than the match,
+ *   4. the candidate's content is not byte-identical to the match's.
+ *
+ * Condition 3 uses a strict `>`: equal-size skeletons collapsing is harmless and
+ * keeps the store from growing one row per compaction while the summarizer is
+ * broken. Only a genuine improvement is worth declining a collapse for.
+ *
+ * Condition 4 is a CORRECTNESS requirement, not a refinement. `context_chunks`
+ * carries a partial UNIQUE index on (session_id, content_hash) (schema/core.ts
+ * QA #1), so declining a match whose content hash already exists would fall
+ * through to an INSERT that throws — inside add(), which sits on the agent loop.
+ * It is also the semantically right call: identical bytes are the SAME region,
+ * so re-storing them adds no information and heals nothing. Only L0 may own the
+ * exact-match case; the guard exists for fuzzy matches on genuinely different
+ * text, which is exactly the incident's shape (each compaction produced a
+ * *similar but distinct* skeleton).
+ */
+export function shouldSkipDegenerateMatch(
+	matched: StoredCheckpoint,
+	candidate: DegenerateSubject & { contentHash?: string },
+	tunables: DegenerateGuardTunables,
+): boolean {
+	if (!tunables.DEDUP_DEGENERATE_GUARD) return false;
+	if (!isDegenerateCheckpoint(matched, tunables)) return false;
+	if ((candidate.tokenEstimate ?? 0) <= (matched.tokenEstimate ?? 0)) return false;
+	// Byte-identical content → not a healing opportunity (and would violate the
+	// UNIQUE index). Compared only when both hashes are known.
+	const a = candidate.contentHash;
+	const b = matched.contentHash;
+	return !(a !== undefined && b !== undefined && a === b);
+}

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) + "…";
+}