claude-mem-lite 6.24.0 → 6.25.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "6.24.0",
+      "version": "6.25.1",
       "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.24.0",
+  "version": "6.25.1",
   "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,22 @@ rm -rf ~/claude-mem-lite/   # pre-v0.5 unhidden (if not auto-moved)
     repos/               # Shallow-cloned source repos
 ```
 
+## Upgrading to 6.25.0
+
+**Every session gets the same first line on a file-recall block again.** No schema-version
+change: 6.24.0 still opens the database after this release has.
+
+- **What changes.** Since 6.16.0 half of sessions got a plain statement of where the notes come
+  from instead of "system-injected context, continue your planned action", so the two could be
+  compared by how often the agent cited a lesson. On the maintainer's own sessions the comparison
+  found no difference it could detect, and a scan of the agent's replies found neither line
+  surfaced to the user, so the split is closed: unset now means the older line in every session.
+  `CLAUDE_MEM_RECALL_FRAMING=factual` keeps the plain statement; `=ab` restores the split.
+- **Also in this release:** when the data directory cannot be read, `doctor` says "not checked"
+  for what it could not look at and `status` names the directory, instead of reporting a missing
+  or empty store. `maintain execute --ops dedup` names the merge pairs it skips. Details in
+  CHANGELOG.md.
+
 ## Upgrading to 6.24.0
 
 **If you set `CLAUDE_CONFIG_DIR`, the installer, updates and hooks now use that directory, as
@@ -253,7 +269,8 @@ release has. Without `CLAUDE_CONFIG_DIR` nothing in this item changes.
   entries an older version wrote into `~/.claude/settings.json` stay there; if no other profile
   uses `~/.claude`, `env -u CLAUDE_CONFIG_DIR claude-mem-lite cleanup-hooks` removes them.
 - **Also in this release:** `npm install -g claude-mem-lite` and `npx` no longer install the
-  development toolchain (96 packages / 57 MB instead of 298 / 541 MB). A confirmed
+  development toolchain. As a dependency install it went from 298 packages / 541 MB to 96 / 57 MB;
+  after the release, `-g` and `npx` measured the same 96 packages. A confirmed
   `maintain execute --ops purge_stale` now deletes every row its preview counted in one run,
   behind one snapshot. `doctor` warns about a failing update check and about an
   `ANTHROPIC_BASE_URL` that ends in `/v1`. Details in CHANGELOG.md.
@@ -1234,7 +1251,7 @@ and names can change between releases.
 |----------|-------------|---------|
 | `CLAUDE_MEM_TASK_IMPERATIVE` | `on`/`1` injects the single most relevant lesson at prompt position under an imperative template. | _(off)_ |
 | `CLAUDE_MEM_SUBAGENT_INJECT` | Dispatch-time memory injection for subagents. | _(off)_ |
-| `CLAUDE_MEM_RECALL_FRAMING` | First line of a PreToolUse / PostToolUse recall block. `ab` gives each session one of two wordings, the older "system-injected context, continue your planned action" or a plain statement of source, so their cite-rates can be compared in one run (`benchmark/citation-live-replay.mjs --by-framing`); `legacy` / `factual` pin one. | `ab` |
+| `CLAUDE_MEM_RECALL_FRAMING` | First line of a PreToolUse / PostToolUse recall block. Unset or `legacy` = "system-injected context, continue your planned action"; `factual` = a plain statement of where the notes come from; `ab` = each session gets one of the two, for `benchmark/citation-live-replay.mjs --by-framing`. Any other value is `legacy`. | `legacy` |
 | `CLAUDE_MEM_SALIENCE` | Selects how the pre-edit lesson line asks for a response: unset = name a lesson's `#NN` only where it changed the edit; `verdict` = the pre-6.17 per-lesson `applied` / `n/a` verdict (the adoption row in CLAUDE.md and the detail doc keep the new wording, and since 6.17.1 the directive says it overrides them); `bind` / `bridge` = comprehension-bridge arms (`bridge` keeps the pre-6.17 verdict wording as its fallback; neither says it overrides the adopted text, so their measured wording stays fixed); `legacy` = no directive. | _(unset)_ |
 | `CLAUDE_MEM_EDGE_DECAY` | Enables decay of file↔observation edges. | _(off)_ |
 | `CLAUDE_MEM_EDGE_DECAY_K` | Edge-decay threshold when the flag above is on (clamped to ≥1). | `3` |

package/README.zh-CN.md

@@ -199,6 +199,35 @@ rm -rf ~/claude-mem-lite/   # v0.5 前的非隐藏目录（如未自动迁移）
     repos/               # 浅克隆的源代码仓库
 ```
 
+## 升级到 6.25.0
+
+**文件召回块的第一行，所有会话重新用同一种写法。** 没有 schema 版本变更：本版本打开过的数据库，6.24.0 仍能打开。
+
+- **变了什么。** 从 6.16.0 起，一半会话的第一行是说明笔记来源的事实陈述，另一半保留 "system-injected context,
+  continue your planned action"，用来比较 agent 引用教训的频率。在维护者自己的会话上，两种写法看不出差别，
+  按回复文本扫描，两组里 agent 也都没有把这一行当作可疑内容告诉用户，所以结束分组：
+  不设变量时，所有会话都用旧的那一行。
+  `CLAUDE_MEM_RECALL_FRAMING=factual` 保留事实陈述的写法，`=ab` 恢复分组。
+- **本版本还有：** 数据目录读不了时，`doctor` 对看不到的项目显示“not checked”，`status` 直接指出这个目录
+  无法访问，不再报成数据库缺失或为空。`maintain execute --ops dedup` 会列出跳过的合并对。详见 CHANGELOG.md。
+
+## 升级到 6.24.0
+
+**如果你设置了 `CLAUDE_CONFIG_DIR`，安装程序、更新和 hook 现在都使用这个目录，和 Claude Code 一致。**
+没有 schema 版本变更：本版本打开过的数据库，6.23.3 仍能打开。没设 `CLAUDE_CONFIG_DIR` 时，这一条不带来任何变化。
+
+- **受影响的是谁。** 设了 `CLAUDE_CONFIG_DIR` 时，Claude Code 把 `settings.json`、`plugins/` 和 `.claude.json`
+  都放在那个目录里，插件却一直用 `~/.claude` 和 `~/.claude.json`：`install` 把 hook 写到了 Claude Code 不读的
+  地方；有两个配置目录时，会话启动的整理步骤和 `self-update` 会清掉另一个配置目录的插件缓存，并改动它的
+  `.claude.json`。
+- **要做什么。** 用 npm 或 npx 安装的：在设好这个变量的情况下再运行一次 `claude-mem-lite install`，让 hook 写进
+  你的配置目录。插件安装不用做什么。旧版本写进 `~/.claude/settings.json` 的 hook 条目会留在那里；如果没有别的
+  配置目录在用 `~/.claude`，可以用 `env -u CLAUDE_CONFIG_DIR claude-mem-lite cleanup-hooks` 清掉。
+- **本版本还有：** `npm install -g claude-mem-lite` 和 `npx` 不再安装开发工具链。按依赖方式安装，从 298 个包 /
+  541 MB 降到 96 个包 / 57 MB；发布后实测 `-g` 和 `npx` 也是同样的 96 个包。确认执行的
+  `maintain execute --ops purge_stale` 现在一次运行就删掉预览里统计的全部行，只做一次快照。`doctor` 会对失败的
+  更新检查、以及以 `/v1` 结尾的 `ANTHROPIC_BASE_URL` 发出警告。详见 CHANGELOG.md。
+
 ## 升级到 6.23.1
 
 **如果你设置了 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`，后台 LLM 调用现在会发往那个网关。**

package/bash-utils.mjs

@@ -632,6 +632,28 @@ function withoutDiffHunks(text) {
 // Paths excluded from observation capture (ephemeral / virtual filesystems) — applied
 // uniformly to both command-parsed paths and direct file_path/path/filePath fields.
 
+// A line a test runner prints for one test (`# Subtest:` heads a failing one too): it carries the
+// test's name, not a summary.
+const PASSED_TEST_LINE_RE = /^[ \t]*(?:✔|✓|ok[ \t]+\d+[ \t]+-|# Subtest:)/;
+
+/**
+ * Whether test-runner output carries a red summary or failure banner (detectBashSignificance's
+ * veto on a green "0 fail" marker; D#179).
+ * @param {string} scan
+ * @returns {boolean}
+ */
+function hasRedTestSummary(scan) {
+  const lines = scan
+    .split('\n')
+    .filter((l) => !PASSED_TEST_LINE_RE.test(l))
+    .join('\n');
+  return (
+    /\b[1-9]\d*[ \t]+(?:fail|failed|failures|failing|errors?)\b(?=[ \t]*(?:$|[,;|(]|\.(?:[ \t]|$)|in[ \t]+\S))|^[ \t]*(?:ℹ|#)[ \t]*(?:fail|cancelled)[ \t]+[1-9]\d*[ \t]*$/im.test(
+      lines,
+    ) || /^[ \t]*(?:--- )?FAIL(?:ED)?(?::|[ \t]|$)/m.test(lines)
+  );
+}
+
 /**
  * Detect significance signals in a Bash command and its response.
  * Checks for errors, test runs, builds, git operations, and deployments.
@@ -675,12 +697,23 @@ export function detectBashSignificance(input, response) {
   // suites prints one summary each, and a node:test run whose failures were all timeouts says
   // "fail 0" next to "cancelled 1" (pre-tag defect review, item 7 F1). Red = a nonzero fail /
   // cancelled count in either summary form.
+  // D#179: a count-first red must sit where a summary puts it — end of line, or before `,` `;`
+  // `|` `(` `. ` or `in …` — on ONE line, and never on a line a runner prints for a PASSED test
+  // (node:test `✔ name (1ms)`, vitest / bun `✓ name`, TAP `ok 1 - name` and its `# Subtest:`),
+  // which carries the test's NAME. Matched anywhere and across newlines, a passing run whose test
+  // name or log said "3 failed" / "2 failed attempts" read red, and "want 2\nFAIL" read as
+  // "2 FAIL". `errors?` is red too (pytest "1 passed, 1 error", tsc "Found 1 error in …",
+  // eslint "(2 errors, 0 warnings)"). go / jest / vitest / shell-suite failures carry a
+  // case-sensitive FAIL / FAILED banner at line start ("--- FAIL:", "FAILED: 3 case(s)", pytest
+  // "FAILED test_x.py::…"), read on its own. The green marker still
+  // spans lines on purpose: made one-line, 17 of this machine's 77,819 recorded results flipped
+  // to errors, and 15 of them were passing batteries, file reads and reports that only ever
+  // matched "0\nFAIL" by accident; 2 were real failures (measured 2026-10-07, recounted by the
+  // pre-tag delta review).
   const hasGreenTestSummary =
     looksLikeError &&
     /\b0\s+(fail|failed|failures)\b|^[ \t]*(?:ℹ|#)[ \t]*fail[ \t]+0[ \t]*$/im.test(scan) &&
-    !/\b[1-9]\d*\s+(fail|failed|failures|failing)\b|^[ \t]*(?:ℹ|#)[ \t]*(?:fail|cancelled)[ \t]+[1-9]\d*[ \t]*$/im.test(
-      scan,
-    );
+    !hasRedTestSummary(scan);
   // NOTE: do not add `\bFAIL\s` here — with /i flag it would re-match the
   // very `0 fail\n` token green-summary is trying to exempt. A real test
   // failure produces "N fail" (N≥1) which never triggers hasGreenTestSummary,

package/hook-optimize.mjs

@@ -484,8 +484,8 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
       // clampImportance floor it to 1 (kept visible, low-ranked) instead of hiding.
       // A compression keeper is never hidden: hiding it hides every member compressed into it
       // (the same rule NOT_COMPRESSION_KEEPER_SQL enforces on the maintenance writers). It falls
-      // through to the normal update instead: floored to importance 1 and stamped, so it is not
-      // re-sent. That update keeps its stored title and narrative in both scopes (keepStoredText).
+      // through instead: in narrow scope to the stamp-only write below (floored to importance 1
+      // and stamped, so it is not re-sent), in wide scope to the normal update.
       const isKeeper = !!db
         .prepare('SELECT 1 FROM observations WHERE compressed_into = ? LIMIT 1')
         .get(cand.id);
@@ -518,6 +518,31 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
         processed++;
         continue;
       }
+      // A narrow 0 reply reaches this point only for a row that may not be hidden (a compression
+      // keeper, or an importance a person set). It judged the row worthless, so it is no basis for
+      // any of the row's text either: the stored title and narrative stay (D#207: 'Weekly summary:
+      // auth refactor' became 'Weekly summary', narrative 'x'), and so do type, lesson, concepts,
+      // facts, aliases and scope (D#268). Written instead: what hiding would have written bar the
+      // hide, i.e. the stamp, so the row is not re-sent, plus the importance floor below. Wide
+      // scope stays on the normal path: its rows are substantive by construction, so a 0 there
+      // reads as a misjudgment of importance, not of the row.
+      if (scoredZero && scope !== 'wide') {
+        const res = db
+          .prepare(
+            `UPDATE observations SET
+               importance = CASE WHEN importance_set_at IS NOT NULL THEN importance
+                                 ELSE MAX(?, COALESCE(NULLIF(importance, 0), 1)) END,
+               optimized_at = ?
+             WHERE id = ? AND ${liveObsFilterSql('')} AND optimized_at IS NULL`,
+          )
+          .run(clampImportance(parsed.importance), Date.now(), cand.id);
+        if (res.changes === 0) {
+          skipped++;
+          continue;
+        }
+        processed++;
+        continue;
+      }
 
       // Enrichment ("add a lesson") must not reclassify a specific type down to the generic
       // 'change' (lower TYPE_QUALITY + faster decay); keep the stored type on that downgrade.
@@ -558,13 +583,8 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
       // For `narrow`, the truncate stays on LLM output but NOT on the preserve-on-empty
       // fallback — truncating the row's own stored narrative to buy nothing was the same
       // bug in miniature.
-      //
-      // A reply that scored the row 0 reaches this point only for a row that may not be hidden
-      // (a compression keeper, or an importance a person set). It judged the row worthless, so
-      // its title and narrative do not replace the stored ones either (D#207: 'Weekly summary:
-      // auth refactor' became 'Weekly summary', narrative 'x').
       const isWide = scope === 'wide';
-      const keepStoredText = isWide || scoredZero;
+      const keepStoredText = isWide;
       const title = keepStoredText ? cand.title : truncate(scrubSecrets(parsed.title || ''), 120);
       const narrative = keepStoredText
         ? cand.narrative
@@ -611,8 +631,8 @@ scope: ${SCOPE_PROMPT_LEGEND}`;
       // Narrow replaces title and narrative with model text, so an explicit save it rewrites (one
       // whose save-time enrich failed) moves to the re-enrich writer's id, as a cluster-merge
       // keeper does (D#146, D#138). Wide keeps the stored title and narrative (it fills the lesson
-      // and the side fields), so the row stays an explicit save, and so does a row whose stored
-      // text a 0 reply left in place. The writer's session row is best-effort.
+      // and the side fields), so the row stays an explicit save; a narrow 0 reply never gets here.
+      // The writer's session row is best-effort.
       let rewriteSessionId = null;
       if (!keepStoredText) {
         const cur = db.prepare('SELECT memory_session_id FROM observations WHERE id = ?').get(cand.id);

package/hook-shared.mjs

@@ -281,7 +281,8 @@ export const GC_PRESERVED_MARKER_PREFIXES = Object.freeze([
   // out. Both are version-keyed one-shot migration sentinels written by
   // scripts/setup.sh, and their gate is `! -f <marker>` — deleting one re-runs
   // its migration. `.mcp-dedup-v2.78` gates a block that removes
-  // mcpServers.mem / mcpServers["mem-lite"] from the user's ~/.claude.json with
+  // mcpServers.mem / mcpServers["mem-lite"] from the config home's .claude.json (one marker per
+  // .claude.json since D#270, the same prefix) with
   // a raw writeFileSync (no tmp+rename, no backup), which the repo's own test
   // documents as intentionally one-shot: "If a user later runs `claude mcp add
   // mem ...` themselves, the gate intentionally lets it stand." A 30-day sweep

package/hook-update.mjs

@@ -318,13 +318,28 @@ function shouldCheck(state) {
 // ── GitHub API ─────────────────────────────────────────────
 // Try releases/latest first, fallback to tags (some repos only use tags)
 export async function fetchLatestRelease() {
-  return (await lookupLatestRelease()).release;
+  const { release } = await lookupLatestRelease();
+  if (release) clearRecordedLookupFailure();
+  return release;
+}
+
+// repair looks up through fetchLatestRelease, so a lookup that succeeds there is evidence against
+// the failure doctor reports; without this the warning outlived the repair by a full check interval
+// (D#266). Only the two fields that decide whether doctor warns. lastCheck, latestVersion and
+// rateLimited belong to checkForUpdate (the background check and self-update): rateLimited picks
+// its interval (6 h, else 24 h), so clearing it here pushed the next check back by up to 18 h
+// (post-release review). No write when there is nothing to clear.
+function clearRecordedLookupFailure() {
+  const state = readState();
+  if (!state.lookupError && !state.lookupFailingSince) return;
+  saveState({ ...state, lookupError: null, lookupFailingSince: null });
 }
 
 // One lookup's outcome, returned rather than kept in module state: a module flag let a second
 // lookup running at the same time read the first one's 403 (D#260). `rateLimited` is THIS
-// lookup's refusal; the persisted flag is not that, since only a successful lookup clears it
-// (pre-tag review of cd9f1ab7). `error` says why there is no release, for doctor (D#255).
+// lookup's refusal; the persisted flag is not that, since only a successful checkForUpdate (the
+// background check or self-update) clears it (pre-tag review of cd9f1ab7). `error` says why there
+// is no release, for doctor (D#255).
 async function lookupLatestRelease() {
   const headers = {
     Accept: 'application/vnd.github+json',
@@ -813,11 +828,15 @@ export async function verifyReleaseAuthenticity(extractedDir, assets, publicKey
 // updater that was killed mid-swap (it applies the same staleness bound).
 const SWAP_MARKER = join(STATE_DIR, 'runtime', 'swap-in-progress'); // runtime-dir:stays-put — installation identity
 // Intent journal, written INSIDE the backup dir before each rename. On a hard kill
-// the backup dir survives (every normal exit deletes it) and this file says exactly
+// the backup dir survives (a normal exit deletes it, unless its journal cannot be
+// removed, D#283) and this file says exactly
 // which paths were in flight, so the next entry can finish the rollback at the right
 // granularity — a bare directory walk cannot tell a nested relPath from a directory
 // relPath like `node_modules`.
-const SWAP_JOURNAL = '.swap-journal.json';
+const SWAP_JOURNAL = '.swap-journal.json'; // doctor and cleanup spell it SWAP_JOURNAL_NAME (lib/doctor-stale-temp.mjs)
+// Written into the backup dir when its swap is over (committed, or rolled back): never replay it
+// (D#292 C). Doctor and cleanup spell it SWAP_RESOLVED_NAME.
+const SWAP_RESOLVED = '.swap-resolved';
 
 function markSwapStart() {
   try {
@@ -841,19 +860,131 @@ function clearSwapMarker() {
 // backup dir but nothing records it — recovery would then delete the backup dir with
 // the only copy of that file inside it. rollbackInstall guards every entry with
 // existsSync/force, so an intent that never happened is a harmless no-op.
+//
+// By temp file and rename, and it throws (D#289). writeFileSync truncates the journal before it
+// writes it, so a kill or ENOSPC in between left an empty journal, which recovery read as "nothing
+// moved" and then deleted the backups. A write error was swallowed, so the rename it was meant to
+// record went ahead unrecorded. Now the previous journal stays whole until the new one replaces
+// it, and a swap that cannot journal stops before the rename, through the rollback in the caller.
+//
+// Retried for a moment on EPERM/EBUSY/EACCES: the rename replaces a file just written, about twice
+// per switched path, and on Windows a scanner holding that file makes a rename over it fail
+// briefly. Each failure stopped the update and rolled it back, and a rollback is where a restore
+// can fail (D#292 A). Bounded at about 0.7 s, then it throws as before.
+const JOURNAL_RETRY_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
 function journalSwap(backupDir, backedUp, installed) {
+  const data = JSON.stringify({ backedUp, installed });
+  for (let attempt = 1; ; attempt++) {
+    try {
+      atomicWriteFileSync(join(backupDir, SWAP_JOURNAL), data);
+      return;
+    } catch (e) {
+      if (attempt >= 8 || !JOURNAL_RETRY_CODES.has(e.code)) throw e;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25 * attempt);
+    }
+  }
+}
+
+// Clean up after a swap that is over: committed, or rolled back. Never throws, because a cleanup
+// that throws reaches the caller's catch, which rolls the swap back again (D#283; EBUSY is
+// ordinary on Windows and `force` does not suppress it).
+//
+// The dir is marked resolved first (D#292 C). A journal left behind (it could not be removed, or a
+// kill came first) was replayed by the next recovery: over a committed swap that put the previous
+// release back, and over a rolled-back one whose journal outlived a later swap it deleted a path
+// that swap had installed. Recovery, install, cleanup and doctor leave a resolved dir's journal
+// alone. The marker is a new empty file, so it needs no access to the journal a failed removal
+// could not get. With the marker written, a journal that stays is inert and the backups go anyway,
+// child by child around the journal and the marker: a recursive removal of the dir takes children
+// in directory order and stops at the first failure, so it could take the marker and then stop at
+// the journal (v6.25.1 delta review). If the marker cannot be written either, the journal still
+// goes before the backups, and if it stays, so do the backups, complete, so that a replay restores
+// one whole release.
+function discardBackupDir(backupDir) {
+  let resolved = false;
+  try {
+    writeFileSync(join(backupDir, SWAP_RESOLVED), '');
+    resolved = true;
+  } catch (e) {
+    debugCatch(e, 'mark-swap-resolved');
+  }
+  try {
+    rmSync(join(backupDir, SWAP_JOURNAL), { force: true });
+  } catch (e) {
+    debugCatch(e, 'discard-swap-journal');
+    if (resolved) removeBackupsBeside(backupDir);
+    return;
+  }
+  try {
+    rmSync(backupDir, { recursive: true, force: true });
+  } catch (e) {
+    debugCatch(e, 'discard-backup-dir');
+  }
+}
+
+function removeBackupsBeside(backupDir) {
+  let names = [];
+  try {
+    names = readdirSync(backupDir);
+  } catch (e) {
+    debugCatch(e, 'discard-backups-list');
+  }
+  for (const name of names) {
+    if (name === SWAP_JOURNAL || name === SWAP_RESOLVED) continue;
+    try {
+      rmSync(join(backupDir, name), { recursive: true, force: true });
+    } catch (e) {
+      debugCatch(e, 'discard-backup');
+    }
+  }
+}
+
+// Mark resolved the backup dirs a swap found left over and unfinished (recovery leaves one whose
+// journal it cannot read right now). Called once that swap has committed: it replaced every path
+// it switches, so a later replay of an older journal, once it can be read, would only mix the
+// releases back (v6.25.1 delta review). The same retirement install does after writing the tree.
+function retireUnresolvedBackups(targetDir, names) {
+  for (const name of names) {
+    try {
+      writeFileSync(join(targetDir, name, SWAP_RESOLVED), '');
+      debugLog('WARN', 'hook-update', `Retired ${name}: the committed swap replaced what its journal names`);
+    } catch (e) {
+      debugCatch(e, 'retire-unresolved-backup');
+    }
+  }
+}
+
+// The `.update-backup-*` dirs in targetDir that carry no resolved marker.
+function unresolvedBackups(targetDir) {
   try {
-    writeFileSync(join(backupDir, SWAP_JOURNAL), JSON.stringify({ backedUp, installed }));
+    return readdirSync(targetDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('.update-backup-'))
+      .map((e) => e.name)
+      .filter((name) => !existsSync(join(targetDir, name, SWAP_RESOLVED)));
   } catch (e) {
-    debugCatch(e, 'journalSwap');
+    debugCatch(e, 'list-unresolved-backups');
+    return [];
+  }
+}
+
+// The backup dir is resolved before staging goes: removing a whole staging tree takes long enough
+// for a kill to land in, and a kill there left a committed swap's journal to be replayed.
+function discardSwapDirs(stagingDir, backupDir) {
+  discardBackupDir(backupDir);
+  try {
+    rmSync(stagingDir, { recursive: true, force: true });
+  } catch (e) {
+    debugCatch(e, 'discard-staging-dir');
   }
 }
 
 /**
  * Finish any swap a previous process was killed in the middle of, then clear its
  * residue. Called on every install entry, under the install lock, BEFORE a new
- * staging/backup pair is created.
- * @returns {number} number of interrupted swaps rolled back
+ * staging/backup pair is created; and by install.mjs, under the same lock, before
+ * `install` (and so `repair`) writes the tree and from `cleanup` (D#289).
+ * @returns {number} number of backup dirs processed, with a journal or without; one left in place
+ *   because its journal cannot be read is not counted
  */
 export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
   let entries;
@@ -880,21 +1011,43 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
     }
     if (!entry.name.startsWith('.update-backup-')) continue;
 
-    let journal;
-    try {
-      journal = JSON.parse(readFileSync(join(dir, SWAP_JOURNAL), 'utf8'));
-    } catch {
-      journal = null;
+    // Its swap is over and only its cleanup failed: remove what is left, never replay it (D#292 C).
+    if (existsSync(join(dir, SWAP_RESOLVED))) {
+      discardBackupDir(dir);
+      recovered++;
+      continue;
     }
-    const backedUp = Array.isArray(journal?.backedUp) ? journal.backedUp : [];
-    const installed = Array.isArray(journal?.installed) ? journal.installed : [];
-    // Copies: rollbackInstall reverses the arrays in place.
-    rollbackInstall([...installed], [...backedUp], dir, targetDir);
+
+    // No journal: the swap is over and its journal is gone (or it was killed before its first
+    // rename), so there is nothing to replay and the dir is residue. A journal that is there but
+    // cannot be read, or not as one (an in-place write of 6.25.0 or older torn by a kill), says
+    // nothing about what moved, and the dir may hold the only copy of it: leave it. It used to be
+    // read as "nothing moved" and deleted (v6.25.1 review). doctor and cleanup name it; the next
+    // swap that commits, or an install, retires it.
+    let journal = { backedUp: [], installed: [] };
+    let raw = null;
     try {
-      rmSync(dir, { recursive: true, force: true });
+      raw = readFileSync(join(dir, SWAP_JOURNAL), 'utf8');
     } catch (e) {
-      debugCatch(e, 'recover-backup');
+      if (e.code !== 'ENOENT') {
+        debugCatch(e, 'recover-read-journal');
+        continue;
+      }
     }
+    if (raw !== null) {
+      try {
+        journal = JSON.parse(raw);
+      } catch {
+        journal = null;
+      }
+      if (!Array.isArray(journal?.backedUp) || !Array.isArray(journal?.installed)) {
+        debugLog('WARN', 'hook-update', `Left ${entry.name} in place: its swap journal cannot be read`);
+        continue;
+      }
+    }
+    const { backedUp, installed } = journal;
+    rollbackInstall(installed, backedUp, dir, targetDir);
+    discardBackupDir(dir);
     recovered++;
     debugLog(
       'WARN',
@@ -905,25 +1058,43 @@ export function recoverInterruptedSwaps(targetDir = INSTALL_DIR) {
   return recovered;
 }
 
+// A rollback swaps a file SET back just as the install swapped it in, so it holds the same
+// marker for the same reason (D#239 g). After the MED-5 smoke gate the loop has already cleared
+// it; after a throw inside the loop it is still set, and this call takes it over.
+//
+// Safe to run twice over one journal (D#283). A backed-up path whose backup is gone holds the OLD
+// file already, restored by an earlier rollback or never moved out, so it is not deleted: a
+// second rollback used to delete every installed path, by then the only copy of the old install.
+// That holds for a journal this code wrote: its cleanup removes the journal before any backup, and
+// when the journal cannot be removed, the resolved marker keeps it from being replayed. A backup
+// dir 6.25.0 or older left half deleted beside its journal can still replay to a mix.
+// The arrays are copied, not reversed in place, so a caller's journal is left as it was.
 function rollbackInstall(installed, backedUp, backupDir, targetDir) {
-  for (const relPath of installed.reverse()) {
-    try {
-      rmSync(join(targetDir, relPath), { recursive: true, force: true });
-    } catch {
-      /* best-effort */
+  markSwapStart();
+  try {
+    const restored = new Set(backedUp.filter((relPath) => !existsSync(join(backupDir, relPath))));
+    for (const relPath of [...installed].reverse()) {
+      if (restored.has(relPath)) continue;
+      try {
+        rmSync(join(targetDir, relPath), { recursive: true, force: true });
+      } catch {
+        /* best-effort */
+      }
     }
-  }
-  for (const relPath of backedUp.reverse()) {
-    const backupPath = join(backupDir, relPath);
-    const targetPath = join(targetDir, relPath);
-    try {
-      if (existsSync(backupPath)) {
-        mkdirSync(dirname(targetPath), { recursive: true });
-        renameSync(backupPath, targetPath);
+    for (const relPath of [...backedUp].reverse()) {
+      const backupPath = join(backupDir, relPath);
+      const targetPath = join(targetDir, relPath);
+      try {
+        if (existsSync(backupPath)) {
+          mkdirSync(dirname(targetPath), { recursive: true });
+          renameSync(backupPath, targetPath);
+        }
+      } catch (restoreErr) {
+        debugCatch(restoreErr, `installExtractedRelease-restore-${relPath}`);
       }
-    } catch (restoreErr) {
-      debugCatch(restoreErr, `installExtractedRelease-restore-${relPath}`);
     }
+  } finally {
+    clearSwapMarker();
   }
 }
 
@@ -1026,6 +1197,7 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
   const backupDir = join(targetDir, `.update-backup-${ts}`);
   const backedUp = [];
   const installed = [];
+  let committed = false;
 
   const manifest = await loadReleaseManifest(sourceDir);
   const switchablePaths = buildSwitchablePaths(manifest.SOURCE_FILES);
@@ -1035,6 +1207,9 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     // one — otherwise this install stacks on top of a mixed-version tree and its
     // own backup can no longer restore a coherent state.
     recoverInterruptedSwaps(targetDir);
+    // What recovery left unfinished (a journal it cannot read right now) is retired if this swap
+    // commits, and left for the next entry if it rolls back.
+    const leftUnresolved = unresolvedBackups(targetDir);
 
     mkdirSync(stagingDir, { recursive: true });
     mkdirSync(backupDir, { recursive: true });
@@ -1049,6 +1224,9 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     }
 
     markSwapStart();
+    // Cleared here only when the loop finished. If a rename throws, the half-swapped tree keeps
+    // the marker through the catch below until rollbackInstall has put the old files back.
+    let swapped = false;
     try {
       for (const relPath of switchablePaths) {
         const stagedPath = join(stagingDir, relPath);
@@ -1070,8 +1248,9 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
         journalSwap(backupDir, backedUp, installed);
         renameSync(stagedPath, targetPath);
       }
+      swapped = true;
     } finally {
-      clearSwapMarker();
+      if (swapped) clearSwapMarker();
     }
 
     // MED-5: before discarding the rollback backup, prove the switched code boots.
@@ -1079,13 +1258,14 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     // keeps working rather than leaving a broken install with no way back.
     if (!opts.skipSmoke && !smokeInstalledRelease(targetDir)) {
       rollbackInstall(installed, backedUp, backupDir, targetDir);
-      rmSync(stagingDir, { recursive: true, force: true });
-      rmSync(backupDir, { recursive: true, force: true });
+      discardSwapDirs(stagingDir, backupDir);
       return false;
     }
 
-    rmSync(stagingDir, { recursive: true, force: true });
-    rmSync(backupDir, { recursive: true, force: true });
+    // Committed: from here on the catch below must not roll back (D#283).
+    committed = true;
+    retireUnresolvedBackups(targetDir, leftUnresolved);
+    discardSwapDirs(stagingDir, backupDir);
 
     // Post-update migration: reconcile settings.json against the release we just
     // swapped in. `configureHooks()` already strips stale mem entries — but its only
@@ -1171,17 +1351,11 @@ export async function installExtractedRelease(sourceDir, targetDir = INSTALL_DIR
     return true;
   } catch (err) {
     debugCatch(err, 'installExtractedRelease');
+    // Past the commit point the backups are gone and the new release IS the install: a rollback
+    // would delete the paths it added and restore nothing (D#283).
+    if (committed) return true;
     rollbackInstall(installed, backedUp, backupDir, targetDir);
-    try {
-      rmSync(stagingDir, { recursive: true, force: true });
-    } catch {
-      /* best-effort */
-    }
-    try {
-      rmSync(backupDir, { recursive: true, force: true });
-    } catch {
-      /* best-effort */
-    }
+    discardSwapDirs(stagingDir, backupDir);
     return false;
   } finally {
     release();