dsh-instruction-memory 1.0.14 → 1.0.16

package/lib/index.js

@@ -10,9 +10,12 @@
  * plugin's fiber, so unmounting the row removes all of them.
  */
 
-import { copyFile, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { copyFile, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
+import { watch } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { isIP } from 'node:net'
 import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { basename, dirname, join } from 'node:path'
 
 export const name = 'instruction-memory'
 
@@ -105,6 +108,13 @@ const MAX_WHEN = 200
  */
 export const MAX_BODY_CHARS = MAX_ENTRIES * (MAX_CONTENT + MAX_TITLE + MAX_WHEN + 200) * 2 + 100_000
 
+/** How long a crashed holder's `memory.json.lock` may block writes before it is stolen. */
+const LOCK_STALE_MS = 10_000
+/** How long a write waits for the cross-process lock before proceeding unlocked. */
+const LOCK_WAIT_MS = 2_000
+/** Coalescing window for store-directory watcher events before a re-read. */
+const WATCH_DEBOUNCE_MS = 250
+
 /* ------------------------------------------------------------------ *
  * Pure helpers (no ctx, fully unit-testable)
  * ------------------------------------------------------------------ */
@@ -187,18 +197,64 @@ export function truncatedFields(raw) {
   return cut
 }
 
+/** JSON.stringify keeps quotes/type visible; the String() tail is for values JSON cannot encode. */
+const describeValue = (value) => {
+  const text = JSON.stringify(value)
+  return typeof text === 'string' ? text : String(value)
+}
+
 /**
  * Load a parsed memory file. Returns the sanitized data plus how many array
  * items were discarded (blank entries, or valid ones past the cap). The count
  * is surfaced rather than swallowed because the next save rewrites the file
  * without those items — silently destroying user data is exactly what this
  * plugin must never do.
+ *
+ * `rev` is the store revision, bumped on every committed write and persisted
+ * in the file. Clients echo it back as `baseRev` so a write built on a stale
+ * snapshot (another window, another process) can be refused instead of
+ * silently overwriting it. Missing (pre-rev files) reads as 0.
+ *
+ * A numeric `version` other than 1 sets `rejectedVersion` and leaves the data
+ * untouched: a future format's fields cannot be best-effort parsed as v1, and
+ * adopting a misread would let the next save rewrite the file in the wrong
+ * shape. A MISSING version still loads as v1 — the field has been written as
+ * 1 since the first release, so absence is an old/hand-made file, not a
+ * foreign format.
+ *
+ * `optionFixes` lists options the file carried but the loader had to correct
+ * (a non-boolean `enabled`, an out-of-range or non-numeric `budgetChars`).
+ * Each is a human-readable "field 原值 → 修正值 (原因)" string, surfaced the
+ * same way as `dropped`: the next save persists the corrected values, so the
+ * user must be told their hand edit did not survive verbatim.
  */
 function normalizeData(raw) {
-  const data = { version: 1, enabled: true, budgetChars: DEFAULT_BUDGET, entries: [] }
-  if (raw === null || typeof raw !== 'object') return { data, dropped: 0 }
-  if (typeof raw.enabled === 'boolean') data.enabled = raw.enabled
-  data.budgetChars = clampBudget(raw.budgetChars)
+  const data = { version: 1, rev: 0, enabled: true, budgetChars: DEFAULT_BUDGET, entries: [] }
+  if (raw === null || typeof raw !== 'object') return { data, dropped: 0, optionFixes: [] }
+  if (typeof raw.version === 'number' && raw.version !== 1) {
+    return { data, dropped: 0, optionFixes: [], rejectedVersion: raw.version }
+  }
+  if (typeof raw.rev === 'number' && Number.isFinite(raw.rev) && raw.rev >= 0) {
+    data.rev = Math.round(raw.rev)
+  }
+  // Hand-edited options the loader has to correct are disclosed, not silently
+  // adopted: the next save would otherwise rewrite the file with the fixed
+  // values and the user would never learn their edit had been ignored.
+  const optionFixes = []
+  if (typeof raw.enabled === 'boolean') {
+    data.enabled = raw.enabled
+  } else if ('enabled' in raw) {
+    optionFixes.push('enabled ' + describeValue(raw.enabled) + ' → true（需要 true/false）')
+  }
+  if ('budgetChars' in raw) {
+    const clamped = clampBudget(raw.budgetChars)
+    if (clamped !== raw.budgetChars) {
+      optionFixes.push(typeof raw.budgetChars === 'number' && Number.isFinite(raw.budgetChars)
+        ? 'budgetChars ' + raw.budgetChars + ' → ' + clamped + '（有效范围 ' + MIN_BUDGET + '–' + MAX_BUDGET + '）'
+        : 'budgetChars ' + describeValue(raw.budgetChars) + ' → ' + clamped + '（需要 ' + MIN_BUDGET + '–' + MAX_BUDGET + ' 的数字）')
+    }
+    data.budgetChars = clamped
+  }
   const list = Array.isArray(raw.entries) ? raw.entries : []
   const seen = new Set()
   let dropped = 0
@@ -216,7 +272,7 @@ function normalizeData(raw) {
     seen.add(entry.id)
     data.entries.push(entry)
   }
-  return { data, dropped }
+  return { data, dropped, optionFixes }
 }
 
 /**
@@ -231,6 +287,7 @@ function normalizeData(raw) {
 function cloneData(data) {
   return {
     version: 1,
+    rev: data.rev || 0,
     enabled: data.enabled === true,
     budgetChars: data.budgetChars,
     entries: (Array.isArray(data.entries) ? data.entries : []).map((entry) => ({ ...entry })),
@@ -242,6 +299,22 @@ const droppedEntriesMessage = (count) =>
     ? '存储文件中有 ' + count + ' 条条目未能载入（内容为空或超过 ' + MAX_ENTRIES + ' 条上限）；下次保存时它们将从文件中移除'
     : null
 
+/**
+ * The load-time disclosures for one normalizeData result: dropped entries and
+ * corrected hand-edited options, joined with a full-width semicolon.
+ * Returns null when neither applies, so callers can assign it directly to
+ * `state.storageWarning` (a null means "no warning", not an empty string).
+ */
+const loadWarnings = (loaded) => {
+  const parts = []
+  const dropped = droppedEntriesMessage(loaded.dropped)
+  if (dropped !== null) parts.push(dropped)
+  if (Array.isArray(loaded.optionFixes) && loaded.optionFixes.length > 0) {
+    parts.push('存储文件中的以下选项值无效，已按规则修正：' + loaded.optionFixes.join('；') + '；下次保存时修正值将写入文件')
+  }
+  return parts.length > 0 ? parts.join('；') : null
+}
+
 /**
  * Hostnames a loopback-bound server may legitimately be reached by.
  *
@@ -255,6 +328,13 @@ const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '::1', '::ffff:127
  *
  * `127.0.0.1:8080` -> `127.0.0.1`; `[::1]:8080` -> `::1`; `localhost` -> `localhost`.
  * Exported so the parsing itself can be pinned by tests.
+ *
+ * HTTP requires IPv6 literals in Host to wear brackets, so the bracketed
+ * form is the one real traffic uses; the bare form still has to parse instead
+ * of being chopped at the last colon (the old code turned a bare `::1` into
+ * `:`, which never matched the loopback set). A bare value carrying MORE than
+ * one colon is an IPv6 literal with no port — with at most one colon it is
+ * host:port.
  */
 export function hostnameOf(value) {
   if (typeof value !== 'string') return ''
@@ -262,15 +342,104 @@ export function hostnameOf(value) {
   if (trimmed === '') return ''
   if (trimmed.startsWith('[')) {
     const end = trimmed.indexOf(']')
-    return end === -1 ? trimmed : trimmed.slice(1, end)
+    return end === -1 ? trimmed.slice(1) : trimmed.slice(1, end)
   }
+  // Unbracketed IPv6 literal: the colons are part of the address, not a port.
+  if (trimmed.indexOf(':') !== trimmed.lastIndexOf(':')) return trimmed
   const colon = trimmed.lastIndexOf(':')
   return colon === -1 ? trimmed : trimmed.slice(0, colon)
 }
 
 /**
- * Why the settings-page route checks `Host` and `Origin` at all, when it already
- * refuses any content-type that is not `application/json`.
+ * Normalise a hostname the same way on BOTH sides of the Origin comparison.
+ *
+ * `new URL('http://[::1]:8080').hostname` keeps the brackets (`[::1]`), while
+ * `hostnameOf('[::1]:8080')` strips them (`::1`) — comparing the two raw forms
+ * rejected every same-origin request that reached the GUI over IPv6 loopback.
+ * Strip one surrounding pair of brackets here so both sides spell an IPv6
+ * literal identically.
+ */
+const normalizeHostname = (value) => (
+  typeof value === 'string' && value.startsWith('[') && value.endsWith(']') && value.length >= 2
+    ? value.slice(1, -1)
+    : value
+)
+
+/**
+ * Expand an IPv6 literal to eight lower-cased zero-padded groups, translating a
+ * trailing embedded IPv4 suffix to two hex groups. Returns null for anything
+ * that is not a valid literal.
+ *
+ * Needed because the two sides of the Origin check spell the SAME address
+ * differently: a browser sends Host `[::ffff:127.0.0.1]` while the URL parser
+ * canonicalises Origin to `[::ffff:7f00:1]` — text comparison says these are
+ * different; address comparison must say they are the same.
+ */
+export function canonicalIp(value) {
+  if (typeof value !== 'string') return null
+  let addr = normalizeHostname(value.trim().toLowerCase())
+  const percent = addr.indexOf('%')
+  if (percent !== -1) addr = addr.slice(0, percent)
+  if (isIP(addr) === 4) {
+    return 'v4:' + addr.split('.').map((part) => Number(part)).join('.')
+  }
+  if (isIP(addr) !== 6) return null
+
+  // Translate a trailing dotted-quad (e.g. ::ffff:127.0.0.1) into two groups.
+  const v4 = /(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(addr)
+  if (v4 !== null) {
+    const octets = v4[1].split('.').map((part) => Number(part))
+    if (octets.some((octet) => octet > 255)) return null
+    const prefix = addr.slice(0, v4.index)
+    const hi = (octets[0] << 8 | octets[1]).toString(16)
+    const lo = (octets[2] << 8 | octets[3]).toString(16)
+    // Keep the trailing ':' of the prefix as the separator before the two
+    // translated groups; it may also be the second ':' of a '::' compression,
+    // which must survive (so do not strip a leading colon afterwards).
+    addr = (prefix.endsWith(':') ? prefix : prefix + ':') + hi + ':' + lo
+  }
+
+  const halves = addr.split('::')
+  if (halves.length > 2) return null
+  if (halves.length === 1) {
+    const groups = halves[0].split(':')
+    if (groups.length !== 8 || groups.some((group) => !/^[0-9a-f]{1,4}$/i.test(group))) return null
+    return groups.map((group) => parseInt(group, 16).toString(16).padStart(4, '0')).join(':')
+  }
+  const [leftRaw, rightRaw] = halves
+  const left = leftRaw === '' ? [] : leftRaw.split(':')
+  const right = rightRaw === '' ? [] : rightRaw.split(':')
+  const missing = 8 - left.length - right.length
+  if (missing < 0) return null
+  const groups = left.concat(Array(missing).fill('0'), right)
+  if (groups.length !== 8 || groups.some((group) => !/^[0-9a-f]{1,4}$/i.test(group))) return null
+  return groups.map((group) => parseInt(group, 16).toString(16).padStart(4, '0')).join(':')
+}
+
+/** Whether two hostnames are the same endpoint: exact text or same IP literal. */
+const sameHostname = (a, b) => {
+  if (a === b) return true
+  const ca = canonicalIp(a)
+  const cb = canonicalIp(b)
+  return ca !== null && cb !== null && ca === cb
+}
+
+/** Loopback by exact name or by equivalent IP spelling (mapped/hex forms). */
+const isLoopbackName = (name) => {
+  if (LOOPBACK_HOSTNAMES.has(name)) return true
+  const canonical = canonicalIp(name)
+  if (canonical === null) return false
+  for (const known of LOOPBACK_HOSTNAMES) {
+    const knownCanonical = canonicalIp(known)
+    if (knownCanonical !== null && knownCanonical === canonical) return true
+  }
+  return false
+}
+
+/**
+ * Why the settings-page route checks `Host`, `Origin` and `Sec-Fetch-Site` at
+ * all, when it already refuses any content-type that is not
+ * `application/json`.
  *
  * The content-type rule stops a cross-site form post, and no CORS headers are
  * sent so a cross-origin `fetch` with a JSON body dies in preflight. Both
@@ -283,10 +452,21 @@ export function hostnameOf(value) {
  * change is the `Host` header the browser sends: it still carries `evil.com`.
  *
  * So when the server is bound to loopback (the default) the route requires a
- * loopback `Host`. An operator who binds `0.0.0.0` has deliberately published
- * the whole server on every interface, where no Host value can be known in
- * advance — the check is disabled there rather than breaking every legitimate
- * client, and that trade-off is documented in the README.
+ * loopback `Host`. An operator who binds a non-loopback address (`0.0.0.0`,
+ * `::`, or a concrete one) has deliberately published the server beyond this
+ * machine, where no Host value can be known in advance — the check is disabled
+ * there rather than breaking every legitimate client, and that trade-off is
+ * documented in the README.
+ *
+ * `Sec-Fetch-Site` adds a second browser-only signal (absent from curl, Node,
+ * and pre-2020 browsers, which is exactly why it can only ADD rejections, never
+ * replace the checks above): a modern browser stamps every request with it, so
+ * a page at evil.com talking to this route — even through tricks that drop the
+ * `Origin` header — still says `cross-site`. Only `cross-site` is refused;
+ * `same-site` must pass because schemeful same-site ignores ports (the GUI and
+ * the route live on the same host but different ports), and local non-browser
+ * clients never send the header at all, so they are governed by the Host and
+ * content-type checks alone.
  */
 export function requestOriginVerdict(headers, guarded) {
   const read = (name) => {
@@ -297,22 +477,32 @@ export function requestOriginVerdict(headers, guarded) {
   const requestHost = read('host').trim().toLowerCase()
   const requestHostname = hostnameOf(requestHost)
 
-  if (guarded && !LOOPBACK_HOSTNAMES.has(requestHostname)) {
+  if (guarded && !isLoopbackName(requestHostname)) {
     return { ok: false, reason: 'Host 头不是回环地址（可能是 DNS 重绑定攻击）：' + (requestHost === '' ? '(缺失)' : requestHost) }
   }
 
+  const fetchSite = read('sec-fetch-site').trim().toLowerCase()
+  if (fetchSite === 'cross-site') {
+    return { ok: false, reason: '请求被浏览器标记为跨站（Sec-Fetch-Site: cross-site）' }
+  }
+
   const origin = read('origin').trim()
   if (origin !== '') {
     let originHostname = ''
     try {
-      originHostname = new URL(origin).hostname.toLowerCase()
+      // URL.hostname keeps the brackets on an IPv6 literal; normalizeHostname
+      // takes them off so it can meet the bracket-free Host parsing on equal
+      // terms.
+      originHostname = normalizeHostname(new URL(origin).hostname.toLowerCase())
     } catch {
       originHostname = ''
     }
     // Compare hostnames, not host:port: a proxy may rewrite the port, and the
     // hostname is the part rebinding actually attacks. `Origin: null`
     // (sandboxed iframe, file://) parses to no hostname and is refused.
-    if (originHostname === '' || originHostname !== requestHostname) {
+    // Canonical IP comparison covers the two spellings of one address:
+    // ::1 vs [::1], and ::ffff:127.0.0.1 vs ::ffff:7f00:1.
+    if (originHostname === '' || !sameHostname(originHostname, requestHostname)) {
       return { ok: false, reason: 'Origin 与 Host 不同源：' + origin }
     }
   }
@@ -435,6 +625,13 @@ export function apply(ctx) {
     loadedFrom: null,
     savedAt: null,
     migratedFrom: null,
+    /**
+     * Set while the store on disk declares an unsupported format version.
+     * Mutating commands are refused in that state: a save would rewrite a
+     * future-format file into v1, destroying whatever the newer format meant.
+     */
+    versionRejected: false,
+    rejectedVersion: null,
     sectionRegistered: false,
     sectionError: null,
     /** Whether a store file is actually present on disk (diagnostics + the panel). */
@@ -590,14 +787,194 @@ export function apply(ctx) {
         console.error('[instruction-memory] cleanup failed:', err)
       }
     }
+    stopWatching()
+    disposeStreams()
   })
 
+  /* ---------------- external-change watching (SSE) ---------------- */
+
+  /**
+   * Live subscribers to the settings page's event stream. Each entry maps a
+   * stream's `send(payload)` writer to its own teardown, so a write that fails
+   * (the socket went away) can dispose THAT stream instead of just dropping
+   * it from the broadcast set while its response stays open.
+   */
+  const sseStreams = new Map()
+  let storeWatcher = null
+  let watchDebounce = null
+
+  const pushSnapshot = () => {
+    if (sseStreams.size === 0) return
+    const payload = 'data: ' + JSON.stringify(snapshot()) + '\n\n'
+    for (const [send, cleanup] of Array.from(sseStreams)) {
+      try {
+        send(payload)
+      } catch {
+        // The response is dead: run its full teardown (end + unsubscribe),
+        // not just a set delete that leaves the stream half-registered.
+        cleanup()
+      }
+    }
+  }
+
+  /**
+   * A store file changed on disk. Debounced (one atomic save fires rename +
+   * copy events), then serialised through the same diskQueue as every other
+   * mutation so a watcher re-read can never interleave with a save.
+   *
+   * The file is read WITHOUT adopting it first, because this plugin's own
+   * writes fire the watcher too: if the sanitised content is identical to the
+   * in-memory state, the event was ours and there is nothing to tell anyone.
+   * A failed read (the file is momentarily absent mid-replace, or corrupt) is
+   * skipped rather than recovered-from — recovery belongs to reload, which a
+   * human asked for.
+   */
+  const onStoreFileEvent = () => {
+    if (watchDebounce !== null) clearTimeout(watchDebounce)
+    watchDebounce = setTimeout(() => {
+      watchDebounce = null
+      void enqueue(async () => {
+        try {
+          const parsed = await readStoreFile(storePath)
+          if (parsed === null) return
+          const loaded = normalizeData(parsed)
+          if (loaded.rejectedVersion === undefined
+            && JSON.stringify(loaded.data) === JSON.stringify(state.data)) {
+            return
+          }
+          await readFromDisk()
+          syncSection()
+          pushSnapshot()
+        } catch {
+          // Transient: the next event, or the panel's 重新载入, catches up.
+        }
+      })
+    }, WATCH_DEBOUNCE_MS)
+  }
+
+  const stopWatching = () => {
+    if (watchDebounce !== null) {
+      clearTimeout(watchDebounce)
+      watchDebounce = null
+    }
+    if (storeWatcher !== null) {
+      const watcher = storeWatcher
+      storeWatcher = null
+      try {
+        watcher.close()
+      } catch {
+        // Already closed by the OS side.
+      }
+    }
+  }
+
+  /**
+   * Watch the store DIRECTORY, not the file: this plugin's saves replace
+   * memory.json through an atomic rename, which on Windows can orphan a
+   * file-level watch handle (the watched inode is gone). Directory events
+   * survive replaces. A missing directory (first run, nothing materialised
+   * yet) throws and is retried by the first successful write.
+   */
+  const startWatching = () => {
+    if (storeWatcher !== null) return
+    try {
+      storeWatcher = watch(dirname(storePath), { persistent: false }, (event, filename) => {
+        // Only events naming memory.json matter; the .tmp/.bak/.lock churn of
+        // our own writes is filtered out here (the content compare in
+        // onStoreFileEvent catches what slips through).
+        if (typeof filename === 'string' && filename !== basename(storePath)) return
+        onStoreFileEvent()
+      })
+      storeWatcher.on('error', () => stopWatching())
+    } catch {
+      storeWatcher = null
+    }
+  }
+
+  const disposeStreams = () => {
+    for (const cleanup of Array.from(sseStreams.values())) {
+      try {
+        cleanup()
+      } catch {
+        // The response is already gone.
+      }
+    }
+    sseStreams.clear()
+  }
+
   /* ---------------- storage ---------------- */
 
   const storePath = resolveStorePath()
 
   const serialize = () => JSON.stringify(state.data, null, 2) + '\n'
 
+  /**
+   * Cross-process write lock: a `memory.json.lock` marker created exclusively
+   * (`wx`) holding a random owner token, kept for the duration of one atomic
+   * replace, and removed afterwards ONLY BY ITS OWNER.
+   *
+   * The in-process diskQueue serialises this plugin's own writes, but two DSH
+   * processes sharing a `$DSH_HOME` (e.g. `web` and `tui` profiles running at
+   * once) can interleave a copy-backup/atomic-rename sequence. The rename
+   * itself keeps the file uncorrupted; what the lock narrows is the
+   * last-write-wins window in which one process's edit silently erases the
+   * other's.
+   *
+   * Availability beats exclusion for a user-facing store: a lock that cannot
+   * be acquired within a short wait is NEVER allowed to fail the save — the
+   * write proceeds anyway (disclosed in the debug log). A lock older than
+   * LOCK_STALE_MS is treated as crashed-holder debris and stolen, so a killed
+   * process cannot wedge every later save behind a stale marker.
+   *
+   * The token matters: stealing used to be a plain unlink, and the slow
+   * holder's `finally` then unlinked the lock the NEW owner had just created —
+   * a classic TOCTOU that silently unlocked the third writer. The marker
+   * carries this attempt's UUID, and release deletes it only when the file
+   * still carries that UUID, so a finished holder can never remove a lock it
+   * no longer owns.
+   *
+   * @returns `{ path, token }` while held, or `null` when the wait elapsed
+   * (the save proceeds unlocked by design).
+   */
+  const acquireStoreLock = async () => {
+    const lockPath = storePath + '.lock'
+    const token = randomUUID()
+    const deadline = Date.now() + LOCK_WAIT_MS
+    for (;;) {
+      try {
+        await writeFile(lockPath, token, { flag: 'wx' })
+        return { path: lockPath, token }
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err
+        const info = await stat(lockPath).catch(() => null)
+        if (info !== null && Date.now() - info.mtimeMs > LOCK_STALE_MS) {
+          // Crashed-holder debris. It may be recreated by a live process
+          // between this unlink and the next wx attempt — that case simply
+          // loops and re-evaluates freshness instead of forcing its way in.
+          await unlink(lockPath).catch(() => {})
+          continue
+        }
+        if (Date.now() >= deadline) return null
+        await new Promise((resolve) => setTimeout(resolve, 50))
+      }
+    }
+  }
+
+  /**
+   * Release a lock only when THIS attempt still owns it. Reading the marker
+   * back and comparing the token closes the window in which a finished slow
+   * holder deleted a lock the next owner had already taken over.
+   */
+  const releaseStoreLock = async (lock) => {
+    if (lock === null) return
+    try {
+      const owner = await readFile(lock.path, 'utf8').catch(() => null)
+      if (owner === lock.token) await unlink(lock.path).catch(() => {})
+    } catch {
+      // Cleanup must never throw into the save's finally.
+    }
+  }
+
   const writeToDisk = async () => {
     // Atomic replace (write a sibling temp file, then rename) with a rolling
     // one-version backup: a crash mid-write must never leave a truncated
@@ -614,8 +991,18 @@ export function apply(ctx) {
     // any step leaves the previous store readable at its own path.
     const tmpPath = storePath + '.tmp'
     const bakPath = storePath + '.bak'
+    let lock = null
+    let previousRev = null
     try {
       await mkdir(dirname(storePath), { recursive: true })
+      lock = await acquireStoreLock()
+      if (lock === null) {
+        logDebug('store lock still held by another process; writing anyway (last write wins)')
+      }
+      // The rev is bumped before serialising so the file on disk and the state
+      // in memory agree on it; a failed write restores the old value.
+      previousRev = state.data.rev || 0
+      state.data.rev = previousRev + 1
       const text = serialize()
       await writeFile(tmpPath, text, 'utf8')
       try {
@@ -644,14 +1031,20 @@ export function apply(ctx) {
       // A successful write is the one thing that makes the file real, so it is
       // also what clears the "not materialised yet" flag set by a first run.
       needsMaterialize = false
+      // ...and what guarantees the store directory exists, so the watcher can
+      // be (re)armed after a first run that had nothing to watch.
+      startWatching()
       state.savedAt = Date.now()
       logDebug('store written: ' + storePath + ' bytes=' + text.length
-        + ' entries=' + state.data.entries.length
+        + ' entries=' + state.data.entries.length + ' rev=' + state.data.rev
         + (state.backupError === null ? ' backup=refreshed' : ' backup=FAILED'))
       return true
     } catch (err) {
+      if (previousRev !== null) state.data.rev = previousRev
       state.storageError = '保存失败：' + describeError(err)
       return false
+    } finally {
+      await releaseStoreLock(lock)
     }
   }
 
@@ -660,25 +1053,57 @@ export function apply(ctx) {
     return text.trim() === '' ? null : JSON.parse(text)
   }
 
+  /**
+   * 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
+   * legacy-location migration writes the migrated store. The return value says
+   * which happened, because `reload` reports it as its `saved` field: the
+   * response envelope's `saved` means "this operation persisted the store",
+   * and a read-only reload claiming true would be indistinguishable from a
+   * real save.
+   *
+   * @returns whether this load performed a successful write.
+   */
   const readFromDisk = async () => {
     state.storagePath = storePath
     state.storageDisplay = storePath
     state.storageWarning = null
     state.loadedFrom = null
     state.storeExists = false
+    state.versionRejected = false
+    state.rejectedVersion = null
+
+    /**
+     * A store declaring an unsupported format version: adopt nothing, write
+     * nothing, and say why. The one thing that must NEVER happen in this
+     * state is a save — it would rewrite the file as v1 and destroy whatever
+     * the newer format meant (the mutating commands refuse while
+     * versionRejected is set).
+     */
+    const rejectVersion = (version, source) => {
+      state.versionRejected = true
+      state.rejectedVersion = version
+      state.storageError = '存储文件声明为格式版本 ' + version + '，本插件只支持版本 1；已拒绝载入以防数据损坏，原文件已保留，修改操作已暂停。请升级插件，或手动将文件改回版本 1 后点「重新载入」'
+      state.loadedFrom = source + ' (unsupported version ' + version + ')'
+      state.storeExists = true
+    }
 
     // 1. The canonical location under the harness home.
     try {
       const parsed = await readStoreFile(storePath)
       if (parsed !== null) {
         const loaded = normalizeData(parsed)
+        if (loaded.rejectedVersion !== undefined) {
+          rejectVersion(loaded.rejectedVersion, 'memory.json')
+          return false
+        }
         state.data = loaded.data
-        state.storageWarning = droppedEntriesMessage(loaded.dropped)
+        state.storageWarning = loadWarnings(loaded)
         state.loadedFrom = 'memory.json'
         state.storeExists = true
       }
       state.storageError = null
-      return
+      return false
     } catch (err) {
       if (err === null || err === undefined || err.code !== 'ENOENT') {
         // The main file is unreadable or corrupt. A previous good version
@@ -687,16 +1112,27 @@ export function apply(ctx) {
         // itself stays untouched for hand repair; it gets overwritten on the
         // next save (the pre-existing and disclosed behaviour).
         if (err instanceof SyntaxError) {
+          // The file was READ and only failed to PARSE, so a store file is
+          // physically present on disk. Saying onDisk=no here contradicted
+          // the branch's own story ("损坏文件已保留") and produced a mounted
+          // log line reading "from=memory.json.bak (main file corrupt)
+          // onDisk=no". (Other non-ENOENT errors stay no: ENOTDIR, say, means
+          // nothing exists at the store path at all.)
+          state.storeExists = true
           try {
             const backup = await readStoreFile(storePath + '.bak')
             if (backup !== null) {
               const loaded = normalizeData(backup)
+              if (loaded.rejectedVersion !== undefined) {
+                rejectVersion(loaded.rejectedVersion, 'memory.json.bak')
+                return false
+              }
               state.data = loaded.data
-              state.storageWarning = (droppedEntriesMessage(loaded.dropped) || '')
-                + (loaded.dropped > 0 ? '；' : '')
+              const warnings = loadWarnings(loaded)
+              state.storageWarning = (warnings !== null ? warnings + '；' : '')
                 + 'memory.json 解析失败（' + describeError(err) + '），已临时回退到最近备份 memory.json.bak；损坏文件已保留，下次保存时会覆盖它'
               state.loadedFrom = 'memory.json.bak (main file corrupt)'
-              return
+              return false
             }
           } catch {
             // No usable backup either; fall through to the error below.
@@ -706,7 +1142,7 @@ export function apply(ctx) {
         state.storageError = err instanceof SyntaxError
           ? '配置文件解析失败（' + describeError(err) + '），原文件已保留；你下次保存时会覆盖它'
           : '读取失败：' + describeError(err)
-        return
+        return false
       }
     }
 
@@ -722,14 +1158,18 @@ export function apply(ctx) {
       const backup = await readStoreFile(storePath + '.bak')
       if (backup !== null) {
         const loaded = normalizeData(backup)
+        if (loaded.rejectedVersion !== undefined) {
+          rejectVersion(loaded.rejectedVersion, 'memory.json.bak')
+          return false
+        }
         state.data = loaded.data
         const promoted = await writeToDisk()
-        state.storageWarning = (droppedEntriesMessage(loaded.dropped) || '')
-          + (loaded.dropped > 0 ? '；' : '')
+        const warnings = loadWarnings(loaded)
+        state.storageWarning = (warnings !== null ? warnings + '；' : '')
           + 'memory.json 不存在，已从最近备份 memory.json.bak 恢复'
           + (promoted ? '，并已写回 memory.json' : '；写回 memory.json 失败，下次保存时会重试')
         state.loadedFrom = 'memory.json.bak (main file missing)'
-        return
+        return promoted
       }
     } catch {
       // An unusable backup must never block a fresh store; fall through.
@@ -742,15 +1182,21 @@ export function apply(ctx) {
       const parsed = await readStoreFile(legacyPath)
       if (parsed !== null) {
         const loaded = normalizeData(parsed)
+        if (loaded.rejectedVersion !== undefined) {
+          // A legacy file in a future format is not ours to migrate or judge.
+          state.storageError = '旧位置文件为不支持的格式版本 ' + loaded.rejectedVersion + '，已忽略'
+          return false
+        }
         state.data = loaded.data
-        state.storageWarning = droppedEntriesMessage(loaded.dropped)
-        if (await writeToDisk()) {
+        state.storageWarning = loadWarnings(loaded)
+        const migrated = await writeToDisk()
+        if (migrated) {
           state.migratedFrom = legacyPath
           // Keep the original as evidence instead of deleting user data.
           await rename(legacyPath, legacyPath + '.migrated').catch(() => {})
         }
         state.loadedFrom = 'legacy cwd file (migrated)'
-        return
+        return migrated
       }
     } catch (err) {
       // A missing or unreadable legacy file must never block a fresh store.
@@ -770,6 +1216,7 @@ export function apply(ctx) {
     needsMaterialize = true
     state.loadedFrom = 'first run (no store on disk yet)'
     state.storeExists = false
+    return false
   }
 
   /**
@@ -789,11 +1236,19 @@ export function apply(ctx) {
   // Load the store, then register the section if anything must be injected.
   // Every entry point awaits this, so a request that arrives before the disk
   // read settles can never overwrite the file with an empty in-memory state.
+  //
+  // `bootSettled` flips only after the read lands. The SSE connect frame is
+  // gated on it: a stream opened in the gap between apply() and the read
+  // finishing must wait, or its first frame would describe the EMPTY boot
+  // state and the panel would flash "no instructions" before the real
+  // snapshot arrived (POST /state already awaited boot; the stream did not).
+  let bootSettled = false
   const boot = readFromDisk()
     .catch((err) => {
       state.storageError = '读取失败：' + describeError(err)
     })
     .then(() => {
+      bootSettled = true
       syncSection()
       // The one always-on line: it answers "is memory mounted, where does it
       // live, and how much is being injected?" without any further digging.
@@ -809,6 +1264,9 @@ export function apply(ctx) {
         + ' section=' + (chars > 0 ? chars + ' chars (pending assembly)' : 'nothing to inject')
         + ' pulls=' + sectionPulls
         + (state.storageError !== null ? ' error=' + state.storageError : ''))
+      // Arm the external-change watcher once the store is known to exist. A
+      // first run has nothing to watch yet; the first successful write rearms.
+      if (state.storeExists) startWatching()
     })
 
   /**
@@ -833,6 +1291,7 @@ export function apply(ctx) {
     return {
       data: {
         version: 1,
+        rev: state.data.rev || 0,
         enabled: state.data.enabled === true,
         budgetChars: clampBudget(state.data.budgetChars),
         entries: (Array.isArray(state.data.entries) ? state.data.entries : []).map((entry) => ({ ...entry })),
@@ -859,7 +1318,13 @@ export function apply(ctx) {
         pulls: sectionPulls,
       },
       preview,
-      limits: { minBudget: MIN_BUDGET, maxBudget: MAX_BUDGET, maxEntries: MAX_ENTRIES },
+      /**
+       * `maxBodyChars` is the route's request-body ceiling, published so the
+       * Client can refuse an obviously oversized import file BEFORE reading it
+       * into memory. It is a character budget against byte sizes, so the
+       * Client applies a generous multiplier — see importSizeVerdict there.
+       */
+      limits: { minBudget: MIN_BUDGET, maxBudget: MAX_BUDGET, maxEntries: MAX_ENTRIES, maxBodyChars: MAX_BODY_CHARS },
     }
   }
 
@@ -872,6 +1337,41 @@ export function apply(ctx) {
 
   /* ---------------- commands (shared by route and callers) ---------------- */
 
+  /**
+   * Optimistic concurrency: a mutating command may carry `baseRev` — the
+   * `data.rev` its caller last saw. A mismatch means another window or process
+   * committed in between, and applying this command now would build on a stale
+   * view (e.g. resurrect an entry another tab just deleted). The refusal hands
+   * back the FRESH snapshot so the panel resyncs immediately; the user retries
+   * and the retry carries the new rev.
+   *
+   * Absent `baseRev` (older clients) disables the check entirely — legacy
+   * behaviour, not an error.
+   */
+  const isStaleBaseRev = (baseRev) =>
+    typeof baseRev === 'number' && Number.isFinite(baseRev) && baseRev !== (state.data.rev || 0)
+
+  const conflictResponse = () => ({
+    ok: false,
+    saved: false,
+    conflict: true,
+    message: '指令记忆刚被其他窗口或进程修改，已为你载入最新内容；请检查后重试本次操作',
+    snapshot: snapshot(),
+  })
+
+  /**
+   * Refusal while the store on disk declares an unsupported format version:
+   * a save here would rewrite the file as v1 and destroy whatever the newer
+   * format meant. The file stays untouched until the user upgrades the plugin
+   * or restores a v1 file and hits 重新载入.
+   */
+  const versionRefusal = () => ({
+    ok: false,
+    saved: false,
+    message: '存储文件为不支持的格式版本 ' + state.rejectedVersion + '，修改已暂停：现在保存会用版本 1 覆盖它，可能损坏数据。请先升级插件，或手动将文件改回版本 1 后点「重新载入」',
+    snapshot: snapshot(),
+  })
+
   /**
    * Apply an in-memory mutation, persist it, and UNDO it when the write fails.
    *
@@ -896,6 +1396,14 @@ export function apply(ctx) {
       // dropped-entries warning from load time ("they will be removed on the
       // next save") has played out and must not keep showing.
       state.storageWarning = null
+      // The write is real, so every OTHER open panel must hear about it. The
+      // file watcher stays silent for this plugin's own writes (disk now
+      // equals memory, see onStoreFileEvent), which is correct for recovery —
+      // but a second window on the same host would otherwise sit on its stale
+      // view until someone clicks 重新载入. The initiating window receives the
+      // same frame and drops it client-side (identical content), so pushing to
+      // everyone is safe and closing the loop needs no per-client bookkeeping.
+      pushSnapshot()
       return true
     }
     logDebug('commit rolled back: the disk write failed, in-memory state restored')
@@ -905,7 +1413,9 @@ export function apply(ctx) {
     return false
   }
 
-  const saveEntry = (raw) => enqueue(async () => {
+  const saveEntry = (raw, baseRev) => enqueue(async () => {
+    if (state.versionRejected) return versionRefusal()
+    if (isStaleBaseRev(baseRev)) return conflictResponse()
     const entry = sanitizeEntry(raw)
     if (entry === null) return { ok: false, saved: false, message: '标题与指令内容不能同时为空', snapshot: snapshot() }
     entry.updatedAt = Date.now()
@@ -928,14 +1438,25 @@ export function apply(ctx) {
     return settle(note, saved)
   })
 
-  const deleteEntry = (id) => enqueue(async () => {
+  const deleteEntry = (id, baseRev) => enqueue(async () => {
+    if (state.versionRejected) return versionRefusal()
+    if (isStaleBaseRev(baseRev)) return conflictResponse()
+    // Deleting an id that is not there changes nothing, so it must not touch
+    // disk, bump rev, or push an echo frame — otherwise two panels deleting
+    // the same entry one after another would manufacture a pointless write
+    // (and an external process watching the file would wake for nothing).
+    if (!state.data.entries.some((entry) => entry.id === id)) {
+      return { ok: true, saved: false, message: null, snapshot: snapshot() }
+    }
     const saved = await commit(() => {
       state.data.entries = state.data.entries.filter((entry) => entry.id !== id)
     })
     return settle(null, saved)
   })
 
-  const setOptions = (patch) => enqueue(async () => {
+  const setOptions = (patch, baseRev) => enqueue(async () => {
+    if (state.versionRejected) return versionRefusal()
+    if (isStaleBaseRev(baseRev)) return conflictResponse()
     const saved = await commit(() => {
       if (patch !== null && typeof patch === 'object') {
         if (typeof patch.enabled === 'boolean') state.data.enabled = patch.enabled
@@ -948,14 +1469,19 @@ export function apply(ctx) {
   })
 
   const reload = () => enqueue(async () => {
-    await readFromDisk()
+    // `saved` is only true when the load itself wrote to disk (the
+    // backup-promotion or legacy-migration branch); a plain re-read claiming
+    // true would be indistinguishable from a real save on the wire.
+    const wrote = await readFromDisk()
     syncSection()
-    return { ok: state.storageError === null, saved: true, message: state.storageError, snapshot: snapshot() }
+    return { ok: state.storageError === null, saved: wrote === true, message: state.storageError, snapshot: snapshot() }
   })
 
   const exportData = () => enqueue(async () => ({
     ok: true,
-    saved: true,
+    // An export reads the store and never writes it; a truthful `saved:false`
+    // keeps the field's meaning ("this operation persisted the store") intact.
+    saved: false,
     message: null,
     // A self-describing envelope: re-importable by this plugin, and readable
     // as plain JSON by anything else.
@@ -963,7 +1489,9 @@ export function apply(ctx) {
     snapshot: snapshot(),
   }))
 
-  const importData = (payload) => enqueue(async () => {
+  const importData = (payload, baseRev) => enqueue(async () => {
+    if (state.versionRejected) return versionRefusal()
+    if (isStaleBaseRev(baseRev)) return conflictResponse()
     if (payload === null || typeof payload !== 'object') {
       return { ok: false, saved: false, message: '导入内容不是有效的 JSON 对象', snapshot: snapshot() }
     }
@@ -1037,23 +1565,31 @@ export function apply(ctx) {
         // A first run writes nothing at boot (readFromDisk step 3), so the
         // materialisation happens here, on a deliberate user action, instead of
         // as a side effect of the host merely starting up.
-        await ensureStoreMaterialized()
+        const materialized = await ensureStoreMaterialized()
         // Same envelope as every other method. One response shape means the
         // Client can never again be handed a payload it silently ignores.
-        return { ok: true, saved: true, message: null, snapshot: snapshot() }
+        // `saved` is true only on the first run, when materialisation actually
+        // wrote the file; every later read wrote nothing and says so.
+        return { ok: true, saved: materialized === true, message: null, snapshot: snapshot() }
       }
       case 'save-entry':
-        return saveEntry(args !== null && typeof args === 'object' ? args.entry : null)
+        return saveEntry(
+          args !== null && typeof args === 'object' ? args.entry : null,
+          args !== null && typeof args === 'object' ? args.baseRev : undefined)
       case 'delete-entry':
-        return deleteEntry(args !== null && typeof args === 'object' && typeof args.id === 'string' ? args.id : '')
+        return deleteEntry(
+          args !== null && typeof args === 'object' && typeof args.id === 'string' ? args.id : '',
+          args !== null && typeof args === 'object' ? args.baseRev : undefined)
       case 'set-options':
-        return setOptions(args)
+        return setOptions(args, args !== null && typeof args === 'object' ? args.baseRev : undefined)
       case 'reload':
         return reload()
       case 'export-data':
         return exportData()
       case 'import-data':
-        return importData(args !== null && typeof args === 'object' ? args.payload : null)
+        return importData(
+          args !== null && typeof args === 'object' ? args.payload : null,
+          args !== null && typeof args === 'object' ? args.baseRev : undefined)
       default:
         return { ok: false, saved: false, message: '未知方法：' + String(method), snapshot: snapshot() }
     }
@@ -1068,7 +1604,88 @@ export function apply(ctx) {
   let guardHost = true
 
   let routeDispose = null
+
+  /**
+   * The live-update stream for the settings page (GET + `Accept:
+   * text/event-stream`, i.e. exactly what an EventSource sends).
+   *
+   * Why the method/accept pair instead of a sub-path: the route is registered
+   * as a plain prefix and how the harness presents `req.url` to it is not part
+   * of any contract, while `req.method` and the Accept header are. A plain GET
+   * (someone navigating to the URL) keeps the old 405.
+   *
+   * Frames carry the bare snapshot — the same shape `state` answers with —
+   * which the Client's normalizer already accepts.
+   */
+  const handleEventStream = (req, res) => {
+    const verdict = requestOriginVerdict(req.headers, guardHost)
+    if (!verdict.ok) {
+      logInfo('route rejected a request: ' + verdict.reason)
+      res.writeHead(403, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(JSON.stringify({ ok: false, message: '请求来源被拒绝：' + verdict.reason }))
+      return
+    }
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-store',
+      connection: 'keep-alive',
+    })
+    // Ask the browser to retry politely if the stream drops (e.g. the host was
+    // restarted) instead of hammering the route.
+    res.write('retry: 5000\n\n')
+    const send = (payload) => { res.write(payload) }
+    let closed = false
+    const cleanup = () => {
+      closed = true
+      sseStreams.delete(send)
+      try {
+        res.end()
+      } catch {
+        // The response is already gone.
+      }
+    }
+    sseStreams.set(send, cleanup)
+    req.on('close', cleanup)
+    req.on('error', cleanup)
+    res.on('error', cleanup)
+    // A snapshot on connect, so a late subscriber synchronises immediately
+    // instead of waiting for the next change. It must wait for boot: a stream
+    // opened while the initial disk read is still in flight would otherwise be
+    // handed the empty boot state as its first frame, flashing "no
+    // instructions" before the loaded store arrives.
+    const sendConnectFrame = () => {
+      if (closed) return
+      try {
+        send('data: ' + JSON.stringify(snapshot()) + '\n\n')
+      } catch {
+        cleanup()
+      }
+    }
+    if (bootSettled) {
+      sendConnectFrame()
+    } else {
+      boot.then(sendConnectFrame, sendConnectFrame)
+    }
+  }
+
   const handler = (req, res) => {
+    if (req.method === 'GET') {
+      const accept = String(
+        (req.headers !== null && typeof req.headers === 'object') ? (req.headers.accept || '') : '',
+      )
+      if (accept.indexOf('text/event-stream') !== -1) {
+        // A call aborted mid-flight makes these streams emit 'error'; a server
+        // stream with no error listener would take the host process down over
+        // one dead HTTP request.
+        req.on('error', () => {})
+        res.on('error', () => {})
+        handleEventStream(req, res)
+        return
+      }
+      res.writeHead(405, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: false, message: 'only POST is supported' }))
+      return
+    }
     if (req.method !== 'POST') {
       res.writeHead(405, { 'content-type': 'application/json; charset=utf-8' })
       res.end(JSON.stringify({ ok: false, message: 'only POST is supported' }))
@@ -1149,12 +1766,16 @@ export function apply(ctx) {
       return
     }
     // The Host allowlist only makes sense when the operator bound the server to
-    // loopback. `0.0.0.0` means they deliberately published it on every
-    // interface, where no Host value can be known in advance — enforcing a
-    // loopback allowlist there would break every legitimate client, so the
-    // check is disabled and the trade-off is documented in the README.
-    const boundHost = typeof webServer.host === 'string' ? webServer.host.trim().toLowerCase() : '127.0.0.1'
-    guardHost = boundHost !== '0.0.0.0'
+    // loopback. Anything else — `0.0.0.0`/`::` (every interface) or a concrete
+    // address such as `192.168.1.5` — is a deliberate publication beyond this
+    // machine, where no Host value can be known in advance; enforcing a
+    // loopback allowlist there would 403 every legitimate client of that
+    // published deployment. (The previous check compared against `0.0.0.0`
+    // only, which silently broke `::` and concrete-address binds.) The check is
+    // disabled for all non-loopback binds and the trade-off is documented in
+    // the README.
+    const boundHost = typeof webServer.host === 'string' ? webServer.host.trim().toLowerCase() : ''
+    guardHost = boundHost === '' || isLoopbackName(boundHost)
     try {
       routeDispose = webServer.register({ kind: 'prefix', path: API_PREFIX, handler })
       logDebug('settings route registered at ' + API_PREFIX + ' (boundHost=' + boundHost + ', hostGuard=' + guardHost + ')')