claude-mem-lite 3.77.0 → 3.79.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -814,7 +814,10 @@ benchmark and A/B harness are calibrated against — changing them invalidates t
 | `CLAUDE_MEM_UPS_BM25_MIN_FOLLOWUP` | Looser floor for follow-up prompts inside an already-injected session. | `5e-6` |
 | `CLAUDE_MEM_UPS_OR_BM25_MIN` | Floor applied to the OR-fallback arm (looser query, needs a stricter floor). | `30` |
 | `CLAUDE_MEM_UPS_TOP_MIN` | Minimum score for the top hit; `0` disables (useful on tiny test corpora). | `50` |
-| `CLAUDE_MEM_UPS_FLOOR_REF_CORPUS` | Reference corpus size the score floors are normalized against, so a fresh install with few rows is not silently gated to zero injections. | `584` |
+| `CLAUDE_MEM_UPS_FLOOR_REF_CORPUS` | Reference corpus size the score floors are normalized against, so a fresh install with few rows is not silently gated to zero injections. Shared by every floor-bearing surface, including error-recall below. | `584` |
+| `CLAUDE_MEM_ERROR_RECALL_BM25_MIN` | Relevance floor for the error-recall surface (memories injected after a failed Bash command). **Off by default.** Setting it to `10.5` (the calibrated value) makes the surface stay silent when its best-matching memory is not actually about the failure — the whole set is dropped, never trimmed row-by-row. **It is a real trade, not a free win:** measured on a live database at that threshold, injections fall ~37% and ~39% of firings go silent, concentrated in projects with few memories. Off by default because nothing shows the dropped rows were noise. Explore with `node benchmark/error-recall-suite.mjs --sweep`. | `0` (off) |
+| `CLAUDE_MEM_ERROR_RECALL_RERANK` | `off` restores the flat keyword ordering of the error-recall surface. **On by default**, and unlike the floor above it removes nothing: memories that share only the failed command's vocabulary are demoted below memories that mention the failure itself, and when a project has none of the latter the result is unchanged. Measured on a live database over 52 real failing commands × 15 projects: the lead memory matched no error term in 42.3% of firings before, 21.5% after, with the injected row count identical. | _(on)_ |
+| `CLAUDE_MEM_ERROR_RECALL_ON_FAILURE` | `off` stops the plugin from recalling memories when a Bash command **fails at the host level**. On by default. Claude Code delivers failed tool calls to a separate `PostToolUseFailure` hook event, so before this the surface only ever saw commands that exited `0` while printing error-ish text — a genuinely failing build recalled nothing. Denials from your own guardrails (sandbox, policy hooks, declined permission prompts) and commands you interrupted are never recalled for. | _(on)_ |
 | `CLAUDE_MEM_UPS_IDENTIFIER_BYPASS` | `0` disables the bypass that lets an exact identifier match skip the score floors. | _(on)_ |
 | `CLAUDE_MEM_UPS_PROMPT_FALLBACK_LIMIT` | How many past-prompt rows the fallback arm may return. | `1` |
 | `MEM_COVERAGE_THRESHOLD` | Fraction of query terms a memory must cover to qualify (∈ [0,1]). | `0.4` |

package/bash-utils.mjs

@@ -120,6 +120,58 @@ const ERROR_STOP_WORDS = new Set([
 const ERROR_LINE_RE = /error|fail|exception|cannot|not found|undefined|null/i;
 const ERROR_RECALL_MAX_TERMS = 6;
 
+/**
+ * The token that NAMES the failure: an exception class (`ModuleNotFoundError`,
+ * `JSONDecodeError`), an errno-style code (`ENOENT`, `EACCES`), a signal (`SIGSEGV`),
+ * or Rust's `panicked`.
+ *
+ * WHY THIS EXISTS (D#167). The line scan below takes the FIRST 3 matching lines and the
+ * first 5 tokens of each, and a real failure puts its banner first and its name last:
+ *
+ *     Traceback (most recent call last):        <- matches, contributes `traceback most recent`
+ *       File "<string>", line 3, in <module>
+ *     ModuleNotFoundError: No module named 'x'  <- the only line that says WHAT broke
+ *
+ * Measured over 52 real failing commands pulled from 1110 transcripts: 28 of them name
+ * their failure this way, and in 25 of those 28 (89.3%) THE NAME NEVER REACHED THE
+ * QUERY. The six-term budget went to the banner (`traceback,most,recent`) and to path
+ * fragments from the command (`mnt,data_ssd,dev`). Downstream, 39.2% of injected rows
+ * (764/1947 over 8 projects x 52 shapes on the live DB) matched no error term at all —
+ * they were admitted on command vocabulary alone — and for 42.3% of firing cases that
+ * was true of the TOP-1 row, whose lesson_learned is inlined into the model's context.
+ *
+ * This is deliberately a POSITIVE pattern for the signal, not a stop-list for the noise:
+ * a stop-list of boilerplate ("traceback", "most", "recent", "call", "last", …) grows
+ * once per runtime forever, which is the enumeration the D#136 docblock below warns
+ * against. Matching the shape of an exception name instead covers runtimes nobody has
+ * seen yet, and when nothing matches, extraction is byte-identical to before.
+ *
+ * Note `E[A-Z]{3,}` also matches the literal `ERROR`; it is dropped by ERROR_STOP_WORDS
+ * on the next line, and that interaction is load-bearing rather than incidental.
+ */
+const ERROR_NAMER_RE = /\b(?:[A-Z][A-Za-z]*(?:Error|Exception)|E[A-Z]{3,}|SIG[A-Z]{2,}|panicked)\b/g;
+
+/**
+ * How many names may jump the queue. Each one displaces a scanned term (the 6-term cap
+ * is unchanged), so this trades tail tokens for the identifier.
+ *
+ * ONE, and that is measured rather than argued. Swept on the live DB over the same 52
+ * shapes x 15 projects, reading the share of injected rows that match no error term and
+ * the share of cases whose top row does:
+ *
+ *   MAX=1   434 rows (22.4%)   154 cases (21.5%)
+ *   MAX=2   442 rows (22.8%)   157 cases (22.0%)
+ *   MAX=3   445 rows (22.9%)   157 cases (22.0%)
+ *
+ * The second name never pays: 96.4% of shapes already have their failure named by the
+ * first, so slots 2 and 3 buy a duplicate or a second-order name while still evicting a
+ * scanned term — and the evicted tail is often the most specific token in the list (see
+ * the golden case in tests/error-recall-gate.test.mjs, where a filename is lost). This
+ * shipped at 2 on the reasoning that a chained Python traceback has two real names; the
+ * sweep says that reasoning does not survive contact with the sample.
+ */
+const ERROR_NAMER_MAX = 1;
+
 /**
  * Split a failed command + its output into command-derived and error-derived terms.
  * Shared by extractErrorKeywords (merged view, unchanged contract) and
@@ -137,6 +189,19 @@ function collectErrorTerms(cmd, response) {
     if (!ERROR_STOP_WORDS.has(lw) && !seen.has(lw)) { seen.add(lw); cmdWords.push(lw); }
   }
   const errWords = [];
+  // The failure's NAME goes in first — see ERROR_NAMER_RE for the measurement that put
+  // it here. Prepending rather than re-ordering the LINE scan is deliberate: sorting
+  // namer-bearing lines to the front also promotes their verbose neighbours, which costs
+  // real terms (on npm's ENOENT output it evicts `syscall` in favour of `such`/`file`
+  // from the long "no such file or directory" line). Prepending only ever displaces the
+  // TAIL of what the scan would have produced.
+  for (const m of String(response || '').match(ERROR_NAMER_RE) || []) {
+    if (errWords.length >= ERROR_NAMER_MAX) break;
+    const lt = m.toLowerCase();
+    if (ERROR_STOP_WORDS.has(lt) || seen.has(lt)) continue;
+    seen.add(lt);
+    errWords.push(lt);
+  }
   // The line filter is the TRIGGER's pattern list OR'd with the prose one. Anything
   // that made detectBashSignificance call this a hard error is, by construction, also
   // something we will extract terms from — which closes the "trigger fired, extractor
@@ -163,6 +228,40 @@ function collectErrorTerms(cmd, response) {
   return { cmdWords, errWords };
 }
 
+/**
+ * THE CAP TRUNCATES BY POSITION, AND THAT WAS TESTED AGAINST THE ALTERNATIVE (D#169).
+ *
+ * The alternative looked obviously right. Tokens are scanned line by line, prose comes
+ * before identifiers within a line, so `AssertionError: expected observation-write.mjs
+ * to be defined` yields `assertionerror, expected, observation-write.mjs` — and whatever
+ * the cap removes comes off that end. On a real shape, `npx vitest run
+ * tests/scope-label.test.mjs` failing with an AssertionError kept `fail, tests` and
+ * dropped `scope-label.test.mjs`: a filename traded for a word in thousands of memories.
+ * Keeping identifier-shaped tokens (`[._-]`) first should fix that.
+ *
+ * Measured on the live DB, same 58 real shapes x 15 projects either way:
+ *
+ *                              cmd-only rows     cmd-only at TOP-1
+ *   positional cap (shipped)   493/2184  22.6%   171/801  21.3%
+ *   identifier-first cap        749/2093  35.8%   259/775  33.4%
+ *
+ * Thirteen points WORSE on both, and the mechanism is worth keeping written down:
+ * `[._-]` conflates "discriminative" with "unique to this invocation". The tokens it
+ * promotes are this run's own paths and filenames — `d167-measure.mjs`,
+ * `s-default.json` — whose IDF is so high they match NOTHING in the corpus, and the
+ * tokens it evicts to make room are `enoent`, `syscall`: low-IDF, but present in the
+ * memories that actually explain the failure. A row then survives on command vocabulary
+ * alone, which is the D#167 defect re-created from the other side.
+ *
+ * (A variant that promoted identifiers only among ERROR words, sparing command words,
+ * measured byte-identical: command words sit at low indices, so a positional tiebreak
+ * already keeps them and promotion never decides their fate.)
+ *
+ * The premise "the evicted tail is systematically the good part" is therefore FALSE.
+ * The tail is often hapax. Any future attempt here needs real document frequencies, not
+ * a shape heuristic — and planErrorRecall is pure, with no corpus to count against.
+ */
+
 /**
  * Extract discriminative keywords from a failed command and its error output.
  * Filters out common stop words to produce useful FTS5 search terms.
@@ -172,6 +271,8 @@ function collectErrorTerms(cmd, response) {
  */
 export function extractErrorKeywords(cmd, response) {
   const { cmdWords, errWords } = collectErrorTerms(cmd, response);
+  // Same cap rule as planErrorRecall — the two must not drift into dialects, which is
+  // pinned by a test asserting they emit identical lists.
   const result = [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS);
   return result.length >= 1 ? result : null;
 }
@@ -231,12 +332,26 @@ export function extractErrorKeywords(cmd, response) {
  *
  * @param {string} cmd The command that was executed
  * @param {string} response The error output text
- * @returns {{terms: string[]}|null} null ⇒ do not inject
+ * @returns {{terms: string[], cmdWords: string[], errWords: string[]}|null}
+ *   null ⇒ do not inject. The two classes are returned ALONGSIDE the merged list, and
+ *   post-cap, so the retrieval surface can rank on "did this row match the failure or
+ *   only the command" without re-deriving the split from the command string — a
+ *   re-derivation is the "second program that merely looks like the first" trap this
+ *   file's consumer (lib/error-recall-core.mjs) is structured to avoid.
  */
 export function planErrorRecall(cmd, response) {
   const { cmdWords, errWords } = collectErrorTerms(cmd, response);
   if (errWords.length === 0) return null;
-  return { terms: [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS) };
+  const terms = [...cmdWords, ...errWords].slice(0, ERROR_RECALL_MAX_TERMS);
+  // Intersect with the CAPPED list: a term the cap dropped is not in the query, so
+  // reporting it as an error term would have the surface rank on a word it never
+  // matched on.
+  const kept = new Set(terms);
+  return {
+    terms,
+    cmdWords: cmdWords.filter((t) => kept.has(t)),
+    errWords: errWords.filter((t) => kept.has(t)),
+  };
 }
 
 // ─── File Paths ──────────────────────────────────────────────────────────────

package/hook.mjs

@@ -24,9 +24,9 @@ import { readFileSync, writeFileSync, unlinkSync, readdirSync, renameSync, statS
 import { homedir } from 'os';
 import {
   inferProject, detectBashSignificance,
-  planErrorRecall, extractFilePaths, isRelatedToEpisode,
+  extractFilePaths, isRelatedToEpisode,
   makeEntryDesc, scrubSecrets, stripPrivate, EDIT_TOOLS, debugCatch, debugLog,
-  OBS_BM25, notLowSignalTitleClause, formatErrorRecallHints,
+  formatErrorRecallHints,
   MAX_HOOK_STDIN_BYTES,
 } from './utils.mjs';
 import {
@@ -49,6 +49,7 @@ import { readFastSummarySource, insertFastSummary, FAST_SUMMARY_LIMITS } from '.
 import { formatHookError } from './lib/native-binding-hint.mjs';
 import { recordHookError } from './lib/hook-telemetry.mjs';
 import { queueHookContext, queueHookSystemMessage, flushHookStdout } from './lib/hook-stdout.mjs';
+import { shouldRecallOnFailure } from './lib/tool-refusal.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import { cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, resolveDefaultMaintainOps, markAutoCompressible, selectFuzzyDedupeIds, stampDedupSuperseded, hardDeleteCandidateCount, purgeStale, recoverOrphanedChildren, recoverBuriedLessons, sweepDeferredWorkOrphans } from './lib/maintain-core.mjs';
 import { snapshotDb } from './lib/db-backup.mjs';
@@ -75,7 +76,8 @@ import { gcOldMetricShards, recordMetric } from './lib/metrics.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
 import { injectedIdsFileName, keyContextIdsFileName } from './lib/injected-ids.mjs';
 import { recordKeyContextInjection, touchKeyContextMarker } from './lib/keyctx-marker.mjs';
-import { liveObsFilterSql, recencyDecaySql } from './lib/inject-search-core.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';
@@ -482,7 +484,18 @@ async function handlePostToolUse() {
 
 // ─── Error-Triggered Recall (Tier 2 G) ─────────────────────────────────────
 
-function triggerErrorRecall(db, toolInput, response) {
+/**
+ * @param {object} db Open handle.
+ * @param {object} toolInput The failed tool's input (needs `.command`).
+ * @param {string} response The failure text.
+ * @param {{eventName?: string, metricEvent?: string}} [opts] Which hook event this is
+ *   answering. The envelope carries exactly one hookEventName and the host rejects a
+ *   mismatch, so the PostToolUseFailure path MUST pass its own — defaulting silently
+ *   would emit a PostToolUse envelope from a PostToolUseFailure hook.
+ */
+function triggerErrorRecall(db, toolInput, response, opts = {}) {
+  const eventName = opts.eventName || 'PostToolUse';
+  const metricEvent = opts.metricEvent || 'error_recall';
   try {
     const project = inferProject();
 
@@ -494,44 +507,22 @@ function triggerErrorRecall(db, toolInput, response) {
     // query degraded to ['npm','run','build'] — the command's topic, not the failure.
     // planErrorRecall still returns null when nothing usable survives (empty output, or
     // only stop words), and then we stay silent rather than query the command's topic.
-    const cmd = toolInput.command || '';
-    const plan = planErrorRecall(cmd, response);
-    if (!plan) return;
-
-    // FTS5 OR query for broader recall
-    const ftsQuery = plan.terms.map(t => `"${t.replace(/"/g, '""')}"`).join(' OR ');
-    if (!ftsQuery) return;
-
-    const nowR = Date.now();
-    const rows = db.prepare(`
-      SELECT o.id, o.type, o.title, o.lesson_learned
-      FROM observations_fts
-      JOIN observations o ON observations_fts.rowid = o.id
-      WHERE observations_fts MATCH ? AND o.project = ?
-        -- Live-row invariant, same as every other model-facing retrieval path
-        -- (hook-context obsPool/fallbackObs/keyObs, hook-memory, search-engine,
-        -- recent/search/timeline/recall-core, pre-tool-recall, user-prompt-search).
-        -- This surface INLINES rows[0].lesson_learned into the model context, so an
-        -- unfiltered SELECT handed a retracted lesson to the agent verbatim while its
-        -- correction trailed as a bare pointer. compressed_into is filtered too, not
-        -- only for symmetry: the block's own footer is a mem_get(ids=...) pointer, and a
-        -- COMPRESSED_PENDING_PURGE row is queued for deletion by maintain purge_stale,
-        -- so that pointer would resolve to nothing.
-        AND ${liveObsFilterSql('o')}
-        AND ${notLowSignalTitleClause('o')}
-      -- Decay via the shared core (P2-11): the M-1 MAX(0,…) age clamp lives there.
-      -- Fixed 14d half-life (error recency matters more than obs type here).
-      ORDER BY ${OBS_BM25}
-        * ${recencyDecaySql({ tsExpr: 'o.created_at_epoch', halfLifeSql: '1209600000.0' })}
-      LIMIT 3
-    `).all(ftsQuery, project, nowR);
+    // Selection lives in lib/error-recall-core.mjs so the offline calibration suite
+    // scores THIS statement rather than a re-typed lookalike. null ⇒ do not inject.
+    const selected = selectErrorRecall(db, {
+      cmd: toolInput.command || '',
+      response,
+      project,
+    });
+    if (!selected) return;
+    const rows = selected.rows;
 
     const out = formatErrorRecallHints(rows);
     if (out) {
       // 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: 'error_recall', returned: rows.length });
+      recordMetric(join(RUNTIME_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
@@ -539,11 +530,118 @@ function triggerErrorRecall(db, toolInput, response) {
       // flushEpisode in one handlePostToolUse, and two documents make the parser
       // fall back to plain text — which the renderer drops entirely for
       // PostToolUse. Both receipts vanished. Queue; one envelope is written at exit.
-      queueHookContext('PostToolUse', out);
+      queueHookContext(eventName, out);
     }
   } catch (e) { debugCatch(e, 'triggerErrorRecall'); }
 }
 
+/**
+ * PostToolUseFailure — the event that carries tool calls the HOST judged failed (D#170).
+ *
+ * WHY A SECOND ENTRY POINT AT ALL. `PostToolUse` does not fire for a failed tool call;
+ * Claude Code routes those here. Registering only `PostToolUse` therefore made this
+ * plugin blind to every host-flagged failure, and the only "failures" error-recall ever
+ * saw were commands that exited 0 while printing error-ish text — the classic shape
+ * being `cmd 2>&1 | tail`, where the pipe launders a failure into a success. Verified on
+ * the 2.1.241 bundle (the event and its schema) and by live probe (two genuinely failing
+ * Bash calls, one with a full stack frame, left zero trace in the episode buffer and the
+ * events table while the successful calls either side were recorded).
+ *
+ * THE PAYLOAD IS NOT PostToolUse'S. There is no `tool_response`; the failure text is in
+ * `error`, and `is_interrupt` marks a user cancellation. Reading `tool_response` here
+ * would find undefined and silently do nothing — which is exactly how this class of
+ * wiring bug stays invisible, so the field names are asserted in the tests.
+ *
+ * DELIBERATELY NARROWER THAN THE EVENT. Only `Bash` (this surface queries on a command
+ * plus its output; no other tool has that shape), only when the failure came from a
+ * PROGRAM rather than from the agent's own tool chain (lib/tool-refusal.mjs — 68.9% of
+ * host-flagged failures on the maintainer's machine were guardrails working), and NOT
+ * feeding the episode buffer. That last exclusion is scope, not oversight: episode
+ * entries flow into LLM summarisation and the bugfix save-nudge, whose behaviour under a
+ * sudden influx of failures has not been measured, and this change is already worth a
+ * 3.5x increase in this surface's firing volume.
+ *
+ * NO `isHardError` GATE HERE, AND THAT IS THE POINT — stated because review found it
+ * unwritten and it is a real semantic difference between the two entry points. On the
+ * PostToolUse path the host says nothing about success, so `isHardError` has to GUESS
+ * from vocabulary whether a command failed; here the host has already ruled, and
+ * re-deriving its verdict from the text would only discard cases. The measurable
+ * consequence: `Segmentation fault (core dumped)` and a Rust `panicked at` both score
+ * `isHardError === false` (the first has no error word, the second loses on `\bpanic\b`'s
+ * word boundary), so until this event they could not reach term extraction at all. They
+ * can now. That is the coverage this event was wired for, not an oversight — but it does
+ * mean ERROR_NAMER_RE's `SIG…`/`panicked` alternatives went live here first.
+ *
+ * Off switch: CLAUDE_MEM_ERROR_RECALL_ON_FAILURE=off.
+ */
+async function handlePostToolFailure() {
+  if (String(process.env.CLAUDE_MEM_ERROR_RECALL_ON_FAILURE || '').toLowerCase() === 'off') return;
+
+  let raw;
+  try { raw = await readStdin(); } catch { return; }
+  let hookData;
+  try { hookData = JSON.parse(raw.text); } catch { return; }
+
+  const { tool_name, tool_input, error, is_interrupt } = hookData || {};
+  // The manifest matcher already scopes this to Bash. Re-checking is not redundancy for
+  // its own sake: install.mjs writes a SECOND registration into the user's settings.json,
+  // and a hand-edited matcher there would otherwise hand this path an Edit or a Read.
+  //
+  // A payload whose SHAPE is wrong is recorded, not just dropped. Tests pin the field
+  // names against a payload we construct; they cannot see the host renaming `error` or
+  // changing `tool_name`'s type, and this whole path fails silently by design — the
+  // v3.60 binding outage ran four days on exactly that combination, and hook-errors/ was
+  // the only window that would have shown it. Volume is bounded by the recorder's
+  // 14-day retention and one short line per fire.
+  if (tool_name !== undefined && typeof tool_name !== 'string') {
+    recordHookError(
+      'post-tool-failure:tool_name-type',
+      new TypeError(`tool_name is ${Array.isArray(tool_name) ? 'array' : typeof tool_name}, expected string`),
+      RUNTIME_DIR,
+    );
+    return;
+  }
+  if (tool_name !== 'Bash') return;
+  if (error !== undefined && typeof error !== 'string') {
+    recordHookError(
+      'post-tool-failure:error-type',
+      new TypeError(`error is ${typeof error}, expected string — host payload shape may have changed`),
+      RUNTIME_DIR,
+    );
+    return;
+  }
+
+  const verdict = shouldRecallOnFailure({ error, is_interrupt });
+  if (!verdict.ok) return;
+
+  const toolInput = typeof tool_input === 'string' ? tryParseJson(tool_input) : (tool_input || {});
+  if (typeof toolInput?.command !== 'string' || !toolInput.command) return;
+
+  let db = null;
+  try {
+    db = openDb();
+    if (!db) return;
+    // Same selection, same rendering, same core as the PostToolUse path — only the event
+    // name on the envelope differs. A second copy of the query here is the twin-drift
+    // defect this project keeps paying for.
+    triggerErrorRecall(db, toolInput, error, {
+      eventName: 'PostToolUseFailure',
+      // A separate counter, so the volume this event adds is readable on its own rather
+      // than merged into the existing surface's total. The citation funnel deliberately
+      // keeps ONE `error_recall` surface: these are the same injections to the model, and
+      // splitting the cite-rate denominator would make both halves too small to read.
+      metricEvent: 'error_recall_failure',
+    });
+  } catch (e) {
+    debugCatch(e, 'handlePostToolFailure');
+  } finally {
+    // No flushHookStdout() here: the single flush after the event switch owns writing
+    // the envelope, and two flush points is how a process ends up emitting two JSON
+    // documents — the degradation that made BOTH receipts vanish in v3.68.
+    if (db) try { db.close(); } catch {}
+  }
+}
+
 // ─── Stop Handler ───────────────────────────────────────────────────────────
 
 async function handleStop() {
@@ -2004,6 +2102,8 @@ function normalizeToolResponse(toolResponse) {
 try {
   switch (event) {
     case 'post-tool-use':    await handlePostToolUse(); break;
+    // Host-flagged tool failures arrive on their own event; PostToolUse never sees them.
+    case 'post-tool-failure': await handlePostToolFailure(); break;
     case 'session-start':    await handleSessionStart(); break;
     case 'pre-compact':      await handlePreCompactDispatch(); break;
     case 'stop':             await handleStop(); break;

package/hooks/hooks.json

@@ -84,6 +84,18 @@
         ]
       }
     ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-launcher.mjs\" hook.mjs post-tool-failure",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "*",

package/install.mjs

@@ -718,6 +718,19 @@ const memPostToolRecall = {
   }]
 };
 
+// D#170. A SEPARATE event from PostToolUse, not a variant of it: Claude Code does not
+// fire PostToolUse for a tool call it judged failed, so without this registration the
+// plugin never sees a single host-flagged failure. Matched on Bash alone — the surface
+// it feeds queries on a command plus its output, and no other tool has that shape.
+const memPostToolFailure = {
+  matcher: 'Bash',
+  hooks: [{
+    type: 'command',
+    command: nodeHook('hook.mjs', 'post-tool-failure'),
+    timeout: 5
+  }]
+};
+
 const memSessionStart = {
   matcher: 'startup|clear|compact',
   hooks: [{
@@ -819,6 +832,7 @@ const memPreAgentInject = {
 const hookConfigs = {
   PreToolUse: [memPreToolRecall, memPreSkillBridge, memPreAgentInject],
   PostToolUse: [memPostToolUse, memPostToolRecall],
+  PostToolUseFailure: [memPostToolFailure],
   PreCompact: [memPreCompact],
   SessionStart: [memSessionStart],
   Stop: [memStop],

package/lib/citation-tracker.mjs

@@ -900,16 +900,35 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
   // literal +1: a FIRST resolution counts the obs into the denominator (1); a
   // cross-turn LATE upgrade of an already-resolved obs must NOT re-count it (0), else
   // cite-rate reads N/2 for a single injected-then-cited obs instead of N/1.
+  // v46 (D#159): stamp decay_seen_at_first_cite on the FIRST citation only.
+  //
+  // `cited_count = 0` is evaluated against the row's PRE-UPDATE state (SQLite reads
+  // the old values on the right-hand side of every SET), so it identifies the first
+  // promote even though the same statement increments the counter. Once set, the
+  // CASE re-writes the column to itself and later citations cannot move it.
+  //
+  // The stamped value INCLUDES this resolution (`decay_seen_count + @seenInc`), i.e.
+  // "this memory was cited on the Nth time the decay loop saw it" — so 1 means cited
+  // immediately, and a large N means it was injected-and-ignored N-1 times first.
+  // That is exactly the quantity a future "stop injecting after K silent decays"
+  // gate must be validated against.
+  //
+  // NAMED parameters: this statement now binds the same value twice, and a positional
+  // list would silently renumber if a clause were ever reordered.
   const updatePromote = db.prepare(`
     UPDATE observations
-       SET importance = MIN(?, COALESCE(importance, 1) + 1),
+       SET importance = MIN(@cap, COALESCE(importance, 1) + 1),
            cited_count = cited_count + 1,
            uncited_streak = 0,
            demoted_at = NULL,
-           last_decided_session_id = ?,
-           last_cited_session_id = ?,
-           decay_seen_count = decay_seen_count + ?
-     WHERE id = ?
+           last_decided_session_id = @session,
+           last_cited_session_id = @session,
+           decay_seen_count = decay_seen_count + @seenInc,
+           decay_seen_at_first_cite = CASE
+             WHEN COALESCE(cited_count, 0) = 0 THEN decay_seen_count + @seenInc
+             ELSE decay_seen_at_first_cite
+           END
+     WHERE id = @id
   `);
   const updateStreakOnly = db.prepare(`
     UPDATE observations
@@ -959,7 +978,9 @@ export function applyCitationDecay(db, project, injectedIds, citedIds, sessionId
         // obs already in the injected denominator, so re-counting it would inflate both
         // decay_seen_count and the funnel's injected_n (cite-rate would read N/2, not N/1).
         const firstResolution = !decidedThisSession;
-        updatePromote.run(IMPORTANCE_CAP, sessionId, sessionId, firstResolution ? 1 : 0, id);
+        updatePromote.run({
+          cap: IMPORTANCE_CAP, session: sessionId, seenInc: firstResolution ? 1 : 0, id,
+        });
         promoted++;
         if (firstResolution) touched++;
       } else {