claude-mem-lite 3.91.0 → 3.92.0

package/hook.mjs

@@ -47,6 +47,7 @@ import { entry as preCompactEntry } from './hook-precompact.mjs';
 import {
   RUNTIME_DIR, EPISODE_BUFFER_SIZE, EPISODE_TIME_GAP_MS,
   SESSION_EXPIRY_MS, STALE_SESSION_MS, STALE_LOCK_MS, AUTO_MAINTAIN_LOCK,
+  STALE_EPISODE_BUFFER_AGE_MS,
   HANDOFF_EXPIRY_CLEAR, HANDOFF_EXPIRY_EXIT,
   sessionFile, getSessionId, createSessionId, openDb,
   spawnBackground, sweepOrphanEpisodeFiles, sweepStaleProjectMarkers,
@@ -80,20 +81,15 @@ import { searchRelevantMemories, formatMemoryLine, selectImperativeLesson } from
 import { searchInjectableEvents, renderInjectableEvent } from './lib/events-injection.mjs';
 import { upsFtsQuery } from './lib/ups-query.mjs';
 import { formatTaskImperative } from './lib/task-imperative.mjs';
-import { recordSkillAdoption, gcOldShadowShards } from './registry-recommend.mjs';
 import { gcOldMetricShards, recordMetric } from './lib/metrics.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
-import { injectedIdsFileName, keyContextIdsFileName } from './lib/injected-ids.mjs';
-import { pathAMeterEnabled, coerceMarkerIds, recordPathAExclude } from './lib/patha-exclude-meter.mjs';
+import { injectedIdsFileName, keyContextIdsFileName, readInjectedMarker } from './lib/injected-ids.mjs';
 import { recordKeyContextInjection, touchKeyContextMarker } from './lib/keyctx-marker.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 import { selectErrorRecall } from './lib/error-recall-core.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
-import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-update.mjs';
-import { handleLLMOptimize } from './hook-optimize.mjs';
-import { silentAutoAdopt } from './adopt-cli.mjs';
-import { emitV270UpgradeBanner, hasPreV270Data } from './lib/upgrade-banner.mjs';
 import { loadCiteBackForEpisode, extractCiteBackSignals, buildUnsavedBugfixHint, countUnsavedBugfixShape, buildCiteRecallNudge as libBuildCiteRecallNudge, nextCiteLowStreak } from './lib/cite-back-hint.mjs';
+import { citeRecallPathFor } from './lib/cite-recall-path.mjs';
 import { detectUnpersistedDecision } from './lib/persist-reminder.mjs';
 // plugin-cache-guard.mjs loaded dynamically — pre-2.31.2 installs that auto-upgraded
 // from an older hook-update.mjs SOURCE_FILES (which did not list this module) would
@@ -105,6 +101,31 @@ async function loadCacheGuard() {
   catch { _cacheGuardCache = {}; }
   return _cacheGuardCache;
 }
+// Audit 2026-09-02 P1-8. `hook.mjs` is ONE entry point for seven events, so every static
+// import is paid by every event — PostToolUse, the highest-frequency one, was loading 85
+// modules (1.37 MB) to use a handful. The six modules below are loaded inside the handler
+// that needs them instead: registry-recommend, patha-exclude-meter, hook-update,
+// hook-optimize, adopt-cli, upgrade-banner. Measured marginal cost of the four largest,
+// same process: hook-update 9.4 ms, registry-recommend 5.1, hook-optimize 5.9, the rest
+// 0.5-2.4 each.
+//
+// A failing dynamic import lands in the dispatcher's tail catch -> recordHookError, the
+// same place a failing static import would have landed the whole process; each site keeps
+// whatever local try/catch it already had, so a missing module degrades exactly one
+// feature rather than the event.
+//
+// Three named by the audit are deliberately NOT converted, because the reason they are
+// loaded is not that nobody looked:
+//   * hook-llm.mjs (+16.3 ms, the single largest) — `flushEpisode` is SYNCHRONOUS and on
+//     the PostToolUse path, and it calls `saveEpisodeImmediate` from that module. Lazy
+//     loading needs either an async rewrite of the flush path or extracting the function,
+//     and extraction does not pay: `saveEpisodeImmediate` reaches `saveObservation`, which
+//     pulls tfidf / observation-write / activity / maintain-core anyway — only
+//     haiku-client would actually stop loading.
+//   * lib/db-backup.mjs and lib/compress-core.mjs (<=2.4 ms each) — their call sites sit
+//     in `runSessionStartAutoMaintain` and `handleAutoCompress`, both synchronous. Turning
+//     two functions and their callers async across a background-worker path costs more
+//     risk than the milliseconds are worth.
 import { SKIP_TOOLS, SKIP_PREFIXES } from './skip-tools.mjs';
 import { getVocabulary } from './tfidf.mjs';
 
@@ -523,7 +544,12 @@ async function handlePostToolUse() {
     const ti = typeof tool_input === 'string' ? tryParseJson(tool_input) : (tool_input || {});
     // hookData.session_id (CC UUID) pairs this adoption to the would-be reco from the
     // UserPromptSubmit hook earlier in the same session (matched precision, B1).
-    try { recordSkillAdoption('Skill', ti, inferProject(), hookData.session_id); } catch {}
+    // Lazy: only a `Skill` tool call needs this module, which is a small fraction of
+    // PostToolUse fires.
+    try {
+      const { recordSkillAdoption } = await import('./registry-recommend.mjs');
+      recordSkillAdoption('Skill', ti, inferProject(), hookData.session_id);
+    } catch { /* telemetry only — never blocks capture */ }
   }
 
   const resp = normalizeToolResponse(tool_response);
@@ -1160,7 +1186,7 @@ async function handleStop() {
             // alongside cite-recall. Same scan target (transcript already in OS
             // cache); same persistence file; one extra line in buildCiteRecallNudge.
             const bugfixStats = countUnsavedBugfixShape(transcriptPath);
-            const dest = join(RUNTIME_DIR, `cite-recall-${project.replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64)}.json`);
+            const dest = citeRecallPathFor(RUNTIME_DIR, project);
             // Carry the consecutive-low-cite streak forward so the SessionStart
             // nag can self-silence after the project has ignored it N times.
             let priorStreak = 0;
@@ -1526,8 +1552,18 @@ function runSessionStartAutoMaintain(db, project) {
       // the file behind, and the doctor "Stale temp files" warning then
       // accumulates indefinitely. fs-only; runs inside the 24h gate so it
       // shares cadence with the rest of auto-maintain.
+      //
+      // Since audit P1-12 this also reclaims abandoned per-project episode buffers at 7d.
+      // That one is named individually in the log: every other family it sweeps is residue
+      // or a re-derivable tracker, while `ep-<project>.json` holds unflushed observations —
+      // and the alternative to deleting it is worse (SessionStart flushes whatever it finds
+      // with no staleness gate, so a revisit stamps months-old activity with today's date).
       try {
-        const swept = sweepOrphanEpisodeFiles(RUNTIME_DIR);
+        const swept = sweepOrphanEpisodeFiles(RUNTIME_DIR, {
+          onSweep: (name, kind) => {
+            if (kind === 'buffer') debugLog('DEBUG', 'auto-maintain', `discarding abandoned episode buffer ${name} (>7d; would otherwise flush mis-dated on revisit)`);
+          },
+        });
         if (swept > 0) debugLog('DEBUG', 'auto-maintain', `swept ${swept} orphan ep-flush/pending file(s)`);
       } catch (e) { debugCatch(e, 'auto-maintain-orphan-sweep'); }
 
@@ -1798,7 +1834,7 @@ async function handleSessionStart() {
   // SessionStart cadence, 30d gate, named family list (hook-shared.mjs).
   try { sweepStaleProjectMarkers(RUNTIME_DIR); } catch { /* best-effort */ }
   // Bound the shadow-recommendation log (daily JSONL shards, no GC at write time).
-  try { gcOldShadowShards(); } catch { /* best-effort, never blocks SessionStart */ }
+  try { const { gcOldShadowShards } = await import('./registry-recommend.mjs'); gcOldShadowShards(); } catch { /* best-effort, never blocks SessionStart */ }
   // Same for the opt-in metrics sink (RUNTIME_DIR's parent is DB_DIR). Runs even when
   // metrics are disabled, so shards left by a since-toggled-off run still get pruned.
   try { gcOldMetricShards(join(RUNTIME_DIR, '..')); } catch { /* best-effort */ }
@@ -1842,6 +1878,7 @@ async function handleSessionStart() {
     if (process.env.MEM_NO_AUTO_ADOPT !== '1') {
       const project = inferProject();
       const cwd = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      const { silentAutoAdopt } = await import('./adopt-cli.mjs');
       const r = silentAutoAdopt({ cwd, markerDir: RUNTIME_DIR, markerKey: project });
       if (r.ok) {
         debugLog('DEBUG', 'session-start-auto-adopt', `action=${r.action} project=${project}`);
@@ -1865,12 +1902,30 @@ async function handleSessionStart() {
   // Snapshot episode BEFORE flush for handoff extraction
   const episodeSnapshot = readEpisodeRaw();
 
-  // Flush any leftover episode buffer from previous session (e.g. after /clear)
+  // Flush any leftover episode buffer from previous session (e.g. after /clear).
+  //
+  // A buffer older than STALE_EPISODE_BUFFER_AGE_MS is DISCARDED, not flushed. This is the
+  // half of P1-12 the orphan sweep cannot reach: the sweep runs inside the detached
+  // auto-maintain worker scheduled further down this same function, so on the revisit that
+  // matters the flush below has already happened and the sweeper finds nothing. Without this
+  // gate, returning to a project abandoned months ago injects its months-old tool activity
+  // stamped with today's date — the exact harm hook-shared.mjs's threshold docblock names.
+  // Same constant, because it is the same question ("did this buffer outlive its session by
+  // an order of magnitude?"), asked at the other end.
   if (acquireLock()) {
     try {
-      const prevEpisode = readEpisode();
-      if (prevEpisode && prevEpisode.entries && prevEpisode.entries.length > 0) {
-        flushEpisode(prevEpisode, 'SessionStart');
+      let stale = false;
+      try {
+        stale = Date.now() - statSync(episodeFile()).mtimeMs > STALE_EPISODE_BUFFER_AGE_MS;
+      } catch { /* no buffer file — readEpisode() returns null below */ }
+      if (stale) {
+        debugLog('INFO', 'session-start', `discarding stale episode buffer (>${STALE_EPISODE_BUFFER_AGE_MS}ms): ${episodeFile()}`);
+        try { unlinkSync(episodeFile()); } catch { /* best-effort */ }
+      } else {
+        const prevEpisode = readEpisode();
+        if (prevEpisode && prevEpisode.entries && prevEpisode.entries.length > 0) {
+          flushEpisode(prevEpisode, 'SessionStart');
+        }
       }
     } finally {
       releaseLock();
@@ -1949,6 +2004,7 @@ async function handleSessionStart() {
     // the single envelope; the spawn stays a side effect and is fired below.
     let updateCheckDue = false;
     try {
+      const { getCachedUpdateBanner, isUpdateCheckDue } = await import('./hook-update.mjs');
       const banner = getCachedUpdateBanner();
       // The human channel, not additionalContext: "vX available" is a notice for the
       // USER. Folding it into additionalContext under suppressOutput:true kept its
@@ -1998,6 +2054,7 @@ async function handleSessionStart() {
       // "Any observations at all" still misfired for someone who installed today
       // and saved a few memories before their first SessionStart — age is what
       // actually identifies an upgrader (see lib/upgrade-banner.mjs).
+      const { emitV270UpgradeBanner, hasPreV270Data } = await import('./lib/upgrade-banner.mjs');
       emitV270UpgradeBanner({
         project,
         runtimeDir: RUNTIME_DIR,
@@ -2175,13 +2232,16 @@ async function handleUserPrompt() {
         // project-keyed name), so a concurrent session's write can no longer
         // replace this session's payload between the UPS write and this read.
         const injectedFile = join(RUNTIME_DIR, injectedIdsFileName(project, ccSessionId));
-        const raw = readFileSync(injectedFile, 'utf8');
-        const { ids, ts, session } = JSON.parse(raw);
-        // Only use if written within last 10 seconds (same prompt cycle) AND by this
-        // CC session (M-6 payload gate, still load-bearing for legacy files).
-        // Legacy payloads without `session` keep the old time-window-only behavior.
-        if (ts && Date.now() - ts < 10000 && Array.isArray(ids)
-            && !(session && ccSessionId && session !== ccSessionId)) {
+        // The freshness + same-session gate is lib/injected-ids.mjs's (audit 2026-09-02
+        // P1-2); this was the third hand-typed copy of it. THE 10 s WINDOW STAYS HERE and
+        // is passed in: the two writers gate on DEDUP_STALE_MS (5 min) and this reader on
+        // 10 s ("same prompt cycle"), and that disagreement is a real open question
+        // (P1-2's second half — the 10 s window still accepts the PREVIOUS prompt's
+        // marker), not a copy-paste slip to be normalised away by the consolidation.
+        // Legacy payloads without `session` keep the old time-window-only behaviour.
+        const { ids, fresh } = readInjectedMarker(injectedFile,
+          { sessionId: ccSessionId, maxAgeMs: 10000 });
+        if (fresh) {
           // D#193, DELIBERATELY NOT NUMERICALISED — read this before "fixing" it.
           //
           // Ids arrive here as written. `user-prompt-search.js` writes plain numbers, but
@@ -2258,7 +2318,16 @@ async function handleUserPrompt() {
       // Arm B also carries its OWN imperative pick. Reusing arm A's put a pick the
       // repaired system would not have made into arm B's exclude, so on any prompt where
       // the pick changed, the delta described a system that does not exist.
-      const meterCoerced = (pathAMeterEnabled() && pathAInjectedIds.length > 0)
+      // Lazy on "the marker carried ids", NOT on the metrics env. Gating the import on
+      // `CLAUDE_MEM_METRICS === '1'` would read cheaper still, and would put a second copy
+      // of `pathAMeterEnabled`'s own predicate here — the twin shape this meter's tests
+      // exist to pin. `pathAMeterEnabled()` stays the only place that predicate lives; the
+      // module still stops loading on every OTHER event, which is what P1-8 is about.
+      let pathAMeterEnabled, coerceMarkerIds, recordPathAExclude;
+      if (pathAInjectedIds.length > 0) {
+        ({ pathAMeterEnabled, coerceMarkerIds, recordPathAExclude } = await import('./lib/patha-exclude-meter.mjs'));
+      }
+      const meterCoerced = (pathAMeterEnabled && pathAMeterEnabled())
         ? [...coerceMarkerIds(pathAInjectedIds)]
         : null;
       let meterArmB = null;
@@ -2493,7 +2562,7 @@ try {
     case 'auto-compress':    handleAutoCompress(); break;
     case 'enrich-save':      await handleEnrichSave(process.argv[3]); break;
     case 'auto-maintain':    handleAutoMaintain(process.argv[3]); break;
-    case 'llm-optimize':   await handleLLMOptimize(); break;
+    case 'llm-optimize':   { const { handleLLMOptimize } = await import('./hook-optimize.mjs'); await handleLLMOptimize(); break; }
     // Detached update refresh spawned by handleSessionStart (audit P3d) — does the
     // GitHub fetch off the SessionStart critical path, writing update-state.json so
     // the NEXT session's cached banner is fresh.
@@ -2507,7 +2576,7 @@ try {
     // self-installer back on in the same release that resurrects the worker. The
     // module default and the installer's own guards are unchanged — install.mjs
     // still passes allowInstall:true for the explicit, user-invoked update.
-    case 'update-check':     await checkForUpdate({ allowInstall: false }); break;
+    case 'update-check':     { const { checkForUpdate } = await import('./hook-update.mjs'); await checkForUpdate({ allowInstall: false }); break; }
   }
 } catch (err) {
   // Log fatal errors (ungated) with structured format. ERR_DLOPEN_FAILED (an

package/install.mjs

@@ -614,7 +614,11 @@ if (existsSync(pluginDir)) {
     if (existsSync(pluginHooksPath)) {
       const pluginHooks = JSON.parse(readFileSync(pluginHooksPath, 'utf8'));
       if (pluginHooks.hooks && Object.keys(pluginHooks.hooks).length > 0) {
-        writeFileSync(pluginHooksPath, JSON.stringify({
+        // Atomic (audit 2026-09-02 P1-10): a torn hooks.json is not a fail-open marker —
+        // Claude Code parses it at plugin load, so half a file disables the plugin's hooks
+        // for that install until the next successful write. Same writer settings.json
+        // already uses 1600 lines down.
+        atomicWriteFileSync(pluginHooksPath, JSON.stringify({
           description: pluginHooks.description || 'claude-mem-lite hooks',
           _note: 'Hooks managed by install.mjs in settings.json — this file cleared to prevent duplicates',
           hooks: {}
@@ -653,7 +657,10 @@ if (existsSync(pluginDir)) {
           try {
             const h = JSON.parse(readFileSync(cachedHooksPath, 'utf8'));
             if (h.hooks && Object.keys(h.hooks).length > 0) {
-              writeFileSync(cachedHooksPath, JSON.stringify({
+              // Atomic, same reason as the marketplace-source copy above (P1-10). This one
+              // is the higher-cost of the two: it runs once PER CACHED VERSION, so a tear
+              // here disables hooks for whichever version Claude Code happens to load.
+              atomicWriteFileSync(cachedHooksPath, JSON.stringify({
                 description: h.description || 'claude-mem-lite hooks',
                 _note: `Hooks managed by install.mjs in settings.json — cache hooks.json cleared to prevent duplicate registration (cache ver: ${ver})`,
                 hooks: {}

package/lib/atomic-write.mjs

@@ -8,7 +8,7 @@
 // This writes to a pid-unique temp then renames (atomic on POSIX), and can drop
 // a one-time ".bak" so a logic bug in the caller's merge is recoverable.
 
-import { writeFileSync, renameSync, existsSync, copyFileSync, mkdirSync, lstatSync, realpathSync } from 'node:fs';
+import { writeFileSync, renameSync, existsSync, copyFileSync, mkdirSync, lstatSync, realpathSync, unlinkSync } from 'node:fs';
 import { dirname } from 'node:path';
 
 /**
@@ -43,7 +43,18 @@ export function atomicWriteFileSync(filePath, data, { backup = false } = {}) {
   // pid-unique temp: a fixed ".tmp" name lets two concurrent installs clobber
   // each other's temp mid-write. Same-dir-as-target temp keeps the rename atomic (no
   // cross-device move) even when the target lives in a dotfiles repo on another mount.
+  // The temp is removed on ANY failure. Without this a failed rename (target replaced by a
+  // directory, permissions, a symlink whose resolution path fails) leaves
+  // `<name>.tmp-<pid>` behind — and several call sites write into the USER's project root
+  // (CLAUDE.md), where the residue shows up in their `git status` and nothing sweeps it:
+  // the orphan sweep only walks RUNTIME_DIR. Cleaning here covers every caller rather than
+  // asking each one to remember, which is the mistake the private twins made.
   const tmp = `${target}.tmp-${process.pid}`;
-  writeFileSync(tmp, data);
-  renameSync(tmp, target);
+  try {
+    writeFileSync(tmp, data);
+    renameSync(tmp, target);
+  } catch (e) {
+    try { unlinkSync(tmp); } catch { /* nothing written, or already gone */ }
+    throw e;
+  }
 }

package/lib/cite-back-hint.mjs

@@ -11,7 +11,7 @@
 // Cooldown schema (post-v2.81): { "<path>": { ts: <number>, lessonIds: [#NN, ...] } }
 // Legacy schema   (pre-v2.81):  { "<path>": <number> } — tolerated, never emits.
 
-import { basename, join } from 'path';
+import { basename } from 'path';
 import { readFileSync } from 'fs';
 import { readTranscriptEntries } from './transcript-scan.mjs';
 import { EDIT_TOOLS } from '../utils.mjs';
@@ -22,6 +22,7 @@ import { EDIT_TOOLS } from '../utils.mjs';
 // in the ordinary case: it is whatever the repository being worked on happens to contain.
 import { neutralizeContextDelimiters } from '../format-utils.mjs';
 import { cooldownPathFor as sharedCooldownPathFor } from './cooldown-path.mjs';
+import { citeRecallPathFor } from './cite-recall-path.mjs';
 // One caliber for `#NN`. citation-tracker.mjs does NOT import this module, so the edge
 // is acyclic.
 import { citationIdRe } from './citation-tracker.mjs';
@@ -230,8 +231,7 @@ export function nextCiteLowStreak(priorStreak, stats, env = process.env) {
 export function buildCiteRecallNudge(project, runtimeDir, env = process.env) {
   if (env.CLAUDE_MEM_NO_CITE_NUDGE === '1') return '';
   try {
-    const safe = project.replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
-    const path = join(runtimeDir, `cite-recall-${safe}.json`);
+    const path = citeRecallPathFor(runtimeDir, project);
     const raw = readFileSync(path, 'utf8');
     const data = JSON.parse(raw);
     const silenceAfter = env.CLAUDE_MEM_CITE_NUDGE_SILENCE_AFTER !== undefined

package/lib/cite-recall-path.mjs

@@ -0,0 +1,52 @@
+// lib/cite-recall-path.mjs — the ONE definition of the cite-recall snapshot file's path.
+//
+// Same shape, same failure mode and same fix as lib/cooldown-path.mjs (audit 2026-08-29
+// ARCH-2). `handleStop` writes `runtime/cite-recall-<project>.json` and
+// `buildCiteRecallNudge` reads it back, and each derived the name itself:
+//
+//   hook.mjs:1163            join(RUNTIME_DIR, `cite-recall-${project.replace(…).slice(0,64)}.json`)
+//   lib/cite-back-hint.mjs   const safe = project.replace(…).slice(0,64); join(runtimeDir, `cite-recall-${safe}.json`)
+//
+// A writer and a reader disagreeing about a filename does not throw — the reader opens a
+// file nobody wrote, `readFileSync` misses, the catch swallows it, and the SessionStart
+// nudge is silently gone. That is the whole reason this class keeps getting collapsed:
+// nothing in the system reports it, so the only defence is that the rule has one home.
+// This is the third instance found (cooldown, injected-ids, cite-recall); the sanitize
+// literal is deliberately NOT shared across the three, because they key on different
+// things (session id vs project) and a single "sanitize" helper would invite exactly the
+// cross-family coupling that makes one of them impossible to change later.
+//
+// `hook-shared.mjs`'s marker-GC list is the third consumer: it matches this family by
+// prefix, so the prefix is exported rather than re-typed there.
+
+import { join } from 'path';
+
+/** Filename prefix. Exported so the marker GC can match the family without re-deriving it. */
+export const CITE_RECALL_FILE_PREFIX = 'cite-recall-';
+
+/**
+ * Project name → filesystem-safe key. The 64-char cap and the character class are part of
+ * the contract, not defensive hygiene: writer and reader must derive the same name from the
+ * same project, so a change here is a change to both at once.
+ *
+ * Note the cap differs from `project-utils.mjs:sanitizeProject` (100) — these are different
+ * keys for different files, and silently unifying them would rename every existing snapshot
+ * on upgrade, i.e. drop one nudge per project. Kept separate on purpose.
+ *
+ * @param {unknown} project
+ * @returns {string}
+ */
+export function citeRecallProjectKey(project) {
+  return String(project).replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 64);
+}
+
+/**
+ * Absolute path to a project's cite-recall snapshot.
+ *
+ * @param {string} runtimeDir Absolute RUNTIME_DIR.
+ * @param {unknown} project   Project name as `inferProject` returns it.
+ * @returns {string}
+ */
+export function citeRecallPathFor(runtimeDir, project) {
+  return join(runtimeDir, `${CITE_RECALL_FILE_PREFIX}${citeRecallProjectKey(project)}.json`);
+}

package/lib/compress-core.mjs

@@ -17,9 +17,9 @@
 // smart-compress path already wrote vectors, so the deterministic path was the
 // sole gap (audit P6).
 
-import { isoWeekKey, COMPRESSED_AUTO, debugCatch } from '../utils.mjs';
-import { getVocabulary, computeVector } from '../tfidf.mjs';
+import { isoWeekKey, COMPRESSED_AUTO } from '../utils.mjs';
 import { scrubRecord } from './scrub-record.mjs';
+import { upsertObservationVector } from './observation-write.mjs';
 
 /**
  * Low-value compression candidates: importance<=1, never accessed, older than
@@ -44,6 +44,13 @@ export function selectCompressionCandidates(db, { cutoff, project = null, includ
       -- weekly summary discards the lesson (the distilled value of a lessons store).
       -- Mirrors the hook auto-compress lesson guard so neither path buries a lesson.
       AND (lesson_learned IS NULL OR lesson_learned = '' OR lesson_learned = 'none')
+      -- Tombstones stay out (audit 2026-09-02 P0-3). A superseded row keeps
+      -- compressed_into NULL, so compressedFilter alone admitted retracted content into a
+      -- weekly summary — and the summary is a LIVE importance-2 row, so the retraction is
+      -- undone by the compression. Spelled out rather than reusing liveObsFilterSql because
+      -- the compressed_into half is deliberately looser here (includeAutoMarked folds in
+      -- COMPRESSED_AUTO rows for re-summarization).
+      AND superseded_at IS NULL
       AND created_at_epoch < ?
       ${compressedFilter}
       ${projectFilter}
@@ -105,21 +112,30 @@ export function compressGroup(db, proj, obs) {
   // with save-observation.mjs and the LLM smart-compress path). Best-effort:
   // vocab may be uninitialized on a fresh DB — a failure here must not abort the
   // compression the caller is transacting.
-  try {
-    const vocab = getVocabulary(db);
-    if (vocab) {
-      const vec = computeVector(`${safe.title} ${safe.narrative}`, vocab);
-      if (vec) {
-        db.prepare(
-          'INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)'
-        ).run(summaryId, Buffer.from(vec.buffer), vocab.version, medianEpoch);
-      }
-    }
-  } catch (e) { debugCatch(e, 'compress-vector'); }
+  // SQL + text derivation are lib/observation-write.mjs's (audit 2026-09-02 P1-4).
+  // `at: medianEpoch` is this site's one real difference: the summary is stamped with the
+  // median date of the rows it compresses, not with now. `gate: false` preserves the prior
+  // behaviour, which never consulted vectorsEnabled().
+  upsertObservationVector(db, summaryId, `${safe.title} ${safe.narrative}`, {
+    gate: false, at: medianEpoch, scope: 'compress-vector',
+  });
 
   const obsIds = obs.map((o) => o.id);
   const obsPh = obsIds.map(() => '?').join(',');
-  db.prepare(`UPDATE observations SET compressed_into = ? WHERE id IN (${obsPh})`).run(summaryId, ...obsIds);
+  // Re-assert the candidate predicate at write time (audit 2026-09-02 P0-3): the hook path
+  // transacts per group, so a row can be superseded or absorbed by another summary between
+  // selection and here, and re-pointing it would drop it out of that summary's child set.
+  // Deliberately NOT liveObsFilterSql: COMPRESSED_AUTO rows are legitimate inputs
+  // (includeAutoMarked), so only the superseded half plus "no positive keeper yet" applies.
+  const compressed = db.prepare(`
+    UPDATE observations SET compressed_into = ?
+    WHERE id IN (${obsPh})
+      AND superseded_at IS NULL
+      AND (compressed_into IS NULL OR compressed_into = ${COMPRESSED_AUTO})
+  `).run(summaryId, ...obsIds).changes;
 
-  return { summaryId, compressed: obs.length };
+  // `changes`, not obs.length: with the guard above those differ exactly when a row lost
+  // eligibility between selection and write, and reporting the intended count would make
+  // the guard invisible in every caller's totals.
+  return { summaryId, compressed };
 }

package/lib/frontmatter.mjs

@@ -0,0 +1,67 @@
+// lib/frontmatter.mjs — the ONE YAML-frontmatter parser for skill/agent markdown.
+//
+// Audit 2026-09-02 P1-16. There were three, and they were not all the same:
+//
+//   registry-importer.mjs      the shipped one, full
+//   scripts/index-managed.mjs  byte-identical to it apart from the `export` keyword —
+//                              30 lines, the largest duplicate block in the tree
+//   scripts/convert-commands.mjs  a SIMPLIFIED cut with no `|` / `>` block support and no
+//                              JSON-array handling, i.e. already diverged
+//
+// The divergence is the part that matters: `description:` in a Claude Code SKILL.md is
+// routinely a `|` block, and the simplified parser returned the literal `|` for it. Two
+// scripts reading the same files with different parsers produce different registry rows
+// depending on which one last ran.
+//
+// Zero dependencies on purpose — it is imported by a shipped module (registry-importer)
+// and by two dev scripts, so it must not drag anything into either.
+
+/**
+ * Split `---`-delimited YAML frontmatter from a markdown body.
+ *
+ * Not a YAML parser, and deliberately so: it handles the subset Claude Code skill and
+ * agent files actually use — scalars, quoted scalars, JSON-ish arrays, and `|` / `>`
+ * blocks — and leaves anything else as the raw string rather than guessing.
+ *
+ * The `description` special case is load-bearing rather than defensive: a description
+ * written as a plain scalar is very often CONTINUED on the following indented lines
+ * without a block marker, and dropping the continuation silently truncates the one field
+ * the recommendation gate reads.
+ *
+ * @param {string} content full file text
+ * @returns {{frontmatter: Record<string, unknown>, body: string}}
+ */
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const raw = match[1];
+  const body = content.slice(match[0].length).trim();
+  const fm = {};
+  let currentKey = null, currentValue = '', inMultiline = false;
+
+  for (const line of raw.split('\n')) {
+    if (inMultiline && (line.startsWith('  ') || line.startsWith('\t') || line.trim() === '')) {
+      currentValue += ' ' + line.trim();
+      continue;
+    }
+    if (inMultiline && currentKey) { fm[currentKey] = currentValue.trim(); inMultiline = false; }
+
+    const kv = line.match(/^(\w[\w-]*)\s*:\s*(.*)/);
+    if (kv) {
+      currentKey = kv[1];
+      let val = kv[2].trim();
+      if (val === '|' || val === '>') { inMultiline = true; currentValue = ''; continue; }
+      if (val.startsWith('[') && val.endsWith(']')) {
+        try { fm[currentKey] = JSON.parse(val); } catch { fm[currentKey] = val; }
+        continue;
+      }
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))
+        val = val.slice(1, -1);
+      if (currentKey === 'description' && val) { inMultiline = true; currentValue = val; continue; }
+      fm[currentKey] = val;
+    }
+  }
+  if (inMultiline && currentKey) fm[currentKey] = currentValue.trim();
+  return { frontmatter: fm, body };
+}

package/lib/injected-ids.mjs

@@ -1,7 +1,11 @@
-// lib/injected-ids.mjs — file-name derivation for the cross-hook injected-ids
-// dedup marker. Single source of truth for user-prompt-search.js (writer),
-// pre-tool-recall.js (read/merge), and hook.mjs (path-A reader): all three must
-// derive the same name or cross-hook dedup silently goes blind.
+// lib/injected-ids.mjs — the cross-hook injected-ids dedup marker: file name, freshness +
+// same-session gate, and payload shape. Single source of truth for user-prompt-search.js
+// (writer), pre-tool-recall.js (read/merge), and hook.mjs (path-A reader): all three must
+// derive the same name AND agree on when a payload counts, or cross-hook dedup silently
+// goes blind — it does not error, it reads a marker nobody wrote.
+//
+// Scope widened 2026-09-03 (audit P1-2): this module used to own only the FILE NAME while
+// the gate and the write were hand-typed in five places across three files.
 //
 // D#120: M-6 session-keyed the marker's PAYLOAD but kept ONE file per project,
 // so two concurrent CC windows full-replaced each other's marker — no dedup
@@ -14,6 +18,9 @@
 // colliding with the scripts/ directory rename in installExtractedRelease —
 // same constraint as lib/mem-override.mjs.
 
+import { readFileSync } from 'node:fs';
+import { atomicWriteFileSync } from './atomic-write.mjs';
+
 /**
  * Runtime-dir FILE NAME for the injected-ids marker (no directory component).
  * No sessionId → legacy project-keyed name (env-less harnesses, old callers).
@@ -28,6 +35,88 @@ export function injectedIdsFileName(project, sessionId) {
   return `${base}-${safe}`;
 }
 
+/**
+ * Read a marker file, applying the freshness + same-session gate.
+ *
+ * That gate had THREE byte-identical hand-typed copies (audit 2026-09-02 P1-2):
+ * `hook.mjs handleUserPrompt`, `readCrossHookInjected` and `mergeCrossHookInjected` in
+ * scripts/pre-tool-recall.js, and both legs of scripts/user-prompt-search.js — five sites
+ * spelling out the same `ts && Date.now() - ts < W && !(session && mine && session !== mine)`.
+ * The lib had collapsed only the FILE NAME. Every new writer added a sixth copy, and a
+ * writer/reader disagreement here does not error: it reads a marker nobody wrote.
+ *
+ * THE WINDOW STAYS A PARAMETER, because the callers genuinely disagree and that
+ * disagreement is a live open question, not an accident to be tidied away: the two writers
+ * use DEDUP_STALE_MS (5 min) and the hook.mjs reader uses 10 s. Hard-coding either one here
+ * would silently decide it. Legacy payloads with no `session` keep the old
+ * window-only behaviour, as before.
+ *
+ * IDS COME BACK EXACTLY AS WRITTEN — no Number(), no String(). The marker holds a mix of
+ * raw numbers and strings and the consumers test `Set.has()` against numbers from SQLite,
+ * so coercing here would turn an inert exclude live. That is D#213/D#216's decision to
+ * make, on its ruler (lib/patha-exclude-meter.mjs), not a drive-by of this consolidation.
+ *
+ * @param {string} file Absolute path to the marker.
+ * @param {object} opts
+ * @param {string} [opts.sessionId] CC session id; a payload from another session is rejected.
+ * @param {number} opts.maxAgeMs Freshness window.
+ * @returns {{ids: Array<number|string>, count: number, fresh: boolean}} `fresh:false` ⇒ ids [] and count 0.
+ *
+ * ONE deliberate non-identity in the consolidation, stated rather than glossed: the copies
+ * disagreed at the boundary by 1 ms. pre-tool-recall used `age > W` (stale only when
+ * strictly greater), hook.mjs used `age < W` (fresh only when strictly less), so a payload
+ * exactly W old was fresh to one and stale to the other. This adopts the former for all
+ * callers. Nothing selects on a 1 ms boundary, but "identical behaviour" would have been
+ * false and the next person to diff the two would have had to rediscover why.
+ */
+export function readInjectedMarker(file, { sessionId, maxAgeMs } = {}) {
+  const empty = { ids: [], count: 0, fresh: false };
+  try {
+    const { ids, ts, count, session } = JSON.parse(readFileSync(file, 'utf8'));
+    if (session && sessionId && session !== sessionId) return empty;
+    if (!ts || Date.now() - ts > maxAgeMs) return empty;
+    if (!Array.isArray(ids)) return empty;
+    return { ids, count: count || 0, fresh: true };
+  } catch { return empty; }
+}
+
+/**
+ * Write `newIds` into a marker, unioning with a fresh same-session payload or replacing it.
+ *
+ * `mode` is not a convenience — the two modes have different id-typing behaviour and BOTH
+ * are load-bearing:
+ *   - `union`   stringifies the whole result. Both union callers already did
+ *               (`prev.ids.map(String)` plus new ids that are `D<id>` strings anyway), so
+ *               this is their behaviour, not a new normalisation.
+ *   - `replace` writes `newIds` verbatim. The UPS main leg passes `candidateIds`, a MIX of
+ *               raw observation numbers and `P<id>` strings, and writing those unchanged is
+ *               exactly the state D#213 measures. Stringifying here would change it.
+ * Keeping both under one function is the point: the next writer picks a mode instead of
+ * copying a fifth predicate and inventing a fifth typing rule.
+ *
+ * The write is atomic for the reason M-6 recorded: a plain write torn by a concurrent hook
+ * left the shared marker as invalid JSON, silently disabling cross-hook dedup for the window.
+ *
+ * @param {string} file
+ * @param {Array<number|string>} newIds
+ * @param {object} opts
+ * @param {string} [opts.sessionId]
+ * @param {number} opts.maxAgeMs
+ * @param {'union'|'replace'} opts.mode
+ */
+export function mergeInjectedMarker(file, newIds, { sessionId, maxAgeMs, mode } = {}) {
+  const prev = readInjectedMarker(file, { sessionId, maxAgeMs });
+  const ids = mode === 'union'
+    ? [...new Set([...prev.ids.map(String), ...newIds.map(String)])]
+    : newIds;
+  atomicWriteFileSync(file, JSON.stringify({
+    ids,
+    ts: Date.now(),
+    count: prev.count + 1,
+    ...(sessionId ? { session: sessionId } : {}),
+  }));
+}
+
 /**
  * Namespace prefix for an id written into the shared injected-ids marker.
  *