claude-mem-lite 6.9.1 → 6.10.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.9.1",
+      "version": "6.10.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.9.1",
+  "version": "6.10.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

@@ -119,7 +119,9 @@ How claude-mem-lite differs from the major neighbors in the LLM-memory space (ve
 - **Schema auto-migration** -- Idempotent `ALTER TABLE` migrations run on every startup, safely adding new columns and indexes without data loss
 - **LLM concurrency control** -- File-based semaphore limits background workers to 2 concurrent LLM calls, preventing resource contention
 - **stdin overflow protection** -- Hook input truncated at 256KB with regex-based action salvage for oversized tool outputs
-- **Cross-session handoff** -- Captures session state (request, completed work, next steps, key files) on `/exit`, then injects context when the next session detects continuation intent via explicit keywords or FTS5 term overlap. **The `/clear` and `/compact` arm fires since v5.4.0** (R10-P1-1); before that it had never once written a row — `session_handoffs` on the maintainer's install held 4 `exit` rows and **0** `clear` rows. Two host facts settled it, both measured rather than assumed. (1) `Stop` runs at the end of every assistant *turn*, not once per session, and it deleted the session file that SessionStart reads to learn which session just ended — so the branch was unreachable, and mem sessions were minted per turn (58 prompts over 16 host sessions produced 56 mem sessions and 56 summary rows, 2026-09-07). (2) Claude Code **rotates its session id across `/clear`**: of 21 real transcripts, 12 carry a `/clear` command record, and in 12/12 that record's timestamp precedes its own file's first record by ~0.1s — the command is issued in the old session and replayed into a new file under a new id. So `Stop` no longer deletes the file, SessionStart asks the host's `source` (`startup`/`clear`/`compact`/`resume`) instead of guessing from the file, and the handoff's prompt lookup falls back to the unscoped set when the new session's id matches none. Revert path: `CLAUDE_MEM_LEGACY_STOP_UNLINK=1`
+- **Cross-session handoff** -- Captures session state on `/exit` and `/clear`, then injects context when the next session detects continuation intent
+  <br>**Changed in v6.10.0**: the injected block went from two sections to six. Its observation queries were keyed on the hook-minted session id while every `mem_save` writes a `manual-<project>` id, so `completed` and `key_decisions` could not reach a saved lesson at all — 17 of 17 stored rows held 0 bytes in both. The block now also carries `## Tree state` (branch, short sha, uncommitted count) and `## Next steps`, read from the project's newest `tasks/<slug>-paused.md` when it is under a week old. Four additive nullable columns land on `session_handoffs`; the schema version deliberately does not move, so an older build still opens the database (measured: the v6.9.1 tree read and wrote a database this release had migrated). Revert by pinning `claude-mem-lite@6.9.1` — no data-directory work.
+  <br>Original behaviour and the measurements behind it via explicit keywords or FTS5 term overlap. **The `/clear` and `/compact` arm fires since v5.4.0** (R10-P1-1); before that it had never once written a row — `session_handoffs` on the maintainer's install held 4 `exit` rows and **0** `clear` rows. Two host facts settled it, both measured rather than assumed. (1) `Stop` runs at the end of every assistant *turn*, not once per session, and it deleted the session file that SessionStart reads to learn which session just ended — so the branch was unreachable, and mem sessions were minted per turn (58 prompts over 16 host sessions produced 56 mem sessions and 56 summary rows, 2026-09-07). (2) Claude Code **rotates its session id across `/clear`**: of 21 real transcripts, 12 carry a `/clear` command record, and in 12/12 that record's timestamp precedes its own file's first record by ~0.1s — the command is issued in the old session and replayed into a new file under a new id. So `Stop` no longer deletes the file, SessionStart asks the host's `source` (`startup`/`clear`/`compact`/`resume`) instead of guessing from the file, and the handoff's prompt lookup falls back to the unscoped set when the new session's id matches none. Revert path: `CLAUDE_MEM_LEGACY_STOP_UNLINK=1`
 - **Git-SHA continuation anchor** (v2.31.0) -- Handoff rows include `git_sha_at_handoff`; any handoff matching the current `HEAD` counts as continuation regardless of TTL. Code state is a stronger continuation signal than wall-clock time
 - **Startup dashboard** (v2.31.0) -- SessionStart hook aggregates `git status` + `~/.claude/tasks/*.json` + `~/.claude/plans/*.md` + most-recent exit handoff + recent event count into a single structured block injected via `hookSpecificOutput.additionalContext`
 - **Activity namespace** (v2.31.0) -- Dedicated `events` table + FTS5 for non-memdir types (`bugfix`, `lesson`, `bug`, `discovery`, `refactor`, `feature`, `observation`, `decision`) that don't compete with `WHAT_NOT_TO_SAVE` semantics on the observations table. CLI: `claude-mem-lite activity save|search|recent|show`. `hook-llm` routes non-memdir summary types through `persistHaikuSummary` so upgrades from observations→events are atomic. (v3.39: the `/lesson` and `/bug` slash commands were redirected from this events table to searchable **observations** — `mem_search` never read the events table, so explicit saves were unfindable; the events table remains the auto-capture activity log.)

package/README.zh-CN.md

@@ -91,6 +91,7 @@
 - **LLM 并发控制** -- 基于文件的信号量将后台 worker 限制为 2 个并发 LLM 调用，防止资源争用
 - **stdin 溢出保护** -- Hook 输入在 256KB 处截断，对超大工具输出使用正则挽救关键信息
 - **跨会话交接** -- 在 `/clear` 或 `/exit` 时捕获会话状态（请求、已完成工作、后续步骤、关键文件），下次会话检测到继续意图时自动注入上下文（支持显式关键词和 FTS5 术语重叠匹配）
+  <br>**v6.10.0 变更**：注入块从 2 段变为 6 段。此前它的观测查询按钩子铸造的会话 id 过滤，而每一次 `mem_save` 写的是 `manual-<project>` id，两个命名空间不相交，所以 `completed` 与 `key_decisions` 根本够不到已保存的经验——库里 17 行交接记录这两个字段全是 0 字节。现在还会带 `## Tree state`（分支、短 sha、未提交文件数）和 `## Next steps`（读取项目里最新且未超过 7 天的 `tasks/<slug>-paused.md`）。`session_handoffs` 新增 4 个可空列；schema 版本号**刻意不动**，所以旧版本仍能打开数据库（已实测：v6.9.1 的代码能读写本版本迁移过的库）。回退方式：固定到 `claude-mem-lite@6.9.1`，无需处理数据目录。
 - **插件缓存 hook 自愈** -- Claude Code runtime 从 `~/.claude/plugins/cache/<mp>/<plugin>/<ver>/hooks/hooks.json` 读取插件 hook，而非 marketplace 源。当 `install.mjs` 写入 `settings.json` 的 hooks 与残留 cache `hooks.json` 同时存在（例如曾装过 marketplace 版本，或插件被 Claude Code 自动升级重建 cache），runtime 会注册两套 hook → 每次 SessionStart / UserPromptSubmit 都触发两份。`install.mjs` 和 `hook-update.mjs` 现在会清理每个 cache 版本目录下的 `hooks.json`；`hook.mjs session-start` 每次启动自愈（通过 `hasInstallManagedHooks` 门控，不影响纯插件模式用户）；`install.mjs status` 会报告 cache 污染状况（自 v2.31.1 / v2.31.2 起）。
 - **Git-SHA 延续锚点**（v2.31.0）-- handoff 记录包含 `git_sha_at_handoff` 字段，任何匹配当前 `HEAD` 的 handoff 都视为延续会话，不受 TTL 限制。代码状态比时钟时间更能反映上下文延续。
 - **启动面板**（v2.31.0）-- SessionStart hook 将 `git status` + `~/.claude/tasks/*.json` + `~/.claude/plans/*.md` + 最近 /exit 交接 + 最近事件数聚合为一个结构化块，通过 `hookSpecificOutput.additionalContext` 注入。

package/hook-context.mjs

@@ -27,6 +27,7 @@ import {
   effectiveQuiet,
   isQuietHooks,
   KEY_CONTEXT_LIMIT,
+  UNCONSUMED_HANDOFF_SQL,
 } from './hook-shared.mjs';
 import { extractUnfinishedSummary } from './hook-handoff.mjs';
 import { recentInjectableEvents, renderInjectableEvent } from './lib/events-injection.mjs';
@@ -752,6 +753,7 @@ export function buildSessionContextLines(
         SELECT working_on, unfinished, key_files
         FROM session_handoffs
         WHERE project = ? AND type = 'clear' AND session_id = ? AND created_at_epoch > ?
+          AND ${UNCONSUMED_HANDOFF_SQL}
         ORDER BY created_at_epoch DESC LIMIT 1
       `,
         )
@@ -761,7 +763,7 @@ export function buildSessionContextLines(
           `
         SELECT working_on, unfinished, key_files
         FROM session_handoffs
-        WHERE project = ? AND type = 'clear' AND created_at_epoch > ?
+        WHERE project = ? AND type = 'clear' AND created_at_epoch > ? AND ${UNCONSUMED_HANDOFF_SQL}
         ORDER BY created_at_epoch DESC LIMIT 1
       `,
         )

package/hook-handoff.mjs

@@ -14,19 +14,23 @@ import {
   notLowSignalTitleClause,
   neutralizeContextDelimiters,
 } from './utils.mjs';
-import { scrubRecord } from './lib/scrub-record.mjs';
+import { scrubRecord, scrubFilePath } from './lib/scrub-record.mjs';
 import {
   HANDOFF_EXPIRY_CLEAR,
   HANDOFF_EXPIRY_EXIT,
   HANDOFF_ANCHOR_MAX_AGE,
   HANDOFF_MATCH_THRESHOLD,
   CONTINUE_KEYWORDS,
+  UNCONSUMED_HANDOFF_SQL,
 } from './hook-shared.mjs';
 // T10d: import the whole module (not a named export) so tests can spy on
 // gitStateModule.readGitState via vi.spyOn. Named-import bindings are
 // immutable in ESM and cannot be mocked after the fact.
 import * as gitStateModule from './lib/git-state.mjs';
 import * as taskReaderModule from './lib/task-reader.mjs';
+// Namespace import for the same reason as the two above: ESM named bindings are immutable,
+// so a named import could not be spied on in tests.
+import * as pausedReaderModule from './lib/paused-reader.mjs';
 import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 
 /**
@@ -142,6 +146,24 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
       .get(sessionId, ccScope);
     if (typeof w?.startEpoch === 'number') ccWindowStart = w.startEpoch;
   }
+  // Fall back to THIS MEM SESSION's own start when the CC window is unavailable, rather
+  // than running unbounded.
+  //
+  // `ccWindowStart` is null by construction on the /clear path: the host rotates the CC id
+  // across /clear (measured 12/12, see the note above), so the scope passed here belongs to
+  // the NEW session and has no prompts, and MIN over zero rows is null. Before the
+  // namespace widening the id predicate still bounded the pool to one session; after it,
+  // `OR project = ?` with no window pulled the project's entire recent history — a
+  // month-old decision from a different session was reported as this one's Completed AND
+  // replayed as standing Key Decisions. Found by the pre-ship defect lens, reproduced
+  // end-to-end, and invisible to the suite because every control case passed an
+  // `exit`-shaped scope that HAS prompts.
+  if (ccWindowStart === null) {
+    const w = db
+      .prepare(`SELECT MIN(created_at_epoch) AS startEpoch FROM user_prompts WHERE content_session_id = ?`)
+      .get(sessionId);
+    if (typeof w?.startEpoch === 'number') ccWindowStart = w.startEpoch;
+  }
   const obsWindowClause = ccWindowStart !== null ? 'AND created_at_epoch >= ?' : '';
   const obsWindowParams = ccWindowStart !== null ? [ccWindowStart] : [];
 
@@ -155,15 +177,31 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   // key_decisions excludes a retracted decision" in tests/audit-silent-20260814.test.mjs.
   // Audit R8 §11.3 proposed adding the filter here from a repo-wide regex sweep of the
   // predicate shape; it was rejected on this reasoning, and the guard catches it.
+  // `(memory_session_id = ? OR project = ?)`, not the bare id equality this shipped with.
+  // The id side alone is unreachable for the rows that matter: the hook mints
+  // `hook-<project>-<uuid8>` (hook-shared.mjs) and hands it here, while every explicit
+  // mem_save writes `manual-<project>` (lib/save-observation.mjs). Disjoint prefixes, so
+  // the join could not match a saved lesson at all. Measured on the live DB 2026-09-21:
+  // 101 of 105 observations sat in the `manual-` namespace and all 17 stored handoff rows
+  // carried `completed` = 0 bytes.
+  //
+  // The widening does NOT give back what D#28 bought: isolation is the TIME WINDOW's job
+  // (`obsWindowClause`, lower-bounded at this CC session's first prompt), and it still
+  // excludes a prior session's rows — pinned by the control case in
+  // tests/handoff-payload-reach.test.mjs. The id side is kept as an OR so every row that
+  // matched before still matches (project names have been renormalized before, see the
+  // `normalize-project-names` migration in schema.mjs, and a row can carry the old name).
+  // The earlier citation here and in the commit body pointed at schema.mjs:1127, which is
+  // inside the observation_files backfill — the right fact, the wrong line.
   const completed = db
     .prepare(
       `
     SELECT title, type, narrative FROM observations
-    WHERE memory_session_id = ? AND COALESCE(compressed_into, 0) = 0 ${obsWindowClause}
+    WHERE (memory_session_id = ? OR project = ?) AND COALESCE(compressed_into, 0) = 0 ${obsWindowClause}
     ORDER BY created_at_epoch DESC LIMIT 15
   `,
     )
-    .all(sessionId, ...obsWindowParams);
+    .all(sessionId, project, ...obsWindowParams);
 
   // 3. Recent activity — episode snapshot + full session edit history from narratives.
   // Keep only entries that represent in-flight work (file edits) or outright failures
@@ -218,24 +256,57 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
 
   // 4. Key files — from episode snapshot + observations
   const fileSet = new Set();
+  // Ask the BASENAME for an extension, rather than asking the string for a separator.
+  // The separator test answered "does this look like a path", which is a different
+  // question and got both halves wrong.
+  //
+  // key_files is built from TWO sources — the episode buffer on disk (`episodeSnapshot
+  // .files`) and `observations.files_modified` — and the measurement covered only the
+  // second, so quote it for only that half: over all 218 non-null files_modified entries
+  // on the live DB 2026-09-21, 59 (27%) were repo-root filenames like `hook.mjs`, rejected
+  // for having no `/`. That is the dropped-file half, and it reproduces.
+  //
+  // The directory half comes from the EPISODE BUFFER, which that measurement never read:
+  // `~/.claude-mem-lite/runtime/ep-<project>.json` carries entries like
+  // `/home/ai/dev/loop-testing`, byte-for-byte the key_files of the matching handoff row.
+  // `Key Files: claude-mem-lite` in a real injection came from there, NOT from
+  // files_modified — no entry in that column equals a project directory. The three
+  // extensionless slash-bearing values it does hold are one executable
+  // (`claude-plugin/bin/code-graph-mcp`) and two `/var/tmp` scratch dirs, and the
+  // executable is an instance of the named cost below rather than evidence for this
+  // defect. Corrected by the pre-ship claims lens; the fix is unaffected because
+  // isValidFile gates both sources.
+  //
+  // Named cost, and it is wider than "Makefile, LICENSE" — the pre-ship review diffed old
+  // against new over a plausible path set and the drop list is two classes: (a) every
+  // extensionless file, which includes the ones under `bin/` and `scripts/` that are
+  // executables rather than docs (this repo tracks `.githooks/pre-commit`), and (b) any
+  // extension longer than 10 characters, so `.env` qualifies but `.editorconfig` does not.
+  // The alternative to the whole rule is a hand-drawn list of extensionless filenames. The
+  // alternative is a hand-drawn list of extensionless filenames, and a hand-drawn class is
+  // the shape that has been rejected three times in this repo for rejecting real cases.
+  // Residual, equally named: a directory that happens to end in `.something` still passes.
+  // The dot may lead the basename, so `.env` and `.env.example` qualify.
+  const FILE_BASENAME_RE = /\.[A-Za-z0-9_+-]{1,10}$/;
   const isValidFile = (f) =>
     f &&
     f.length > 2 &&
-    f.includes('/') &&
-    f.indexOf('/', 1) !== -1 &&
+    FILE_BASENAME_RE.test(basename(f)) &&
     !f.startsWith('/dev/') &&
     !f.startsWith('/proc/') &&
     !f.startsWith('/tmp/');
   if (episodeSnapshot?.files) episodeSnapshot.files.filter(isValidFile).forEach((f) => fileSet.add(f));
+  // Same namespace widening as `completed` above — see the reasoning there. Measured
+  // 2026-09-21: 8 of the 17 live handoff rows stored key_files as the empty array.
   const obsFiles = db
     .prepare(
       `
     SELECT files_modified FROM observations
-    WHERE memory_session_id = ? AND files_modified IS NOT NULL ${obsWindowClause}
+    WHERE (memory_session_id = ? OR project = ?) AND files_modified IS NOT NULL ${obsWindowClause}
     ORDER BY created_at_epoch DESC LIMIT 10
   `,
     )
-    .all(sessionId, ...obsWindowParams);
+    .all(sessionId, project, ...obsWindowParams);
   for (const row of obsFiles) {
     try {
       JSON.parse(row.files_modified)
@@ -253,19 +324,68 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   // retracted decision rendered there is indistinguishable from live policy. The
   // carry-forward fallback at the top of this function already filters the same column;
   // this is the sibling that did not.
+  // Same namespace widening as `completed` above — see the reasoning there. This is the
+  // field the widening exists for: a `decision` / `bugfix` lesson is written by mem_save,
+  // which is exactly the namespace the id equality could not reach, and all 17 live rows
+  // carried key_decisions = 0 bytes. The liveness predicate stays the FULL one (this field
+  // is replayed to a later session as standing policy — see the note above).
+  // `type` alongside the title: the render drops the duplicate copy of each decision from
+  // `## Completed`, so this section is the only place those entries still appear and it has
+  // to carry the `[bugfix]` / `[decision]` tag that Completed was providing. The only
+  // production reader of session_handoffs.key_decisions is this file's own renderer
+  // (session_summaries.key_decisions is a different column, a JSON array from Haiku), and
+  // every existing assertion on it is a substring/regex match on the title, so the added
+  // prefix is not a contract change for them.
   const decisions = db
     .prepare(
       `
-    SELECT title FROM observations
-    WHERE memory_session_id = ? AND COALESCE(importance, 1) >= 2
+    SELECT title, type FROM observations
+    WHERE (memory_session_id = ? OR project = ?) AND COALESCE(importance, 1) >= 2
       AND ${liveObsFilterSql('')} ${obsWindowClause}
     ORDER BY created_at_epoch DESC LIMIT 10
   `,
     )
-    .all(sessionId, ...obsWindowParams)
+    .all(sessionId, project, ...obsWindowParams)
     .filter((d) => d.title && !LOW_SIGNAL_TITLE.test(d.title))
     .slice(0, 5);
 
+  // 5b. Next steps — the remaining work a paused note spells out, which is the only
+  // next-step source in this system that a human wrote down on purpose. Deliberately not
+  // folded into `unfinished`: that field renders as "Recent activity" and mixes in-flight
+  // edits with surfaced errors, so a hand-written remaining-work list would be mislabelled.
+  //
+  // Deliberately NOT sourced from deferred_work, even though it is the other project-scoped
+  // durable queue: those rows are already delivered at SessionStart by the `### Deferred
+  // Work` block in hook-context.mjs, inside `<claude-mem-context>` — NOT by
+  // lib/startup-dashboard.mjs, which contains no reference to the table (the claims lens
+  // corrected that attribution). It renders the top 5 open rows by priority, so "already
+  // delivered" is true of the head of the queue rather than all of it; 12 were open on
+  // 2026-09-21. Adding them here would double-inject that head. Nothing delivers the
+  // paused note.
+  let nextSteps = null;
+  try {
+    // No explicit projectPath: the reader defaults to cwd, and neutralises that default
+    // under the test guard so no suite writes this repo's own paused note into its rows.
+    const note = pausedReaderModule.readPausedNote();
+    if (note) {
+      // Scrub per ELEMENT before stringify, never the JSON string — letting scrubSecrets
+      // rewrite the serialized form risks breaking the downstream JSON.parse. Same rule
+      // key_files follows below.
+      nextSteps = JSON.stringify({
+        // scrubFilePath, not scrubSecrets: this field is a filesystem PATH, and eight of
+        // the secret patterns carry a value class that does not exclude `/`, so a
+        // whole-path scrub eats the separator and destroys the filename. That is the named
+        // mechanism this repo grew for exactly this shape; the prose fields below are prose
+        // and correctly take the plain scrub.
+        file: scrubFilePath(String(note.file)),
+        title: scrubSecrets(String(note.title)),
+        items: note.items.map((i) => scrubSecrets(String(i))),
+      });
+    }
+  } catch {
+    /* best-effort, like the task reader above — never block the handoff */
+  }
+
   // 6. Match keywords
   const allText = [workingOn, ...completed.map((c) => c.title).filter(Boolean), unfinished].join(' ');
   const keywords = extractMatchKeywords(allText, [...fileSet]);
@@ -273,8 +393,17 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
   // T10d: capture HEAD sha so detectContinuationIntent can anchor on it later.
   // Best-effort — failures (non-git dir, missing binary, timeout) yield null.
   let gitShaAtHandoff = null;
+  let gitBranch = null;
+  let gitDirtyCount = null;
   try {
-    gitShaAtHandoff = gitStateModule.readGitState({ cwd: process.cwd() }).headSha || null;
+    const st = gitStateModule.readGitState({ cwd: process.cwd() });
+    gitShaAtHandoff = st.headSha || null;
+    gitBranch = st.branch || null;
+    // 0 and NULL are different answers here: "measured, and the tree is clean" versus "no
+    // measurement happened". readGitState returns an empty `changed` for BOTH a clean repo
+    // and a directory that is not a repo at all, so the sha/branch decide which one it was.
+    // Collapsing them would let a handoff written outside a repo claim a clean tree.
+    gitDirtyCount = st.headSha || st.branch ? st.changed.length : null;
   } catch {
     /* swallow — handoff must still persist */
   }
@@ -295,14 +424,23 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
     working_on: workingOn,
     completed: completed.map((c) => `[${c.type}] ${c.title}`).join('\n'),
     unfinished,
-    key_decisions: decisions.map((d) => d.title).join('\n'),
+    key_decisions: decisions.map((d) => `[${d.type}] ${d.title}`).join('\n'),
     match_keywords: keywords,
   });
   const safeKeyFiles = JSON.stringify([...fileSet].slice(0, 20).map((f) => scrubSecrets(String(f))));
+  // The UPSERT below resets `consumed_at`. Rewriting a handoff makes it fresh again, so it
+  // must become injectable again: the DELETE that consumeHandoff replaced did this
+  // implicitly (row gone, next build INSERTed a new one), while the UPSERT reuses the row.
+  // Without the reset, a session whose handoff was consumed by a sibling stays permanently
+  // invisible to injection however much work it does afterwards. Pre-ship defect lens.
+  //
+  // This prose lives here and not in the SQL because a backtick inside a SQL comment inside
+  // a template literal ends the literal — the same defect this repo shipped at v6.9.1, and
+  // it recurred right here while writing this fix.
   db.prepare(
     `
-    INSERT INTO session_handoffs (project, type, session_id, working_on, completed, unfinished, key_files, key_decisions, match_keywords, created_at_epoch, git_sha_at_handoff)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO session_handoffs (project, type, session_id, working_on, completed, unfinished, key_files, key_decisions, match_keywords, created_at_epoch, git_sha_at_handoff, git_branch, git_dirty_count, next_steps)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(project, type, session_id) DO UPDATE SET
       working_on = excluded.working_on,
       completed = excluded.completed,
@@ -311,7 +449,11 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
       key_decisions = excluded.key_decisions,
       match_keywords = excluded.match_keywords,
       created_at_epoch = excluded.created_at_epoch,
-      git_sha_at_handoff = excluded.git_sha_at_handoff
+      git_sha_at_handoff = excluded.git_sha_at_handoff,
+      git_branch = excluded.git_branch,
+      git_dirty_count = excluded.git_dirty_count,
+      next_steps = excluded.next_steps,
+      consumed_at = NULL
   `,
   ).run(
     project,
@@ -327,6 +469,9 @@ export function buildAndSaveHandoff(db, sessionId, project, type, episodeSnapsho
     safe.match_keywords,
     Date.now(),
     gitShaAtHandoff,
+    gitBranch,
+    gitDirtyCount,
+    nextSteps,
   );
 }
 
@@ -371,6 +516,7 @@ export function detectContinuationIntent(db, promptText, project, currentCcSessi
               `
             SELECT created_at_epoch, match_keywords FROM session_handoffs
             WHERE project = ? AND git_sha_at_handoff = ? AND (type = 'exit' OR session_id = ?)
+              AND ${UNCONSUMED_HANDOFF_SQL}
             ORDER BY created_at_epoch DESC LIMIT 1
           `,
             )
@@ -379,7 +525,7 @@ export function detectContinuationIntent(db, promptText, project, currentCcSessi
             .prepare(
               `
             SELECT created_at_epoch, match_keywords FROM session_handoffs
-            WHERE project = ? AND git_sha_at_handoff = ?
+            WHERE project = ? AND git_sha_at_handoff = ? AND ${UNCONSUMED_HANDOFF_SQL}
             ORDER BY created_at_epoch DESC LIMIT 1
           `,
             )
@@ -405,7 +551,7 @@ export function detectContinuationIntent(db, promptText, project, currentCcSessi
         .prepare(
           `
         SELECT created_at_epoch, match_keywords FROM session_handoffs
-        WHERE project = ? AND type = 'clear' AND session_id = ?
+        WHERE project = ? AND type = 'clear' AND session_id = ? AND ${UNCONSUMED_HANDOFF_SQL}
         ORDER BY created_at_epoch DESC LIMIT 1
       `,
         )
@@ -414,7 +560,7 @@ export function detectContinuationIntent(db, promptText, project, currentCcSessi
         .prepare(
           `
         SELECT created_at_epoch, match_keywords FROM session_handoffs
-        WHERE project = ? AND type = 'clear'
+        WHERE project = ? AND type = 'clear' AND ${UNCONSUMED_HANDOFF_SQL}
         ORDER BY created_at_epoch DESC LIMIT 1
       `,
         )
@@ -455,6 +601,7 @@ export function detectContinuationIntent(db, promptText, project, currentCcSessi
         SELECT type, match_keywords, created_at_epoch FROM session_handoffs
         WHERE project = ?
           AND ((type = 'clear' AND session_id = ?) OR type = 'exit')
+          AND ${UNCONSUMED_HANDOFF_SQL}
         ORDER BY created_at_epoch DESC
       `,
         )
@@ -463,7 +610,7 @@ export function detectContinuationIntent(db, promptText, project, currentCcSessi
         .prepare(
           `
         SELECT type, match_keywords, created_at_epoch FROM session_handoffs
-        WHERE project = ? ORDER BY created_at_epoch DESC
+        WHERE project = ? AND ${UNCONSUMED_HANDOFF_SQL} ORDER BY created_at_epoch DESC
       `,
         )
         .all(project);
@@ -518,6 +665,7 @@ export function pickHandoffToInject(db, project, currentCcSessionId = null) {
         SELECT * FROM session_handoffs
         WHERE project = ?
           AND ((type = 'clear' AND session_id = ?) OR (type = 'exit' AND session_id != ?))
+          AND ${UNCONSUMED_HANDOFF_SQL}
         ORDER BY created_at_epoch DESC LIMIT 5
       `,
         )
@@ -526,7 +674,7 @@ export function pickHandoffToInject(db, project, currentCcSessionId = null) {
         .prepare(
           `
         SELECT * FROM session_handoffs
-        WHERE project = ? ORDER BY created_at_epoch DESC LIMIT 5
+        WHERE project = ? AND ${UNCONSUMED_HANDOFF_SQL} ORDER BY created_at_epoch DESC LIMIT 5
       `,
         )
         .all(project);
@@ -539,12 +687,97 @@ export function pickHandoffToInject(db, project, currentCcSessionId = null) {
   );
 }
 
+/**
+ * Mark one handoff row as delivered.
+ *
+ * Replaces the DELETE that used to follow injection. Two things that DELETE cost: a handoff
+ * injected at a moment the model could not act on it was gone for good, and the row behind a
+ * bad injection no longer existed by the time anyone went looking for it. Marking keeps the
+ * row until the existing age-based GC in hook.mjs's auto-maintain reaps it, so retention is
+ * unchanged in the limit — only the window in which it can be read back grows.
+ *
+ * Scoped to the exact PK so a parallel session's handoff is untouched (the DELETE this
+ * replaces already had that property, and pre-v2.46 not having it made the DB forgetful).
+ *
+ * @param {Database} db Opened main database
+ * @param {{project: string, type: string, session_id: string}} handoff Row from pickHandoffToInject
+ * @param {number} [now=Date.now()] Injected for tests
+ * @returns {number} Rows changed (0 when a concurrent session consumed it first)
+ */
+export function consumeHandoff(db, handoff, now = Date.now()) {
+  if (!handoff) return 0;
+  // `consumed_at IS NULL` in the WHERE, not just the SET: two sessions can race to inject
+  // the same exit handoff, and the first stamp is the one that should stand.
+  const res = db
+    .prepare(
+      `UPDATE session_handoffs SET consumed_at = ?
+       WHERE project = ? AND type = ? AND session_id = ? AND ${UNCONSUMED_HANDOFF_SQL}`,
+    )
+    .run(now, handoff.project, handoff.type, handoff.session_id);
+  return res.changes;
+}
+
 export function renderHandoffInjection(db, project, currentCcSessionId = null) {
   const handoff = pickHandoffToInject(db, project, currentCcSessionId);
   if (!handoff) return null;
   return renderHandoffFromRow(handoff, db, project);
 }
 
+// Markdown ATX markers carried by replayed text, at a token boundary.
+//
+// This block frames itself with `## Working On` / `## Completed` / `## Next steps`, and
+// working_on is user prompt text — a prompt that opens with its own outline flattens into
+// the block carrying `#` and `##` of its own, on the same line, because working_on joins up
+// to five prompts with ` → `. A real injection read
+// `## Working On` / `# 自主端到端测试与修复循环  ## 角色与授权 …`, at which point the
+// block's structure and the replayed text's structure are indistinguishable to whatever
+// reads it next. Same class as the authority-tag defanging one level down: a forged
+// SECTION rather than a forged tag.
+//
+// Only a marker followed by whitespace, at a token boundary, counts — `#42`, `C#` and
+// `D#216` are ordinary in this project's prose and survive untouched.
+const ATX_HEADING_RE = /(^|\s)#{1,6}\s/g;
+const ATX_MAX_PASSES = 32;
+
+/**
+ * Strip ATX markers to a FIXPOINT, not in one pass.
+ *
+ * The gap is two characters wide and it is the same one format-utils' `defangToFixpoint`
+ * documents for the tag half: `(^|\s)` CONSUMES the boundary, so after removing the first
+ * `## ` the regex resumes past the second one and leaves it live. `## ## Key Decisions`
+ * came out of a single pass as a real `## Key Decisions` section inside the block — the
+ * precise property this defanging exists to hold, defeated by two extra characters. Found
+ * by the pre-ship defect lens; reproduced end-to-end before the fix.
+ *
+ * TERMINATION: every match contains at least one `#` and the replacement drops all of them,
+ * so any pass that changes the string removes at least one `#`. Self-bounded by the number
+ * of `#` in the input, and bounded again by the constant.
+ *
+ * INERT AT ANY DEPTH: still changing at the cap (≥32 nested forged layers, not reachable by
+ * accident) → drop every remaining `#`. Lossier, but the return value then provably carries
+ * no marker, which is the property callers rely on. Same fail-closed shape as the sibling.
+ */
+function stripAtxToFixpoint(s) {
+  let text = s;
+  for (let pass = 0; pass < ATX_MAX_PASSES; pass++) {
+    const next = text.replace(ATX_HEADING_RE, '$1');
+    if (next === text) return text;
+    text = next;
+  }
+  return text.replace(/#/g, '');
+}
+
+/** Defang authority tags AND section markers, for any replayed free text. */
+function safeText(value) {
+  return stripAtxToFixpoint(neutralizeContextDelimiters(String(value)));
+}
+
+// `[bugfix] title` → `title`. Both `completed` and `key_decisions` store the observation
+// type this way; the bracket run is length-capped so a title that merely opens with a
+// bracket ("[WIP] ..." is not a type) is not silently truncated to nothing.
+const TYPE_PREFIX_RE = /^\[[^\]]{1,20}\]\s*/;
+const titleOf = (line) => line.replace(TYPE_PREFIX_RE, '').trim();
+
 function renderHandoffFromRow(handoff, db, project) {
   const ageSec = Math.round((Date.now() - handoff.created_at_epoch) / 1000);
   const ageStr =
@@ -572,16 +805,66 @@ function renderHandoffFromRow(handoff, db, project) {
   // user prompt or edit snippet carrying a literal </session-handoff> would otherwise
   // close the block early and the rest would read as a real user message.
   if (handoff.working_on) {
-    lines.push('## Working On', neutralizeContextDelimiters(handoff.working_on), '');
+    lines.push('## Working On', safeText(handoff.working_on), '');
   }
-  if (handoff.completed) {
-    lines.push(
-      '## Completed',
-      ...neutralizeContextDelimiters(handoff.completed)
+
+  // Tree state. The sha has been stored since v25 but was only ever an INPUT to the
+  // continuation anchor — it was never shown, so a resumed session opened by running
+  // `git status` / `git rev-parse` to find out where it stood. Rendered right after the
+  // objective, because "which branch, and is the tree dirty" is the next question after
+  // "what was I doing". Branch names are defanged for the same reason key_files basenames
+  // are: git ref names admit angle brackets, and this text is replayed into the prompt.
+  // A 7-char sha cannot carry a complete tag, so it is sliced rather than scrubbed.
+  const treeBits = [];
+  if (handoff.git_branch) treeBits.push(`branch ${safeText(handoff.git_branch)}`);
+  if (handoff.git_sha_at_handoff) treeBits.push(`@ ${String(handoff.git_sha_at_handoff).slice(0, 7)}`);
+  if (typeof handoff.git_dirty_count === 'number') {
+    // NULL stays silent: a row written before this shipped, or written outside a repo, has
+    // no measurement, and "clean" would be a claim nobody made.
+    treeBits.push(handoff.git_dirty_count === 0 ? 'clean' : `${handoff.git_dirty_count} uncommitted file(s)`);
+  }
+  if (treeBits.length > 0) lines.push('## Tree state', treeBits.join(' · '), '');
+
+  // Key Decisions is computed here, before Completed renders, because Completed is deduped
+  // against it. Measured on the live corpus 2026-09-21 with the real predicates, population
+  // = every project with observations: 35 of 35 rendered Key Decisions lines were
+  // byte-identical to a Completed line, in all 8 projects. The overlap only became visible
+  // once the payload fix landed — before that both sections were empty.
+  //
+  // One-directional on purpose, and this is the F4 ruling rather than a preference:
+  // `completed` is the session's OWN HISTORY, `key_decisions` is standing policy replayed to
+  // a LATER session, which is why only the latter filters superseded_at. So the line to drop
+  // is the duplicate in history, and the one case where the two genuinely differ — a
+  // retracted decision, absent from key_decisions — is exactly the case where nothing is
+  // dropped and the history keeps it. Render-time only: the stored row is untouched, so all
+  // three F4 guards in tests/audit-silent-20260814.test.mjs still read what they pinned.
+  const decisionLines = handoff.key_decisions
+    ? safeText(handoff.key_decisions)
         .split('\n')
-        .map((l) => `- ${l}`),
-      '',
-    );
+        .filter((l) => l.trim())
+    : [];
+  // Match on the WHOLE line. Matching on the stripped title collapsed two DIFFERENT
+  // observations that share a title but not a type — `[change] 更新测试` vanished from
+  // Completed because `[decision] 更新测试` was standing policy — and that false match was
+  // permanent while the thing it accommodated is not. Pre-ship defect lens.
+  const decisionWhole = new Set(decisionLines);
+  // The accommodation, scoped to the rows that actually need it: a row written before
+  // key_decisions carried the `[type]` prefix holds a bare title, so only those get the
+  // looser title-only match. They age out at the handoff's own expiry.
+  const legacyTitles = new Set(decisionLines.filter((l) => !TYPE_PREFIX_RE.test(l)).map((l) => titleOf(l)));
+  const isDuplicateOfDecision = (line) => decisionWhole.has(line) || legacyTitles.has(titleOf(line));
+
+  if (handoff.completed) {
+    const kept = safeText(handoff.completed)
+      .split('\n')
+      .filter((l) => l.trim() && !isDuplicateOfDecision(l));
+    // An empty `## Completed` header is worse than no header — TWO of the eight measured
+    // projects had a session whose entire history was its decisions (dev--daagu and
+    // scratchpad--loop-smoke; the next closest keeps 2 lines). The commit body and an
+    // earlier draft of this comment said three; re-derived at both the 105- and
+    // 107-observation corpus states it is two. No type tags are lost with the header:
+    // key_decisions carries them now too.
+    if (kept.length > 0) lines.push('## Completed', ...kept.map((l) => `- ${l}`), '');
   }
   if (handoff.unfinished) {
     // Extract only the pending-work portion (before narrative history separator).
@@ -592,7 +875,7 @@ function renderHandoffFromRow(handoff, db, project) {
     if (pending) {
       lines.push(
         '## Recent activity',
-        ...neutralizeContextDelimiters(pending)
+        ...safeText(pending)
           .split('; ')
           .map((l) => `- ${l}`),
         '',
@@ -606,17 +889,32 @@ function renderHandoffFromRow(handoff, db, project) {
       // (Linux allows almost any char but '/'), and this is the one field in this block
       // that was rendered raw while working_on/unfinished/key_decisions all neutralize.
       if (files.length > 0)
-        lines.push('## Key Files', neutralizeContextDelimiters(files.map((f) => basename(f)).join(', ')), '');
+        lines.push('## Key Files', safeText(files.map((f) => basename(f)).join(', ')), '');
     } catch {}
   }
-  if (handoff.key_decisions) {
-    lines.push(
-      '## Key Decisions',
-      ...neutralizeContextDelimiters(handoff.key_decisions)
-        .split('\n')
-        .map((l) => `- ${l}`),
-      '',
-    );
+  // Next steps, from the project's newest paused note. Placed after Key Files and before
+  // Key Decisions: it is the most actionable block here, and it cites its own source file
+  // so the resuming session can open the full note instead of trusting this summary.
+  // Defanged like every other free-text field — the note is repo text, replayed verbatim
+  // into the prompt, and a literal closer would end the block early.
+  if (handoff.next_steps) {
+    try {
+      const note = JSON.parse(handoff.next_steps);
+      if (Array.isArray(note?.items) && note.items.length > 0) {
+        lines.push('## Next steps');
+        const from = note.file ? ` (from ${safeText(String(note.file))})` : '';
+        if (note.title) lines.push(`${safeText(String(note.title))}${from}`);
+        else if (from) lines.push(from.trim());
+        for (const item of note.items) lines.push(`- ${safeText(String(item))}`);
+        lines.push('');
+      }
+    } catch {
+      /* malformed JSON — skip, same as key_files */
+    }
+  }
+
+  if (decisionLines.length > 0) {
+    lines.push('## Key Decisions', ...decisionLines.map((l) => `- ${l}`), '');
   }
 
   lines.push('</session-handoff>');
@@ -660,10 +958,9 @@ function renderHandoffFromRow(handoff, db, project) {
       // Defang: these come from session_summaries, populated by Haiku OR by
       // extractStructuredSummary over the assistant transcript tail — replayed text that can
       // carry tool-XML / forged authority tags, same class as working_on above (audit MED-4).
-      if (summary.completed) lines.push(neutralizeContextDelimiters(summary.completed));
-      if (summary.remaining_items)
-        lines.push(`Remaining: ${neutralizeContextDelimiters(summary.remaining_items)}`);
-      if (summary.next_steps) lines.push(`Next steps: ${neutralizeContextDelimiters(summary.next_steps)}`);
+      if (summary.completed) lines.push(safeText(summary.completed));
+      if (summary.remaining_items) lines.push(`Remaining: ${safeText(summary.remaining_items)}`);
+      if (summary.next_steps) lines.push(`Next steps: ${safeText(summary.next_steps)}`);
       lines.push('</session-summary>');
     }
   } catch {}

package/hook-shared.mjs

@@ -43,6 +43,7 @@ export {
   HANDOFF_ANCHOR_MAX_AGE,
   HANDOFF_MATCH_THRESHOLD,
   CONTINUE_KEYWORDS,
+  UNCONSUMED_HANDOFF_SQL,
 } from './lib/handoff-constants.mjs';
 
 import { DAY_MS, ORPHAN_EPISODE_AGE_MS } from './lib/time-constants.mjs';

package/hook.mjs

@@ -138,6 +138,7 @@ import { liveObsFilterSql } from './lib/inject-search-core.mjs';
 import { selectErrorRecall } from './lib/error-recall-core.mjs';
 import {
   buildAndSaveHandoff,
+  consumeHandoff,
   detectContinuationIntent,
   renderHandoffInjection,
   pickHandoffToInject,
@@ -1974,9 +1975,11 @@ function runSessionStartAutoMaintain(db, project) {
         debugCatch(e, 'auto-maintain-orphan-sweep');
       }
 
-      // GC expired session_handoffs: the consume-DELETE (handleSessionStart) only removes
-      // the single handoff a continuation reads back; an 'exit'/'compact' that is never
-      // resumed (and every superseded 'clear') lingers forever — read paths filter by
+      // GC expired session_handoffs. This is now the ONLY reaper: consuming a handoff
+      // stamps `consumed_at` (injectHandoffIfEarly, the UserPromptSubmit path) instead of
+      // deleting the row, so nothing removes rows but this. Before that change a consume
+      // did delete one row, and an 'exit'/'compact' that is never
+      // resumed (and every superseded 'clear') lingered forever — read paths filter by
       // expiry but nothing reaped the rows. Delete past-expiry rows with a +1d margin so a
       // still-readable handoff is never raced away. 'clear' 6h+1d, 'exit'/other 7d+1d.
       try {
@@ -2893,12 +2896,13 @@ function injectHandoffIfEarly(db, { project, promptText, promptNumber, ccSession
           // Pre-v2.46 wiped every exit handoff for the project on any continuation
           // intent, which made the DB effectively forgetful: 115 completed sessions
           // produced 1 persisted handoff.
+          //
+          // Consuming STAMPS the row (consumed_at) rather than deleting it: the age-based
+          // GC in auto-maintain still reaps it, but until then the row that produced this
+          // injection can be read back. Every pool that relied on the row being gone now
+          // filters on UNCONSUMED_HANDOFF_SQL instead — the list is in handoff-constants.
           try {
-            db.prepare('DELETE FROM session_handoffs WHERE project = ? AND type = ? AND session_id = ?').run(
-              project,
-              picked.type,
-              picked.session_id,
-            );
+            consumeHandoff(db, picked);
           } catch {}
         }
       }

package/lib/git-state.mjs

@@ -47,7 +47,10 @@ export function readGitState({ cwd = process.cwd() } = {}) {
   const changed = statusOut ? statusOut.split('\n').filter(Boolean) : [];
   const stashOut = run('git', ['stash', 'list'], { cwd });
   const stashes = stashOut ? stashOut.split('\n').filter(Boolean) : [];
-  const branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd }) || null;
+  // `symbolic-ref`, not `rev-parse --abbrev-ref`: the latter returns the literal string
+  // "HEAD" on a detached head, which the handoff's tree-state line then rendered as
+  // `branch HEAD`. Failing to null is the honest answer — there is no branch.
+  const branch = run('git', ['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd }) || null;
   const headSha = run('git', ['rev-parse', 'HEAD'], { cwd }) || null;
   return { changed, stashes, branch, headSha };
 }

package/lib/handoff-constants.mjs

@@ -14,5 +14,18 @@ export const HANDOFF_EXPIRY_CLEAR = 6 * 3600000; // 6 hours (covers lunch/meetin
 export const HANDOFF_EXPIRY_EXIT = 7 * 24 * 60 * 60 * 1000; // 7 days
 export const HANDOFF_ANCHOR_MAX_AGE = 72 * 3600000; // 72h cap on git_sha anchor — avoids stale-HEAD false positives
 export const HANDOFF_MATCH_THRESHOLD = 3; // min weighted score
+
+// Availability predicate for a stored handoff. Injecting one STAMPS `consumed_at`
+// (hook-handoff.mjs::consumeHandoff) instead of deleting the row, so every pool that used
+// to rely on the row simply being GONE has to say so now. Spelled once, here, because the
+// five sites that need it are a decision and not a sweep:
+//   - pickHandoffToInject (both arms)        — else the same row re-injects on prompts 2-3
+//   - detectContinuationIntent Stage -1/0/2  — a consumed handoff is not resumable
+//   - hook-context's "Working State (from /clear)" block
+//   - startup-dashboard's "Continuation available" pointer, whose stated contract is to
+//     only promise what the injection could actually deliver
+// The one deliberate NON-site is hook.mjs's read-back immediately after buildAndSaveHandoff:
+// it reads the row it just wrote, by exact PK, before anything could have consumed it.
+export const UNCONSUMED_HANDOFF_SQL = 'consumed_at IS NULL';
 export const CONTINUE_KEYWORDS =
   /继续|接着|上次|之前的|前面的|刚才|\bcontinue\b|\bresume\b|\bwhere[\s-]+we[\s-]+left\b|\bpick[\s-]+up\b|\bcarry[\s-]+on\b/i;

package/lib/paused-reader.mjs

@@ -0,0 +1,167 @@
+// lib/paused-reader.mjs — read the newest `tasks/<slug>-paused.md` in a project.
+//
+// A paused note is the one place a session writes down BY HAND what is left and how to
+// verify it; the spec governing this repo makes writing one mandatory when a session exits
+// mid-task. Nothing read them. Measured 2026-09-21: 27 such files across 7 projects on this
+// machine, zero readers — the handoff was reconstructing "what next" from tool history
+// while the answer sat in the repo in prose.
+//
+// It is also why the next step is taken from a FILE rather than from a model summary:
+// session_summaries.next_steps is non-empty in 11 of 310 rows (3.5%), so that route has
+// already been measured and does not work.
+//
+// A leaf on purpose — `fs`/`path` only, no package imports and no edge back into the hook
+// layer, so importing it costs nothing at load time (same reason lib/data-paths.mjs is a
+// leaf). Every failure mode (missing dir, unreadable file, binary content, races between
+// readdir and stat) yields null or fewer items, never a throw: this runs inside handoff
+// construction, which must still persist a row.
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { join, basename } from 'path';
+// The one non-builtin import, and it does not cost the leaf property: format-utils' only
+// edge is lib/time-constants.mjs, itself importless. Reused rather than reimplemented
+// because a raw slice gets two things wrong that this function already documents — it
+// leaves no mark that the text was cut, and it can split a UTF-16 surrogate pair and emit
+// a lone surrogate.
+import { truncate } from '../format-utils.mjs';
+// Also importless — the handoff policy module. One number for "how old is too old" rather
+// than a second constant that can drift away from it.
+import { HANDOFF_EXPIRY_EXIT } from './handoff-constants.mjs';
+
+// Headings whose body is REMAINING WORK, in priority order — the first one present wins,
+// regardless of where it sits in the document. "Resume" is last because the generated notes
+// use it for a generic instruction, which is worth something but less than an explicit list.
+// Deliberately NOT matched: "Last mutation tool call(s)" and the completed sections, whose
+// bullets read like work items and are the opposite of work items.
+const REMAINING_HEADINGS = [
+  /^#{1,6}\s*(?:未完成|待办|剩余(?:工作)?)\s*$/i,
+  /^#{1,6}\s*(?:not\s+done|remaining(?:\s+work)?|todo|next\s+steps?)\s*$/i,
+  /^#{1,6}\s*(?:resume|恢复)\s*$/i,
+];
+
+// "# Paused — X" / "# 暂停 — X" / "# Paused: X" → X. A note whose title is only the word
+// keeps the whole line rather than becoming empty.
+const TITLE_PREFIX_RE = /^#{1,6}\s*(?:paused|暂停)\s*(?:[—–\-:：]\s*)?/i;
+const LIST_MARKER_RE = /^(?:[-*+]|\d+[.)])\s+/;
+const MAX_ITEM_CHARS = 200;
+// The read is synchronous and sits on the Stop path, once per assistant turn. Output was
+// already bounded (5 items x 200 chars) and the INPUT was not — a note is prose a human
+// wrote, so anything past this is not a note. Pre-ship defect lens.
+const MAX_NOTE_BYTES = 256 * 1024;
+
+/**
+ * Default project root, with test containment on the same channel lib/resolve-data-dir.mjs
+ * uses (audit 2026-08-22 P2-4).
+ *
+ * Under vitest the default resolves to the maintainer's real repo, which carries fifteen
+ * `tasks/*-paused.md` files of its own — so every suite that builds a handoff would quietly
+ * write this repo's paused note into the row under test. That was measured, not imagined:
+ * a probe over an unstubbed buildAndSaveHandoff came back carrying
+ * `tasks/session-end-b3c0c20d-paused.md`.
+ *
+ * Per-file `vi.spyOn` stubs fix the same leak but are discipline, not structure — nothing
+ * goes red when a new suite forgets one, which is how the sibling readers (readGitState,
+ * readProjectTasks) still leak into the files that do not stub them. Neutralising the
+ * DEFAULT instead makes the leak impossible while leaving an explicit `projectPath`
+ * untouched, so this module's own tests still read their temp dirs.
+ *
+ * The var is inherited by spawned hooks too, so e2e subprocesses are contained as well.
+ */
+function defaultProjectPath() {
+  return process.env.CLAUDE_MEM_TEST_GUARD === '1' ? null : process.cwd();
+}
+
+/**
+ * Read the newest paused note for a project.
+ *
+ * @param {object} [options]
+ * @param {string} [options.projectPath] Absolute path to the project root. Defaults to the
+ *        current working directory, and to nothing at all under the test guard.
+ * @param {number} [options.maxItems=5] Cap on returned items.
+ * @param {number} [options.maxAgeMs=HANDOFF_EXPIRY_EXIT] Ignore notes older than this.
+ * @returns {{file: string, title: string, items: string[]}|null} null when there is no note,
+ *          the newest one is stale, or it has nothing left to do.
+ */
+export function readPausedNote({
+  projectPath = defaultProjectPath(),
+  maxItems = 5,
+  maxAgeMs = HANDOFF_EXPIRY_EXIT,
+} = {}) {
+  if (!projectPath) return null;
+  const tasksDir = join(projectPath, 'tasks');
+  let newest = null;
+  try {
+    for (const name of readdirSync(tasksDir)) {
+      if (!name.endsWith('-paused.md')) continue;
+      try {
+        const st = statSync(join(tasksDir, name));
+        if (st.size > MAX_NOTE_BYTES) continue;
+        if (!newest || st.mtimeMs > newest.mtime) newest = { name, mtime: st.mtimeMs };
+      } catch {
+        /* vanished between readdir and stat — skip it */
+      }
+    }
+  } catch {
+    return null; // no tasks/ dir
+  }
+  if (!newest) return null;
+  // Staleness bound, on the NEWEST note only — if the freshest thing the project has to say
+  // is weeks old, nothing here is a next step. Measured on this repo 2026-09-21: 15 notes,
+  // 10 to 16 days old, all of them the generated session-end boilerplate, and the item they
+  // contributed quotes `bash tests/run-all.sh`, which this repo does not have. Bound is the
+  // exit handoff's own expiry: the note rides in on that row, so outliving it is incoherent.
+  if (Date.now() - newest.mtime > maxAgeMs) return null;
+
+  let text;
+  try {
+    text = readFileSync(join(tasksDir, newest.name), 'utf8');
+  } catch {
+    return null;
+  }
+
+  const lines = text.split('\n');
+  let title = '';
+  for (const line of lines) {
+    if (/^#\s+/.test(line)) {
+      title = line.replace(TITLE_PREFIX_RE, '').replace(/^#\s+/, '').trim();
+      break;
+    }
+  }
+
+  const items = [];
+  for (const heading of REMAINING_HEADINGS) {
+    const start = lines.findIndex((l) => heading.test(l.trim()));
+    if (start === -1) continue;
+    // A line is not an item. Markdown here comes in two shapes and hard-wrapping makes
+    // them look alike: a LIST, where each marker starts a new entry, and a PARAGRAPH,
+    // where a single sentence is split across physical lines. Treating every line as an
+    // item shreds one generated note's four-line Resume sentence into four fragments, each
+    // beginning mid-clause. So a marker opens an entry and everything up to the next marker
+    // or blank line is folded into it.
+    let current = '';
+    const flush = () => {
+      const item = current.trim();
+      if (item) items.push(truncate(item, MAX_ITEM_CHARS));
+      current = '';
+    };
+    for (let i = start + 1; i < lines.length && items.length < maxItems; i++) {
+      const raw = lines[i];
+      if (/^#{1,6}\s/.test(raw)) break; // next heading ends the section
+      const line = raw.trim();
+      if (!line) {
+        flush();
+        continue;
+      }
+      if (LIST_MARKER_RE.test(line)) {
+        flush();
+        current = line.replace(LIST_MARKER_RE, '').trim();
+      } else {
+        current = current ? `${current} ${line}` : line;
+      }
+    }
+    if (items.length < maxItems) flush();
+    if (items.length > 0) break;
+  }
+
+  if (items.length === 0) return null; // a note with nothing left to do is not a next step
+  return { file: `tasks/${basename(newest.name)}`, title, items };
+}

package/lib/scrub-record.mjs

@@ -53,6 +53,13 @@ export const TEXT_FIELDS_BY_TABLE = {
     'unfinished',
     // Excluded:
     //   key_files       — JSON.stringify(array); pre-scrub elements at call site
+    //   next_steps      — same shape, same reason: JSON.stringify({file,title,items}),
+    //                     pre-scrubbed element-wise in buildAndSaveHandoff. Listing it
+    //                     here would let scrubSecrets rewrite the SERIALIZED JSON, and the
+    //                     renderer's JSON.parse sits behind a `catch {}` — so the whole
+    //                     Next steps section would disappear silently rather than fail.
+    //                     Named here because the pre-ship review found the column had been
+    //                     added without updating this block, which is the file's contract.
     //   match_keywords  — currently a space-joined plain string; keeping it
     //                     here would scrub safely, but the value is built from
     //                     tokenizeHandoff() output (alphanumeric tokens only),

package/lib/startup-dashboard.mjs

@@ -9,7 +9,7 @@ import { readGitState } from './git-state.mjs';
 import { readProjectTasks } from './task-reader.mjs';
 import { recentPlans } from './plan-reader.mjs';
 import { isAdoptedHere } from './quiet-scope.mjs';
-import { HANDOFF_EXPIRY_EXIT } from './handoff-constants.mjs';
+import { HANDOFF_EXPIRY_EXIT, UNCONSUMED_HANDOFF_SQL } from './handoff-constants.mjs';
 
 function ageStr(ms) {
   const diff = Date.now() - ms;
@@ -32,7 +32,7 @@ function readRecentHandoff(db, project) {
       .prepare(
         `
       SELECT created_at_epoch, working_on FROM session_handoffs
-      WHERE project = ? AND type = 'exit' AND created_at_epoch > ?
+      WHERE project = ? AND type = 'exit' AND created_at_epoch > ? AND ${UNCONSUMED_HANDOFF_SQL}
       ORDER BY created_at_epoch DESC LIMIT 1
     `,
       )

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.9.1",
+  "version": "6.10.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-mem-lite",
-      "version": "6.9.1",
+      "version": "6.10.0",
       "os": [
         "darwin",
         "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "6.9.1",
+  "version": "6.10.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).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -69,6 +69,7 @@
     "lib/cli-flags.mjs",
     "lib/git-state.mjs",
     "lib/task-reader.mjs",
+    "lib/paused-reader.mjs",
     "lib/plan-reader.mjs",
     "lib/startup-dashboard.mjs",
     "lib/doctor-benchmark.mjs",

package/schema.mjs

@@ -191,6 +191,12 @@ export const CURRENT_SCHEMA_VERSION = 49;
 // pragma_table_info on a missing table returns zero rows (it does not throw), so
 // naming any column of the new table is a table-presence check.
 const LATEST_MIGRATION_COLUMNS = [
+  // No version tag: this one ships WITHOUT a CURRENT_SCHEMA_VERSION bump on purpose (see
+  // the ALTER's note). It is listed here for exactly the reason the list exists — to force
+  // the migration pass on a DB whose version row already says "done" — and listing it is
+  // what makes the ALTER reachable at all. Pinned by the legacy-upgrade case in
+  // tests/handoff-consume.test.mjs rather than left as an assertion in a comment.
+  { table: 'session_handoffs', column: 'consumed_at' },
   { table: 'observations', column: 'last_access_session_id' }, // v48
   { table: 'observations', column: 'decay_seen_at_first_cite' }, // v46
   { table: 'citation_surface_log', column: 'surface' }, // v45
@@ -576,6 +582,36 @@ export function initSchema(db) {
     if (!handoffCols.includes('git_sha_at_handoff')) {
       db.exec(`ALTER TABLE session_handoffs ADD COLUMN git_sha_at_handoff TEXT DEFAULT NULL`);
     }
+    // Injecting a handoff now STAMPS it (hook-handoff.mjs::consumeHandoff) where it used to
+    // DELETE the row, so the row survives for the expiry GC to reap on age and stays
+    // available to anyone auditing what was injected. Additive + nullable: a legacy row
+    // reads NULL, which is exactly "not yet consumed".
+    //
+    // No CURRENT_SCHEMA_VERSION bump, deliberately. The version row is what locks an older
+    // code home out of this DB permanently, and nothing here needs that: the forced-migration
+    // probe below (LATEST_MIGRATION_COLUMNS) already makes this ALTER reachable on a DB whose
+    // version row says 49/done, which is the whole reason that list exists. An older build
+    // opening this DB keeps working — it simply deletes handoffs the way it always did.
+    if (!handoffCols.includes('consumed_at')) {
+      db.exec(`ALTER TABLE session_handoffs ADD COLUMN consumed_at INTEGER DEFAULT NULL`);
+    }
+    // Tree state at handoff time. `git_sha_at_handoff` has been captured since v25 but was
+    // never rendered into the injection, and the sha alone does not answer the question a
+    // resuming session actually asks first ("which branch, and is the tree dirty?") — so the
+    // other two fields of the readGitState call that was already being made are stored too.
+    if (!handoffCols.includes('git_branch')) {
+      db.exec(`ALTER TABLE session_handoffs ADD COLUMN git_branch TEXT DEFAULT NULL`);
+    }
+    if (!handoffCols.includes('git_dirty_count')) {
+      db.exec(`ALTER TABLE session_handoffs ADD COLUMN git_dirty_count INTEGER DEFAULT NULL`);
+    }
+    // The remaining work a paused note spells out (lib/paused-reader.mjs). Kept out of
+    // `unfinished`, which renders as "Recent activity" and mixes in-flight edits with
+    // surfaced errors — calling a hand-written remaining-work list "recent activity" would
+    // mislabel the one field in this row that a human actually wrote.
+    if (!handoffCols.includes('next_steps')) {
+      db.exec(`ALTER TABLE session_handoffs ADD COLUMN next_steps TEXT DEFAULT NULL`);
+    }
   } catch {
     /* non-critical — migration retries on next open */
   }

package/source-files.mjs

@@ -66,6 +66,7 @@ export const SOURCE_FILES = [
   'lib/activity.mjs',
   'lib/cli-flags.mjs',
   'lib/task-reader.mjs',
+  'lib/paused-reader.mjs',
   'lib/plan-reader.mjs',
   'lib/git-state.mjs',
   'lib/startup-dashboard.mjs',