claude-mem-lite 6.13.6 → 6.14.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.13.6",
+      "version": "6.14.0",
       "source": "./",
       "homepage": "https://github.com/sdsrss/claude-mem-lite",
       "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": "6.13.6",
+  "version": "6.14.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

@@ -138,7 +138,7 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 |----------|--------|-------|
 | **Linux** | Supported | Primary development and testing platform; the whole CI matrix runs here |
 | **macOS** | Supported | Fully compatible (Intel and Apple Silicon) |
-| **Windows** | Installs, not CI-covered | The MCP server, the CLI and the `node` hooks work (`better-sqlite3` ships `win32-x64` and `win32-arm64` prebuilds, so nothing is compiled). **Three hook commands run under `bash`** — `setup.sh`, `post-tool-use.sh`, `pre-agent-inject.sh` — and need Git for Windows or WSL on `PATH`; `claude-mem-lite doctor` reports it when `bash` cannot be found. No GitHub Actions runner exercises Windows, so this rests on user reports ([#28](https://github.com/sdsrss/claude-mem-lite/issues/28)), not on a green pipeline |
+| **Windows** | Installs, not CI-covered | The MCP server, the CLI and the `node` hooks work (`better-sqlite3` ships `win32-x64` and `win32-arm64` prebuilds, so nothing is compiled). **Four hook commands run under `bash`** — `setup.sh`, `post-tool-use.sh`, `pre-agent-inject.sh`, `pre-tool-recall-bash.sh` — and need Git for Windows or WSL on `PATH`; `claude-mem-lite doctor` reports it when `bash` cannot be found. No GitHub Actions runner exercises Windows, so this rests on user reports ([#28](https://github.com/sdsrss/claude-mem-lite/issues/28)), not on a green pipeline |
 | **WSL2** | Untested | Linux under the hood, so it should behave as the Linux row; nobody has reported either way |
 
 From v5.1.0 through v6.1.0, `package.json` declared `os: ["darwin", "linux"]`. That is an npm *install*
@@ -152,7 +152,7 @@ is still outside it gets a message naming both sides of the mismatch instead of
 - **Node.js** >= 22
 - **Claude Code** CLI installed and configured (`claude` command available)
 - **SQLite3** support (provided by `better-sqlite3` 13, which ships prebuilt binaries for 8 platforms — no compiler needed on any of them; a platform it has no prebuild for falls back to building from source)
-- **Platform**: Linux or macOS; Windows installs and runs but is not CI-covered and needs Git Bash or WSL for three hooks (see [Platform Support](#platform-support))
+- **Platform**: Linux or macOS; Windows installs and runs but is not CI-covered and needs Git Bash or WSL for four hooks (see [Platform Support](#platform-support))
 
 ## Installation
 
@@ -237,6 +237,29 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
     repos/               # Shallow-cloned source repos
 ```
 
+## Upgrading to 6.14.0
+
+**Five defaults change; three have an off switch.** No schema change and no migration: an
+older build still opens the database, so reverting everything is pinning
+`claude-mem-lite@6.13.6`.
+
+- **File recall now also fires before Bash commands that view or write a file** (`cat`,
+  `sed -n`, `head`; `sed -i`, `cat > f`, a python patch) — on recent models most reads and
+  edits go through Bash, and the recall face with the highest measured cite rate had almost
+  stopped firing. A **fourth hook command runs under `bash`**, `pre-tool-recall-bash.sh`; on
+  Windows it needs Git Bash or WSL like the other three. Off: `CLAUDE_MEM_BASH_RECALL=off`.
+- **Error recall stays quiet on a failure you meant to cause** (running a test file you just
+  wrote or edited) and on commands that only print data and exit 0. No switch; pin 6.13.6 to
+  revert. `error_recall` counts in `citation-stats` drop from here on — do not compare them
+  across this version.
+- **Auto-captured lessons must quote what happened.** The episode summarizer ignores
+  mutation-test probes, the agent's own failing inline scripts and subagent calls that do not
+  edit the project, and a lesson that quotes nothing from its window is dropped (the event is
+  kept, at importance 1). Off: `CLAUDE_MEM_EPISODE_INPUT_FILTER=off` /
+  `CLAUDE_MEM_LESSON_GROUNDING=off`.
+- **The `[mem] episode flushed: N entries` line is no longer injected.** The hints that
+  followed it are unchanged.
+
 ## Upgrading to 6.13.0
 
 **One default changes: SessionStart no longer injects `### Key Events`.** That section listed
@@ -916,6 +939,9 @@ claude-mem-lite.
 | `CLAUDE_MEM_DEBUG` | Enable debug logging (`1` to enable). | _(disabled)_ |
 | `MEM_QUIET_HOOKS` | Low-noise hooks. `1` drops the `File Lessons` / `Key Context` sections from SessionStart injection, the lesson suffix from `[mem] Related memories`, and the `WHEN TO USE` / `Decision rules` blocks from MCP server instructions. IDs and the `Recent` table still surface so `mem_get(ids=[…])` remains reachable. Intended for users running the invited-memory adopt path or who otherwise want minimal auto-injection. **Since v2.82.0 this env no longer gates auto-adopt — use `MEM_NO_AUTO_ADOPT=1` for that.** | _(disabled)_ |
 | `CLAUDE_MEM_SESSION_EVENTS` | `1`/`on` restores the SessionStart `### Key Events` section (recent high-importance rows from the `events` table). **Off by default since v6.13.0**: an audit of 30 events read 2 accurate and 16 wrong. The UserPromptSubmit events block and PreToolUse recall are query-matched and stay on; `mem_search` still reaches every event. | _(off)_ |
+| `CLAUDE_MEM_EPISODE_INPUT_FILTER` | What the episode summarizer may learn from. A subagent's tool calls stay out of the episode buffer unless they edit a file inside the project, and mutation probes (mutate → RED run → restore) and the agent's own failing inline scripts (a patch's `anchor not found`) are dropped before a window is saved or summarized — replayed over the 30 audited events, this removes 3 of the 16 that were wrong outright; with `CLAUDE_MEM_LESSON_GROUNDING` none of the 16 lessons is injected. `off` restores the unfiltered input. | _(on)_ |
+| `CLAUDE_MEM_BASH_RECALL` | File recall before a Bash command that views (`cat`, `sed -n`, `head`…) or writes (`sed -i`, `cat > f`, a python patch…) a file, like the Read / Edit recall. A bash prefilter keeps Node from starting for other commands. `off` disables this leg only. | _(on)_ |
+| `CLAUDE_MEM_LESSON_GROUNDING` | An auto-captured event keeps its lesson only when the lesson quotes the window's own diagnosis (a failing output line, a comment the edit added, or the commit message); otherwise the row is kept without it at importance 1, below every injection face. `off` keeps unquoted lessons. | _(on)_ |
 | `MEM_NO_AUTO_ADOPT` | Global opt-out for auto-adopt (v2.82.0+). `1` prevents the per-SessionStart auto-write of the `CLAUDE.md` managed block across **all** projects. For per-project opt-out use `claude-mem-lite adopt --disable` instead (writes a durable `<memdir>/.mem-no-auto-adopt` sentinel that survives marker deletion). | _(disabled)_ |
 | `MEM_NO_ADOPT_HINT` | Silences the one-line "Invited-memory 未启用：`claude-mem-lite adopt`…" hint that SessionStart appends when the current project hasn't been adopted. Since v2.82.1 auto-adopt runs on every SessionStart for any install path, so this hint typically surfaces only when you've explicitly opted out (`MEM_NO_AUTO_ADOPT=1` or `claude-mem-lite adopt --disable`). | _(disabled)_ |
 

package/README.zh-CN.md

@@ -103,7 +103,7 @@
 |------|------|------|
 | **Linux** | 支持 | 主要开发和测试平台；整个 CI 矩阵都跑在这里 |
 | **macOS** | 支持 | 完全兼容（Intel 和 Apple Silicon） |
-| **Windows** | 可安装，但无 CI 覆盖 | MCP server、CLI 和 `node` 类 hook 均可用（`better-sqlite3` 自带 `win32-x64` / `win32-arm64` 预编译产物，无需编译）。**有三个 hook 命令走 `bash`** —— `setup.sh`、`post-tool-use.sh`、`pre-agent-inject.sh` —— 需要 PATH 上有 Git for Windows 或 WSL；`bash` 找不到时 `claude-mem-lite doctor` 会报出来。GitHub Actions 没有 Windows runner，所以这一行依据的是用户报告（[#28](https://github.com/sdsrss/claude-mem-lite/issues/28)）而不是绿色流水线 |
+| **Windows** | 可安装，但无 CI 覆盖 | MCP server、CLI 和 `node` 类 hook 均可用（`better-sqlite3` 自带 `win32-x64` / `win32-arm64` 预编译产物，无需编译）。**有四个 hook 命令走 `bash`** —— `setup.sh`、`post-tool-use.sh`、`pre-agent-inject.sh`、`pre-tool-recall-bash.sh` —— 需要 PATH 上有 Git for Windows 或 WSL；`bash` 找不到时 `claude-mem-lite doctor` 会报出来。GitHub Actions 没有 Windows runner，所以这一行依据的是用户报告（[#28](https://github.com/sdsrss/claude-mem-lite/issues/28)）而不是绿色流水线 |
 | **WSL2** | 未测试 | 底层就是 Linux，预期与 Linux 行一致；但无人报告过实际结果 |
 
 v5.1.0 到 v6.1.0 之间，`package.json` 声明的是 `os: ["darwin", "linux"]`。那是 npm 的**安装**门禁，不是运行时检查：
@@ -116,7 +116,7 @@ v5.1.0 到 v6.1.0 之间，`package.json` 声明的是 `os: ["darwin", "linux"]`
 - **Node.js** >= 22（v4.0.0 起：better-sqlite3 13 要求 >=22，Node 20 已于 2026-04 EOL；`package.json` 的 `engines` 是唯一事实来源）
 - **Claude Code** CLI 已安装并配置（`claude` 命令可用）
 - **SQLite3** 支持（由 `better-sqlite3` 13 提供，它自带 8 个平台的预编译产物，这些平台上都不需要编译器；没有对应预编译产物的平台才会回退到源码编译）
-- **平台**：Linux 或 macOS；Windows 可安装运行，但无 CI 覆盖，且三个 hook 需要 Git Bash 或 WSL（参见[平台支持](#平台支持)）
+- **平台**：Linux 或 macOS；Windows 可安装运行，但无 CI 覆盖，且四个 hook 需要 Git Bash 或 WSL（参见[平台支持](#平台支持)）
 
 ## 安装
 
@@ -199,6 +199,23 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
     repos/               # 浅克隆的源代码仓库
 ```
 
+## 升级到 6.14.0
+
+**五个默认行为变化，其中三个有关闭开关。** 没有 schema 变更、没有迁移：旧版本仍能打开数据库，
+全部回退就是固定到 `claude-mem-lite@6.13.6`。
+
+- **查看或写入文件的 Bash 命令执行前，也会做文件召回**（`cat`、`sed -n`、`head`；`sed -i`、
+  `cat > f`、python 补丁）。新模型的读写大多走 Bash，实测引用率最高的召回面几乎不再触发。
+  **第四个 hook 命令走 `bash`**：`pre-tool-recall-bash.sh`；在 Windows 上与另外三个一样需要
+  Git Bash 或 WSL。关闭：`CLAUDE_MEM_BASH_RECALL=off`。
+- **error recall 不再回应你故意制造的失败**（刚写好或刚改过的测试文件跑红），也不回应只打印数据、
+  退出码为 0 的命令。没有开关，回退请固定 6.13.6。从这个版本起 `citation-stats` 里的
+  `error_recall` 计数会下降，不要跨版本直接比较。
+- **自动捕获的教训必须引用原文。** episode 摘要器忽略变异测试探针、agent 自己失败的内联脚本，以及
+  不修改项目的子代理调用；不引用窗口内任何原文的教训会被丢弃（event 保留，importance 降为 1）。
+  关闭：`CLAUDE_MEM_EPISODE_INPUT_FILTER=off` / `CLAUDE_MEM_LESSON_GROUNDING=off`。
+- **不再注入 `[mem] episode flushed: N entries` 这一行。** 它后面的提示不变。
+
 ## 升级到 6.13.0
 
 **只有一个默认行为变化：SessionStart 不再注入 `### Key Events`。** 这一节在每个会话开头列出
@@ -702,6 +719,9 @@ npm run benchmark:gate    # CI 门控：指标回退超过 5% 容差时失败
 | `CLAUDE_MEM_DEBUG` | 启用调试日志（设为 `1` 启用）。 | _(禁用)_ |
 | `MEM_QUIET_HOOKS` | 低噪声 hook。设为 `1` 时，SessionStart 注入去掉 `File Lessons` / `Key Context` 两节，`[mem] Related memories` 去掉 lesson 后缀，MCP server instructions 去掉 `WHEN TO USE` / `Decision rules` 两段。ID 与 `Recent` 表仍保留，`mem_get(ids=[…])` 可继续展开细节。适用于启用了 invited-memory adopt 流程或偏好最小化自动注入的用户。**v2.82.0 起此 env 不再阻挡 auto-adopt——如需关闭 auto-adopt 用 `MEM_NO_AUTO_ADOPT=1`。** | _(禁用)_ |
 | `CLAUDE_MEM_SESSION_EVENTS` | 设为 `1`/`on` 时恢复 SessionStart 的 `### Key Events` 一节（`events` 表中最近的高重要度条目）。**v6.13.0 起默认关闭**：对 30 条 event 的核验只有 2 条属实、16 条错误。UserPromptSubmit 的 events 块与 PreToolUse 召回按查询匹配，保持开启；`mem_search` 仍可检索全部 event。 | _(关闭)_ |
+| `CLAUDE_MEM_EPISODE_INPUT_FILTER` | 决定 episode 摘要器能从哪些输入里学。子代理的工具调用不进入 episode 缓冲（修改项目内文件的除外）；变异探针（改文件 → 跑红 → 还原）和 agent 自己失败的内联脚本（补丁的 `anchor not found`）在保存或摘要前被剔除——在 30 条已核验 event 上重放，这一项直接去掉 16 条错误中的 3 条；配合 `CLAUDE_MEM_LESSON_GROUNDING`，16 条错误教训一条都不会被注入。设为 `off` 恢复未过滤的输入。 | _(开启)_ |
+| `CLAUDE_MEM_BASH_RECALL` | 在查看（`cat`、`sed -n`、`head`…）或写入（`sed -i`、`cat > f`、python 补丁…）文件的 Bash 命令执行前做文件召回，与 Read / Edit 召回相同。bash 预过滤让其他命令不启动 Node。设为 `off` 只关闭这一路。 | _(开启)_ |
+| `CLAUDE_MEM_LESSON_GROUNDING` | 自动捕获的 event 只有在教训引用了本窗口自己的诊断文字（失败输出行、编辑新增的注释或提交信息）时才保留教训；否则保留这一行但去掉教训，importance 降为 1，低于所有注入面的门槛。设为 `off` 保留未引用原文的教训。 | _(开启)_ |
 | `MEM_NO_AUTO_ADOPT` | auto-adopt 全局关闭开关（v2.82.0+）。设为 `1` 阻止每次 SessionStart 在**所有**项目自动写入 `CLAUDE.md` 托管块。项目级关闭走 `claude-mem-lite adopt --disable`（写 `<memdir>/.mem-no-auto-adopt` 哨兵，存活于 marker 删除）。 | _(禁用)_ |
 | `MEM_NO_ADOPT_HINT` | 静音当前项目未 adopt 时 SessionStart 追加的那一行 "Invited-memory 未启用…" 提示。v2.82.1 起任何安装路径每次 SessionStart 都自动 adopt，所以该提示一般只在你显式 opt out（`MEM_NO_AUTO_ADOPT=1` 或 `claude-mem-lite adopt --disable`）的项目才会出现。 | _(禁用)_ |
 

package/bash-utils.mjs

@@ -9,6 +9,8 @@ import { basename } from 'path';
 // import this file. Cold-start scripts are unaffected — scripts/pre-tool-recall.js
 // deliberately imports nothing from the utils.mjs barrel that re-exports this.
 import { toolEditPath } from './lib/file-edge-match.mjs';
+import { bashFileTargets, isTransientPath, isScratchCommandPath } from './lib/bash-file-targets.mjs';
+export { isTransientPath };
 
 // Read/search commands whose output legitimately contains "error"-like keywords without
 // being a failure. Matched against the PRIMARY command (see isReadOnlyCommand).
@@ -522,11 +524,89 @@ function commandKind(cmd, depth = 0) {
   return sawRead ? 'read' : 'neutral';
 }
 
+// ─── Data printers and writers (error-recall N2) ─────────────────────────────
+
+// Interpreters whose INLINE program (`-e`/`-c`/a heredoc on stdin) is the agent's own
+// throwaway code. Run by a script FILE they are a program like any other.
+const INLINE_INTERPRETER_RE = /^(?:node|nodejs|bun|python(?:\d+(?:\.\d+)?)?)$/;
+
+// A redirection operator token (`>`, `2>>`, `&>`, `<`, `<<-`), optionally glued to its target.
+const REDIRECT_TOKEN_RE = /^(?:\d*|&)(?:>>?\|?|<<?-?)(.*)$/;
+
+/**
+ * True when one simple command runs an INLINE program or prints a CI log — the shapes
+ * whose output at exit 0 is data (a transcript line, a log excerpt, a script's own
+ * `assert`), not a failure of anything the corpus could explain.
+ */
+function isPrinterElement(text) {
+  const toks = shellWords(text);
+  let i = 0;
+  while (i < toks.length && (/^\w+=/.test(toks[i]) || CMD_WRAPPERS.has(toks[i]))) i++;
+  const prog = toks[i];
+  if (!prog) return false;
+  const args = toks.slice(i + 1);
+  // `gh run view … --log[-failed]`: a CI log is somebody else's failure, reprinted. `--json`
+  // is gh's structured READ (list/view/status only), typically feeding a run id to the former.
+  if (prog === 'gh')
+    return args.some((a) => a === '--log' || a === '--log-failed' || /^--json(?:=|$)/.test(a));
+  if (!INLINE_INTERPRETER_RE.test(prog)) return false;
+  const py = prog.startsWith('python');
+  for (let k = 0; k < args.length; k++) {
+    const a = args[k];
+    if (py ? a === '-c' || a === '-' : /^-(?:e|p|pe|ep)$|^--(?:eval|print)(?:=|$)/.test(a)) return true;
+    const redirect = REDIRECT_TOKEN_RE.exec(a);
+    if (redirect) {
+      if (!redirect[1]) k++; // `<< EOF` / `> f`: the next word is the operand, not a script
+      continue;
+    }
+    // A positional is a script file (or `-m`'s module): a program, not an inline print.
+    if (!a.startsWith('-') || (py && a === '-m')) return false;
+  }
+  // No positional at all: the program comes from stdin, i.e. a heredoc.
+  return /<</.test(text);
+}
+
+/** 'print' | 'read' | 'neutral' | 'other' — commandKind with printers admitted. */
+function printKind(cmd, depth = 0) {
+  if (depth > MAX_SUBST_DEPTH) return 'other';
+  const parsed = splitStatements(cmd);
+  if (!parsed) return 'other';
+  let sawPrint = false;
+  for (const body of parsed.subs) {
+    const kind = printKind(body, depth + 1);
+    if (kind === 'other') return 'other';
+    if (kind === 'print') sawPrint = true;
+  }
+  for (const pipeline of parsed.statements) {
+    for (const element of pipeline) {
+      if (isPrinterElement(element)) {
+        sawPrint = true;
+        continue;
+      }
+      if (classifySimpleCommand(element) === 'other') return 'other';
+    }
+  }
+  return sawPrint ? 'print' : 'read';
+}
+
+/**
+ * True when the command's only programs are inline scripts (`node -e/-p`, `python3 -c`,
+ * `python3 - <<EOF`, a heredoc-fed interpreter) or `gh … --log[-failed]`, plus reads
+ * (isReadOnlyCommand's verbs) and neutral set-up. Parsed with the same statement/pipeline
+ * splitter, so `node -e '…'; npm test` and `python3 - <<PY … PY` followed by a vitest run
+ * are NOT printers: the real run is judged on its own.
+ *
+ * Deliberately a SEPARATE predicate from isReadOnlyCommand, not a new verb in it: that one
+ * also decides `isError` for the episode narrative and the bugfix save-nudge, and an inline
+ * script that crashes is a real error there. Only error-recall's injection is narrowed.
+ */
+export function isDataPrintingCommand(cmd) {
+  if (typeof cmd !== 'string' || !cmd) return false;
+  return printKind(stripNonCommands(cmd)) === 'print';
+}
+
 // Paths excluded from observation capture (ephemeral / virtual filesystems) — applied
 // uniformly to both command-parsed paths and direct file_path/path/filePath fields.
-function isExcludedPath(p) {
-  return p.startsWith('/dev/') || p.startsWith('/proc/') || p.startsWith('/tmp/');
-}
 
 /**
  * Detect significance signals in a Bash command and its response.
@@ -887,16 +967,24 @@ export function planErrorRecall(cmd, response) {
 // ─── File Paths ──────────────────────────────────────────────────────────────
 
 /**
- * Extract file paths from tool input (file_path, path, filePath, or command args).
- * Deduplicates and excludes /dev/, /proc/, and /tmp/ paths.
+ * Files a tool call touched, split so callers can tell an edit from a read.
+ * `files`: every file edge (direct path fields + all Bash targets);
+ * `writes`: the subset a Bash command WROTE (`sed -i`, `cat > f`, a python patch, …) —
+ * the Bash counterpart of an Edit/Write `file_path`, consumed via `entryEditedFiles`.
  * @param {object} input Tool input object
- * @returns {string[]} Unique array of file paths
+ * @param {{cwd?: string|null, projectDir?: string|null}} [opts] the hook's `cwd`, to resolve
+ *   relative Bash paths; the project root, whose files count even when it lives under /tmp
+ * @returns {{files: string[], writes: string[]}}
  */
-export function extractFilePaths(input) {
+export function extractFileTargets(input, opts = {}) {
   const paths = [];
-  // Direct fields (Edit/Write file_path) are kept unconditionally — an explicit edit to a
+  const writes = [];
+  if (!input || typeof input !== 'object') return { files: [], writes: [] };
+  // Direct fields (Edit/Write file_path) are kept even under /tmp — an explicit edit to a
   // /tmp path is real work the user chose to make, unlike a /tmp path that merely appears as
   // a transient argument inside a Bash command (excluded as noise in the command branch below).
+  // Session-scoped paths (isTransientPath) are the exception: they are the agent's own
+  // scratch, not the user's work.
   //
   // `toolEditPath`, not a fourth hand-spelling of the same rule: this function knew
   // file_path/path/filePath and not `notebook_path`, while hooks.json matches PostToolUse
@@ -905,27 +993,39 @@ export function extractFilePaths(input) {
   // files, so the observation built from it got no observation_files edge and no file-keyed
   // recall could reach it. Same root cause as R12 B-2; the fourth site, and the one its
   // own follow-up note did not name.
-  const editedPath = toolEditPath(input);
-  if (editedPath) paths.push(editedPath);
-  if (input.path) paths.push(input.path);
-  if (input.filePath) paths.push(input.filePath);
-  if (input.command) {
-    // Match absolute paths; extension optional to support Makefile, Dockerfile etc.
-    const match = input.command.match(/(?:^|\s)(\/[\w./-]+\w)/g);
-    if (match) {
-      for (const m of match) {
-        const p = m.trim();
-        if (
-          !isExcludedPath(p) &&
-          // Skip single-component paths like /exit, /clear — likely slash commands, not files
-          (p.indexOf('/', 1) !== -1 || /\.\w+$/.test(p))
-        ) {
-          paths.push(p);
-        }
-      }
+  for (const p of [toolEditPath(input), input.path, input.filePath]) {
+    if (typeof p === 'string' && p && !isTransientPath(p)) paths.push(p);
+  }
+  if (typeof input.command === 'string' && input.command) {
+    // Shell-aware: cwd prefixes, relative and quoted paths, write-verb targets and
+    // interpreter-script literals (lib/bash-file-targets.mjs). The `cd` target itself is
+    // never an edge — it made every `cd <repo> && …` command look like it touched the
+    // repo root and nothing else.
+    const keep = (p) =>
+      !isScratchCommandPath(p, opts.projectDir) &&
+      !isTransientPath(p) &&
+      // Skip single-component paths like /exit, /clear — likely slash commands, not files
+      (p.indexOf('/', 1) !== -1 || /\.\w+$/.test(p));
+    const t = bashFileTargets(input.command, { cwd: opts.cwd || null });
+    for (const p of t.writes) {
+      if (!keep(p)) continue;
+      writes.push(p);
+      paths.push(p);
     }
+    for (const p of [...t.reads, ...t.mentions]) if (keep(p)) paths.push(p);
   }
-  return [...new Set(paths)];
+  return { files: [...new Set(paths)], writes: [...new Set(writes)] };
+}
+
+/**
+ * Extract file paths from tool input (file_path, path, filePath, or command args).
+ * Deduplicates and excludes /dev/, /proc/, /tmp/ command paths and session-scoped paths.
+ * @param {object} input Tool input object
+ * @param {{cwd?: string|null}} [opts] the hook's `cwd`, to resolve relative Bash paths
+ * @returns {string[]} Unique array of file paths
+ */
+export function extractFilePaths(input, opts = {}) {
+  return extractFileTargets(input, opts).files;
 }
 
 // ─── Episode Logic ───────────────────────────────────────────────────────────

package/cli/doctor.mjs

@@ -34,7 +34,7 @@ export async function cmdDoctor(db, args) {
         WHERE s.project = ?
           AND p.prompt_text IS NOT NULL
           AND length(p.prompt_text) >= 15
-        ORDER BY p.created_at_epoch DESC
+        ORDER BY p.created_at_epoch DESC, p.id DESC
         LIMIT ?
       `,
         )

package/hook-context.mjs

@@ -850,11 +850,11 @@ export function buildSessionContextLines(
       `
     SELECT id, title, priority,
            ROW_NUMBER() OVER (
-             ORDER BY priority DESC, created_at_epoch ASC
+             ORDER BY priority DESC, created_at_epoch ASC, id ASC
            ) AS ordinal
     FROM deferred_work
     WHERE project = ? AND status = 'open'
-    ORDER BY priority DESC, created_at_epoch ASC
+    ORDER BY priority DESC, created_at_epoch ASC, id ASC
     LIMIT 5
   `,
     )

package/hook-episode.mjs

@@ -14,7 +14,7 @@ import {
   statSync,
   constants as fsConstants,
 } from 'fs';
-import { inferProject, EDIT_TOOLS } from './utils.mjs';
+import { inferProject, isEditEntry } from './utils.mjs';
 import { RUNTIME_DIR } from './hook-shared.mjs';
 
 /**
@@ -454,7 +454,7 @@ export function explainSignificance(episode) {
   const base = { readCount, grepCount, grepDecisive: false };
 
   // 1. File edits → always significant (code changes matter)
-  if (entries.some((e) => EDIT_TOOLS.has(e.tool))) return { ...base, significant: true, rule: 1 };
+  if (entries.some(isEditEntry)) return { ...base, significant: true, rule: 1 };
 
   // 2. Test/build errors → significant (actionable failures)
   // Plain bash errors without edits are noise (e.g. typos, exploration errors)

package/hook-handoff.mjs

@@ -10,7 +10,7 @@ import {
   isSpecificTerm,
   scrubSecrets,
   LOW_SIGNAL_TITLE,
-  EDIT_TOOLS,
+  isEditEntry,
   isMetaTriggerPrompt,
   notLowSignalTitleClause,
   safeText,
@@ -262,7 +262,7 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   if (episodeSnapshot?.entries) {
     const seenDescs = new Set();
     const pendingDescs = episodeSnapshot.entries
-      .filter((e) => e.isError || EDIT_TOOLS.has(e.tool))
+      .filter((e) => e.isError || isEditEntry(e))
       .map((e) => e.desc)
       .filter((d) => {
         if (seenDescs.has(d)) return false;

package/hook-llm.mjs

@@ -14,7 +14,8 @@ import {
   computeMinHash,
   estimateJaccardFromMinHash,
   cjkBigrams,
-  EDIT_TOOLS,
+  isEditEntry,
+  entryEditedFiles,
   LOW_SIGNAL_TITLE,
   debugCatch,
   debugLog,
@@ -55,6 +56,7 @@ import { DAY_MS } from './lib/time-constants.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 import { recoverChildrenOf } from './lib/maintain-core.mjs';
 import { MEMORY_INPUT_GUARD } from './lib/memory-input-guard.mjs';
+import { isLessonGrounded, lessonGroundingEnabled } from './lib/episode-input-filter.mjs';
 
 /**
  * Retract a pre-saved observation this worker created moments ago, after the Haiku
@@ -97,6 +99,31 @@ export function retractPreSavedObs(db, obsId, where) {
 // Set lookup is O(1) — authoritative source is lib/activity.mjs::EVENT_TYPES.
 const EVENT_TYPE_SET = new Set(EVENT_TYPES);
 
+// ─── The window's own diagnosis (D#69) ──────────────────────────────────────
+//
+// Episode entries carry `diag`: failing output lines, comment blocks an edit added, a
+// commit message — captured at PostToolUse by lib/episode-input-filter.mjs. The prompt
+// shows them verbatim and asks the lesson to quote one; isLessonGrounded then CHECKS it.
+const DIAGNOSIS_MAX_LINES = 12;
+
+/** Distinct diagnosis lines of an episode, in order, capped. Exported for tests. */
+export function episodeDiagnosis(episode) {
+  const out = [];
+  for (const e of Array.isArray(episode?.entries) ? episode.entries : []) {
+    for (const l of Array.isArray(e?.diag) ? e.diag : []) {
+      if (typeof l === 'string' && l && !out.includes(l)) out.push(l);
+      if (out.length >= DIAGNOSIS_MAX_LINES) return out;
+    }
+  }
+  return out;
+}
+
+function diagnosisBlock(diag) {
+  return diag.length
+    ? `DIAGNOSIS (verbatim from this window — the only text a lesson may rest on):\n${diag.map((l, i) => `D${i + 1}. ${l}`).join('\n')}`
+    : 'DIAGNOSIS: (none — no failing output, added comment or commit message in this window; lesson_learned must be null)';
+}
+
 // ─── Memory-input injection guard (cso F#4 follow-up, EverAlgo-validated) ────
 //
 // Defense-in-depth against memory-poisoning: episode/summary prompts ingest
@@ -630,7 +657,7 @@ function linkRelatedObservations(db, savedId, obs, episode) {
 export function buildDegradedTitle(episode) {
   const files = (episode.files || []).filter(Boolean);
   const hasError = episode.entries.some((e) => e.isError);
-  const hasEdit = episode.entries.some((e) => EDIT_TOOLS.has(e.tool));
+  const hasEdit = episode.entries.some(isEditEntry);
 
   // Extract a short error hint from the first error entry's desc
   let errorHint = '';
@@ -708,7 +735,7 @@ export function saveEpisodeImmediate(episode, externalDb, scope = 'saveEpisodeIm
  */
 export function buildImmediateObservation(episode) {
   const hasError = episode.entries.some((e) => e.isError);
-  const hasEdit = episode.entries.some((e) => EDIT_TOOLS.has(e.tool));
+  const hasEdit = episode.entries.some(isEditEntry);
   const readCount = episode.entries.filter((e) => e.tool === 'Read' || e.tool === 'Grep').length;
   const isReviewPattern = !hasEdit && !hasError && readCount >= 5;
   const inferredType = hasError ? 'bugfix' : hasEdit ? 'change' : 'discovery';
@@ -761,11 +788,9 @@ export function buildImmediateObservation(episode) {
   const searchedFiles = new Set();
   for (const entry of episode.entries) {
     if (!entry.files) continue;
-    if (EDIT_TOOLS.has(entry.tool)) {
-      for (const f of entry.files) modifiedFiles.add(f);
-    } else {
-      for (const f of entry.files) searchedFiles.add(f);
-    }
+    // A Bash entry can do both: `cp a b` reads a and writes b.
+    const edited = new Set(entryEditedFiles(entry));
+    for (const f of entry.files) (edited.has(f) ? modifiedFiles : searchedFiles).add(f);
   }
   // Merge bash-tracked reads and search tool files into filesRead
   const allReads = new Set([...(episode.filesRead || []), ...searchedFiles]);
@@ -855,7 +880,7 @@ export function hasEnrichmentContent(parsed) {
 // (MEMORY_INPUT_GUARD used to be the other example here; it is now exported from
 // lib/memory-input-guard.mjs and imported by two modules and two tests, so it no longer
 // illustrates the point.)
-function buildLessonRetryPrompt(episode, firstPass) {
+function buildLessonRetryPrompt(episode, firstPass, diag = []) {
   const actionList = episode.entries
     .map((e, i) => `${i + 1}. [${e.tool}] ${e.desc}${e.isError ? ' (ERROR)' : ''}`)
     .join('\n');
@@ -868,12 +893,20 @@ function buildLessonRetryPrompt(episode, firstPass) {
 
 If the work was purely mechanical with no insight worth remembering, reply {"lesson":null}.
 Otherwise reply in 12-280 chars. Do NOT invent a fake lesson, do NOT write the string "none".
+The lesson MUST copy at least 4 consecutive words verbatim, in double quotes, from one DIAGNOSIS line, and claim nothing that line does not state. No DIAGNOSIS line states a cause → {"lesson":null}.
+
+Reply ONLY valid JSON, no markdown fences: {"lesson":"..."} or {"lesson":null}
 
-Reply ONLY valid JSON, no markdown fences: {"lesson":"..."} or {"lesson":null}`;
+${MEMORY_INPUT_GUARD}`;
+  // The guard, because this user message carries the DIAGNOSIS block — verbatim tool
+  // output — and grounding rewards copying from it (pre-ship defect review P3-4). The
+  // first pass has carried it since cso F#4; the retry did not.
   const user = `A ${firstPass.type} episode just completed. First-pass title: "${firstPass.title || 'untitled'}".
 
 Actions:
-${actionList}`;
+${actionList}
+
+${diagnosisBlock(diag)}`;
   return { system, user };
 }
 
@@ -927,10 +960,11 @@ export async function handleLLMEpisode() {
 type: pick by strongest signal. decision = explicit tradeoff / "chose X over Y because Z" / rejected an approach (e.g. "Rejected schema migration — single-source module + sync test instead"; "Heterogeneous hook events → heterogeneous context budgets"). bugfix = prior-failing path fixed with a named root cause. feature = new user-visible capability. refactor = behavior unchanged but structure improved. discovery = learned how a system works (read-heavy, no writes). change = routine edit with no new principle (default if unsure and nothing else fits).
 Facts: each MUST be (1) atomic—one claim, (2) self-contained—no pronouns, include file/function name, (3) specific—"refreshToken() in auth.ts:45 uses 1h TTL" not "handles tokens"
 importance: Be strict — default to 1. 0=pure browsing with zero learning value. 1=routine file edits, standard changes, normal workflow (MOST episodes). 2=notable ONLY if it reveals something non-obvious: error fix with discovered root cause, architectural decision with explicit tradeoff, config change with unexpected side effects. 3=critical: breaking change affecting users, security vulnerability fix, data migration. Ask yourself: "would a future session benefit from knowing this?" — if not, it's importance=1.
-lesson_learned: The non-obvious insight a future session would benefit from. Examples: "FTS5's default tokenizer doesn't split CJK — need bigram workaround", "vitest --reporter=verbose hangs on large test suites, use default reporter". Look hard before giving up — most coding episodes contain at least one micro-lesson (an undocumented flag, a surprising default, a debugging shortcut, an unexpected interaction). If literally no insight worth teaching (e.g. version bump, whitespace fix, file rename), output JSON null. Do NOT invent a lesson, do NOT write the strings "none"/"n/a"/"todo"/"tbd"/"-" — those will be discarded as noise.
+lesson_learned: The non-obvious insight a future session would benefit from, resting ONLY on the DIAGNOSIS lines: copy at least 4 consecutive words verbatim, in double quotes, from one DIAGNOSIS line, and claim no mechanism that line does not state. Example: FTS5's "default tokenizer doesn't split CJK" — index bigrams instead. No DIAGNOSIS line, or none that states a cause → output JSON null; a lesson without such a quote is discarded. Do NOT invent a lesson. A mutation/probe run (a file changed on purpose, a checksum, a restore) and the agent's own script errors are not product bugs. Do NOT write the strings "none"/"n/a"/"todo"/"tbd"/"-" — those will be discarded as noise.
 scope: ${SCOPE_PROMPT_LEGEND}
 search_aliases: 2-6 alternative search terms someone might use to find this memory later (include CJK if project uses Chinese)`;
 
+  const diag = episodeDiagnosis(episode);
   let prompt;
   if (episode.entries.length === 1) {
     const e = episode.entries[0];
@@ -941,7 +975,9 @@ ${SHARED_OBS_SCHEMA_TAIL}`;
     const user = `Tool: ${e.tool}
 File: ${episodeFiles.join(', ') || 'unknown'}
 Action: ${e.desc}
-Error: ${e.isError ? 'yes' : 'no'}`;
+Error: ${e.isError ? 'yes' : 'no'}
+
+${diagnosisBlock(diag)}`;
     prompt = { system, user };
   } else {
     const actionList = episode.entries
@@ -955,7 +991,9 @@ ${SHARED_OBS_SCHEMA_TAIL}`;
     const user = `Project: ${episode.project}
 Files: ${fileList}
 Actions (${episode.entries.length} total):
-${actionList}`;
+${actionList}
+
+${diagnosisBlock(diag)}`;
     prompt = { system, user };
   }
 
@@ -1037,6 +1075,25 @@ ${actionList}`;
       const isLessonLowSignal = isLowSignalLesson(rawLesson);
       let lessonLearned = isLessonLowSignal ? null : rawLesson.slice(0, 500);
 
+      // D#69 grounding post-check. An event's lesson is kept only when it quotes the
+      // window's own DIAGNOSIS (isLessonGrounded: a shared 4-word run with one diag line).
+      // The 2026-09-25 audit read 16 of 30 events WRONG and found lessons accurate only
+      // where the window itself stated the cause; the prompt now asks for the quote, and
+      // this is the mechanism — prompt wording alone barely moves Haiku (#8605).
+      // Least destructive outcome: the row is still saved (title, narrative, files — all
+      // searchable), the lesson is dropped, and importance is capped at 1 below, which is
+      // under every automatic injection face's floor (SessionStart / UserPromptSubmit /
+      // PreToolUse all read importance >= 2). Event types only: `change` rows go to
+      // `observations`, were not in the audit, and a lesson-less `change` is DELETED by
+      // isLowYieldChangeObs — demotion there would be a deletion.
+      const groundingOn = lessonGroundingEnabled() && EVENT_TYPE_SET.has(parsed.type);
+      let groundingDropped = false;
+      if (groundingOn && lessonLearned && !isLessonGrounded(lessonLearned, diag)) {
+        debugLog('DEBUG', 'llm-episode', `ungrounded lesson dropped: "${truncate(lessonLearned, 60)}"`);
+        lessonLearned = null;
+        groundingDropped = true;
+      }
+
       // P3: for bugfix/decision, retry once with a lesson-focused prompt.
       // These types have the highest reuse value (~72.7% hit-rate vs change
       // ~16.5%), and Haiku's first pass writes NULL ~70% of the time for
@@ -1044,10 +1101,13 @@ ${actionList}`;
       // episode. Opt-out: CLAUDE_MEM_NO_LESSON_RETRY=1.
       let retryAttempted = false;
       let retryRecovered = false;
+      // With grounding on, a window with no diagnosis cannot yield a keepable lesson, so
+      // the retry (an extra LLM call) is skipped there rather than paid for and discarded.
       if (
-        isLessonLowSignal &&
+        !lessonLearned &&
         (parsed.type === 'bugfix' || parsed.type === 'decision') &&
-        !process.env.CLAUDE_MEM_NO_LESSON_RETRY
+        !process.env.CLAUDE_MEM_NO_LESSON_RETRY &&
+        (!groundingOn || diag.length > 0)
       ) {
         retryAttempted = true;
         // The first callLLM released its slot in the finally above; this lesson
@@ -1057,13 +1117,15 @@ ${actionList}`;
         // rather than exceed the limit (the lesson is an optional enhancement).
         const retrySlot = await acquireLLMSlot();
         try {
-          const retryPrompt = buildLessonRetryPrompt(episode, parsed);
+          const retryPrompt = buildLessonRetryPrompt(episode, parsed, diag);
           const retryRaw = retrySlot ? await callLLM(retryPrompt, BG_LLM_TIMEOUT_MS) : null;
           if (retryRaw) {
             const retry = parseJsonFromLLM(retryRaw);
             const retryLesson = typeof retry?.lesson === 'string' ? retry.lesson.trim() : '';
             const retryIsLow = isLowSignalLesson(retryLesson);
-            if (!retryIsLow) {
+            const retryUngrounded = !retryIsLow && groundingOn && !isLessonGrounded(retryLesson, diag);
+            if (retryUngrounded) groundingDropped = true;
+            if (!retryIsLow && !retryUngrounded) {
               lessonLearned = retryLesson.slice(0, 500);
               retryRecovered = true;
               debugLog(
@@ -1137,8 +1199,12 @@ ${actionList}`;
         // to schema.mjs). Haiku's OWN importance can still reach 3 (genuine judgment); only the
         // path heuristic is capped. The isLessonLowSignal branch still floors no-lesson
         // non-decision autos at ≤1; manual mem_save uses a different path and is unaffected.
+        // D#69: `!lessonLearned` is the old `isLessonLowSignal && !retryRecovered` (the
+        // two are equal with grounding off). A lesson the grounding check dropped caps
+        // `decision` too: its body falls back to the model's narrative, which is exactly
+        // as unanchored as the lesson it replaces.
         importance:
-          isLessonLowSignal && !retryRecovered && parsed.type !== 'decision'
+          !lessonLearned && (groundingDropped || parsed.type !== 'decision')
             ? Math.min(ruleImportance, 1)
             : Math.max(Math.min(ruleImportance, 2), clampImportance(parsed.importance)),
         lessonLearned,