dsh-instruction-memory 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -7,6 +7,82 @@
 > 1.0.13 起由 CI 经 OIDC Trusted Publishing 发布（首个带 provenance 的版本）。
 > 这些历史 tag **不应回填**——npm 上的版本号已被占用。
 
+## [1.5.3] — 2026-11-09
+
+1.5.2 的发布后修正，两处都是当天发现：一处**判断依据用错**，一处**依赖了初始化顺序**。没有新功能，
+存储格式、注入文本与面板行为不变。
+
+### 修复
+
+- **背压判断把健康但读得慢的订阅者当成死连接（1.5.2 引入）**：1.5.2 让 `send()` 返回 `res.write()`
+  的结果，并在返回 `false` 时立刻 `cleanup()`。但 `write()` 的 `false` 只表示**这一次写入超过了
+  socket 缓冲的高水位**——一个健康、但此刻读得慢的客户端同样会拿到 `false`。于是一个大帧（极限存储
+  约 3.4 MB）就可能把正常订阅者踢下线。现在返回值不再用作存活判据：心跳只负责让"写失败"这条路走通
+  ——对端真的消失时，写入会报错并触发该流早已注册的 `close`/`error` 清理；`pushSnapshot` 恢复
+  1.5.1 的语义。
+- **`diskRevFrom()` 的声明顺序依赖**：1.5.2 把它定义在 `writeToDisk()` 之后。`apply()` 是同步函数，
+  通常情况下没有问题；但"缺主文件时从 `.bak` 恢复"这条路径会在 boot 序列里调用 `writeToDisk()`，
+  那是一次**可能先于声明执行**的调用，而 `const` 会落在暂时性死区并抛 `ReferenceError`（保存因此
+  失败、`storageError` 报"保存失败"）。现在两个 helper 提到 `writeToDisk()` 之前，用顺序消除这个
+  假设，而不是依赖"今天恰好先 await"。
+
+### 验收
+
+- 全套 7 个套件与 `node check-metadata.mjs` 全绿；`contract-test.mjs` 连续独立运行 5 次均 ALL PASS。
+- 1.5.2 的 CI 在 `windows-latest / Node 24` 上失败了 2 条 SSE 断言：
+  `sse: a writer that throws on broadcast is fully disposed (response ended)` 与
+  `sse: disposing the dead writer does not interrupt a healthy stream`。本版按上面的修正重新验证这两个
+  断言所在的路径（死连接清理 + 健康流不受牵连）。
+
+## [1.5.2] — 2026-11-09
+
+针对 2026-11-09 的代码审查（Host 侧与 Client 侧并行只读审查，逐条复核后落地）。本版**没有新增功能、
+没有格式变更**：存储文件、注入文本与面板行为在正常路径上与 1.5.1 逐字节一致，改的是一条静默失效的
+降级路径、一条失效的乱序保护，以及几处可以量化的重复 I/O 与空转渲染。
+
+### 修复
+
+- **watcher 降级把轮询器一起杀掉了（P0）**：`storeWatcher.on('error')` 的日志写的是「falling back to
+  the 5s poller」，紧接着却调用 `stopWatching()` —— 而该函数同时 `clearInterval(storePoll)`。于是
+  `fs.watch` 一旦报错（被监视目录被删或 rename、Windows 目录句柄失效、inotify 句柄耗尽），**watcher
+  与轮询器双双消失**，外部改动检测彻底静默，直到本进程下一次保存成功才重新装回。期间手改
+  `memory.json`、或另一个 DSH 进程保存，本窗口会一直显示旧数据，而面板没有任何提示。现在错误分支
+  只关闭 watcher 并显式 `startPolling()`（幂等），注释所承诺的降级才真的发生。
+- **SSE 乱序快照保护在推送路径上失效（P1）**：`absorb()` 用渲染作用域的 `view` 判定「到来的快照是否
+  比已在屏上的更旧」，但 SSE effect 的依赖是空数组，它捕获的是**首渲染**那份 `absorb`，其闭包里的
+  `view` 恒为 `null`，`currentRev` 永远是 `undefined` —— 于是注释点名的「SSE 触发刷新与 POST 回包
+  竞争」恰恰是唯一没被保护的那条路径。现在改读 `viewRef.current`（面板一直在维护它）。
+
+### 性能与加固（不改变外部行为）
+
+- **一次保存不再整读同一个文件三次（P1）**：`writeToDisk()` 在跨进程锁内依次 `readDiskRev()`、
+  再一次 `readDiskRev()`、再 `readStoreFile()`，只为拿磁盘 rev（两次结果必然相同，锁在自己手上）
+  与 `.bak` 的形状判定。现在一次读取同时供两处使用，`diskReadError` 保留原有 `ENOENT` / 空文件 /
+  非本插件存储三条分支的语义。极限存储（200 条 × 6000 字 ≈ 3.4 MB）下每次保存少约 10 MB 读取与
+  2 次整文件 `JSON.parse`，并缩短了锁的持有时间。
+- **事件流加上心跳与背压（P2）**：原来的 `send` 丢弃 `res.write()` 的返回值，清理只依赖
+  `close`/`error` 事件。客户端崩溃或休眠（没有 FIN）时条目不会被移除，积满 `MAX_SSE_STREAMS=32`
+  后所有新订阅者都被 503 拒绝，面板实时同步失效直到重启宿主；慢客户端还会让极限 3.4 MB 的全量帧
+  在 socket 缓冲里无界堆积。现在 25 秒共享心跳（`: ping` 注释帧，SSE 客户端按规范忽略）逐个探测，
+  `write()` 返回 `false` 即清理该流；`pushSnapshot` 同样按返回值清理。
+- **暂停倒计时不再空转重渲染整个面板（P2）**：`nowTick` 每秒写一次 state，但全文没有任何地方读取它
+  （剩余时间在渲染时用 `Date.now()` 现算）——每秒重跑并 diff 约 3000 个 vnode，只为让一行文字变化。
+  现在倒计时抽成 `MuteCountdown` 子组件，自带 1s tick，且只在归零时回调一次（SSE 已断、宿主不再推
+  快照时，暂停条也能自行退场）。
+- **列表派生计算记忆化（P2）**：排序、标签索引、筛选、关键词扫描与「按需预演」打分原先全部裸写在
+  渲染体里，每次按键或勾选一条都要重排 200 条并对全部正文重复小写化。现在收进 `deriveListState()`
+  并由 `useStableMemo()` 按（快照, UI 状态）缓存；预演只在展开时才打分（收起后不再扫全库）。
+  `useStableMemo` 建在 `useRef` 上而不是 `useMemo` 上，因为 ui-test 里那套迷你 React 只实现了
+  `useState`/`useEffect`/`useRef` —— 这样测试与生产走同一条代码路径，而不是为了测试加分支。
+
+### 验收
+
+- 全套 7 个套件（lint / host-range / smoke / contract / verify / feedback / ui）与
+  `node check-metadata.mjs` 全绿；`lib/` 13 个文件全部 PARSE 且无宿主包名导入。
+- **未做的验证（明确记录）**：watcher 故障注入没有做成真机测试——`storeWatcher` 是闭包内变量，
+  无法从外部触发 `error`，Windows 上删除被监视目录只会产生 `rename` 事件。第一条的保证来自
+  「`stopWatching()` 现在只剩插件卸载一处调用点」这一结构性证明，不是行为测试。
+
 ## [1.5.1] — 2026-11-05
 
 针对 2026-11-05 桌面端 / 网页端复核（架构 / 安全 / 验收三方）的 P1–P3 逐项修复。运行时在

package/lib/client.js

@@ -1178,8 +1178,8 @@ window.__ModuleLoader__.load({
       if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)) return null
       const data = snapshot.data
       if (data === undefined || data === null || typeof data !== 'object' || Array.isArray(data)) return null
-      // Every consumer reads data.entries and sortEntries() calls .slice() on
-      // it; a non-array threw mid-render instead of surfacing a readable error.
+      // Every consumer reads data.entries and deriveListState() slices it; a
+      // non-array threw mid-render instead of surfacing a readable error.
       if (!Array.isArray(data.entries)) return null
       return {
         snapshot,
@@ -1469,6 +1469,127 @@ window.__ModuleLoader__.load({
       return { terms, results, autoTotal }
     }
 
+    /**
+     * A useMemo equivalent built on useRef.
+     *
+     * This module runs against two React instances: the real one inside the DSH
+     * web shell, and the minimal stand-in ui-test.mjs drives the panel with,
+     * which implements useState / useEffect / useRef only. useMemo is absent
+     * there, so the memo is written against useRef — which both provide — with
+     * the same reference-comparison semantics, rather than a test-only branch
+     * that would leave the shipped path unexercised.
+     *
+     * @param {Array} deps
+     * @param {() => any} compute
+     * @returns {any} the cached value
+     */
+    function useStableMemo(deps, compute) {
+      const box = React.useRef(null)
+      const previous = box.current
+      let fresh = previous === null || previous.deps.length !== deps.length
+      if (!fresh) {
+        for (let i = 0; i < deps.length; i += 1) {
+          if (previous.deps[i] !== deps[i]) {
+            fresh = true
+            break
+          }
+        }
+      }
+      if (fresh) box.current = { deps, value: compute() }
+      return box.current.value
+    }
+
+    /**
+     * Sort, filter and index the entry list ONCE per (snapshot, UI state).
+     *
+     * All of this used to run inline in the panel's render body, so a keystroke
+     * in the search box or a single checkbox toggle re-sorted up to 200 entries
+     * and re-lowered every title/body/scenario to scan for the keyword. None of
+     * it is expensive on its own; the cost was paying it on every unrelated
+     * render. The lower-cased haystack is built per entry, not per keystroke,
+     * and the on-demand preview only scores while its panel is open.
+     *
+     * @param {{entries: Array, sortKey: string, tagFilter: string, modeFilter: string,
+     *   statusFilter: string, query: string, simQuery: string, simOpen: boolean}} input
+     * @returns {{entries: Array, allTags: string[], visible: Array,
+     *   autoEntries: Array, sim: {terms: string[], results: Array, autoTotal: number}}}
+     */
+    function deriveListState(input) {
+      const source = Array.isArray(input.entries) ? input.entries : []
+      const copy = source.slice()
+      if (input.sortKey === 'updated') {
+        copy.sort((a, b) => (b.updatedAt - a.updatedAt) || (b.priority - a.priority))
+      } else if (input.sortKey === 'title') {
+        copy.sort((a, b) =>
+          a.title.localeCompare(b.title, undefined, { sensitivity: 'base' })
+          || (b.priority - a.priority)
+          || (b.updatedAt - a.updatedAt))
+      } else {
+        copy.sort((a, b) => (b.priority - a.priority) || (b.updatedAt - a.updatedAt))
+      }
+      const tagCounts = new Map()
+      const haystack = new Map()
+      for (const entry of source) {
+        const tags = Array.isArray(entry.tags) ? entry.tags : []
+        for (const tag of tags) {
+          if (typeof tag === 'string' && tag !== '') tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1)
+        }
+        haystack.set(entry, [
+          typeof entry.title === 'string' ? entry.title : '',
+          typeof entry.content === 'string' ? entry.content : '',
+          typeof entry.when === 'string' ? entry.when : '',
+          tags.join(' '),
+        ].join(' ').toLowerCase())
+      }
+      const allTags = [...tagCounts.entries()]
+        .sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0], undefined, { sensitivity: 'base' }))
+        .map(([tag]) => tag)
+      // Same predicate order as the inline version: filters first, then the
+      // keyword, so a filtered-out entry never pays for the search.
+      const keyword = typeof input.query === 'string' ? input.query.trim().toLowerCase() : ''
+      const visible = copy.filter((entry) => {
+        if (input.tagFilter !== '' && !(Array.isArray(entry.tags) && entry.tags.includes(input.tagFilter))) return false
+        if (input.modeFilter !== '' && entry.mode !== input.modeFilter) return false
+        if (input.statusFilter === 'enabled' && entry.enabled !== true) return false
+        if (input.statusFilter === 'disabled' && entry.enabled !== false) return false
+        if (keyword === '') return true
+        return (haystack.get(entry) || '').indexOf(keyword) !== -1
+      })
+      // The card visibility check needs the count even while collapsed, so the
+      // candidate list is always built; only scoring is skipped.
+      const autoEntries = source.filter((entry) => entry.mode === 'auto' && entry.enabled !== false)
+      const sim = input.simOpen === true
+        ? relevancePreview(autoEntries, input.simQuery)
+        : { terms: [], results: [], autoTotal: 0 }
+      return { entries: copy, allTags, visible, autoEntries, sim }
+    }
+
+    /**
+     * F7's remaining-time line, with its own 1s clock.
+     *
+     * The tick used to live in the panel's state: it re-rendered (and diffed)
+     * the whole settings tree every second for a value nothing ever read, since
+     * the text is derived from Date.now() at render time. Scoping it here
+     * re-renders one span instead. It also reports expiry, so the pause bar
+     * steps aside even when the SSE stream is already dead and no fresh
+     * snapshot is coming to flip the flag.
+     */
+    function MuteCountdown(props) {
+      const [, force] = React.useState(0)
+      const remaining = Math.max(0, props.until - Date.now())
+      const live = remaining > 0
+      React.useEffect(() => {
+        if (!live) return undefined
+        const tick = setInterval(() => force((n) => n + 1), 1000)
+        return () => clearInterval(tick)
+      }, [live])
+      React.useEffect(() => {
+        if (live) return
+        if (typeof props.onExpired === 'function') props.onExpired()
+      }, [live])
+      return h('span', null, props.format(remaining))
+    }
+
     /* ---------------- F16: source-mode validation ---------------- */
 
     /**
@@ -1888,12 +2009,13 @@ window.__ModuleLoader__.load({
       const [feedbackBusy, setFeedbackBusy] = React.useState(false)
       const [feedbackError, setFeedbackError] = React.useState('')
       const [feedbackSent, setFeedbackSent] = React.useState('')
-      // F7: the pause menu (null-state boolean) and a 1s clock tick that exists
-      // ONLY while a pause is live (its effect cleans up after itself). The
-      // tick drives nothing but the remaining-time text; authority stays with
-      // the host snapshot (injection.muted / data.disabledUntil).
+      // F7: the pause menu (null-state boolean). The countdown that used to
+      // live here as a panel-wide 1s tick now lives in MuteCountdown, so a live
+      // pause re-renders one line instead of the whole settings tree.
       const [pauseMenuOpen, setPauseMenuOpen] = React.useState(false)
-      const [nowTick, setNowTick] = React.useState(Date.now())
+      // Bumped once when the countdown reaches zero: the panel then re-renders
+      // and the pause bar yields to the normal control even without a snapshot.
+      const [, setMuteExpired] = React.useState(0)
       // F18: the backup-location draft (focused-input protection like budget).
       const [backupText, setBackupText] = React.useState('')
       const backupTextRef = React.useRef('')
@@ -1947,14 +2069,33 @@ window.__ModuleLoader__.load({
       const mutedNow = view !== null && view.injection !== null && typeof view.injection === 'object'
         && view.injection.muted === true
       React.useEffect(() => {
-        if (!mutedNow) return undefined
+        if (!mutedNow) return
         // A pause started from ANOTHER window replaces the menu row; the open
         // flag must not resurface when the row returns after expiry.
         setPauseMenuOpen(false)
-        const tick = setInterval(() => setNowTick(Date.now()), 1000)
-        return () => clearInterval(tick)
       }, [mutedNow])
 
+      /**
+       * The whole list derivation (sort, tag index, filter, keyword scan,
+       * on-demand preview), memoised on the snapshot and the UI inputs that
+       * feed it. It sits before the early returns because hooks cannot be
+       * called conditionally — a null view simply derives empty lists.
+       */
+      const derivedList = useStableMemo([view, sortKey, tagFilter, modeFilter, statusFilter, query, simQuery, simOpen],
+        () => deriveListState({
+          entries: view !== null && view.data !== null && typeof view.data === 'object'
+            && Array.isArray(view.data.entries)
+            ? view.data.entries
+            : [],
+          sortKey,
+          tagFilter,
+          modeFilter,
+          statusFilter,
+          query,
+          simQuery,
+          simOpen,
+        }))
+
       /**
        * F16 live validation, debounced: parsing on every keystroke would stall
        * the panel on a multi-megabyte paste, and 250 ms is below the threshold
@@ -1988,7 +2129,13 @@ window.__ModuleLoader__.load({
         && typeof snapshot.data.rev === 'number'
         ? snapshot.data.rev
         : undefined)
-      const revOf = () => revOfFrom(view)
+      // The LIVE snapshot, through the ref — not the render-scoped `view`.
+      // absorb() is also called from the SSE effect, which is registered once
+      // (deps []), so its closure holds the FIRST render's absorb and with it
+      // the first render's `view` (null). Reading `view` here made the
+      // out-of-order guard below accept every pushed snapshot, which is exactly
+      // the SSE-vs-POST race its comment promises to drop.
+      const revOf = () => revOfFrom(viewRef.current)
 
       function absorb(result) {
         const normalized = normalizeResult(result)
@@ -2733,23 +2880,9 @@ window.__ModuleLoader__.load({
         ? view.security
         : { hostGuarded: true, boundHost: '' }
       // List order is display-only and never changes what the Host injects
-      // (the injection order is decided host-side). The default mirrors the
-      // previous fixed order; updated-time and title are the other sorts.
-      const sortEntries = (list) => {
-        const copy = list.slice()
-        if (sortKey === 'updated') {
-          copy.sort((a, b) => (b.updatedAt - a.updatedAt) || (b.priority - a.priority))
-        } else if (sortKey === 'title') {
-          copy.sort((a, b) =>
-            a.title.localeCompare(b.title, undefined, { sensitivity: 'base' })
-            || (b.priority - a.priority)
-            || (b.updatedAt - a.updatedAt))
-        } else {
-          copy.sort((a, b) => (b.priority - a.priority) || (b.updatedAt - a.updatedAt))
-        }
-        return copy
-      }
-      const entries = sortEntries(data.entries)
+      // (the injection order is decided host-side). Sorting, filtering and the
+      // keyword scan all happen once, inside the memoised deriveListState.
+      const entries = derivedList.entries
       const activeCount = data.entries.filter((e) => e.enabled && e.content !== '').length
       // Persona profiles, in stored order (stable injection order). Old hosts
       // simply have no array.
@@ -2762,17 +2895,7 @@ window.__ModuleLoader__.load({
         : profiles.reduce((n, p) => n + (p.enabled === true && p.content ? p.name.length + p.content.length + 5 : 0), 0)
       // Every tag actually in use, most frequent first (then name), for the
       // tag filter row.
-      const allTags = (() => {
-        const counts = new Map()
-        for (const entry of data.entries) {
-          for (const tag of Array.isArray(entry.tags) ? entry.tags : []) {
-            if (typeof tag === 'string' && tag !== '') counts.set(tag, (counts.get(tag) || 0) + 1)
-          }
-        }
-        return [...counts.entries()]
-          .sort((a, b) => (b[1] - a[1]) || a[0].localeCompare(b[0], undefined, { sensitivity: 'base' }))
-          .map(([tag]) => tag)
-      })()
+      const allTags = derivedList.allTags
       // Budget usage + per-entry marks straight from the Host's injection plan.
       // Older hosts simply publish none of these fields: the meter falls back
       // to data.budgetChars and the maps stay empty.
@@ -2809,8 +2932,8 @@ window.__ModuleLoader__.load({
       // F17: the local preview scores the ACTIVE set's on-demand entries.
       // Disabled entries can never be injected, so scoring them as 预演 hits
       // would mislead — they are excluded from the preview entirely.
-      const autoEntries = data.entries.filter((entry) => entry.mode === 'auto' && entry.enabled !== false)
-      const sim = relevancePreview(autoEntries, simQuery)
+      const autoEntries = derivedList.autoEntries
+      const sim = derivedList.sim
       const simById = new Map(sim.results.map((hit) => [hit.id, hit]))
       const omittedById = new Map()
       const truncatedById = new Map()
@@ -2827,22 +2950,8 @@ window.__ModuleLoader__.load({
       }
       const keyword = query.trim().toLowerCase()
       const filtersActive = tagFilter !== '' || modeFilter !== '' || statusFilter !== ''
-      const matchesFilters = (entry) => {
-        if (tagFilter !== '' && !(Array.isArray(entry.tags) && entry.tags.includes(tagFilter))) return false
-        if (modeFilter !== '' && entry.mode !== modeFilter) return false
-        if (statusFilter === 'enabled' && entry.enabled !== true) return false
-        if (statusFilter === 'disabled' && entry.enabled !== false) return false
-        return true
-      }
-      const visible = entries.filter((entry) => {
-        if (!matchesFilters(entry)) return false
-        if (keyword === '') return true
-        const inTags = (Array.isArray(entry.tags) ? entry.tags.join(' ') : '').toLowerCase()
-        return entry.title.toLowerCase().indexOf(keyword) !== -1
-          || entry.content.toLowerCase().indexOf(keyword) !== -1
-          || entry.when.toLowerCase().indexOf(keyword) !== -1
-          || inTags.indexOf(keyword) !== -1
-      })
+      // Filters and keyword were applied in one pass inside deriveListState.
+      const visible = derivedList.visible
 
       const dotClass = injection.error
         ? 'im-dot im-dot-err'
@@ -3013,7 +3122,11 @@ window.__ModuleLoader__.load({
             // 自动恢复，无需用户操作、不写盘。倒计时只是展示，权威在快照。
             muted && muteRemainingMs > 0
               ? h('div', { className: 'im-pause-bar' },
-                h('span', null, t('mute.active', { remaining: muteRemainingText(muteRemainingMs) })),
+                h(MuteCountdown, {
+                  until: disabledUntil,
+                  format: (ms) => t('mute.active', { remaining: muteRemainingText(ms) }),
+                  onExpired: () => setMuteExpired((n) => n + 1),
+                }),
                 h('button', { className: 'im-btn', disabled: busy, onClick: resumePause }, t('mute.resume')))
               : h('div', { className: 'im-pause-row' },
                 h('button', {

package/lib/index.js

@@ -128,6 +128,10 @@ const MAX_MUTE_MS = 7 * 24 * 60 * 60 * 1000
  * duplicated tab left open for weeks) cannot grow the set without bound.
  */
 const MAX_SSE_STREAMS = 32
+/** Idle keep-alive for event streams; well under the usual 60s proxy idle timeout. */
+const SSE_HEARTBEAT_MS = 25 * 1000
+/** An SSE comment line: every spec-compliant client ignores it. */
+const SSE_PING_FRAME = ': ping\n\n'
 const HISTORY_DIR_NAME = 'history'
 /** Name of the JSON Schema shipped with the package and copied next to the store. */
 const SCHEMA_FILE_NAME = 'memory.schema.json'
@@ -2205,6 +2209,49 @@ export function apply(ctx) {
    * pushSnapshot).
    */
   const sseStreams = new Map()
+  /**
+   * Shared heartbeat over every live event stream, started with the first
+   * subscriber and stopped with the last. Two jobs:
+   *
+   *  - intermediaries (and some client stacks) close an idle stream; a comment
+   *    frame every 25s keeps it warm, and SSE clients are required to ignore
+   *    `:` lines, so an older panel sees no difference;
+   *  - it is the only place that can PROVE a subscriber stopped reading.
+   *    `res.write()` returning false means the socket buffer is full. Without
+   *    checking it, a crashed or sleeping client keeps its Map entry, socket and
+   *    file handle until TCP notices — minutes — and enough such zombies hold
+   *    MAX_SSE_STREAMS so that every later subscriber is refused with 503 until
+   *    the host is restarted.
+   */
+  let sseHeartbeat = null
+  const stopHeartbeat = () => {
+    if (sseHeartbeat === null) return
+    clearInterval(sseHeartbeat)
+    sseHeartbeat = null
+  }
+  const ensureHeartbeat = () => {
+    if (sseHeartbeat !== null || disposed) return
+    sseHeartbeat = setInterval(() => {
+      if (disposed || sseStreams.size === 0) {
+        stopHeartbeat()
+        return
+      }
+      for (const [send, entry] of Array.from(sseStreams)) {
+        try {
+          // The RETURN VALUE is deliberately not read as a liveness signal:
+          // res.write() answers false when THIS write exceeded the socket's
+          // high-water mark, which a healthy but momentarily slow reader
+          // produces too — killing on it tore down live streams. A dead peer
+          // is detected the reliable way instead: the write fails, which fires
+          // the close/error handler this stream has already registered.
+          send(SSE_PING_FRAME)
+        } catch {
+          entry.cleanup()
+        }
+      }
+    }, SSE_HEARTBEAT_MS)
+    if (typeof sseHeartbeat.unref === 'function') sseHeartbeat.unref()
+  }
   let storeWatcher = null
   let watchDebounce = null
   /**
@@ -2366,7 +2413,20 @@ export function apply(ctx) {
         // an external edit) but it must not happen silently: the downgrade is
         // invisible otherwise.
         logInfo('store watcher failed, falling back to the 5s poller: ' + describeError(err))
-        stopWatching()
+        // Drop the WATCHER only. stopWatching() also clears the poller, which
+        // is the one mechanism still able to notice an external edit after this
+        // error — calling it here contradicted the log line above and left the
+        // process with NO change detection at all until the next successful
+        // save re-armed both. The poller is idempotent, so re-asserting it is a
+        // no-op when it is already running.
+        const dead = storeWatcher
+        storeWatcher = null
+        try {
+          dead.close()
+        } catch {
+          // The OS side already dropped the handle.
+        }
+        startPolling()
       })
     } catch {
       storeWatcher = null
@@ -2378,6 +2438,7 @@ export function apply(ctx) {
   }
 
   const disposeStreams = () => {
+    stopHeartbeat()
     for (const entry of Array.from(sseStreams.values())) {
       try {
         entry.cleanup()
@@ -2392,6 +2453,28 @@ export function apply(ctx) {
 
   const storePath = resolveStorePath()
 
+  /**
+   * The rev a PARSED store carries, or 0 when it carries none usable.
+   *
+   * Defined BEFORE writeToDisk on purpose: the missing-primary recovery path
+   * calls writeToDisk from the boot sequence, and a `const` declared later in
+   * apply() would still be in its temporal dead zone if that write ever ran
+   * before apply() reached the declaration. Ordering it here removes the
+   * question instead of relying on the await that happens to come first today.
+   */
+  const diskRevFrom = (parsed) => {
+    const rev = parsed !== null && parsed !== undefined && typeof parsed === 'object' ? parsed.rev : null
+    return typeof rev === 'number' && Number.isFinite(rev) && rev > 0 ? Math.round(rev) : 0
+  }
+
+  const readDiskRev = async () => {
+    try {
+      return diskRevFrom(await readStoreFile(storePath))
+    } catch {
+      return 0
+    }
+  }
+
   /**
    * The exact object written to memory.json — and the one an export carries.
    *
@@ -2872,7 +2955,19 @@ export function apply(ctx) {
       // monotonic while the CONTENT of their save was dropped without an error
       // — "rev 3" looked healthy and the entry was simply gone. Refuse instead,
       // so the caller retries against the newer store.
-      const diskRevNow = await readDiskRev()
+      //
+      // ONE read serves both this check and the ".bak" shape guard further
+      // down: the previous shape read the same file three times inside the lock
+      // (twice just to obtain the rev) while another DSH process could already
+      // be waiting on that very lock. `diskReadError` preserves the exact
+      // failure the later guard would have raised itself, so its ENOENT / empty
+      // / not-a-store branches keep their current behaviour.
+      let diskReadError = null
+      const diskSnapshot = await readStoreFile(storePath).catch((err) => {
+        diskReadError = err === null || err === undefined ? new Error('unreadable store') : err
+        return undefined
+      })
+      const diskRevNow = diskRevFrom(diskSnapshot)
       if (diskRevNow > (state.data.rev || 0)) {
         state.storageError = '另一个 DSH 进程刚刚保存了记忆（磁盘 rev ' + diskRevNow
           + '，本进程 rev ' + (state.data.rev || 0) + '），本次未写入以免覆盖，请重试'
@@ -2901,8 +2996,9 @@ export function apply(ctx) {
       // ACROSS processes: two windows that loaded rev 5 would otherwise both
       // write rev 6, and anything that watches the rev for change (the lite
       // SSE stream) cannot tell the second save from a repeat of the first.
-      const diskRev = await readDiskRev()
-      previousRev = Math.max(state.data.rev || 0, diskRev)
+      // Same read as the check above: the lock is ours, so the file cannot have
+      // moved in between.
+      previousRev = Math.max(state.data.rev || 0, diskRevNow)
       state.data.rev = previousRev + 1
       const text = serialize()
       // mode 0600: the store holds the user's private instructions and (with a
@@ -2932,7 +3028,11 @@ export function apply(ctx) {
       // discloses it (the .bak may be stale, and the panel says so).
       let hadPrevious = true
       try {
-        const previous = await readStoreFile(storePath)
+        // Reuse the read taken above instead of touching the file a third
+        // time. The captured failure is rethrown so every branch of the catch
+        // below keeps exactly its current meaning.
+        if (diskReadError !== null) throw diskReadError
+        const previous = diskSnapshot
         // "Reads as a store", not merely "reads as JSON" — this is the test the
         // comment above promises. A foreign-but-parseable primary (an array, a
         // scalar, another tool's object) must NOT be copied over the last good
@@ -3058,16 +3158,6 @@ export function apply(ctx) {
    * then silently misses the second save; and (b) deciding whether a save made
    * while another process holds the lock would clobber a newer store.
    */
-  const readDiskRev = async () => {
-    try {
-      const parsed = await readStoreFile(storePath)
-      const rev = parsed !== null && typeof parsed === 'object' ? parsed.rev : null
-      return typeof rev === 'number' && Number.isFinite(rev) && rev > 0 ? Math.round(rev) : 0
-    } catch {
-      return 0
-    }
-  }
-
   /**
    * Load the store from disk. Most branches only read; two of them also write —
    * the missing-primary recovery promotes the backup to memory.json, and the
@@ -5293,6 +5383,9 @@ export function apply(ctx) {
       }
     }
     sseStreams.set(send, { cleanup, lite })
+    // Start the shared keep-alive lazily: a host with no open panel pays
+    // nothing, and the timer stops itself when the last stream closes.
+    ensureHeartbeat()
     req.on('close', cleanup)
     req.on('error', cleanup)
     res.on('error', cleanup)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-instruction-memory",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "User-only instruction memory for DSH: long-term instructions maintained in the settings UI and auto-injected into every conversation — the model has no write access. 指令记忆：只由用户在设置页维护的长期指令，自动注入此后每轮对话；模型没有任何写入口。",
   "license": "MIT",
   "type": "module",