claude-mem-lite 6.5.0 → 6.6.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.5.0",
+      "version": "6.6.0",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.5.0",
+  "version": "6.6.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/README.md

@@ -896,7 +896,8 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `MEM_DISABLE_CITATION_DECAY` | `1` disables only the decay writes, keeping access-count bumps. | _(enabled)_ |
 | `CLAUDE_MEM_CITATION_ADOPTION_THRESHOLD` | **Removed — inert.** Tuned the per-project adoption gate, which is gone (D#204). Setting it warns on stderr and changes nothing. | _(n/a)_ |
 | `CLAUDE_MEM_NO_CITE_NUDGE` | `1` fully silences the cite-back nudge. | _(enabled)_ |
-| `CLAUDE_MEM_CITE_NUDGE_THRESHOLD` | Cite-rate below which the nudge fires. | `0.6` |
+| `CLAUDE_MEM_CITE_NUDGE_THRESHOLD` | Cite-rate below which the nudge fires. | `0.4` |
+| `CLAUDE_MEM_CITE_NUDGE_WIDE_DENOMINATOR` | `1` judges the wide cite-recall ratio (every `#NN`-shaped token the model saw) instead of the lessons the hooks injected. **Half of the revert**: the threshold moved too, so pre-v6.6.0 gating needs this **and** `CLAUDE_MEM_CITE_NUDGE_THRESHOLD=0.6`. This switch alone gives you the wide ratio judged at 0.4, which is neither release's behaviour. | unset |
 | `CLAUDE_MEM_CITE_NUDGE_MIN_INJECTED` | Minimum injection volume before the ratio gate is judged at all. | `5` |
 | `CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER` | Consecutive low-cite sessions before the nudge goes quiet; `0` = never silence. | `3` |
 | `CLAUDE_MEM_CITATION_RELEVANCE_GATE` | Stop credits an `access_count` to a memory the session cited only when something made that memory relevant to the session — it was injected, or you typed its `#NN` yourself. `off` restores the pre-v3.84.0 behaviour of crediting every `#NN` the assistant wrote, which over-counts sessions that discuss memories in prose (release notes, audit reports): measured on real transcripts, 267 of 859 credited (id, session) pairs — 31.1% — were mentions nothing had put in front of the model. Superseded citations are redirected to their keeper on both settings. | _(on)_ |

package/hook-context.mjs

@@ -336,6 +336,69 @@ export function selectWithTokenBudget(db, project, budget = 2000) {
  * removes the paired hint comment if present, and normalizes residual whitespace
  * at the seam. Uses atomic tmp+rename write.
  */
+/**
+ * Half-open [start, end) ranges of every fenced code span in a markdown document.
+ *
+ * A fence opens on a line whose first non-space run is three or more backticks or tildes,
+ * and closes on the next line opening with at least as many of the SAME character — CommonMark's
+ * rule, and the reason a ```` ```` ```` block can contain a ``` line. An unterminated fence
+ * runs to EOF.
+ */
+function fencedRanges(content) {
+  const ranges = [];
+  let open = null;
+  let offset = 0;
+  for (const line of content.split('\n')) {
+    const m = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (m) {
+      if (!open) {
+        open = { char: m[1][0], len: m[1].length, start: offset };
+      } else if (m[1][0] === open.char && m[1].length >= open.len) {
+        ranges.push([open.start, offset + line.length]);
+        open = null;
+      }
+    }
+    offset += line.length + 1; // +1 for the '\n' split removed
+  }
+  if (open) ranges.push([open.start, content.length]);
+  return ranges;
+}
+
+/** True when `idx` sits inside a backtick-delimited inline code span on its own line. */
+function insideInlineCode(content, idx) {
+  const lineStart = content.lastIndexOf('\n', idx - 1) + 1;
+  // Count backtick RUNS before the position; an odd count means the position is inside a
+  // span. Runs, not characters: ``code with ` inside`` is one span opened by two ticks.
+  const before = content.slice(lineStart, idx);
+  const runs = before.match(/`+/g);
+  return runs !== null && runs.length % 2 === 1;
+}
+
+/**
+ * The last index of `needle` that is a real block's tag, or -1.
+ *
+ * Three exclusions, and the pre-ship review is why there are three rather than one. A
+ * legacy block written by the old `updateClaudeMd` put its tags at COLUMN 0 on their own
+ * lines, so anything else is prose ABOUT the tag:
+ *   - inside a fenced code span (```/~~~)          — the first cut, and only a third of it
+ *   - not at the start of a line                    — an inline mention mid-sentence
+ *   - indented four or more spaces                  — CommonMark's other code block
+ * Measured before the widening, with the shipped function: an inline span went 101 -> 55
+ * bytes and an indented block 95 -> 33, atomically, with no backup.
+ */
+function lastIndexOutsideFences(content, needle, ranges) {
+  let idx = content.lastIndexOf(needle);
+  while (idx !== -1) {
+    const lineStart = content.lastIndexOf('\n', idx - 1) + 1;
+    const indent = content.slice(lineStart, idx);
+    const atLineStart = indent.length === 0;
+    const inFence = ranges.some(([a, b]) => idx >= a && idx < b);
+    if (atLineStart && !inFence && !insideInlineCode(content, idx)) return idx;
+    idx = content.lastIndexOf(needle, idx - 1);
+  }
+  return -1;
+}
+
 export function cleanupClaudeMdLegacyBlock() {
   // v2.48 P2-4: idempotent marker. First run (whether it finds a block or not,
   // whether CLAUDE.md exists or not) drops a project-scoped marker in RUNTIME_DIR.
@@ -369,10 +432,21 @@ export function cleanupClaudeMdLegacyBlock() {
   const startTag = '<claude-mem-context>';
   const endTag = '</claude-mem-context>';
 
-  // Use lastIndexOf so documentation references to the tag earlier in the file
-  // (e.g. inside a code block in architecture notes) are not accidentally swept.
-  const startIdx = content.lastIndexOf(startTag);
-  const endIdx = content.lastIndexOf(endTag);
+  // A4 (audit 2026-09-08): `lastIndexOf` alone was NOT the protection the old comment
+  // here claimed. It shields a documentation reference only when a real block sits AFTER
+  // it; when the file's only occurrence IS the reference — the ordinary case for someone
+  // who wrote down what this plugin emits — both searches land on it, `startIdx < endIdx`
+  // holds, and the user's fenced sample is deleted with its two fences spliced into a
+  // broken ``````. Atomic write, no backup, once per project, so it shows up as a small
+  // stray diff days later. Measured on a plain 226-byte CLAUDE.md: 226 → 145.
+  //
+  // "The tag is alone on its line" does not discriminate — inside a fence it usually is.
+  // The fence itself is the signal, so fenced spans are excluded before the search, and an
+  // UNTERMINATED fence is treated as running to EOF: that errs toward leaving the file
+  // alone, which is the safe direction for a write into someone's own notes.
+  const fenced = fencedRanges(content);
+  const startIdx = lastIndexOutsideFences(content, startTag, fenced);
+  const endIdx = lastIndexOutsideFences(content, endTag, fenced);
   if (startIdx === -1 || endIdx === -1 || startIdx >= endIdx) {
     dropMarker();
     return;

package/hook-llm.mjs

@@ -279,7 +279,7 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
         `
       SELECT title FROM observations
       WHERE project = ? AND created_at_epoch > ?
-      ORDER BY created_at_epoch DESC LIMIT 10
+      ORDER BY created_at_epoch DESC, id DESC LIMIT 10
     `,
       )
       .all(project, fiveMinAgo);
@@ -313,7 +313,7 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
           `
         SELECT title FROM observations
         WHERE project = ? AND created_at_epoch > ? AND created_at_epoch <= ?
-        ORDER BY created_at_epoch DESC LIMIT 60
+        ORDER BY created_at_epoch DESC, id DESC LIMIT 60
       `,
         )
         .all(project, threeDaysAgo, fiveMinAgo);
@@ -331,7 +331,7 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
           `
         SELECT minhash_sig FROM observations
         WHERE project = ? AND created_at_epoch > ? AND minhash_sig IS NOT NULL
-        ORDER BY created_at_epoch DESC LIMIT 200
+        ORDER BY created_at_epoch DESC, id DESC LIMIT 200
       `,
         )
         .all(project, sevenDaysAgo);
@@ -1383,7 +1383,7 @@ export async function handleLLMSummary() {
       FROM observations
       WHERE memory_session_id = ?
         AND ${notLowSignalTitleClause('')}
-      ORDER BY created_at_epoch DESC
+      ORDER BY created_at_epoch DESC, id DESC
       LIMIT 30
     `,
       )
@@ -1585,28 +1585,33 @@ ${obsList}`;
 // spinning up the full LLM dispatcher. Lets the e2e leak test verify that
 // the observations INSERT path scrubs all configured text fields.
 export const __insertObservationForTest = (db, obs) => {
+  // R11 C-P3-3: this used to hand-spell an 18-column INSERT of its own while the
+  // shipping writer above went through insertObservationRow's 19-column list, so the
+  // secret-scrub leak test asserted on a REPLICA of the write point rather than the
+  // write point. Column-list drift between the two is exactly what
+  // lib/observation-write.mjs exists to make impossible, and a test copy is the one
+  // caller that can drift without anyone noticing — it has no user.
   const safe = scrubRecord('observations', obs);
-  db.prepare(
-    `INSERT INTO observations (memory_session_id, project, text, type, title, subtitle, narrative, concepts, facts, files_read, files_modified, importance, minhash_sig, lesson_learned, search_aliases, branch, created_at, created_at_epoch)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-  ).run(
-    obs.session_id,
-    obs.project,
-    safe.text,
-    'change',
-    safe.title,
-    safe.subtitle,
-    safe.narrative,
-    safe.concepts,
-    safe.facts,
-    obs.files_read,
-    obs.files_modified,
-    obs.importance,
-    obs.minhash_sig,
-    safe.lesson_learned,
-    safe.search_aliases,
-    obs.branch,
-    new Date().toISOString(),
-    Date.now(),
-  );
+  const now = new Date();
+  return insertObservationRow(db, {
+    memory_session_id: obs.session_id,
+    project: obs.project,
+    text: safe.text,
+    type: 'change',
+    title: safe.title,
+    subtitle: safe.subtitle,
+    narrative: safe.narrative,
+    concepts: safe.concepts,
+    facts: safe.facts,
+    files_read: obs.files_read,
+    files_modified: obs.files_modified,
+    importance: obs.importance,
+    minhash_sig: obs.minhash_sig,
+    lesson_learned: safe.lesson_learned,
+    search_aliases: safe.search_aliases,
+    branch: obs.branch,
+    created_at: now.toISOString(),
+    created_at_epoch: now.getTime(),
+    scope: normalizeScope(obs.scope),
+  });
 };

package/hook-memory.mjs

@@ -8,12 +8,9 @@ import {
   OBS_BM25,
   notLowSignalTitleClause,
   noisePenaltyClause,
-  tokenizeHandoff,
-  HANDOFF_STOP_WORDS,
-  extractCjkKeywords,
   neutralizeContextDelimiters,
 } from './utils.mjs';
-import { upsFtsQuery } from './lib/ups-query.mjs';
+import { upsFtsQuery, upsQueryTerms } from './lib/ups-query.mjs';
 import { citeFactorJs, TYPE_QUALITY, TYPE_QUALITY_DEFAULT } from './scoring-sql.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 import { recordMetric } from './lib/metrics.mjs';
@@ -169,17 +166,6 @@ function getCrossProjectBoost() {
   const n = parseFloat(raw);
   return Number.isFinite(n) && n >= 0 && n <= 1 ? n : 0.4;
 }
-function extractQueryTerms(text) {
-  if (!text) return [];
-  const ascii = tokenizeHandoff(text).filter((t) => !HANDOFF_STOP_WORDS.has(t));
-  let cjk = [];
-  try {
-    cjk = extractCjkKeywords(text) || [];
-  } catch {
-    /* CJK extraction best-effort */
-  }
-  return [...new Set([...ascii, ...cjk.map((t) => String(t).toLowerCase())])];
-}
 // v2.41: hay spans every FTS column whose BM25 weight is >=5 in OBS_BM25
 // (title=10, subtitle=5, narrative=5, lesson_learned=8). Pre-v2.41 was only
 // title + lesson_learned — rows that matched on narrative but happened to
@@ -509,7 +495,16 @@ export function searchRelevantMemories(
     let coverageFiltered = aboveThreshold;
     const coverageThreshold = getCoverageThreshold();
     if (coverageThreshold > 0) {
-      const queryTerms = extractQueryTerms(userPrompt);
+      // A1: the denominator is the terms the query was actually BUILT from, via the one
+      // source (lib/ups-query.mjs -> nlp.mjs::ftsQueryTokens). Counting anything else
+      // counts terms that were never searched, so no matched row can cover them and the
+      // ratio falls with prompt length until the whole surface goes silent.
+      //
+      // The first cut of this fix shared only maxChars and the pre-ship review measured
+      // the hole it left: sanitizeFtsQuery also caps at maxTokens = 64, so a 1511-character
+      // prompt — under the char cap, where the shared cut is a no-op — still returned []
+      // against a row whose narrative was the entire prompt.
+      const queryTerms = upsQueryTerms(userPrompt);
       if (queryTerms.length >= COVERAGE_MIN_QUERY_TERMS) {
         coverageFiltered = aboveThreshold.filter(
           (r) => candidateCoverage(r, queryTerms) >= coverageThreshold,

package/hook-optimize.mjs

@@ -1517,6 +1517,13 @@ export async function executeSmartCompressCluster(db, observations, project) {
       //
       // optimized_at is not in OBS_COLUMNS, so it stays a separate UPDATE below — the
       // summary must be marked processed so the re-enrich pools do not pick it up.
+      //
+      // R11 C-P3-2 read the three-item list above as a completeness claim and asked why
+      // the fourth OBS_COLUMNS entry, `scope`, is absent. It is absent on purpose: the
+      // merge prompt does not ask for one, so there is no value to pass, and NULL is the
+      // `scopes` backfill pool's own predicate (findReenrichCandidates, scope==='scopes')
+      // — which is deliberately NOT gated on optimized_at, so stamping this row processed
+      // does not evict it. Writing a guessed scope here would.
       const newId = insertObservationRow(db, {
         memory_session_id: sessionId,
         project,

package/hook.mjs

@@ -1406,6 +1406,34 @@ function trackCitationsAtStop(db, { sessionId, project, ccSessionId, transcriptP
       // which was ~all of the cost.)
       try {
         const stats = computeCiteRecall(transcriptPath);
+        // D#19: the RATIO GATE's own denominator, alongside the wide one. `stats` counts
+        // every `#NN`-shaped token in non-assistant text — tool_result bodies, file
+        // contents, CLI output, pasted reports — which is the right caliber for "what has
+        // the model seen" and the wrong one for "did it cite back what the hooks gave it"
+        // (measured 11.2x inflation, R11-B-P2-2). Both are persisted; buildCiteRecallNudge
+        // gates on this pair and falls back to the wide one for older payloads.
+        //
+        // Cost is an array iteration, not a parse: this block runs after the decay loop's
+        // own extractInjectedBySurface on the same path, and lib/transcript-scan.mjs memoizes
+        // the parse. mainOnly mirrors the decay loop — an id injected only inside a subagent
+        // would otherwise enter the denominator while its citation lands in another
+        // transcript, scoring a miss the main thread never had a chance to avoid.
+        let gate = { gateInjected: null, gateRecalled: null, gateRatio: null };
+        try {
+          const gateInjectedIds = unionSurfaces(extractInjectedBySurface(transcriptPath, { mainOnly: true }));
+          const gateCited = extractCitationsFromTranscript(transcriptPath, { mainOnly: true });
+          let hit = 0;
+          for (const id of gateInjectedIds) if (gateCited.has(id)) hit++;
+          gate = {
+            gateInjected: gateInjectedIds.size,
+            gateRecalled: hit,
+            gateRatio: gateInjectedIds.size > 0 ? hit / gateInjectedIds.size : 0,
+          };
+        } catch (e) {
+          // Leaving the gate* keys null is the defined fallback, not a silent loss: the
+          // reader treats a payload without them exactly like a pre-release one.
+          debugCatch(e, 'handleStop-cite-recall-gate-denominator');
+        }
         // B2 (v2.83.1): also persist the bugfix-shape nudge/save delta so
         // the next SessionStart can surface "N unsaved bugfix-shape edits"
         // alongside cite-recall. Same scan target (transcript already in OS
@@ -1422,11 +1450,13 @@ function trackCitationsAtStop(db, { sessionId, project, ccSessionId, transcriptP
         // always said. Stop fires once per assistant TURN, so incrementing here silenced
         // the nudge inside the first session — this machine read lowStreak 58 against 26
         // transcripts before the fix.
-        const { lowStreak, streakBase, lastStreakSession } = nextCiteStreakState(
-          prevPayload,
-          ccSessionId,
-          stats,
-        );
+        // D#19: the streak advances on the SAME gate the nudge fires on, so the merged
+        // stats go in. Handing it the wide triple alone would let the streak climb on a
+        // verdict the SessionStart surface never reached — two policies, one counter.
+        const { lowStreak, streakBase, lastStreakSession } = nextCiteStreakState(prevPayload, ccSessionId, {
+          ...stats,
+          ...gate,
+        });
         // G3: finalized-in-conversation + zero deliberate persistence →
         // decisionSignal rides the payload; next SessionStart reminds once.
         let decisionSignal = null;
@@ -1449,6 +1479,7 @@ function trackCitationsAtStop(db, { sessionId, project, ccSessionId, transcriptP
         }
         const payload = {
           ...stats,
+          ...gate,
           ...bugfixStats,
           lowStreak,
           streakBase,
@@ -1593,8 +1624,9 @@ async function handleStop() {
 
 // Build the SessionStart nudge line shown when the prior session's cite-recall
 // fell below threshold. Empty string = no surface (insufficient signal, recall
-// already healthy, or feature opted-out via env). Default threshold 0.6,
-// min injected 5 — both env-overridable for ops tuning + tests.
+// already healthy, or feature opted-out via env). Default threshold 0.4 against the
+// HOOK-INJECTED denominator (v6.6.0, D#19), min injected 5 — both env-overridable for
+// ops tuning + tests; CLAUDE_MEM_CITE_NUDGE_WIDE_DENOMINATOR=1 restores the wide one.
 // Thin wrapper: lib/cite-back-hint.mjs owns the logic so it stays unit-tested.
 // Passing module-level RUNTIME_DIR keeps the call site identical to pre-v2.83.1.
 function buildCiteRecallNudge(project) {

package/install.mjs

@@ -72,7 +72,6 @@ import {
 } from './lib/binding-probe.mjs';
 import { detectInstallShape, probeRuntimeRoots } from './lib/install-shape.mjs';
 import { probeSchemaCompat, schemaSkewRemedy } from './lib/schema-skew.mjs';
-import { isDbUnusableError, dbUnusableRemedy } from './lib/db-unusable.mjs';
 import { clearNativeBindingBreakage, readNativeBindingBreakage } from './lib/native-binding-hint.mjs';
 import { sweepStaleTestFixtures } from './lib/tmp-fixture-sweep.mjs';
 import { ORPHAN_EPISODE_AGE_MS } from './lib/time-constants.mjs';
@@ -442,12 +441,23 @@ export function nonPluginMemRegistrations(listOutput) {
  * Exported for tests/doctor-db-remedy.test.mjs, which also drives the shipped doctor over a
  * corrupt file — a pure function nothing calls is the wiring gap this repo keeps finding.
  */
-export function dbCheckRemedy(dbPath, err) {
+export async function dbCheckRemedy(dbPath, err) {
   if (isNativeBindingError(err)) return `Repair: ${nativeBindingRepairHint(PROJECT_DIR)}`;
   // Classification and remedy both live in lib/db-unusable.mjs since v6.5.0, because the hook
   // path now has to answer the same question in-session and two copies of a SQLite-message
   // regex is this repo's named twin-drift class. Doctor keeps its own SENTENCE (one line, no
   // leading banner); only the decision is shared.
+  //
+  // Audit 2026-09-08 P1-1: loaded HERE, not at the top of the file. `lib/db-unusable.mjs`
+  // reaches utils.mjs through db-backup, and utils.mjs pulls the whole retrieval/NLP
+  // subtree (nlp / synonyms / stop-words / scoring-sql / secret-scrub / …). As a static
+  // import that made every one of those files a prerequisite for doctor STARTING, on a
+  // command whose whole job is to tell a user which file is missing — so a copy install
+  // short one of them answered with a bare ERR_MODULE_NOT_FOUND stack. This function runs
+  // only inside the Database check's catch, so the cost of loading it lazily is paid by
+  // the rare failure rather than by every invocation. Same shape as the six dynamic
+  // imports doctor already uses.
+  const { isDbUnusableError, dbUnusableRemedy } = await import('./lib/db-unusable.mjs');
   if (!isDbUnusableError(err)) return null;
   const remedy = dbUnusableRemedy(dbPath);
   if (remedy.kind === 'unknown') return remedy.note;
@@ -1947,10 +1957,31 @@ async function doctor() {
   }
 
   // Plugin/hook lifecycle state
-  const settings = readSettings();
-  const hasHooks = hasMemHooksConfigured(settings);
-  const pluginDisabled = isPluginExplicitlyDisabled(settings);
-  if (pluginDisabled && hasHooks) {
+  //
+  // Audit 2026-09-08 P1-2: readSettings() THROWS on a settings.json that exists and does
+  // not parse. That is the right answer for install / uninstall — every write path merges
+  // into its return value, so refusing to act is the only safe move (R10 P1-8) — and the
+  // wrong one to inherit here. doctor never writes settings.json, and a hand-edited
+  // trailing comma is one of the most common self-inflicted "Claude Code is broken"
+  // states, i.e. precisely when someone runs doctor. Inheriting the throw aborted the run
+  // at this check: nine later checks never ran and `--json` emitted zero bytes.
+  //
+  // `null` means NOT READ, and each consumer says "not checked" rather than treating an
+  // empty object as "nothing is configured". "I could not look" is not "there is nothing
+  // there" — the same three-outcome rule the bash-hook and marketplace checks follow.
+  let settings = null;
+  try {
+    settings = readSettings();
+  } catch (e) {
+    fail(`settings.json: unreadable — ${e.message}`);
+    log('    The three checks that read it are skipped below; every other check still runs.');
+    issues++;
+  }
+  const hasHooks = settings !== null && hasMemHooksConfigured(settings);
+  const pluginDisabled = settings !== null && isPluginExplicitlyDisabled(settings);
+  if (settings === null) {
+    dwarn('Plugin lifecycle: not checked (settings.json unreadable)');
+  } else if (pluginDisabled && hasHooks) {
     fail('Plugin lifecycle: plugin is disabled but claude-mem-lite hooks still remain in settings.json');
     issues++;
   } else if (pluginDisabled) {
@@ -1988,8 +2019,10 @@ async function doctor() {
   // with require-error noise every session. README's Uninstall section warns
   // about the right ordering; this check flags the broken state so it surfaces
   // even when the user skipped the README.
-  const orphanPaths = collectOrphanHookPaths(settings);
-  if (orphanPaths.length > 0) {
+  const orphanPaths = settings === null ? null : collectOrphanHookPaths(settings);
+  if (orphanPaths === null) {
+    dwarn('Orphan hooks: not checked (settings.json unreadable)');
+  } else if (orphanPaths.length > 0) {
     fail(
       `Orphan hooks: ${orphanPaths.length} settings.json entr${orphanPaths.length === 1 ? 'y references a missing file' : 'ies reference missing files'}`,
     );
@@ -2014,9 +2047,16 @@ async function doctor() {
     const bare = nonPluginMemRegistrations(list);
     // Registration, not directory — see pluginIsRegistered. Crediting a leftover cache dir
     // here told a working npm-channel install to delete its ONLY MCP registration.
+    // Reuses the `settings` read above rather than calling readSettings() a second time:
+    // the second call carried the same throw, so guarding only the first would have moved
+    // the abort eleven checks later instead of removing it (P1-2).
     const viaPlugin =
-      !!shape?.activePluginVersion && pluginIsRegistered({ home: homedir(), settings: readSettings() });
-    if (viaPlugin && bare.length > 0) {
+      !!shape?.activePluginVersion && settings !== null && pluginIsRegistered({ home: homedir(), settings });
+    if (settings === null) {
+      dwarn(
+        `MCP registration: found ${bare.length} bare registration(s); whether the plugin also provides one is not checked (settings.json unreadable)`,
+      );
+    } else if (viaPlugin && bare.length > 0) {
       dwarn(
         `MCP registration: the plugin manifest provides the server AND a bare "${bare.join('", "')}" registration exists — the server is registered twice`,
       );
@@ -2106,7 +2146,17 @@ async function doctor() {
       // Every other ✗ on this screen carries a remedy; this one used to be the exception,
       // and a corrupt store is the failure a user is least able to diagnose unaided.
       // dbCheckRemedy returns null rather than invent one for an error it cannot classify.
-      const remedy = dbCheckRemedy(DB_PATH, e);
+      // Pre-ship review 2026-09-09: dbCheckRemedy became async and lazy (P1-1), which moved
+      // its failure mode from load time into THIS catch — and an unhandled rejection here
+      // aborts doctor exactly as the static import did, so `--json` still emitted zero bytes
+      // on the compound shape "a file is missing AND the database will not open". A remedy
+      // is an extra sentence on a check that has already failed; never let it take the run.
+      let remedy = null;
+      try {
+        remedy = await dbCheckRemedy(DB_PATH, e);
+      } catch (remedyErr) {
+        log(`    (could not build a repair hint: ${remedyErr.message})`);
+      }
       if (remedy) log(`    ${remedy}`);
       issues++;
     }

package/lib/cite-back-hint.mjs

@@ -189,8 +189,11 @@ export function countUnsavedBugfixShape(transcriptPath) {
 // ─── buildCiteRecallNudge (extracted from hook.mjs for unit-testability) ────
 // Reads `runtime/cite-recall-<project>.json` (written by handleStop) and
 // builds the SessionStart nudge surface. Two independent gates compose:
-//   • cite-recall ratio gate: prior session's ratio < threshold (default 0.6)
-//     AND injected count >= floor (default 5)
+//   • cite-recall ratio gate: prior session's HOOK-INJECTED cite-recall ratio <
+//     threshold (default 0.4) AND that same injected count >= floor (default 5).
+//     D#19: the wide computeCiteRecall ratio is the fallback for payloads written
+//     before v6.6.0, and the forced reading under
+//     CLAUDE_MEM_CITE_NUDGE_WIDE_DENOMINATOR=1.
 //   • B2 (v2.83.1) unsaved-bugfix gate: `unsaved > 0` (no min-volume floor —
 //     the bugfix-shape heuristic already requires ≥3 entries)
 // Either gate can fire independently. Both off → empty string (no surface).
@@ -204,16 +207,66 @@ export function countUnsavedBugfixShape(transcriptPath) {
 // CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER (0 = never silence).
 export const CITE_NUDGE_SILENCE_AFTER = 3;
 
+/**
+ * Which (injected, recalled, ratio) triple the gate judges, and whether it is the
+ * hook-injected one.
+ *
+ * D#19. `computeCiteRecall`'s denominator is deliberately wide — every `#NN`-shaped
+ * token in non-assistant text, which includes tool_result bodies, file contents, CLI
+ * output and pasted reports. That is the right caliber for "which ids has the model
+ * SEEN", and it is not the question this nag asks. The nag asks whether the model cited
+ * back the lessons the HOOKS put in front of it, and against the wide denominator that
+ * ratio is structurally small: measured 2026-09-08 over all 69 transcripts on this
+ * machine, wide median 0.125 vs hook-injected median 0.429, and the shipped 0.6
+ * threshold fired on 46 of 48 qualifying sessions (96%).
+ *
+ * A gate that is 96% true carries almost no information, and because `nextCiteLowStreak`
+ * only resets when the gate does NOT fire, the streak climbs to CITE_NUDGE_SILENCE_AFTER
+ * within the first few sessions and the surface goes quiet for the life of the project.
+ * That — not "the threshold is unsatisfiable", which was D#19's premise and is false
+ * (max ratio is 0.833 today among the sessions that clear the volume floor, which is the
+ * population the gate judges; over all 69 transcripts the hook-injected side reaches 1.000
+ * — state which rows, the two differ) — is the defect.
+ *
+ * Back-compat: a payload written before this release has no `gate*` keys, so the wide
+ * triple is used and the only change such a project sees is the threshold. Full revert:
+ * CLAUDE_MEM_CITE_NUDGE_WIDE_DENOMINATOR=1 plus CLAUDE_MEM_CITE_NUDGE_THRESHOLD=0.6.
+ */
+function gateStats(data, env) {
+  const wide = {
+    injected: data?.injected,
+    recalled: data?.recalled,
+    ratio: data?.ratio,
+    hookScoped: false,
+  };
+  if (env.CLAUDE_MEM_CITE_NUDGE_WIDE_DENOMINATOR === '1') return wide;
+  if (typeof data?.gateInjected === 'number' && typeof data?.gateRatio === 'number') {
+    return {
+      injected: data.gateInjected,
+      recalled: data.gateRecalled,
+      ratio: data.gateRatio,
+      hookScoped: true,
+    };
+  }
+  return wide;
+}
+
 // True iff this session's stats satisfy the ratio-nag gate (low cite-recall with
 // enough injection volume to judge). Shared by buildCiteRecallNudge (decide to
 // nag) and nextCiteLowStreak (decide to keep silencing).
-function ratioGateFires(data, env) {
+function ratioGateFires(rawData, env) {
+  const data = gateStats(rawData, env);
   // `Number(x) || d` was NaN-safe but swallowed an explicit 0, and 0 is meaningful
   // on BOTH knobs: threshold 0 means "never nag on ratio", min-injected 0 means "no
   // volume requirement". Neither was reachable through the env before.
+  // D#19: 0.6 → 0.4. Chosen off the hook-injected distribution measured 2026-09-08 on
+  // this machine's 69 transcripts (n=14 qualifying: p25 0.333, median 0.429, p75 0.5),
+  // where 0.4 fires on 6/14 = 43% — often enough to be a signal, rarely enough that
+  // lowStreak resets and the surface survives. Stamped rather than presented as
+  // calibrated: n=14 is small and the corpus grows every session.
   const threshold = envNumber(env.CLAUDE_MEM_CITE_NUDGE_THRESHOLD, {
     name: 'CLAUDE_MEM_CITE_NUDGE_THRESHOLD',
-    defaultValue: 0.6,
+    defaultValue: 0.4,
     min: 0,
     max: 1,
   });
@@ -291,7 +344,9 @@ export function nextCiteStreakState(prev, ccSessionId, stats, env = process.env)
 
 // Env opt-outs:
 //   • CLAUDE_MEM_NO_CITE_NUDGE=1 — disables BOTH gates (full silence)
-//   • CLAUDE_MEM_CITE_NUDGE_THRESHOLD — ratio gate threshold (default 0.6)
+//   • CLAUDE_MEM_CITE_NUDGE_THRESHOLD — ratio gate threshold (default 0.4)
+//   • CLAUDE_MEM_CITE_NUDGE_WIDE_DENOMINATOR=1 — judge the wide computeCiteRecall
+//     ratio instead of the hook-injected one (pre-v6.6.0 behaviour)
 //   • CLAUDE_MEM_CITE_NUDGE_MIN_INJECTED — ratio gate min-volume (default 5)
 //   • CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER — consecutive-low streak before the
 //     ratio nag self-silences (default 3; 0 = never silence)
@@ -313,9 +368,15 @@ export function buildCiteRecallNudge(project, runtimeDir, env = process.env) {
     const silenced = silenceAfter > 0 && typeof data.lowStreak === 'number' && data.lowStreak >= silenceAfter;
     const lines = [];
     if (!silenced && ratioGateFires(data, env)) {
-      const pct = Math.round(data.ratio * 100);
+      // Report the SAME triple the gate judged — printing the wide numbers next to a
+      // narrow verdict is how a surface stops being auditable.
+      const g = gateStats(data, env);
+      const pct = Math.round(g.ratio * 100);
+      // The `(recalled/injected)` parenthetical keeps its exact shape — two guards
+      // assert on it, and it is the part a reader scans for.
+      const scope = g.hookScoped ? 'of the lessons the hooks injected' : 'of the ids seen';
       lines.push(
-        `[mem] Last session cite-recall ${pct}% (${data.recalled}/${data.injected}) — when injected lessons (#NN lines) inform your action, cite #NN explicitly so the contract loop stays observable.`,
+        `[mem] Last session cite-recall ${pct}% (${g.recalled}/${g.injected}) ${scope} — when injected lessons (#NN lines) inform your action, cite #NN explicitly so the contract loop stays observable.`,
       );
     }
     if (typeof data.unsaved === 'number' && data.unsaved > 0) {

package/lib/save-observation.mjs

@@ -230,7 +230,7 @@ export function saveObservation(db, params) {
       `
     SELECT id, title, text FROM observations
     WHERE project = ? AND created_at_epoch > ? AND ${liveObsFilterSql('')}
-    ORDER BY created_at_epoch DESC LIMIT ?
+    ORDER BY created_at_epoch DESC, id DESC LIMIT ?
   `,
     )
     .all(project, dedupCutoff, DEDUP_RECENT_LIMIT);