@pcircle/memesh 4.6.2 → 4.7.2

package/scripts/hooks/_generated/schema.js

@@ -130,28 +130,24 @@ export function safeAlter(db, sql) {
 }
 export function migrateEntitiesSchema(db) {
     const entityColumns = new Set(db.prepare("PRAGMA table_info(entities)").all().map((c) => c.name));
-    if (!entityColumns.has('status')) {
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN status TEXT NOT NULL DEFAULT 'active'");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_entities_status ON entities(status)");
-    }
-    if (!entityColumns.has('access_count')) {
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN access_count INTEGER DEFAULT 0");
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN last_accessed_at TIMESTAMP");
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN confidence REAL DEFAULT 1.0");
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN valid_from TIMESTAMP");
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN valid_until TIMESTAMP");
-    }
-    if (!entityColumns.has('namespace')) {
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN namespace TEXT DEFAULT 'personal'");
-        db.exec("CREATE INDEX IF NOT EXISTS idx_entities_namespace ON entities(namespace)");
-    }
-    if (!entityColumns.has('recall_hits')) {
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN recall_hits INTEGER DEFAULT 0");
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN recall_misses INTEGER DEFAULT 0");
-    }
-    if (!entityColumns.has('title')) {
-        safeAlter(db, "ALTER TABLE entities ADD COLUMN title TEXT");
-    }
+    const addColumn = (column, sql) => {
+        if (entityColumns.has(column))
+            return;
+        safeAlter(db, sql);
+        entityColumns.add(column);
+    };
+    addColumn('status', "ALTER TABLE entities ADD COLUMN status TEXT NOT NULL DEFAULT 'active'");
+    addColumn('access_count', "ALTER TABLE entities ADD COLUMN access_count INTEGER DEFAULT 0");
+    addColumn('last_accessed_at', "ALTER TABLE entities ADD COLUMN last_accessed_at TIMESTAMP");
+    addColumn('confidence', "ALTER TABLE entities ADD COLUMN confidence REAL DEFAULT 1.0");
+    addColumn('valid_from', "ALTER TABLE entities ADD COLUMN valid_from TIMESTAMP");
+    addColumn('valid_until', "ALTER TABLE entities ADD COLUMN valid_until TIMESTAMP");
+    addColumn('namespace', "ALTER TABLE entities ADD COLUMN namespace TEXT DEFAULT 'personal'");
+    addColumn('recall_hits', "ALTER TABLE entities ADD COLUMN recall_hits INTEGER DEFAULT 0");
+    addColumn('recall_misses', "ALTER TABLE entities ADD COLUMN recall_misses INTEGER DEFAULT 0");
+    addColumn('title', "ALTER TABLE entities ADD COLUMN title TEXT");
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_entities_status ON entities(status);
+     CREATE INDEX IF NOT EXISTS idx_entities_namespace ON entities(namespace);`);
 }
 export function ensureTagsUniqueIndex(db) {
     try {

package/scripts/hooks/_shared.js

@@ -26,15 +26,18 @@ import { fileURLToPath, pathToFileURL } from 'url';
 // Re-exported here so all 6 hooks keep importing these names from `_shared.js`
 // unchanged.
 import {
+  homeDir,
   memeshDir,
   getDbPath,
   getMemeshDirFromDbPath,
   getProjectName,
+  redactSecrets,
   slugFromRemoteUrl,
 } from './_generated/core-paths.js';
 import { autoCaptureDecision } from './_generated/capture-flag.js';
 export { assembleTopologyBlock, buildReferenceContext, extractCitedMemoryIds, DEFAULT_TOPOLOGY_BUDGET, SNIPPET_FETCH_CHARS, TOPOLOGY_CANDIDATE_CAP } from './_generated/work-topology.js';
 export { matchingGuards, guardFromMetadata } from './_generated/guards.js';
+export { writeCitationRule, citationRulePath, CITATION_RULE_BODY } from './_generated/citation-rule.js';
 import { guardFromMetadata as guardFromMetadataLocal } from './_generated/guards.js';
 
 /**
@@ -101,7 +104,16 @@ export function recordGuardFires(dbPath, lessonIds) {
     } finally {
       db.close();
     }
-  } catch { /* counting must never block the user's work */ }
+  } catch (err) {
+    // Never block the user's work — but say so. A read-only database file, a
+    // lost lock, or a schema drift silently stopped the fire counter, and
+    // guard ROI is judged on exactly this number: a guard that fires often
+    // and a guard whose counter never landed look identical in review. One
+    // line on stderr is what guard-check already does for its own failures.
+    try {
+      process.stderr.write(`[memesh guard-fires] not counted: ${err?.message || err}\n`);
+    } catch { /* stderr gone */ }
+  }
 }
 import { isAutoInjectable } from './_generated/work-topology.js';
 export { parseTaskState, taskStateLines, taskStateName } from './_generated/task-state.js';
@@ -114,7 +126,7 @@ import {
   tokenizeQuery,
 } from './_generated/fts-index.js';
 
-export { memeshDir, getDbPath, getMemeshDirFromDbPath, getProjectName, slugFromRemoteUrl };
+export { homeDir, memeshDir, getDbPath, getMemeshDirFromDbPath, getProjectName, redactSecrets, slugFromRemoteUrl };
 
 const require = createRequire(import.meta.url);
 
@@ -332,6 +344,12 @@ import {
 // nothing. node:sqlite is part of the runtime: there is no binary to
 // miss, so the failure mode and its whole recovery apparatus are gone.
 
+/** See the pragma in `openHookDb` for why this is not the 30s the shared
+ *  database class uses. Exported because the three hooks that open a
+ *  read-only handle directly (bypassing `openHookDb`, which cannot express
+ *  `readOnly`) must apply the same cap themselves. */
+export const HOOK_BUSY_TIMEOUT_MS = 2000;
+
 export function openHookDb(env = process.env, opts = {}) {
 
   // Path helpers read process.env directly (no-arg). The `env` parameter
@@ -349,6 +367,23 @@ export function openHookDb(env = process.env, opts = {}) {
   const db = new MemeshDatabase(dbPath, { allowExtension: true });
   db.pragma('journal_mode = WAL');
   db.pragma('foreign_keys = ON');
+  // A hook waits for a held write lock for less time than Claude Code will
+  // wait for the hook.
+  //
+  // `MemeshDatabase` sets `busy_timeout = 30000`, and that number is right
+  // for the processes it was chosen for: a 30k-vector `swapVectorGeneration`
+  // holds the write lock for ~9s, and the CLI, the MCP server and the HTTP
+  // server should WAIT for it rather than fail. A hook cannot. Its budget in
+  // `hooks/hooks.json` is 3s (UserPromptSubmit) to 10s (Stop, PreCompact),
+  // so a 30s wait has exactly one possible ending: the harness kills the
+  // hook. The capture is lost either way — the difference is that the user
+  // also gets a hook-timeout error, which is the failure mode that makes
+  // memesh something to switch off.
+  //
+  // 2s fits inside every budget with room for the hook's own work. On
+  // contention the capture is skipped quietly, this run's `hook_runs` stamp
+  // is not written, and `memesh doctor` reports the gap honestly.
+  db.pragma(`busy_timeout = ${HOOK_BUSY_TIMEOUT_MS}`);
   // Bringing the schema current is a WRITE, and "cannot migrate" must not
   // mean "cannot open": a database file that is read-only but behind on
   // schema (a pre-upgrade backup, a permissions accident) dies on the
@@ -535,6 +570,23 @@ export { truncateTitle } from './_generated/title.js';
  * @returns {{ id: number, isNew: boolean } | null} null if the row could not be resolved
  */
 export function captureEntity(db, { name, type, observations = [], tags = [], title, metadata }) {
+  // One transaction, because this function performs six writes that only
+  // mean anything together: the entity row, its observations, its tags, and
+  // the contentless-FTS delete + insert that make them findable.
+  //
+  // Without it, a throw anywhere in the middle — a lock lost to the CLI, a
+  // full disk, an FTS corruption — committed the prefix and dropped the
+  // rest, and the two most likely resting places are both invisible:
+  // observations inserted with no FTS row (a memory that exists and can
+  // never be recalled), or the old FTS row deleted and the new one not
+  // written (a memory that just stopped being findable). Neither is
+  // retried, because the callers dedupe on the entity NAME existing —
+  // `INSERT OR IGNORE` reports "already there" on the next run and the
+  // half-written state is permanent.
+  return db.transaction(() => captureEntityInner(db, { name, type, observations, tags, title, metadata }))();
+}
+
+function captureEntityInner(db, { name, type, observations, tags, title, metadata }) {
   // source_host provenance: these hooks only ever run under Claude Code (they
   // are wired into ~/.claude/settings.json), so a hook-captured entity is by
   // definition a claude-code capture. Stamped only on the INSERT — an OR
@@ -573,8 +625,11 @@ export function captureEntity(db, { name, type, observations = [], tags = [], ti
     // it's corrupted — replace with {} and log the healing.
     if (!meta && metaRow?.metadata) {
       try {
+        // The id, not the name. The id is what a maintainer needs to look
+        // the row up; the name is user-authored content, and this line goes
+        // to a stderr stream the user may paste anywhere.
         process.stderr.write(
-          `MeMesh: healed corrupted metadata for entity ${id} (${name}). ` +
+          `MeMesh: healed corrupted metadata for entity ${id}. ` +
           `Original value was unparseable; replaced with {}.\n`,
         );
       } catch { /* stderr gone */ }
@@ -745,9 +800,25 @@ export function decideAutoUpdateHook(currentVersion, cache, policy) {
   const policyAllows = (POLICY_RANK[policy] ?? 0) >= BUMP_RANK[bump];
   if (policyAllows) return { run: true, latest, bump, deprecationOverride: false };
 
+  // The deprecation override does NOT apply when the policy is `off`.
+  //
+  // Look at what the override could ever do: it fires only for a `patch`
+  // bump, and any policy above `off` already permits a patch. So its ONLY
+  // effect was to defeat `off` — the one setting whose whole meaning is
+  // "never install anything without me asking".
+  //
+  // And its trigger is `currentVersionDeprecation`, a string the PUBLISHER
+  // writes into the npm registry. Anyone able to publish the package could
+  // therefore make every user who had turned auto-update OFF run a detached
+  // `npm install -g`, unattended, from a Stop hook. That is not a security
+  // override; it is a remote switch on a user's explicit refusal.
+  //
+  // A deprecated version still gets said out loud: `memesh doctor` escalates
+  // the update-status row to FAIL for it (there is a test named for that),
+  // and the session banner reports it. The user decides.
   const deprecated = typeof cache.currentVersionDeprecation === 'string'
     && cache.currentVersionDeprecation.length > 0;
-  if (deprecated && bump === 'patch') {
+  if (deprecated && bump === 'patch' && policy !== 'off') {
     return { run: true, latest, bump, deprecationOverride: true };
   }
 

package/scripts/hooks/guard-check.js

@@ -23,6 +23,7 @@ import { existsSync } from 'fs';
 import {
   buildReferenceContext,
   getDbPath,
+  HOOK_BUSY_TIMEOUT_MS,
   loadActiveGuards,
   matchingGuards,
   guardWarningLines,
@@ -46,6 +47,10 @@ process.stdin.on('end', () => {
     // spelling and hands back a WRITABLE handle. This hook only reads;
     // the fire counter opens its own writable handle for the one UPDATE.
     const db = new MemeshDatabase(dbPath, { readOnly: true });
+    // MemeshDatabase's constructor always sets busy_timeout to the 30s that
+    // is correct for the CLI/MCP/HTTP writers; this hook's own budget
+    // (hooks.json) is 5s, so left alone a contended lock outlives the hook.
+    db.pragma(`busy_timeout = ${HOOK_BUSY_TIMEOUT_MS}`);
     let matches;
     try {
       matches = matchingGuards(loadActiveGuards(db, 'Bash'), 'Bash', command);

package/scripts/hooks/pre-compact.js

@@ -4,13 +4,20 @@ import { basename } from 'path';
 import { existsSync, readFileSync } from 'fs';
 import { AUTO_CAPTURE_TAG, captureEntity, getProjectName, isAutoCaptureEnabled, openHookDb, recordHookRun, truncateTitle } from './_shared.js';
 
-// Timeout guard: always exit within 10 seconds
-const TIMEOUT_MS = 10000;
-const timeoutHandle = setTimeout(() => {
-  try { process.stderr.write('[memesh pre-compact] Timed out after 10s\n'); } catch {}
-  process.exit(0);
-}, TIMEOUT_MS);
-timeoutHandle.unref();
+// There is no in-process timeout guard, and its absence is deliberate.
+//
+// This file used to arm `setTimeout(() => process.exit(0), 10_000).unref()`.
+// It could not fire. Everything after `stdin`'s `end` event is one
+// synchronous block — no `await`, no callback — so the event loop never gets
+// a turn between the handler starting and the process exiting, and a JS
+// timer cannot interrupt a blocking SQLite call. The one window where it
+// COULD have run is while stdin is still open, which is not where a hook
+// hangs.
+//
+// The timeout that does work is external: `hooks/hooks.json` declares
+// `"timeout": 10` for PreCompact, and the harness enforces it on the
+// process. `openHookDb` additionally caps the SQLite lock wait at 2s so
+// contention ends in a skipped capture rather than in that kill.
 
 let input = '';
 process.stdin.setEncoding('utf8');

package/scripts/hooks/pre-edit-recall.js

@@ -18,6 +18,7 @@ import {
   getDbPath,
   getMemeshDirFromDbPath,
   getProjectName,
+  HOOK_BUSY_TIMEOUT_MS,
   isTrustedForAutoContext,
   writePrivateJson,
   hookMatchExpression,
@@ -82,6 +83,27 @@ process.stdin.on('end', () => {
     // and hands back a WRITABLE handle. This hook only reads; the guard
     // fire counter opens its own writable handle for its one UPDATE.
     const db = new MemeshDatabase(dbPath, { readOnly: true });
+    // MemeshDatabase's constructor always sets busy_timeout to the 30s that
+    // is correct for the CLI/MCP/HTTP writers; this hook's own budget
+    // (hooks.json) is 5s, so left alone a contended lock outlives the hook.
+    db.pragma(`busy_timeout = ${HOOK_BUSY_TIMEOUT_MS}`);
+    // A single probe before either pass below. `loadActiveGuards` swallows
+    // a query failure internally — by design, so a guard-matching problem
+    // can never be the reason this hook crashes — which means a lock still
+    // held after the busy_timeout wait comes back as "no guards matched"
+    // rather than as an error this hook can see. Unlike guard-check.js,
+    // this hook still has the recall pass to run after the guard pass, and
+    // that query is NOT swallowed — so a genuinely contended connection
+    // paid the full busy_timeout wait TWICE in sequence, once hidden and
+    // once fatal, before giving up. Probing once here means a contended
+    // database is discovered (and given up on) after paying that wait
+    // exactly once.
+    try {
+      db.prepare('SELECT 1').get();
+    } catch {
+      db.close();
+      return pass();
+    }
     let guardMatches = [];
     const recallLines = [];
     try {

package/scripts/hooks/session-start.js

@@ -11,6 +11,7 @@ import {
   getDbPath,
   getMemeshDirFromDbPath,
   getProjectName,
+  HOOK_BUSY_TIMEOUT_MS,
   importFromPluginRoot,
   assembleTopologyBlock,
   DEFAULT_TOPOLOGY_BUDGET,
@@ -27,7 +28,9 @@ import {
   resolvePluginRoot,
   resolveSessionLimit,
   taskStateLines,
+  homeDir,
   taskStateName,
+  writeCitationRule,
   writePrivateJson,
 } from './_shared.js';
 import { MemeshDatabase } from './_generated/sqlite.js';
@@ -135,6 +138,11 @@ function buildDeprecationBanner(currentVersion, cache) {
         ? `    Run: memesh update   (or set autoUpdate: memesh config set autoUpdate patch)`
         : `    Run: memesh update   (resolves @latest — or set: memesh config set autoUpdate patch)`,
     );
+  } else if (channel === 'plugin-marketplace') {
+    // Was missing entirely, so a plugin user under an active security
+    // advisory fell to the generic npm line below — advice that does not
+    // apply to a version-pinned plugin install on either host.
+    lines.push(pluginUpgradeLine(resolvePluginRoot(import.meta.url)));
   } else if (channel === 'source-checkout') {
     lines.push(`    Source checkout: pull and rebuild (\`git pull && npm install && npm run build\`).`);
   } else if (channel === 'npm-local') {
@@ -262,7 +270,7 @@ function buildUpdateAvailableBanner(currentVersion, cache, getChannel) {
   if (channel === 'npm-global') {
     lines.push(`    Run: memesh update`);
   } else if (channel === 'plugin-marketplace') {
-    lines.push(`    Run: memesh upgrade-plugin   (no CLI? npx @pcircle/memesh upgrade-plugin — or reinstall from /plugin UI)`);
+    lines.push(pluginUpgradeLine(resolvePluginRoot(import.meta.url)));
   } else if (channel === 'source-checkout') {
     lines.push(`    Source checkout: \`git pull && npm install && npm run build\`.`);
   } else if (channel === 'npm-local') {
@@ -314,6 +322,40 @@ function detectInstallChannelHook(pluginRoot) {
   }
 }
 
+/**
+ * Which plugin runtime owns this copy: 'claude-code', 'codex', or null.
+ *
+ * Only consulted to pick the remediation command a plugin user is shown,
+ * so null (dist absent, old dist without the export) falls back to the
+ * Claude Code wording rather than suppressing the hint entirely — the
+ * banner is more useful naming the majority host than naming none.
+ */
+function pluginHostOf(pluginRoot) {
+  try {
+    return _installChannelMod?.detectPluginHost?.(pluginRoot) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The one upgrade line a plugin-marketplace install should be shown.
+ *
+ * Shared by BOTH banners on purpose. They drifted once: the routine
+ * "update available" banner learned that Codex needs a different command
+ * and the deprecation banner did not — and the deprecation banner is the
+ * one that fires on a security advisory AND takes precedence over the
+ * other. So the highest-stakes message carried the least actionable
+ * instruction, and a second copy of this logic is exactly how that
+ * happened. One owner, so it cannot happen again.
+ */
+function pluginUpgradeLine(pluginRoot) {
+  if (pluginHostOf(pluginRoot) === 'codex') {
+    return `    Run: codex plugin marketplace upgrade pcircle-memesh && codex plugin add memesh@pcircle-memesh`;
+  }
+  return `    Run: memesh upgrade-plugin   (no CLI? npx @pcircle/memesh upgrade-plugin — or reinstall from /plugin UI)`;
+}
+
 // Don't fire a fresh-check more often than this. Two parallel
 // session-starts both spawning `memesh status` could otherwise race
 // the cache: a later writer that hits a deprecation-only timeout
@@ -542,6 +584,36 @@ process.stdin.on('end', async () => {
     const data = JSON.parse(input);
     const projectName = getProjectName(data.cwd);
 
+    // Self-heal the citation contract.
+    //
+    // `install-hooks` writes it too, but a PLUGIN install never runs that
+    // command — and plugin is how most users arrive. Without this, the
+    // contract would reach only npm installs, which is the same shape as the
+    // bug it exists to fix: a mechanism that is correct on a path nobody
+    // takes. Idempotent (a byte-identical file is left alone), refuses to
+    // touch a file memesh did not write, and never blocks the session: a
+    // failure here traces and the hook carries on.
+    try {
+      // Scope comes from the install marker, NOT hardcoded to 'user'. A
+      // `--scope project` install keeps everything inside that project, and
+      // writing the contract to ~/.claude/rules/ anyway would leak it into
+      // every OTHER project on the machine — and survive
+      // `uninstall-hooks --scope project`, which only knows about the
+      // project path. No marker means a plugin install, which is user-level
+      // by construction.
+      let ruleScope = 'user';
+      try {
+        const markerPath = join(memeshHomeDir(), 'install-hooks.json');
+        if (existsSync(markerPath)) {
+          const marker = JSON.parse(readFileSync(markerPath, 'utf8'));
+          if (marker?.scope === 'project') ruleScope = 'project';
+        }
+      } catch { /* unreadable marker → user scope, the safe default */ }
+      writeCitationRule(ruleScope, homeDir(), data.cwd || process.cwd());
+    } catch (err) {
+      try { process.stderr.write(`[memesh session-start] citation rule: ${err?.message || err}\n`); } catch {}
+    }
+
     // Clear per-session throttle files from previous session
     try {
       if (existsSync(throttlePath)) {
@@ -594,6 +666,10 @@ process.stdin.on('end', async () => {
     // property of the database file that the writing side already set, and a
     // reader opens a WAL database perfectly well without asking for it.
     const db = new MemeshDatabase(dbPath, { readOnly: true });
+    // MemeshDatabase's constructor always sets busy_timeout to the 30s that
+    // is correct for the CLI/MCP/HTTP writers; this hook's own budget
+    // (hooks.json) is 10s, so left alone a contended lock outlives the hook.
+    db.pragma(`busy_timeout = ${HOOK_BUSY_TIMEOUT_MS}`);
     // Whether the noise-compression epilogue below should run at all —
     // pre-read from this readonly handle before it closes. Defaults to
     // true so any early exit still lets the epilogue's own throttle decide.
@@ -916,7 +992,19 @@ process.stdin.on('end', async () => {
         // this line IS an instruction. One line is the entire write side of
         // the injection-ROI signal; the Stop hook credits recall_hits only
         // from these markers (self-reported: undercounts, never overcounts).
-        memoryContext += '\nWhen a memory above genuinely informs your work, cite it once inline as [mem:ID], using the id shown on its line.';
+        // The citation instruction used to be appended here, outside the
+        // fence, so it would read as an instruction rather than as data.
+        // It never worked: Claude Code wraps a hook's additionalContext in a
+        // system-reminder ending "you should not respond to this context
+        // unless it is highly relevant", so the whole block — instruction
+        // included — arrives as data. Measured on a real database:
+        // citation_sessions_total=4, sessions WITH a citation = 0.
+        //
+        // The contract now lives in `.claude/rules/memesh-citations.md`,
+        // which Claude Code loads as an instruction. Writing it is the
+        // self-heal below; the line here is gone rather than duplicated,
+        // because a per-session copy of an instruction that is read as data
+        // is a per-session cost with no effect.
       }
 
       // --- Record injected entity IDs for recall effectiveness tracking ---
@@ -1038,7 +1126,22 @@ process.stdin.on('end', async () => {
       const lifecycleMod = await importFromPluginRoot(pluginRoot, 'dist/core/lifecycle.js');
       dbMod.openDatabase();
       try {
-        lifecycleMod.compressWeeklyNoise(dbMod.getDatabase());
+        // Say what it did. This archives at least 20 of the user's memories
+        // per week processed and the count was thrown away, so the one
+        // operation in memesh that removes things from view was also the
+        // only one that left no trace anywhere — not in the hook output, not
+        // in doctor, not in the dashboard. Nothing to opt into: it runs at
+        // most once a day and stays silent when it compresses nothing.
+        const noise = lifecycleMod.compressWeeklyNoise(dbMod.getDatabase());
+        if (noise && noise.compressed > 0) {
+          try {
+            process.stderr.write(
+              `[memesh] archived ${noise.compressed} low-signal memor${noise.compressed === 1 ? 'y' : 'ies'} `
+              + `into ${noise.weeksProcessed} weekly summar${noise.weeksProcessed === 1 ? 'y' : 'ies'} `
+              + `(recover with \`memesh recall --include-archived\`)\n`,
+            );
+          } catch { /* stderr gone */ }
+        }
       } finally {
         dbMod.closeDatabase();
       }

package/scripts/hooks/session-summary.js

@@ -36,6 +36,7 @@ import {
   isAutoCaptureEnabled,
   openHookDb,
   readUpdateCheckCache,
+  redactSecrets,
   recordHookRun,
   stampHookRunOnly,
   resolveAutoUpdatePolicy,
@@ -117,7 +118,14 @@ function parseTranscript(transcriptPath) {
             if (block.name === 'Bash') {
               const cmd = block.input?.command ?? '';
               if (typeof cmd === 'string' && cmd.length > 10 && !cmd.startsWith('ls') && !cmd.startsWith('cd')) {
-                bashCommands.push(cmd.slice(0, 100));
+                // Redact BEFORE truncating. A bash command line is the single
+                // most likely place a credential appears in a transcript
+                // (`export ANTHROPIC_API_KEY=sk-...`, `curl -H "Authorization:
+                // Bearer ..."`), and this text is stored verbatim as an
+                // observation — a permanent, searchable, exportable copy.
+                // Truncating first would cut a token in half and leave the
+                // fragment unmatched by every pattern.
+                bashCommands.push(redactSecrets(cmd).slice(0, 100));
               }
             }
           }
@@ -141,7 +149,14 @@ function parseTranscript(transcriptPath) {
             const text = typeof block.content === 'string'
               ? block.content
               : JSON.stringify(block.content);
-            errorsEncountered.push(text.slice(0, 200));
+            // Same reason as the bash branch, and one more: this array is
+            // ALSO the payload `analyzeFailure` sends to the configured LLM
+            // provider. A failed request that echoes its own Authorization
+            // header — the ordinary shape of an auth error — would be stored
+            // and then transmitted off the machine. Redacted once here, at
+            // the point the text enters the process, so every downstream use
+            // inherits it.
+            errorsEncountered.push(redactSecrets(text).slice(0, 200));
           }
         }
 
@@ -511,8 +526,21 @@ process.stdin.on('end', async () => {
               const updateHit = db.prepare(
                 'UPDATE entities SET recall_hits = COALESCE(recall_hits, 0) + 1 WHERE id = ?'
               );
+              // Counted here, not recomputed below. The compliance
+              // numerator and `recall_hits` have to be the SAME
+              // measurement: `cited.size > 0` asked "did this transcript
+              // contain any [mem:N] at all", which counts a marker for an id
+              // this session never injected — one carried over from an
+              // earlier turn, or a number the agent invented — as compliance.
+              // The denominator counts sessions that received an injection,
+              // so the two halves of the rate were answering different
+              // questions.
+              let injectedAndCited = 0;
               for (const id of entityIds) {
-                if (cited.has(id)) updateHit.run(id);
+                if (cited.has(id)) {
+                  updateHit.run(id);
+                  injectedAndCited++;
+                }
               }
 
               // Accounting-mode stamp (constant value, rewritten every
@@ -527,7 +555,16 @@ process.stdin.on('end', async () => {
                  ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT)`
               );
               bump.run('citation_sessions_total');
-              if (cited.size > 0) bump.run('citation_sessions_cited');
+              // Initialised unconditionally, then bumped. Writing it only on
+              // a citation made "zero sessions cited" and "this code never
+              // ran" the same absent key — and that is exactly what a real
+              // database showed on 2026-08-24: total=4, cited absent, with
+              // no way to tell a 0% compliance rate from a dead counter.
+              db.prepare(
+                `INSERT INTO memesh_metadata (key, value) VALUES ('citation_sessions_cited', '0')
+                 ON CONFLICT(key) DO NOTHING`
+              ).run();
+              if (injectedAndCited > 0) bump.run('citation_sessions_cited');
             }
           }
         }

package/scripts/upgrade-plugin.sh

@@ -94,7 +94,15 @@ CURRENT_VERSION="$(INSTALL_REGISTRY="$INSTALL_REGISTRY" node -e "
   const entries = (j.plugins && j.plugins['memesh@pcircle-memesh']) || [];
   if (entries.length === 0) { process.stdout.write('none'); process.exit(0); }
   process.stdout.write(entries[0].version || 'unknown');
-")"
+")" || {
+  # Its sibling twelve lines up has this guard; this read did not, so an
+  # unreadable or malformed installed_plugins.json made CURRENT_VERSION the
+  # empty string. That compares unequal to every target, so the script
+  # reported an upgrade from "" and carried on — on a registry it had just
+  # failed to parse.
+  echo "ERROR: could not read the installed memesh version from $INSTALL_REGISTRY" >&2
+  exit 1
+}
 
 echo "==> Currently installed: $CURRENT_VERSION"