claude-mem-lite 3.91.0 → 3.93.0

package/hook.mjs

@@ -33,6 +33,8 @@ import {
 // backward-compat surface that knip already lists as unused; new shared symbols go to
 // their canonical module.
 import { inferProjectDir } from './project-utils.mjs';
+import { isPluginExplicitlyDisabled } from './lib/plugin-key.mjs';
+import { readHookStdin } from './lib/hook-stdin.mjs';
 // Aliased: `acquireLock` from hook-episode.mjs below is the episode buffer's own
 // (argument-less) lock — a different mutex with a different staleness policy.
 import { acquireLock as acquireProcLock } from './lib/proc-lock.mjs';
@@ -42,11 +44,13 @@ import {
   createEpisode, addFileToEpisode, planEpisodeFlush,
   writePendingEntry, mergePendingEntries, episodeHasSignificantContent, explainSignificance,
 } from './hook-episode.mjs';
+import { DB_DIR } from './schema.mjs';
 import { cleanupClaudeMdLegacyBlock, buildSessionContextLines } from './hook-context.mjs';
 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 +84,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 +104,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';
 
@@ -128,18 +152,22 @@ const BG_EVENTS = new Set(['llm-episode', 'llm-summary', 'auto-compress', 'llm-o
 // Respect Claude Code plugin disable state even when legacy settings.json hooks remain.
 // install.mjs writes direct hooks into ~/.claude/settings.json, so disabling the plugin
 // in Claude UI does not automatically remove them. Exit early to make disable actually work.
-const PLUGIN_KEY = 'claude-mem-lite@sdsrss';
-function isPluginExplicitlyDisabled() {
+// The KEY and the predicate live in lib/plugin-key.mjs (P2-7) — install.mjs branches on the
+// same decision, and a key that drifts on one side leaves the user with a plugin they
+// switched off and a settings.json hook set that never noticed. Reading the file stays here:
+// install.mjs already holds a parsed settings object when it asks, this process does not.
+function pluginDisabledHere() {
   try {
     const settingsPath = join(homedir(), '.claude', 'settings.json');
-    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
-    return settings.enabledPlugins?.[PLUGIN_KEY] === false;
+    return isPluginExplicitlyDisabled(JSON.parse(readFileSync(settingsPath, 'utf8')));
   } catch {
+    // Missing or unparseable settings.json → not disabled. Fail OPEN: a corrupt file must
+    // not switch the plugin off for a user who never asked for that.
     return false;
   }
 }
 
-if (event && isPluginExplicitlyDisabled()) process.exit(0);
+if (event && pluginDisabledHere()) process.exit(0);
 if (process.env.CLAUDE_MEM_HOOK_RUNNING && !BG_EVENTS.has(event)) process.exit(0);
 
 // Crash-safe: flush episode buffer on unexpected termination to prevent data loss
@@ -374,7 +402,7 @@ function flushEpisodeWithDb(db, episode, hookEventName) {
   // and with the flag on that case is strictly better than before, because the reads file
   // was never touched and the retry still finds it.
   // Off unless CLAUDE_MEM_METRICS=1, like every other row in this sink.
-  recordMetric(join(RUNTIME_DIR, '..'), {
+  recordMetric(DB_DIR, {
     event: 'episode_reads',
     readsConsumed: (episode.filesRead || []).length,
     readsHeld,
@@ -438,7 +466,7 @@ function flushEpisodeGroup(ep, db) {
   // episodes are kept ONLY because of their Greps — and demoting what the product
   // remembers on a deduction is how work disappears silently. This is that counter.
   // Off unless CLAUDE_MEM_METRICS=1, like every other row in this sink.
-  recordMetric(join(RUNTIME_DIR, '..'), {
+  recordMetric(DB_DIR, {
     event: 'episode_significance',
     rule: verdict.rule,
     significant: isSignificant,
@@ -523,7 +551,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);
@@ -656,7 +689,7 @@ function triggerErrorRecall(db, toolInput, response, opts = {}) {
       // G13: this surface feeds the citation denominator but had zero metering —
       // the G8 gate change (isError→isHardError) could not be volume-verified
       // from metrics. Counter only; no latency (query is bundled in the hook).
-      recordMetric(join(RUNTIME_DIR, '..'), { event: metricEvent, returned: rows.length });
+      recordMetric(DB_DIR, { event: metricEvent, returned: rows.length });
       // MED-3 (full audit 2026-07-16): go through the envelope, NOT raw stdout —
       // a raw multi-line write corrupts a co-emitted episode-flush receipt.
       // The follow-up correction (2026-08-17): "two separate JSON lines each parse
@@ -1160,7 +1193,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;
@@ -1459,7 +1492,13 @@ function runSessionStartAutoMaintain(db, project) {
       // Auto-dedup (fuzzy): catches near-identical titles that exact-match
       // misses across larger time windows — e.g. episode-batch titles like
       // "Modified A.mjs, B.mjs" vs "Modified B.mjs, A.mjs" written days apart.
-      // MinHash pre-filter (≥0.7) cuts the O(N²) scan; Jaccard ≥0.95 stays
+      // MinHash pre-filter (≥0.7) makes each PAIR cheap; it does not reduce the number of
+      // pairs. Said precisely because the comment here used to read "cuts the O(N²) scan",
+      // which is false and reads as an algorithmic bound (audit 2026-09-02 P2-13): the
+      // estimate is evaluated INSIDE the inner loop of a full nested scan in
+      // `lib/maintain-core.mjs`, so every pair is still visited — what it skips is the
+      // expensive exact Jaccard behind it. Measured, the whole pair pass is ~0.6 ms at
+      // n=500. Jaccard ≥0.95 stays
       // well clear of legit "two updates same area" pairs (those typically
       // score 0.7–0.85, surfaced via `maintain scan` for manual review).
       // Bounded by ${SCAN_LIMIT} recent rows × ${FUZZY_MAX_MERGES}-merge cap.
@@ -1526,8 +1565,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,10 +1847,10 @@ 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 */ }
-  // Same for the opt-in metrics sink (RUNTIME_DIR's parent is DB_DIR). Runs even when
+  try { const { gcOldShadowShards } = await import('./registry-recommend.mjs'); gcOldShadowShards(); } catch { /* best-effort, never blocks SessionStart */ }
+  // Same for the opt-in metrics sink, which lives under 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 */ }
+  try { gcOldMetricShards(DB_DIR); } catch { /* best-effort */ }
 
   // Plugin cache self-heal: Claude Code auto-updates the marketplace plugin can
   // re-populate cache/<ver>/hooks/hooks.json, reintroducing duplicate hook
@@ -1842,6 +1891,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 +1915,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 +2017,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 +2067,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,
@@ -2156,8 +2226,11 @@ async function handleUserPrompt() {
       // (inject, maybe duplicate) rather than fail closed (suppress).
       const keyContextIds = [];
       try {
-        const raw = readFileSync(join(RUNTIME_DIR, keyContextIdsFileName(project, ccSessionId)), 'utf8');
-        const { ids, session } = JSON.parse(raw);
+        // `keyCtxRaw`, not `raw`: this function already binds `raw` to the stdin payload
+        // ~120 lines up, and a second `raw` holding a marker FILE's contents reads as that
+        // one (audit 2026-09-02 P2-17 — the one hit in the tree worth a rename).
+        const keyCtxRaw = readFileSync(join(RUNTIME_DIR, keyContextIdsFileName(project, ccSessionId)), 'utf8');
+        const { ids, session } = JSON.parse(keyCtxRaw);
         if (Array.isArray(ids) && !(session && ccSessionId && session !== ccSessionId)) {
           keyContextIds.push(...ids);
         }
@@ -2175,13 +2248,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 +2334,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;
@@ -2333,7 +2418,7 @@ async function handleUserPrompt() {
       // counterfactual search and the second lesson selection off a stock install.
       try {
         if (meterCoerced) {
-          recordPathAExclude(join(RUNTIME_DIR, '..'), {
+          recordPathAExclude(DB_DIR, {
             markerIds: pathAInjectedIds,
             emitted: memories,
             after: meterArmB,
@@ -2368,14 +2453,14 @@ async function handleEnrichSave(rawId) {
     // work" was invisible (32% alias coverage with 3 indistinguishable failure
     // causes). reason 'filled-concurrently' = txn ran but a concurrent optimize/
     // update had already filled every empty field.
-    recordMetric(join(RUNTIME_DIR, '..'), {
+    recordMetric(DB_DIR, {
       event: 'enrich_save',
       id,
       enriched: result.enriched,
       reason: result.reason ?? (result.enriched ? 'enriched' : 'filled-concurrently'),
     });
   } catch (e) {
-    recordMetric(join(RUNTIME_DIR, '..'), { event: 'enrich_save', id, enriched: false, reason: 'worker-error' });
+    recordMetric(DB_DIR, { event: 'enrich_save', id, enriched: false, reason: 'worker-error' });
     debugCatch(e, 'enrich-save');
   } finally {
     try { db.close(); } catch {}
@@ -2418,22 +2503,20 @@ function handleAutoCompress() {
 
 // ─── Utilities ──────────────────────────────────────────────────────────────
 
+// P1-9: the mechanism is shared (lib/hook-stdin.mjs); the CALIBER stays this entry point's
+// own. 256 KB because a tool response is the largest payload the host sends here, and
+// `rejectOnTimeout` because this reader's callers treat a timeout as "drop the event" — the
+// alternative, acting on a partial payload, means writing a truncated tool response into
+// memory as if it were the whole thing. The other four hook processes are advisory and
+// resolve instead; those are different decisions about different payloads, not drift.
 function readStdin() {
-  const MAX_STDIN = MAX_HOOK_STDIN_BYTES; // large tool responses are truncated (shared tier, utils.mjs)
-  return new Promise((resolve, reject) => {
-    let data = '';
-    const timeout = setTimeout(() => { debugLog('WARN', 'readStdin', 'stdin timeout after 3s — event dropped'); process.stdin.destroy(); reject(new Error('timeout')); }, 3000);
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', chunk => {
-      data += chunk;
-      if (data.length > MAX_STDIN) {
-        process.stdin.destroy(); clearTimeout(timeout);
-        resolve({ text: data.slice(0, MAX_STDIN), truncated: true });
-      }
-    });
-    process.stdin.on('end', () => { clearTimeout(timeout); resolve({ text: data, truncated: false }); });
-    process.stdin.on('error', err => { clearTimeout(timeout); reject(err); });
-    process.stdin.resume();
+  return readHookStdin({
+    timeoutMs: 3000,
+    maxBytes: MAX_HOOK_STDIN_BYTES, // shared tier, utils.mjs
+    rejectOnTimeout: true,
+  }).catch((err) => {
+    if (err?.message === 'timeout') debugLog('WARN', 'readStdin', 'stdin timeout after 3s — event dropped');
+    throw err;
   });
 }
 
@@ -2493,7 +2576,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 +2590,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

@@ -7,7 +7,7 @@ import { join, resolve, dirname, isAbsolute, basename } from 'path';
 import { homedir, tmpdir } from 'os';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { createRequire } from 'node:module';
-import { resolveDataDir } from './lib/resolve-data-dir.mjs';
+import { resolveDataDir, resolveRuntimeDir } from './lib/resolve-data-dir.mjs';
 
 const PROJECT_DIR = resolve(import.meta.dirname ?? dirname(fileURLToPath(import.meta.url)));
 const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
@@ -22,6 +22,11 @@ const DATA_DIR = join(homedir(), '.claude-mem-lite');
 // the relocated dir → preinstalled skills silently vanished, doctor read the wrong
 // DB). Equals DATA_DIR when CLAUDE_MEM_DIR is unset (the common case).
 const MEM_DATA_DIR = resolveDataDir(process.env.CLAUDE_MEM_DIR);
+// Hook-WRITTEN runtime state (breakage markers, ep-flush/pending buffers) lives here.
+// Installation-identity state — install.lock, update-state.json, update residue — stays
+// under MEM_DATA_DIR on purpose: those are about the one real installation, and moving
+// them with a per-harness override would let two concurrent installs take separate locks.
+const MEM_RUNTIME_DIR = resolveRuntimeDir(MEM_DATA_DIR);
 const DB_PATH = join(MEM_DATA_DIR, 'claude-mem-lite.db');
 const OLD_DATA_DIR = join(homedir(), '.claude-mem');
 
@@ -33,8 +38,9 @@ const IS_NPX = process.env.npm_command === 'exec' ||
 const INSTALL_DIR = DATA_DIR;
 const SERVER_PATH = join(INSTALL_DIR, 'server.mjs');
 const HOOK_PATH = join(INSTALL_DIR, 'hook.mjs');
-const MARKETPLACE_KEY = 'sdsrss';
-const PLUGIN_KEY = `claude-mem-lite@${MARKETPLACE_KEY}`;
+// P2-7: both constants and the predicate come from lib/plugin-key.mjs, which hook.mjs also
+// imports — this pair used to be typed out in each.
+import { MARKETPLACE_KEY, PLUGIN_KEY, isPluginExplicitlyDisabled } from './lib/plugin-key.mjs';
 const NPM_INSTALL_CMD = 'npm install --omit=dev --no-audit --no-fund';
 
 import { RESOURCE_METADATA } from './install-metadata.mjs';
@@ -614,7 +620,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 +663,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: {}
@@ -1609,7 +1622,7 @@ async function doctor() {
   // broken install to exit 0 so it never spams a Node stack trace on every hook
   // fire. That silence is intentional but hides failure — it drops a breakage
   // marker so this check can surface the otherwise-invisible degraded state.
-  const brokenMarker = join(MEM_DATA_DIR, 'runtime', 'hook-launcher-broken');
+  const brokenMarker = join(MEM_RUNTIME_DIR, 'hook-launcher-broken');
   if (existsSync(brokenMarker)) {
     let detail = '';
     try {
@@ -1627,7 +1640,7 @@ async function doctor() {
   // is 6h-rate-limited stderr nobody reads), the live probe says "is it broken
   // right now". A Node upgrade breaks every DB-touching path at once, so this is
   // the single highest-value line in doctor when it fires.
-  const breakage = readNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
+  const breakage = readNativeBindingBreakage(MEM_RUNTIME_DIR);
   // Reuses the per-root probes above — same trees, same question, and doctor
   // should not pay for another round of child spawns to ask it twice.
   if (brokenRoots.length > 0) {
@@ -2203,9 +2216,7 @@ function cleanupMemHooksFromSettings(settings) {
   return removed;
 }
 
-function isPluginExplicitlyDisabled(settings) {
-  return settings?.enabledPlugins?.[PLUGIN_KEY] === false;
-}
+
 
 function getInstalledPluginEntries(installed) {
   if (installed?.plugins && typeof installed.plugins === 'object') return installed.plugins;
@@ -2266,8 +2277,8 @@ function cleanup() {
     }
   }
 
-  // Clean pending-* / ep-flush-* in runtime/ (under the env-aware data dir)
-  const runtimeDir = join(MEM_DATA_DIR, 'runtime');
+  // Clean pending-* / ep-flush-* in runtime/ (env-aware, and honouring the runtime override)
+  const runtimeDir = MEM_RUNTIME_DIR;
   if (existsSync(runtimeDir)) {
     for (const f of readdirSync(runtimeDir)) {
       if (f.startsWith('pending-') || f.startsWith('ep-flush-')) {
@@ -2585,7 +2596,7 @@ async function rebuildBinding() {
       process.exitCode = 1;
     } else {
       // Every tree is loadable → drop the marker so session-start stops retrying.
-      clearNativeBindingBreakage(join(MEM_DATA_DIR, 'runtime'));
+      clearNativeBindingBreakage(MEM_RUNTIME_DIR);
     }
   } finally {
     release();

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