claude-mem-lite 3.91.0 → 3.92.0

package/lib/maintain-core.mjs

@@ -18,6 +18,7 @@ import { DEDUP_JACCARD_THRESHOLD, MINHASH_PRE_THRESHOLD as MINHASH_PRE_THRESHOLD
 import { liveObsFilterSql } from './inject-search-core.mjs';
 
 import { DAY_MS } from './time-constants.mjs';
+import { snapshotDb } from './db-backup.mjs';
 export const STALE_AGE_MS = 30 * DAY_MS;
 export const OP_CAP = 1000;
 export const SCAN_LIMIT = 500;
@@ -494,8 +495,13 @@ export function mergeDuplicates(db, groups) {
     return cur; // an id with no outgoing redirect is a keeper
   };
 
-  const isLive = db.prepare('SELECT 1 FROM observations WHERE id = ? AND COALESCE(compressed_into, 0) = 0');
-  const mergeStmt = db.prepare('UPDATE observations SET compressed_into = ? WHERE id = ? AND COALESCE(compressed_into, 0) = 0');
+  // Liveness here is `liveObsFilterSql`, not compressed_into alone (audit 2026-09-02 P0-2):
+  // a superseded row keeps compressed_into=0, so the narrower predicate accepted a TOMBSTONE
+  // as a keeper and pointed a live row at it — the row then vanishes from every read face
+  // (all of which filter superseded_at) with no recovery path, because recoverOrphanedChildren
+  // only resurfaces children whose keeper row is GONE, and a tombstone still exists.
+  const isLive = db.prepare(`SELECT 1 FROM observations WHERE id = ? AND ${liveObsFilterSql('')}`);
+  const mergeStmt = db.prepare(`UPDATE observations SET compressed_into = ? WHERE id = ? AND ${liveObsFilterSql('')}`);
   let merged = 0;
   for (const removeId of redirect.keys()) {
     const keeper = resolveKeeper(removeId);
@@ -569,7 +575,12 @@ export function findDuplicates(db, { projectFilter, baseParams, limit = SCAN_LIM
   const recent = db.prepare(`
     SELECT id, title, project, importance, access_count, created_at_epoch
     FROM observations
-    WHERE COALESCE(compressed_into, 0) = 0 ${projectFilter}
+    -- liveObsFilterSql, not compressed_into alone (audit 2026-09-02 P0-2): this scan renders a
+    -- ready-to-paste "maintain execute --ops dedup --merge-ids A,B", and the keeper rule is
+    -- importance-based (mem-cli.mjs / server.mjs), so a superseded tombstone in the pair could
+    -- be nominated keeper. Same predicate the hook-side fuzzy dedup candidate query uses
+    -- (hook.mjs), and the same one mergeDuplicates now enforces at write time.
+    WHERE ${liveObsFilterSql('')} ${projectFilter}
     ORDER BY created_at_epoch DESC LIMIT ${limit}
   `).all(...baseParams);
 
@@ -652,8 +663,15 @@ export function rebuildVectors(db) {
   return { ok: true, terms: vocab.terms.size, updated, total: allObs.length };
 }
 
-/** VACUUM the whole DB, reporting freelist reclaim. Must run OUTSIDE any transaction. */
-export function vacuum(db) {
+/**
+ * VACUUM the whole DB, reporting freelist reclaim. Must run OUTSIDE any transaction.
+ *
+ * Module-private since P1-5: its only two consumers were mem-cli.mjs and server.mjs, and
+ * both now reach it through `runMaintainOps`. Exporting it again would add a name to the
+ * knip baseline for nobody (the v3.70.0 precedent, #9675) — export it the day something
+ * outside this module needs it.
+ */
+function vacuum(db) {
   const pageSize = db.pragma('page_size', { simple: true });
   const freeBefore = db.pragma('freelist_count', { simple: true });
   db.exec('VACUUM');
@@ -661,3 +679,171 @@ export function vacuum(db) {
   const reclaimedMB = ((Math.max(0, freeBefore - freeAfter) * pageSize) / 1048576).toFixed(1);
   return { reclaimedMB, freeBefore, freeAfter };
 }
+
+// ─── The `maintain execute` sequence, once ──────────────────────────────────
+//
+// Audit 2026-09-02 P1-5. Every OPERATION above was already shared; the SEQUENCE was
+// hand-copied into mem-cli.mjs and server.mjs, and had drifted three ways:
+//
+//   * `server.mjs` rendered the demote_pinned line with a hardcoded `inj>=8` while
+//     mem-cli.mjs interpolated PINNED_INJ_THRESHOLD — change the constant and the MCP
+//     surface reports a threshold the code no longer uses.
+//   * the cap hint was a named `capHint()` on one face and the same ternary inlined
+//     four times on the other.
+//   * the comment explaining WHY demote_pinned must physically follow boost (boostAccessed
+//     lifts any access_count>3 row under importance 3, so demoting first and boosting
+//     second hands the row straight back inside one run) existed only on the CLI, i.e.
+//     the face where it was already right.
+//
+// The order is the contract, so it lives here with its reason. What stays with the
+// surfaces is what genuinely differs: how a caller spells `merge_ids`, and what a purge
+// preview tells the user to type next. Those arrive as explicit parameters rather than
+// being re-implemented, which makes the differences reviewable in one place.
+
+/**
+ * Run the `maintain execute` operation sequence and return the report lines.
+ *
+ * Owns the snapshot, the transaction boundary and the three post-transaction ops, because
+ * all three are part of the ordering contract: the pre-transaction snapshot counts only
+ * PRE-EXISTING pending rows, so purge must run before decay or a row is marked and deleted
+ * in one call with the backup skipped (audit HIGH-1), and VACUUM cannot run inside a
+ * transaction at all.
+ *
+ * @param {object} db
+ * @param {object} ctx  { projectFilter, baseParams, staleAge, opCap }
+ * @param {string[]} ops
+ * @param {object} opts
+ * @param {number} [opts.retainDays=30]
+ * @param {number} opts.retainCutoff
+ * @param {boolean} [opts.confirmed=false]     purge_stale is the only DELETE; unconfirmed previews
+ * @param {Array<number[]>|null} [opts.mergeGroups]  parsed dedup groups, already validated
+ * @param {boolean} [opts.mergeIdsProvided]    true when the caller passed merge ids at all
+ * @param {string[]} [opts.invalidMergeSegments]  malformed segments to warn about (CLI only)
+ * @param {string} [opts.mergeIdsFlagName]     how this surface spells the flag, for the warning
+ * @param {Function} opts.renderPurgePreview   (previewRow, retainDays) => string
+ * @param {Function} [opts.onError]            (err, scope) => void, for the two catch arms
+ * @returns {string[]} report lines, in order
+ */
+export function runMaintainOps(db, ctx, ops, {
+  retainDays = 30,
+  retainCutoff,
+  confirmed = false,
+  mergeGroups = null,
+  mergeIdsProvided = false,
+  invalidMergeSegments = [],
+  mergeIdsFlagName = 'merge_ids',
+  renderPurgePreview,
+  onError = () => {},
+} = {}) {
+  const results = [];
+  const opCap = ctx.opCap ?? OP_CAP;
+  const capHint = (changes) => (changes >= opCap ? ' (cap reached, re-run for more)' : '');
+
+  // Snapshot before the irreversible hard deletes, and only when rows will actually be
+  // removed. OUTSIDE the transaction below — VACUUM cannot run inside one, and a snapshot
+  // taken inside would not see a consistent pre-state anyway. Best-effort; never throws.
+  const willPurge = ops.includes('purge_stale') && confirmed;
+  if (hardDeleteCandidateCount(db, ctx, { cleanup: ops.includes('cleanup'), purge: willPurge }) > 0) {
+    snapshotDb(db, { tag: 'pre-maintain' });
+  }
+
+  db.transaction(() => {
+    // PURGE FIRST — same order as handleAutoMaintain. Running decay before purge in one
+    // transaction marks a stale row pending-purge AND deletes it in the SAME call (zero
+    // grace), and the snapshot above counts only PRE-EXISTING pending rows, so it skips the
+    // backup: permanent, unrecoverable loss of notable imp-2/3 memories (audit HIGH-1).
+    // Purging first deletes only rows a PRIOR run marked — which the guard saw and backed
+    // up — and rows decay marks below wait for the next run, regaining the grace cycle.
+    if (ops.includes('purge_stale')) {
+      if (!confirmed) {
+        results.push(renderPurgePreview(purgeStalePreview(db, ctx, retainCutoff), retainDays));
+      } else {
+        const purged = purgeStale(db, ctx, retainCutoff);
+        results.push(`Purged ${purged} stale observations (retained last ${retainDays} days)${capHint(purged)}`);
+      }
+    }
+
+    if (ops.includes('cleanup')) {
+      const deleted = cleanupBroken(db, ctx);
+      results.push(`Cleaned up ${deleted} broken observations${capHint(deleted)}`);
+      // Self-heal legacy orphans (keeper hard-deleted pre-recoverChildrenOf): resurface
+      // unreachable children. Non-destructive — un-hide only, no delete.
+      const orphans = recoverOrphanedChildren(db, ctx);
+      if (orphans > 0) results.push(`Recovered ${orphans} orphaned compression children`);
+      // Heal lesson rows citation-decay buried at importance 0 (pre floor=1). 0→1 on
+      // lesson-bearing rows only; idempotent no-op once none remain.
+      const lessonsHealed = recoverBuriedLessons(db, ctx);
+      if (lessonsHealed > 0) results.push(`Healed ${lessonsHealed} lesson rows buried at importance 0`);
+      // Heal deferred_work rows whose closing obs / source prompt was hard-deleted while FK
+      // was OFF (dangling refs foreign_key_check flags). Applies the FK's ON DELETE SET NULL.
+      const deferredHealed = sweepDeferredWorkOrphans(db, ctx);
+      if (deferredHealed > 0) results.push(`Healed ${deferredHealed} deferred-work rows with dangling references`);
+    }
+
+    if (ops.includes('decay')) {
+      // injection_count>0 protected (decayAndMarkIdle) — an obs Claude was shown 8× is
+      // contextually proven. The MCP copy lacked this clause before the extraction.
+      const { decayed, idleMarked } = decayAndMarkIdle(db, ctx);
+      results.push(`Decayed ${decayed} stale observations, marked ${idleMarked} idle as pending-purge${capHint(Math.max(decayed, idleMarked))}`);
+    }
+
+    if (ops.includes('boost')) {
+      const boosted = boostAccessed(db, ctx);
+      results.push(`Boosted ${boosted} frequently-accessed observations${capHint(boosted)}`);
+    }
+
+    // AFTER boost, and the order is load-bearing in one direction only: boostAccessed lifts
+    // any access_count>3 row with importance<3, so demoting a pinned row to 1 and then
+    // boosting hands it straight back at 2 — the demotion silently undone inside a single
+    // run. DEFAULT_MAINTAIN_OPS pins the order; this block has to physically follow the
+    // boost block for that order to be real.
+    if (ops.includes('demote_pinned')) {
+      // Repairs the citation-decay blind spot: decay protects injection_count>0, so a
+      // heavily-injected-but-uncited memory stays pinned at max importance forever.
+      // Floor, not purge: no lesson_learned → 1, lesson-bearing → 2 (v3.76.1 dual floor).
+      const demoted = demotePinned(db, ctx);
+      results.push(`Demoted ${demoted} pinned-but-uncited observations (inj>=${PINNED_INJ_THRESHOLD}, cited=0; no lesson → importance 1, lesson → 2)${capHint(demoted)}`);
+    }
+
+    if (ops.includes('dedup') && mergeIdsProvided) {
+      const totalMerged = mergeDuplicates(db, mergeGroups || []);
+      if (invalidMergeSegments.length) {
+        results.push(`Warning: ignored ${invalidMergeSegments.length} malformed ${mergeIdsFlagName} segment(s): ${invalidMergeSegments.join(', ')} (expected keepId:removeId[:removeId...] with positive integers)`);
+      }
+      results.push(`Merged ${totalMerged} duplicate observations`);
+    }
+
+    if (!ops.includes('dedup') && mergeIdsProvided) {
+      results.push(`Warning: ${mergeIdsFlagName} provided but "dedup" not in operations — ${mergeIdsFlagName} ignored`);
+    }
+  })();
+
+  // FTS5 optimize — outside the transaction.
+  db.exec("INSERT INTO observations_fts(observations_fts) VALUES('optimize')");
+  results.push('FTS5 index optimized');
+
+  if (ops.includes('rebuild_vectors')) {
+    try {
+      const r = rebuildVectors(db);
+      results.push(r.ok
+        ? `Vectors: rebuilt vocabulary (${r.terms} terms), updated ${r.updated}/${r.total} vectors`
+        : `Vectors: ${r.reason}`);
+    } catch (e) {
+      onError(e, 'rebuild_vectors');
+      results.push(`Vectors: rebuild failed — ${e.message}`);
+    }
+  }
+
+  // VACUUM: reclaim freelist pages left by DELETEs. Whole-DB, outside any transaction.
+  if (ops.includes('vacuum')) {
+    try {
+      const v = vacuum(db);
+      results.push(`VACUUM: reclaimed ~${v.reclaimedMB}MB (freelist ${v.freeBefore} → ${v.freeAfter} pages)`);
+    } catch (e) {
+      onError(e, 'vacuum');
+      results.push(`VACUUM failed — ${e.message}`);
+    }
+  }
+
+  return results;
+}

package/lib/observation-write.mjs

@@ -8,7 +8,7 @@
 // Statement-only: callers own the transaction boundary (both wrap the row + files
 // + vector writes in one db.transaction so a failure can't leave a partial row).
 
-import { getVocabulary, computeVector, vectorsEnabled } from '../tfidf.mjs';
+import { getVocabulary, computeVector, vectorsEnabled, vecTextForRow } from '../tfidf.mjs';
 import { debugCatch, cjkBigrams, scrubSecrets } from '../utils.mjs';
 
 // Canonical column order — must mirror the observations schema (schema.mjs).
@@ -69,21 +69,79 @@ export function insertObservationFiles(db, obsId, files) {
   for (const f of files) if (typeof f === 'string' && f.length > 0) stmt.run(obsId, f);
 }
 
+// ─── The observation_vectors upsert, once ───────────────────────────────────
+//
+// Audit 2026-09-02 P1-4: this one statement shipped FIVE times — here, hook-optimize's
+// rebuildVector, hook-llm's enrich path, lib/compress-core's summary write and
+// maintain-core's bulk rebuild — and it had already drifted once: hook-optimize wrote the
+// column as `computed_at` instead of `created_at_epoch`, silently swallowed by its own
+// catch until an experiment surfaced it.
+//
+// Four of the five now come through `upsertObservationVector`. The fifth,
+// `maintain-core.rebuildVectors`, deliberately does NOT: it rebuilds the vocabulary
+// itself (so it must pass its own, not read the cache), reuses one prepared statement
+// across every live row, and lets a throw abort the whole rebuild rather than skipping a
+// row. Forcing it through a per-row best-effort helper would change all three. Its SQL is
+// the one remaining copy, and it is a copy on purpose.
+//
+// The `vectorsEnabled()` gate is a PARAMETER, not a decision made here, because the five
+// sites did not agree and this refactor preserves each one's behaviour rather than
+// picking a winner. Worth knowing before reading that as a live defect: `getVocabulary`
+// returns null whenever the arm is disabled, and every path guards on the vocab, so the
+// gate difference has no behavioural consequence today — it is a redundancy, not a hole.
+const VECTOR_UPSERT_SQL =
+  'INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)';
+
 /**
- * Best-effort TF-IDF vector write. Non-critical: vocab may be uninitialized on a
- * fresh DB, so failures are swallowed (caller's transaction must NOT roll back the
- * observation over a missing vector).
+ * The text a vector is computed from, for the three shapes callers hold.
+ *
+ * @param {string|string[]|object} textOrRow  a ready string, parts to join, or an
+ *   observations row (which goes through `vecTextForRow`, so a rebuild derives exactly
+ *   what the save path derived — a second concatenation here would be the next drift).
  */
-export function insertObservationVector(db, obsId, vecText) {
-  if (!vectorsEnabled()) return;  // Phase-1: vector arm disabled by default (audit 2026-06-27)
+function vectorTextFor(textOrRow) {
+  if (typeof textOrRow === 'string') return textOrRow;
+  // `filter(Boolean)` is inherited from rebuildVector and is INERT, measured: a null or
+  // empty entry joins to extra whitespace, which the tokenizer collapses, so the vector
+  // is byte-identical with or without it. Kept rather than deleted because it is
+  // defensive code that costs nothing — but do not write a test for it, because no
+  // mutation of it can fail one.
+  if (Array.isArray(textOrRow)) return textOrRow.filter(Boolean).join(' ');
+  return vecTextForRow(textOrRow);
+}
+
+/**
+ * Best-effort TF-IDF vector write. Non-critical: vocab may be uninitialized on a fresh DB,
+ * so failures are swallowed (the caller's transaction must NOT roll back an observation
+ * over a missing vector).
+ *
+ * @param {object} db
+ * @param {number} obsId
+ * @param {string|string[]|object} textOrRow
+ * @param {object} [opts]
+ * @param {boolean} [opts.gate=true]  apply `vectorsEnabled()` — see the note above on why
+ *                                    this is a parameter
+ * @param {object} [opts.vocab]       use this vocabulary instead of `getVocabulary(db)`
+ * @param {number} [opts.at]          created_at_epoch (compress-core stamps the summary's
+ *                                    median date, not now)
+ * @param {string} [opts.scope]       debugCatch scope, so a failure still names its caller
+ * @returns {boolean} whether a row was written
+ */
+export function upsertObservationVector(db, obsId, textOrRow, { gate = true, vocab = null, at = null, scope = 'upsertObservationVector' } = {}) {
+  if (gate && !vectorsEnabled()) return false;  // Phase-1: vector arm off by default (audit 2026-06-27)
   try {
-    const vocab = getVocabulary(db);
-    if (!vocab) return;
-    const vec = computeVector(vecText, vocab);
-    if (!vec) return;
-    db.prepare('INSERT OR REPLACE INTO observation_vectors (observation_id, vector, vocab_version, created_at_epoch) VALUES (?, ?, ?, ?)')
-      .run(obsId, Buffer.from(vec.buffer), vocab.version, Date.now());
-  } catch (e) { debugCatch(e, 'insertObservationVector'); }
+    const v = vocab ?? getVocabulary(db);
+    if (!v) return false;
+    const vec = computeVector(vectorTextFor(textOrRow), v);
+    if (!vec) return false;
+    db.prepare(VECTOR_UPSERT_SQL).run(obsId, Buffer.from(vec.buffer), v.version, at ?? Date.now());
+    return true;
+  } catch (e) { debugCatch(e, scope); return false; }
+}
+
+/** The save path's vector write. Thin wrapper — kept as a name because it has consumers. */
+export function insertObservationVector(db, obsId, vecText) {
+  upsertObservationVector(db, obsId, vecText, { scope: 'insertObservationVector' });
 }
 
 /**

package/lib/registry-core.mjs

@@ -1,4 +1,4 @@
-// Shared body for the registry write actions — import / remove / reindex.
+// Shared body for the registry write actions — import / remove / reindex / enrich.
 //
 // These were the last un-collapsed CLI/MCP twin (audit 2026-08-22 P1-3): mem-cli.mjs and
 // server.mjs each wrote their own SQL for the same three actions, and had already drifted —
@@ -11,7 +11,10 @@
 // format output or touch process state — rendering (and CLI-only concerns like bare-flag
 // rejection or the "add --capability-summary" tip) stays in the surface.
 
+import { readFileSync } from 'fs';
+
 import { upsertResource } from '../registry.mjs';
+import { isPathConfined } from '../utils.mjs';
 
 /**
  * String columns an import may set, in canonical snake_case. Single source: the CLI derives
@@ -92,3 +95,116 @@ export function reindexResources(db) {
   const row = db.prepare('SELECT COUNT(*) as c FROM resources WHERE status = ?').get('active');
   return { activeCount: row.c };
 }
+
+// ─── Enrichment (four legs, one gate) ───────────────────────────────────────
+//
+// `resources.local_path` is a filesystem path stored in a DB row, and every enrichment leg
+// ends in `readFileSync(local_path)`. Before audit 2026-09-02 P1-3 the confinement check
+// guarded exactly ONE of the four legs — the MCP `enrich` action — while the MCP
+// `import_url --enrich` leg, the CLI `enrich <name>` leg and the CLI `enrich --all` leg read
+// the path bare. That is this repo's first-listed 病类 in its narrowest form: not "CLI vs
+// MCP" but "one branch of one face". Counting the legs is what showed the MCP side was
+// itself half-guarded, so a CLI-only patch would have left the shape alive on both faces.
+//
+// Every leg now funnels through `enrichResourceRow`, so a new leg cannot be written without
+// passing `confineTo` — and omitting it is a visible `undefined`, not a silently absent `if`.
+
+/** Env var that disables the confinement gate (escape hatch for relocated managed dirs). */
+export const REGISTRY_CONFINE_ENV = 'CLAUDE_MEM_REGISTRY_CONFINE';
+
+/**
+ * Whether the confinement gate is active. Only `off` disables it — case-insensitively and
+ * ignoring surrounding whitespace, so `OFF` and ` off\n` also open the gate. Every OTHER
+ * value, including an unset one and every near-miss (`of`, `0`, `false`, `disable`), keeps
+ * the gate ON, because the failure mode of a typo must be "refuses a path it could have
+ * read", never "reads a path it should have refused". Said precisely because the first
+ * version of this sentence claimed "the exact string `off`" in three places, which is the
+ * wrong description of a `.trim().toLowerCase()` — the safety property held, the wording
+ * did not.
+ */
+export function registryConfineEnabled(env = process.env) {
+  return String(env[REGISTRY_CONFINE_ENV] ?? '').trim().toLowerCase() !== 'off';
+}
+
+/**
+ * Enrich one already-resolved resource row.
+ *
+ * @param {object} db                       open resource-registry.db handle
+ * @param {object} row                      must carry {name, type, local_path}
+ * @param {object} opts
+ * @param {string} opts.confineTo           base dir `local_path` must stay within
+ * @param {Function} opts.enrichResource    injected `(db,name,type,content) => Promise<boolean>`;
+ *                                          injected rather than imported so this module stays a
+ *                                          leaf and the Anthropic SDK stays off the CLI's
+ *                                          cold-start path (both faces already lazy-import it)
+ * @param {object} [opts.env]               env source for the escape hatch (tests pass their own)
+ * @returns {Promise<{status:'enriched'|'failed'|'no-path'|'denied'|'unreadable', error?:Error}>}
+ *          `error` is carried on 'unreadable' only: a stale local_path (the file was moved or
+ *          deleted after import) is the common case, and the errno is the whole diagnosis —
+ *          collapsing it into a bare status would make this refactor a diagnosability
+ *          regression on the one leg that already surfaced the message.
+ */
+export async function enrichResourceRow(db, row, { confineTo, enrichResource, env } = {}) {
+  // `confineTo` is REQUIRED, and a missing one throws rather than defaulting to "no gate".
+  // The defect this replaces was three call sites that simply had no `if` — invisible in
+  // review because absence has no syntax. A fifth leg written without the gate now fails
+  // loudly on its first call instead of shipping as a silent hole; the static sweep in
+  // tests/registry-enrich-confinement.test.mjs catches it earlier still.
+  if (!confineTo) throw new TypeError('enrichResourceRow: confineTo is required');
+  if (!row?.local_path) return { status: 'no-path' };
+  if (registryConfineEnabled(env) && !isPathConfined(row.local_path, confineTo)) {
+    return { status: 'denied' };
+  }
+  let content;
+  try {
+    content = readFileSync(row.local_path, 'utf8');
+  } catch (e) {
+    return { status: 'unreadable', error: e };
+  }
+  // Enrichment itself is an LLM round-trip; a throw here is a failed enrichment, not a
+  // refused read, and the two must stay distinguishable in the counts the surfaces render.
+  try {
+    return { status: (await enrichResource(db, row.name, row.type, content)) ? 'enriched' : 'failed' };
+  } catch (e) {
+    return { status: 'failed', error: e };
+  }
+}
+
+/**
+ * Enrich the rows an import just produced (MCP `import_url --enrich` + CLI `import --enrich`).
+ *
+ * `results` carries only {id, name, type}; local_path is read back per row because
+ * importFromGitHub writes it during the import.
+ *
+ * @returns {Promise<{ok:number, denied:number, total:number}>}
+ */
+export async function enrichImportedResources(db, results, { confineTo, enrichResource, env } = {}) {
+  // Checked here too, not only in the delegate: an empty `results` never reaches
+  // enrichResourceRow, so an ungated caller would otherwise pass on the empty input a test
+  // is most likely to use and throw only in production.
+  if (!confineTo) throw new TypeError('enrichImportedResources: confineTo is required');
+  let ok = 0, denied = 0;
+  for (const r of results) {
+    const row = db.prepare('SELECT name, type, local_path FROM resources WHERE id = ?').get(r.id);
+    const { status } = await enrichResourceRow(db, row, { confineTo, enrichResource, env });
+    if (status === 'enriched') ok++;
+    else if (status === 'denied') denied++;
+  }
+  return { ok, denied, total: results.length };
+}
+
+/**
+ * Resolve one active resource by name and enrich it (MCP `enrich` + CLI `enrich <name>`).
+ * @returns {Promise<{status:'not-found'|'enriched'|'failed'|'no-path'|'denied'|'unreadable', name:string, error?:Error}>}
+ */
+export async function enrichNamedResource(db, name, { confineTo, enrichResource, env } = {}) {
+  // Same reason as enrichImportedResources: the 'not-found' return short-circuits above the
+  // delegate, so the gate check cannot be left to it.
+  if (!confineTo) throw new TypeError('enrichNamedResource: confineTo is required');
+  const row = db
+    .prepare("SELECT name, type, local_path FROM resources WHERE name = ? AND status = 'active'")
+    .get(name);
+  if (!row) return { status: 'not-found', name };
+  const { status, error } = await enrichResourceRow(db, row, { confineTo, enrichResource, env });
+  return { status, name: row.name, error };
+}

package/lib/save-enrich.mjs

@@ -33,7 +33,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { scrubSecrets, cjkBigrams, truncate, debugCatch } from '../utils.mjs';
 import { scrubRecord } from './scrub-record.mjs';
-import { normalizeScope, SCOPE_PROMPT_LEGEND } from './observation-write.mjs';
+import { normalizeScope, SCOPE_PROMPT_LEGEND, upsertObservationVector } from './observation-write.mjs';
 
 export const ENRICH_OBLIGATED_TYPES = new Set(['bugfix', 'decision']);
 
@@ -170,13 +170,17 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
   }
 
   if (enriched) {
-    // Refresh the TF-IDF vector so backfilled lesson/aliases reach the vector
-    // arm too (single source: hook-optimize's rebuildVector; lazy import keeps
-    // the save surfaces from loading the optimize stack for the predicate).
+    // Refresh the TF-IDF vector so backfilled lesson/aliases reach the vector arm too.
+    //
+    // This used to `await import('../hook-optimize.mjs')` for its `rebuildVector` — the
+    // ONLY lib -> hook-layer edge in the tree, and a lazy one specifically so the save
+    // surfaces would not drag in a 1139-line optimize stack to write one row (audit
+    // 2026-09-02 P1-4). The function's body now lives in lib/observation-write.mjs, so the
+    // edge is gone and the import is static and cheap. `gate: false` matches what
+    // rebuildVector did.
     try {
-      const { rebuildVector } = await import('../hook-optimize.mjs');
       const full = db.prepare('SELECT * FROM observations WHERE id = ?').get(id);
-      if (full) rebuildVector(db, id, full);
+      if (full) upsertObservationVector(db, id, full, { gate: false, scope: 'save-enrich-vector' });
     } catch (e) { debugCatch(e, 'save-enrich-vector'); }
   }
   return { enriched };

package/lib/save-observation.mjs

@@ -14,6 +14,9 @@
 import { jaccardSimilarity, scrubSecrets, computeMinHash, cjkBigrams, getCurrentBranch } from '../utils.mjs';
 import { DEDUP_JACCARD_THRESHOLD } from './dedup-constants.mjs';
 import { insertObservationRow, insertObservationFiles, insertObservationVector } from './observation-write.mjs';
+// Imported, not injected: `allowStatuses` below is the POLICY this function exists to hold,
+// and a caller free to pass its own resolver could reinstate the one-way gate D#195 closed.
+import { resolveDeferredIds, closeDeferredItems } from './deferred-work.mjs';
 
 const DEDUP_WINDOW_MS = 5 * 60 * 1000;
 const DEDUP_RECENT_LIMIT = 50;
@@ -385,3 +388,44 @@ export function saveObservation(db, params) {
     supersedeSkipped: [...malformedSupersedes, ...skipped],
   };
 }
+
+/**
+ * Save one observation and, on a non-duplicate save, close the deferred items it closes —
+ * in ONE transaction.
+ *
+ * Audit 2026-09-02 P1-6. `server.mjs`'s mem_save and `mem-cli.mjs`'s cmdSave each wrote
+ * this transaction body out, and each carried a comment saying it was "kept in sync with"
+ * the other. Two things inside it are policy rather than plumbing, which is why a comment
+ * was never enough:
+ *
+ *   * the dedup SHORT-CIRCUIT must happen before the resolver, so replaying the same save
+ *     is idempotent — a duplicate must not re-close (or fail to re-close) a deferred item
+ *     that has already transitioned out of 'open';
+ *   * `allowStatuses: ['open', 'dropped']` (D#195) — `defer drop` on an item that was
+ *     actually fixed used to be a one-way gate that permanently lost the obs link.
+ *
+ * The CALLER keeps its own catch: the two surfaces report a failure differently (MCP
+ * re-throws with a prefix so the tool response names the contract failure, the CLI writes
+ * to stderr and exits), and both need `closesTokens` to decide which message to use.
+ *
+ * @param {object} db
+ * @param {object} params                 as `saveObservation`
+ * @param {object} opts
+ * @param {string[]|null} [opts.closesTokens]  deferred tokens the caller asked to close
+ * @param {string} opts.project
+ * @returns {{result: object, closesIds: number[]|null}}
+ */
+export function saveWithClosures(db, params, { closesTokens, project }) {
+  let closesIds = null;
+  const result = db.transaction(() => {
+    const r = saveObservation(db, params);
+    // BEFORE the resolver, deliberately — see the docblock.
+    if (r.kind === 'duplicate') return r;
+    if (closesTokens && closesTokens.length > 0) {
+      closesIds = resolveDeferredIds(db, project, closesTokens, { allowStatuses: ['open', 'dropped'] });
+      closeDeferredItems(db, closesIds, r.id);
+    }
+    return r;
+  })();
+  return { result, closesIds };
+}

package/lib/transcript-scan.mjs

@@ -12,13 +12,56 @@
 // This is a memo, not a rewrite: each scanner keeps its own per-entry logic exactly as
 // it was, and only stops re-reading and re-parsing the file to get at it.
 import { readFileSync, existsSync, statSync } from 'fs';
+import { getHeapStatistics } from 'v8';
 
-// Retention cap. Parsed entries cost ~3.45× the file size in heap (measured, same
-// transcript: 5.7MB → 19.5MB). Holding that across a whole Stop is fine for the sessions
-// people actually have; holding it for a 50MB transcript is not, and a hook that gets
-// OOM-killed loses the session's work outright. Above the cap each caller parses on its
-// own exactly as before, so the worst case is today's behaviour rather than a new one.
+// Parsed entries cost ~3.45× the file size in heap (measured: 5.7MB file → 19.5MB).
+export const TRANSCRIPT_ENTRY_HEAP_FACTOR = 3.45;
+
+// Retention cap, kept as the FLOOR of the heap-aware budget below.
+//
+// Audit 2026-09-02 P2-12: above this cap the memo is declined and every caller parses for
+// itself, so `handleStop` — which asks this file twelve questions — degrades to twelve full
+// parses at exactly the size where one parse is already expensive. The audit's proposed fix
+// was to cache a projected subset of each entry instead. That was NOT taken: the twelve
+// scanners read arbitrary fields, so a projection is a hand-maintained field manifest, and
+// a scanner reading a field nobody remembered to project sees `undefined` and silently
+// answers a narrower question — this repo's most-repeated defect, traded for a path no
+// transcript here reaches (112 transcripts on the machine that filed the audit, largest
+// 4.9MB, ZERO above the cap; the report's "50MB ≈ 3.8s" is an extrapolation from a 4.37MB
+// measurement, not an observation).
+//
+// What changed instead: the cap is no longer a bare constant. The thing it is protecting is
+// the heap, so it is expressed against the heap — a quarter of this process's limit, capped
+// at 256MB and floored at the old 24MB. On an ordinary 64-bit Node (~4GB limit) that admits
+// transcripts up to ~74MB, i.e. the degenerate case the audit described now takes one parse
+// instead of twelve; under a constrained limit (a 512MB CI container) the budget shrinks
+// with it and can fall BELOW the old constant, which is the correct direction and is
+// precisely what a fixed 24MB could not do. No caller sees any difference in what it gets.
 export const TRANSCRIPT_CACHE_MAX_BYTES = 24 * 1024 * 1024;
+const TRANSCRIPT_CACHE_HEAP_SHARE = 0.25;
+const TRANSCRIPT_CACHE_CEILING_BYTES = 256 * 1024 * 1024;
+
+/**
+ * Largest transcript whose parsed form this process is willing to retain.
+ *
+ * @param {number} [heapLimitBytes] test seam; defaults to this process's V8 limit
+ * @returns {number} bytes
+ */
+export function transcriptCacheBudgetBytes(heapLimitBytes) {
+  // "Not supplied" and "supplied but unusable" are different, and collapsing them would
+  // make a bad explicit argument silently read the real heap instead of failing safe.
+  let limit;
+  if (heapLimitBytes === undefined) {
+    try { limit = getHeapStatistics().heap_size_limit; } catch { limit = 0; }
+  } else {
+    limit = heapLimitBytes;
+  }
+  // An unreadable or nonsensical limit must not widen the budget — fall back to the
+  // constant, which is the value this cap had before it became heap-derived.
+  if (!Number.isFinite(limit) || limit <= 0) return TRANSCRIPT_CACHE_MAX_BYTES;
+  const budget = Math.floor((limit * TRANSCRIPT_CACHE_HEAP_SHARE) / TRANSCRIPT_ENTRY_HEAP_FACTOR);
+  return Math.min(Math.max(budget, 0), TRANSCRIPT_CACHE_CEILING_BYTES);
+}
 
 let cacheKey = '';
 let cacheEntries = null;
@@ -31,13 +74,21 @@ let cacheEntries = null;
  * must see the same fresh data it would have read for itself.
  *
  * @param {string|null|undefined} transcriptPath
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes] Retention budget. A TEST SEAM — production passes
+ *   nothing and gets `transcriptCacheBudgetBytes()`. Exercising the over-budget branch for
+ *   real would mean writing a 256MB fixture; the alternative (asserting only the default
+ *   budget's value) would leave the branch that actually declines the memo untested.
+ *   It is part of the cache KEY, not just the decision: two callers in one process passing
+ *   different budgets must not read each other's entry.
  * @returns {object[]} entries (empty array when the path is missing or unreadable)
  */
-export function readTranscriptEntries(transcriptPath) {
+export function readTranscriptEntries(transcriptPath, { maxBytes } = {}) {
   if (!transcriptPath || !existsSync(transcriptPath)) return [];
   let st;
   try { st = statSync(transcriptPath); } catch { return []; }
-  const key = `${transcriptPath} ${st.size} ${st.mtimeMs}`;
+  const budget = Number.isFinite(maxBytes) ? maxBytes : transcriptCacheBudgetBytes();
+  const key = `${transcriptPath} ${st.size} ${st.mtimeMs} ${budget}`;
   if (key === cacheKey && cacheEntries) return cacheEntries;
 
   let raw;
@@ -47,7 +98,7 @@ export function readTranscriptEntries(transcriptPath) {
     if (!line.trim()) continue;
     try { entries.push(JSON.parse(line)); } catch { /* a partially written tail line */ }
   }
-  if (st.size <= TRANSCRIPT_CACHE_MAX_BYTES) {
+  if (st.size <= budget) {
     cacheKey = key;
     cacheEntries = entries;
   } else {