claude-mem-lite 6.28.1 → 6.29.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.28.1",
+      "version": "6.29.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. FTS5 BM25 keyword 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.28.1",
+  "version": "6.29.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. FTS5 BM25 keyword 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

@@ -237,6 +237,35 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
     repos/               # Shallow-cloned source repos
 ```
 
+## Upgrading to 6.29.0
+
+**Chinese text in lessons, facts, concepts and aliases becomes searchable, and the database opens
+after the update fill that in without holding up a hook.** No schema-version change: 6.28.1 still
+opens, searches and writes the database after this release has. Go back only after the fill
+finishes: rows it has not reached stay without the Latin identifiers glued to Chinese under 6.28.1.
+
+- **What it costs.** Each database open spends about 250 ms filling the index terms of existing
+  observations, newest first, each batch committed, until all are done. On a copy of the
+  maintainer's store (516 observations, most already filled by an earlier build of this pass)
+  the pass walked every row in one open of 48–49 ms. On a synthetic v6.27.0 store of 250,000
+  observations and 200,000 events (mostly CJK) the first open takes about 1 s (6.28.1: about 9 s,
+  and a 5 s hook opening it first was killed), and the fill then takes 105 opens of about 0.5 s;
+  an open after it takes 3 ms.
+- **A lesson a model writes onto one of your explicit saves starts with `🤖`**, and `get` says
+  "🤖 lesson auto-written". A lesson you write is never marked.
+- **Exit codes.** A flag that takes no value (`--force`, `--json`, `--confirm`, `--or`,
+  `--dry-run`, …) no longer swallows the next word: `delete --confirm 12` now deletes #12, and
+  `recent --json 5` prints JSON. `maintain`, `compress`, `optimize`, `delete`, `activity promote` /
+  `delete`, `import-jsonl`, `defer drop` and `fts-check rebuild`, which never read `--dry-run`,
+  refuse it with exit 1 on a run that would write, instead of running; `activity save`, `import-jsonl` and `restore` refuse a mistyped
+  `--project`; `uninstall` exits 3 when the MCP registration is left. CHANGELOG.md lists the
+  rest; a script that relied on the old behaviour needs a look.
+- **Also in this release:** the database waits of a hook that opens through `ensureDb` all end by
+  its deadline, the first open's migration, the prompt search and the Agent injection included;
+  the unattended re-enrich raises importance to 2 at most; three more background prompts send
+  stored rows to the model as data, and smart-compress and cluster merge act only on an explicit
+  yes. Details in CHANGELOG.md.
+
 ## Upgrading to 6.28.1
 
 **After the update, events are re-indexed so Chinese text in them is searchable** (the Han ranges

package/README.zh-CN.md

@@ -199,6 +199,15 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
     repos/               # 浅克隆的源代码仓库
 ```
 
+## 升级到 6.29.0
+
+**lesson、facts、concepts 和 aliases 里的中文变得可以搜到；更新后的数据库打开会逐步补上这些索引，不会拖住钩子。** 没有 schema 版本变化：本版打开过的数据库，6.28.1 仍能打开、搜索和写入。要退回，请等补完之后再退：还没补到的行，在 6.28.1 下会缺少粘在中文上的英文标识符。
+
+- **代价。** 每次打开数据库约花 250 ms 为已有的 observation 补索引词，从最新的开始，每批单独提交，直到补完。维护者的库的副本（516 条 observation，大部分已由这一遍的早期版本补过）上，这一遍一次打开（48–49 ms）就走完。在 25 万条 observation、20 万条 event（大部分含中文）的合成 v6.27.0 库上，首次打开约 1 s（6.28.1 约要 9 s，先打开它的 5 s 钩子 3 次都被杀掉），之后补完需要 105 次打开、每次约 0.5 s；补完后的一次打开 3 ms。
+- **模型写在你显式保存的记录上的 lesson 以 `🤖` 开头**，`get` 的标题行注明 "🤖 lesson auto-written"。你自己写的 lesson 不会被标记。
+- **退出码。** 不带值的 flag（`--force`、`--json`、`--confirm`、`--or`、`--dry-run` 等）不再吞掉后面的词：`delete --confirm 12` 现在会删除 #12，`recent --json 5` 输出 JSON。`maintain`、`compress`、`optimize`、`delete`、`activity promote` / `delete`、`import-jsonl`、`defer drop` 和 `fts-check rebuild` 从来不读 `--dry-run`，在会写入的运行中遇到它会以 exit 1 拒绝，而不是照常执行；`activity save`、`import-jsonl` 和 `restore` 拒绝拼错的 `--project`；MCP 注册没删掉时 `uninstall` 以 exit 3 结束。其余见 CHANGELOG.md；依赖旧行为的脚本需要检查一下。
+- **本版还有：** 经 `ensureDb` 打开数据库的钩子，所有数据库等待都在截止时间前结束，包括首次打开的迁移、提示词搜索和 Agent 注入；无人值守的 re-enrich 最多把 importance 提到 2；又有三个后台提示把存储的行作为数据交给模型；smart-compress 和 cluster merge 只在明确同意时才动手。详见 CHANGELOG.md。
+
 ## 升级到 6.28.1
 
 **更新后会给事件重建索引，事件里的中文从此能搜到**（切分 U+4E00–9FFF 和 U+3400–4DBF 两段汉字；假名、韩文和更少见的汉字扩展区不切分）。

package/cli/activity.mjs

@@ -9,7 +9,7 @@
 // events_fts via triggers.
 
 import { inferProject } from '../utils.mjs';
-import { resolveProject } from '../project-utils.mjs';
+import { resolveProject, checkWriteProject } from '../project-utils.mjs';
 import { resolveCliProject as cliProject } from '../lib/cli-project.mjs';
 import { parseArgs, out, fail, rejectBareStringFlags } from './common.mjs';
 import { parseIntFlag, isNumericToken } from '../lib/cli-flags.mjs';
@@ -42,9 +42,11 @@ export async function cmdActivity(db, args) {
   // `save` CREATES a row, so it keeps plain inferProject(): the DB-aware fallback is a read
   // affordance, and applying it to a write absorbs a not-yet-born subproject's first event
   // into the enclosing repo (pre-tag review, reproduced). Every other subcommand reads or
-  // operates on rows that already exist, where falling back is what finds them.
+  // operates on rows that already exist, where falling back is what finds them. A named
+  // project is resolved for `save` the way `save` and `defer add` resolve theirs: exact
+  // matching only, then checkWriteProject below.
   const project = flags.project
-    ? resolveProject(db, flags.project)
+    ? resolveProject(db, flags.project, sub === 'save' ? { mode: 'write' } : undefined)
     : sub === 'save'
       ? inferProject()
       : cliProject(db);
@@ -86,6 +88,13 @@ export async function cmdActivity(db, args) {
       fail(`[mem] Invalid importance "${flags.importance}". Must be 1, 2, or 3.`);
       return;
     }
+    // A near miss of an existing project is refused, a new name is noted: the check `save` and
+    // `defer add` make (pre-tag review 2026-10-16 P3-4). stdout stays the JSON line.
+    const projectCheck = flags.project ? checkWriteProject(db, project) : { ok: true, note: '' };
+    if (!projectCheck.ok) {
+      fail(`[mem] ${projectCheck.message}`);
+      return;
+    }
     const id = saveEvent(db, {
       project,
       event_type: type,
@@ -95,6 +104,7 @@ export async function cmdActivity(db, args) {
       file_paths,
     });
     out(JSON.stringify({ ok: true, id }));
+    if (projectCheck.note) process.stderr.write(`[mem] Saved event E#${id}${projectCheck.note}\n`);
     return;
   }
 

package/cli/common.mjs

@@ -13,6 +13,47 @@ import { neutralizeContextDelimiters, neutralizeSkillDelimiters } from '../forma
 
 // ─── Argument Parsing ────────────────────────────────────────────────────────
 
+/**
+ * Flags that take no value: every reader tests them against true / 'true' (or for presence in
+ * argv), so the word after one is a positional. parseArgs read every `--key next` as key=value,
+ * and `save --type bugfix --title X --force 'text'` parsed `force: 'text'` and no content (the
+ * usage error) while the text-first spelling saved; the swallowed word did not even turn the
+ * flag on, so `search --or redis` lost its query and its --or (D#385, same in v6.27.0). An
+ * explicit `--json true` / `--force false` still parses as before.
+ * tests/cli-boolean-flag-parsing.test.mjs derives the boolean readers from the sources and
+ * fails on one missing here.
+ */
+export const BOOLEAN_CLI_FLAGS = new Set([
+  'all',
+  'apply',
+  'benchmark',
+  'confirm',
+  'deep',
+  'disable',
+  'dry-run',
+  'enable',
+  'execute',
+  'force',
+  'help',
+  'include-compressed',
+  'include-noise',
+  'json',
+  'metrics',
+  'no-deep',
+  'or',
+  'print-project',
+  'quality',
+  'rerank',
+  'retry',
+  'run',
+  'run-all',
+  'search-telemetry',
+  'session-audit',
+  'sidechain',
+  'status',
+  'verbose',
+]);
+
 /**
  * Parse argv-style array into { positional, flags }.
  * `--key value` → flags.key = value; `--flag` (no value) → flags.key = true.
@@ -76,7 +117,11 @@ export function parseArgs(argv, { track = true } = {}) {
       }
       const key = body;
       const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith('--') && (!next.startsWith('-') || /^-\d/.test(next))) {
+      // A flag that takes no value leaves the next word alone, except an explicit true/false.
+      const takes = BOOLEAN_CLI_FLAGS.has(canonicalFlag(key))
+        ? next === 'true' || next === 'false'
+        : next !== undefined && !next.startsWith('--') && (!next.startsWith('-') || /^-\d/.test(next));
+      if (takes) {
         setFlag(key, next);
         i += 2;
       } else {

package/hook-episode.mjs

@@ -16,7 +16,15 @@ import {
   constants as fsConstants,
 } from 'fs';
 import { inferProject, isEditEntry } from './utils.mjs';
-import { RUNTIME_DIR, hostScopeSuffix, deadHostFiles, isOtherLiveHost } from './hook-shared.mjs';
+import {
+  RUNTIME_DIR,
+  hostScopeSuffix,
+  deadHostFiles,
+  isOtherLiveHost,
+  processAlive,
+  STALE_LOCK_MS,
+  ABANDONED_LOCK_MS,
+} from './hook-shared.mjs';
 import { inferProjectDir } from './project-utils.mjs';
 import { legacyProjectNameFromDir } from './lib/project-rekey.mjs';
 
@@ -124,8 +132,12 @@ export function lockFile() {
  */
 export function acquireLock(maxWaitMs = 500) {
   const lf = lockFile();
-  const deadline = Date.now() + maxWaitMs;
-  while (Date.now() < deadline) {
+  // The wait is measured on this process's own clock (performance.now()), which a step of the
+  // system clock does not move, as the hook's DB deadline is (setHookDbDeadline). On Date.now() a
+  // backward step kept a hook spinning here until the host killed it, and a forward one gave up
+  // at once (D#398).
+  const start = performance.now();
+  while (performance.now() - start < maxWaitMs) {
     try {
       let fd;
       try {
@@ -141,15 +153,14 @@ export function acquireLock(maxWaitMs = 500) {
       try {
         const raw = readFileSync(lf, 'utf8');
         const info = JSON.parse(raw);
+        // On the wall clock: the stamp is another process's, and only that clock is shared.
         const age = Date.now() - (info.ts || 0);
-        let stale = age > 30000; // >30s = stale
-        if (!stale && info.pid) {
-          try {
-            process.kill(info.pid, 0);
-          } catch (killErr) {
-            stale = killErr.code === 'ESRCH'; // Only stale if process truly gone
-          }
-        }
+        // A recorded holder is asked first. A gone one's lock is stale at once; a running one keeps
+        // it until ABANDONED_LOCK_MS, the bound cleanStaleLockFiles and proc-lock give a live
+        // holder, past which its pid is taken to be recycled. Age alone (> STALE_LOCK_MS) took a
+        // running holder's lock without asking once a forward clock step or a suspended machine
+        // made it look 30 s old, and two hooks then rewrote the buffer at once (D#398).
+        const stale = info.pid ? !processAlive(info.pid) || age > ABANDONED_LOCK_MS : age > STALE_LOCK_MS;
         if (stale) {
           try {
             unlinkSync(lf);

package/hook-llm.mjs

@@ -246,7 +246,13 @@ function buildFtsTextField(obs) {
   const conceptsText = Array.isArray(obs.concepts) ? obs.concepts.join(' ') : '';
   const factsText = Array.isArray(obs.facts) ? obs.facts.join(' ') : '';
   const aliasesText = obs.searchAliases || '';
-  const bigramText = cjkIndexTerms((obs.title || '') + ' ' + (obs.narrative || ''));
+  // Every field the row is searched by, not title + narrative alone: unicode61 keeps a CJK run as
+  // one token, so CJK in a lesson, fact, concept or alias was unreachable without these (D#374).
+  const bigramText = cjkIndexTerms(
+    [obs.title, obs.narrative, conceptsText, factsText, aliasesText, obs.lessonLearned]
+      .filter(Boolean)
+      .join(' '),
+  );
 
   // Degraded fallback: when LLM enrichment is missing, extract lightweight keywords
   // from title + narrative so degraded observations remain FTS-searchable
@@ -449,7 +455,9 @@ export function saveObservation(obs, projectOverride, sessionIdOverride, externa
         minhash_sig: minhashSig,
         lesson_learned: safe.lesson_learned,
         search_aliases: safe.search_aliases,
-        branch: getCurrentBranch(),
+        // An episode worker passes the branch its flush file names, null included (P3-5); every
+        // other writer runs in the session's own cwd.
+        branch: obs.branch === undefined ? getCurrentBranch() : obs.branch,
         created_at: now.toISOString(),
         created_at_epoch: now.getTime(),
         // P3 (D#78): re-validate at the write boundary — saveObservation is also
@@ -500,7 +508,9 @@ function obsToSummary(obs) {
 //
 // Input shape (matches the v2.31 MVP plan's stable interface):
 //   summary: { type, title, lesson_learned?, narrative?, importance?, files_modified? }
-//   ctx:     { project, session_id, preSavedObsId? }
+//   ctx:     { project, session_id, preSavedObsId?, branch? }
+//   (`branch`: the episode's, observations only — events have no branch column; omitted, the
+//   row takes this process's cwd branch)
 //
 // Returns { table: 'events'|'observations', id: number|null }. Callers inspect
 // `table` to decide whether follow-up observations-only logic (linking, vector
@@ -563,6 +573,7 @@ export function persistHaikuSummary(db, summary, ctx) {
       lessonLearned: summary.lesson_learned || null,
       searchAliases: summary.search_aliases || null,
       scope: summary.scope ?? null,
+      branch: ctx.branch,
     },
     ctx.project,
     ctx.session_id,
@@ -1033,6 +1044,22 @@ export function episodeWorkerMaxMs() {
   return EPISODE_DELAY_MAX_MS + 2 * (LLM_SEM_TIMEOUT + BG_LLM_TIMEOUT_MS) + EPISODE_WORKER_SLACK_MS;
 }
 
+/**
+ * episodeWorkerMaxMs() for a worker of v6.27.0 or older, which never claims its flush file
+ * (claimFlushFile is v6.28.0's) and whose keyed-provider fallback gave the CLI a fresh full
+ * timeout, so each of its two calls could take 2 x BG_LLM_TIMEOUT_MS: 365 s today. The age an
+ * unclaimed file must reach before recoverOrphanEpisodeFlushes hands it on (pre-tag review
+ * 2026-10-16 P3-4): during the update from such a version its worker can still be saving the
+ * episode at 275 s, and a second worker saved it again. A worker of this version claims its file
+ * before its delay, so an unclaimed file is otherwise one whose worker never started, and it is
+ * handed on 90 s later than a claimed one.
+ *
+ * @returns {number} ms
+ */
+export function unclaimedFlushMinAgeMs() {
+  return EPISODE_DELAY_MAX_MS + 2 * (LLM_SEM_TIMEOUT + 2 * BG_LLM_TIMEOUT_MS) + EPISODE_WORKER_SLACK_MS;
+}
+
 /** The ending a flush file takes when it is handed to a second worker. It is never handed on again. */
 export const RECOVERED_FLUSH_SUFFIX = '.recovered.json';
 // Per SessionStart: LLM_SEM_MAX workers can call the model at once, and a backlog after a reboot
@@ -1078,7 +1105,9 @@ export function claimFlushFile(path, pid = process.pid) {
  *     worker paused past that bound by a suspended machine finishes and saves once the machine
  *     wakes, so handing its file on too stored the episode twice (D#383: events have no
  *     duplicate check). A pid reused by an unrelated process reads as alive, and that file is
- *     left to the 1 h sweep, as every flush file was before this hand-off existed.
+ *     left to the 1 h sweep, as every flush file was before this hand-off existed. An unclaimed
+ *     file waits for unclaimedFlushMinAgeMs() instead: it can be a pre-claim worker's, whose
+ *     bound is longer.
  *   - One taker: the file is renamed before the spawn, and of two SessionStarts only one rename
  *     succeeds; of a SessionStart and a worker claiming the same file, likewise.
  *   - No loop: the new name carries `.recovered`, which this never hands on, claimed or not. If
@@ -1106,6 +1135,7 @@ export function recoverOrphanEpisodeFlushes(
     return [];
   }
   const minAge = episodeWorkerMaxMs();
+  const unclaimedMinAge = unclaimedFlushMinAgeMs();
   const candidates = [];
   for (const f of names) {
     const m = FLUSH_NAME_RE.exec(f);
@@ -1117,7 +1147,8 @@ export function recoverOrphanEpisodeFlushes(
       continue; // its worker finished meanwhile
     }
     const age = now - mtimeMs;
-    if (age > minAge && age < ORPHAN_EPISODE_AGE_MS) candidates.push({ f, mtimeMs });
+    if (age > (m[3] ? minAge : unclaimedMinAge) && age < ORPHAN_EPISODE_AGE_MS)
+      candidates.push({ f, mtimeMs });
   }
   candidates.sort((a, b) => a.mtimeMs - b.mtimeMs || (a.f < b.f ? -1 : 1));
   const handed = [];
@@ -1471,6 +1502,10 @@ export async function handleLLMEpisode() {
   try {
     let savedId;
     let savedTable;
+    // One context for every save below. `branch` is the one the flushing hook read in the
+    // session's cwd (P3-5); a file written before that stamp has none, and the row takes this
+    // worker's cwd branch, as before.
+    const ctx = { project: episode.project, session_id: episode.sessionId, branch: episode.branch };
 
     if (episode.savedId && obs) {
       if (EVENT_TYPE_SET.has(obs.type)) {
@@ -1478,11 +1513,7 @@ export async function handleLLMEpisode() {
         // classified by Haiku as an event type. Delete the stale observations
         // row and insert into events instead. Dispatcher handles the atomic
         // swap via transaction.
-        const result = persistHaikuSummary(db, obsToSummary(obs), {
-          project: episode.project,
-          session_id: episode.sessionId,
-          preSavedObsId: episode.savedId,
-        });
+        const result = persistHaikuSummary(db, obsToSummary(obs), { ...ctx, preSavedObsId: episode.savedId });
         savedId = result.id;
         savedTable = result.table;
         debugLog('DEBUG', 'llm-episode', `upgrade-delete: obs #${episode.savedId} → event #${savedId}`);
@@ -1549,10 +1580,7 @@ export async function handleLLMEpisode() {
             'llm-episode',
             `pre-saved obs #${episode.savedId} no longer live — saving enrichment as a fresh row`,
           );
-          const result = persistHaikuSummary(db, obsToSummary(obs), {
-            project: episode.project,
-            session_id: episode.sessionId,
-          });
+          const result = persistHaikuSummary(db, obsToSummary(obs), ctx);
           savedId = result.id;
           savedTable = result.table;
         } else {
@@ -1563,10 +1591,7 @@ export async function handleLLMEpisode() {
       }
     } else {
       // Clean insert (no pre-save) — dispatcher routes by type.
-      const result = persistHaikuSummary(db, obsToSummary(obs), {
-        project: episode.project,
-        session_id: episode.sessionId,
-      });
+      const result = persistHaikuSummary(db, obsToSummary(obs), ctx);
       savedId = result.id;
       savedTable = result.table;
     }
@@ -1591,15 +1616,34 @@ export async function handleLLMEpisode() {
 
 // ─── Background: LLM Session Summary ────────────────────────────────────────
 
-export async function handleLLMSummary() {
-  // Seconds. The default spans an episode worker's whole bound (E2E 2026-10-16 P2-4): it was 15,
-  // below one CLI-leg episode (2-5 s delay + 8-13 s call, + the lesson retry on a bugfix), so the
-  // summary read the DB before the episode's observation existed, found nothing, and the session
-  // kept its Stop-time baseline. A longer default costs nothing when the flush clears early: the
-  // loop below exits on the first tick that finds this summary's files gone.
-  const parsed = parseInt(process.env.CLAUDE_MEM_FLUSH_TIMEOUT, 10);
-  const flushTimeout = Number.isNaN(parsed) ? Math.ceil(episodeWorkerMaxMs() / 1000) : parsed;
+/**
+ * The stem of a flush file whose episode a worker can still save, or null: a name that is not a
+ * flush file's, or a file whose claiming worker (`.w<pid>`, claimFlushFile) is gone. Such a file
+ * waits for SessionStart's hand-off, which takes it only once it is older than
+ * episodeWorkerMaxMs(), so a summary waiting on it waited its whole default for nothing (pre-tag
+ * review 2026-10-16 P3-3: ~82 MB resident for up to 275 s, one per Stop). A pid reused by another
+ * process reads as alive, and its file is waited on as before.
+ *
+ * @param {string} name
+ * @returns {string|null}
+ */
+function inFlightFlushStem(name) {
+  const m = FLUSH_NAME_RE.exec(name);
+  if (!m || (m[3] && !processAlive(Number(m[3])))) return null;
+  return m[1];
+}
 
+/**
+ * Wait up to `flushTimeout` seconds for the episode flushes in flight when it is called, so the
+ * summary reads the observations they save. Returns true as soon as `superseded()` says this
+ * summary's reply would be dropped anyway (checked before every tick): Stop spawns one summary
+ * worker per turn, and each waited out the flush after a later Stop had made it moot (P3-3).
+ *
+ * @param {number} flushTimeout seconds
+ * @param {() => boolean} superseded
+ * @returns {Promise<boolean>}
+ */
+async function waitForEpisodeFlushes(flushTimeout, superseded) {
   // Wait for a DEFINED SET of flush files, not for "the directory is empty" (audit
   // 2026-09-02 P1-7). RUNTIME_DIR is shared by every project on the machine, and the old
   // predicate was `readdirSync(RUNTIME_DIR).some(f => f.startsWith('ep-flush-'))` — so:
@@ -1623,14 +1667,15 @@ export async function handleLLMSummary() {
   // is a bounded overlap with genuinely concurrent work.
   //
   // Tracked by stem (D#383): the worker renames its file when it claims it, and a hand-off renames
-  // it again, so the flush is in flight until no file of that stem is left.
+  // it again, so the flush is in flight until no file of that stem is left, or only one whose
+  // claiming worker is gone (inFlightFlushStem).
   let pending;
   try {
     const cutoff = Date.now() - episodeWorkerMaxMs();
     pending = [
       ...new Set(
         readdirSync(RUNTIME_DIR)
-          .filter((f) => FLUSH_NAME_RE.test(f))
+          .filter((f) => inFlightFlushStem(f) !== null)
           .filter((f) => {
             try {
               return statSync(join(RUNTIME_DIR, f)).mtimeMs >= cutoff;
@@ -1646,6 +1691,7 @@ export async function handleLLMSummary() {
   }
 
   for (let i = 0; i < flushTimeout && pending.length > 0; i++) {
+    if (superseded()) return true;
     await sleep(1000);
     let names;
     try {
@@ -1653,7 +1699,7 @@ export async function handleLLMSummary() {
     } catch {
       names = [];
     }
-    pending = pending.filter((stem) => names.some((f) => f.startsWith(`${stem}.`)));
+    pending = pending.filter((stem) => names.some((f) => inFlightFlushStem(f) === stem));
     debugLog(
       'DEBUG',
       'llm-summary',
@@ -1667,10 +1713,22 @@ export async function handleLLMSummary() {
       `gave up waiting on ${pending.length} flush file(s) after ${flushTimeout}s: ${pending.join(', ')}`,
     );
   }
+  return false;
+}
+
+export async function handleLLMSummary() {
+  // Seconds. The default spans an episode worker's whole bound (E2E 2026-10-16 P2-4): it was 15,
+  // below one CLI-leg episode (2-5 s delay + 8-13 s call, + the lesson retry on a bugfix), so the
+  // summary read the DB before the episode's observation existed, found nothing, and the session
+  // kept its Stop-time baseline. A longer default costs nothing when the flush clears early: the
+  // wait exits on the first tick that finds this summary's files gone.
+  const parsed = parseInt(process.env.CLAUDE_MEM_FLUSH_TIMEOUT, 10);
+  const flushTimeout = Number.isNaN(parsed) ? Math.ceil(episodeWorkerMaxMs() / 1000) : parsed;
 
   // The spawning Stop's epoch (absent for the /clear spawn and pre-upgrade workers). Checked
-  // before the model call and again in the write's transaction, because two workers of one
-  // session can finish out of order (P3-6); the later Stop's worker reads the newer window.
+  // during the flush wait, before the model call and again in the write's transaction, because
+  // two workers of one session can finish out of order (P3-6); the later Stop's worker reads the
+  // newer window.
   const parsedEpoch = Number(process.argv[5]);
   const spawnEpoch = Number.isFinite(parsedEpoch) && parsedEpoch > 0 ? parsedEpoch : null;
   // One `summary_worker` metric row per exit (CLAUDE_MEM_METRICS=1), carrying the session and
@@ -1688,6 +1746,7 @@ export async function handleLLMSummary() {
       ...(llmMs === undefined ? {} : { llmMs }),
     });
 
+  // Opened before the flush wait, which reads the session's latest Stop before every tick.
   const db = openDb();
   if (!db) return outcome('no-db');
 
@@ -1695,6 +1754,11 @@ export async function handleLLMSummary() {
     const sessionId = process.argv[3] || getSessionId();
     const project = process.argv[4] || inferProject();
 
+    if (await waitForEpisodeFlushes(flushTimeout, () => summarySuperseded(db, sessionId, spawnEpoch))) {
+      debugLog('DEBUG', 'llm-summary', 'a later Stop owns this session summary, stopped waiting');
+      return outcome('superseded-before-call');
+    }
+
     // Exclude LOW_SIGNAL hook-llm fallback titles ("Error: files +2 more: ...",
     // "Modified X", "Worked on X", etc.) from the Haiku summary input — they
     // pollute the `completed` field and mislead session-resume context.