dsh-instruction-memory 1.4.8 → 1.5.1

package/lib/index.js

@@ -25,7 +25,7 @@
  * user-chosen backup directory (F18).
  */
 
-import { chmod, copyFile, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
+import { chmod, copyFile, mkdir, open, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
 import { readFileSync, realpathSync, statSync, watch } from 'node:fs'
 import { randomUUID } from 'node:crypto'
 import { isIP } from 'node:net'
@@ -102,6 +102,17 @@ const MAX_HISTORY = 20
  * when it alone exceeds the budget.
  */
 const MAX_HISTORY_BYTES = 32 * 1024 * 1024
+/**
+ * The largest single snapshot this build will READ back. Every other read path
+ * is bounded (the store by MAX_BODY_CHARS, exports by their own ceilings); the
+ * restore path historically was not, so a corrupt or hostile file in the
+ * history directory could be pulled whole into memory by one click. Snapshots
+ * are serialised stores, so this sits above the store ceiling with room to
+ * spare while still refusing an absurd file.
+ */
+const MAX_HISTORY_FILE_BYTES = 8 * 1024 * 1024
+/** The feedback config is a handful of keys; anything near this is not one. */
+const MAX_FEEDBACK_CONFIG_BYTES = 1024 * 1024
 /**
  * F7: the longest single pause. Doubles as the setTimeout guard — 7 days is
  * far below the 2^31-1 ms (≈24.8 days) timer ceiling, so the delay never
@@ -288,6 +299,14 @@ export function expandDisplayPath(value, home = homedir(), platform = process.pl
  * .bak — and only the last two may never be treated as "no memory yet".
  */
 const EMPTY_STORE_CODE = 'EEMPTYSTORE'
+/**
+ * A primary that parses as JSON but is not a store at all. Same role as
+ * EMPTY_STORE_CODE, for the state JSON.parse cannot flag: the file is valid
+ * JSON, so "it read" says nothing about whether it is a store. Keeping it a
+ * distinct code is what lets the .bak rotation refuse to copy it over the last
+ * good backup while leaving the file itself untouched for hand repair.
+ */
+const NOT_A_STORE_CODE = 'ENOTASTORE'
 
 const DEFAULT_BUDGET = 4000
 const MIN_BUDGET = 800
@@ -371,8 +390,14 @@ export const LIMITS = Object.freeze({
   maxFeedbackContact: FEEDBACK_LIMITS.maxContact,
 })
 
-/** 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 crashed holder's `memory.json.lock` may block writes before it is
+ * stolen. This must exceed the worst-case hold time (tmp write + two copies +
+ * rename + a large history snapshot), so a LIVE slow holder is not mistaken for
+ * debris and swept mid-write: the reclaim path re-checks stat identity, but a
+ * wide margin is cheaper than relying on that.
+ */
+const LOCK_STALE_MS = 30_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. */
@@ -775,6 +800,40 @@ const describeValue = (value) => {
  * `dropped`: the next save persists the corrected values, so the user must be
  * told their hand edit did not survive verbatim.
  */
+/**
+ * Does this PARSED json carry a store's shape, as opposed to merely being
+ * valid JSON?
+ *
+ * The distinction is load-bearing: a file that parses but is an array, a
+ * number, or some other tool's object used to be adopted as "an empty
+ * memory" with no warning at all, so the very next save wrote that emptiness
+ * back over the user's memory and rotated the result into `.bak`. JSON.parse
+ * answering is not the same question as "is this a store", and every place
+ * that has to ask the second one now asks it here.
+ *
+ * @returns 'store' for anything adoptable, 'empty-object' for a truthy but
+ *   empty store (`{}`, or only option keys — a hand-cleared file), and
+ *   'not-object' / 'not-store' for the two states that must never be adopted.
+ */
+export function storeShapeVerdict(parsed) {
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return 'not-object'
+  // A declared, supported version is enough on its own: `{"version":2}` is a
+  // store that happens to be empty (and its formatNote says so), not a
+  // foreign file. An unsupported one is handled before this test by the
+  // version gate in normalizeData.
+  if (typeof parsed.version === 'number' && SUPPORTED_VERSIONS.includes(parsed.version)) return 'store'
+  if (Array.isArray(parsed.entries) || Array.isArray(parsed.sets)) return 'store'
+  // Every key is one the loader itself understands: `{}` and `{"rev":3}` are
+  // empty stores, not somebody else's document.
+  const OPTION_KEYS = new Set([
+    'version', 'rev', 'enabled', 'disabledUntil', 'budgetChars',
+    'backupDir', 'activeSetId', 'entries', 'sets', 'profiles',
+  ])
+  const keys = Object.keys(parsed)
+  if (keys.length === 0 || keys.every((key) => OPTION_KEYS.has(key))) return 'empty-object'
+  return 'not-store'
+}
+
 function normalizeData(raw) {
   const data = {
     version: FORMAT_VERSION,
@@ -790,8 +849,18 @@ function normalizeData(raw) {
   }
   const loaded = { data, dropped: 0, droppedProfiles: 0, droppedSets: 0, reattributed: 0, optionFixes: [], formatNote: null }
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return loaded
-  if (typeof raw.version === 'number' && !SUPPORTED_VERSIONS.includes(raw.version)) {
-    return { data, dropped: 0, droppedProfiles: 0, droppedSets: 0, reattributed: 0, optionFixes: [], rejectedVersion: raw.version }
+  // A declared version this build does not support is refused whatever its
+  // TYPE. The old test was `typeof raw.version === 'number'`, so a file
+  // carrying `"2.0"` or `"3"` read as "no version declared" and the next save
+  // rewrote it as the current format — the exact downgrade this gate exists
+  // to prevent, merely reached through a string.
+  if ('version' in raw && raw.version !== null && raw.version !== undefined) {
+    if (!(typeof raw.version === 'number' && SUPPORTED_VERSIONS.includes(raw.version))) {
+      return {
+        data, dropped: 0, droppedProfiles: 0, droppedSets: 0, reattributed: 0, optionFixes: [],
+        rejectedVersion: typeof raw.version === 'number' ? raw.version : String(raw.version),
+      }
+    }
   }
   if (typeof raw.rev === 'number' && Number.isFinite(raw.rev) && raw.rev >= 0) {
     data.rev = Math.round(raw.rev)
@@ -1443,7 +1512,6 @@ function buildProfilesBlock(profiles, budget) {
   const blocks = []
   const items = []
   let used = PERSONA_HEADER.length + 1
-  let omitted = 0
   for (const profile of active) {
     const name = typeof profile.name === 'string' && profile.name !== ''
       ? profile.name
@@ -1475,7 +1543,6 @@ function buildProfilesBlock(profiles, budget) {
       items.push({ id, name, chars: head.length + note.length, truncated: true })
       used += sep + head.length + note.length
     }
-    omitted = active.length - blocks.length
     break
   }
   const text = PERSONA_HEADER + '\n' + blocks.join('\n\n') + footerFor(Math.max(0, active.length - blocks.length))
@@ -1748,6 +1815,15 @@ export function apply(ctx) {
      */
     versionRejected: false,
     rejectedVersion: null,
+    /**
+     * Set while the file on disk parses as JSON but is not a store at all (an
+     * array, a number, another tool's object). Adopting it as "an empty
+     * memory" and then saving over it is precisely the silent-loss chain the
+     * rolling backup exists to survive, so ordinary edits are refused in this
+     * state; the repair doors (history restore, restore-from-backup, import,
+     * source mode) stay open and clear it on the first successful write.
+     */
+    shapeRejected: false,
     sectionRegistered: false,
     sectionError: null,
     /** Whether a store file is actually present on disk (diagnostics + the panel). */
@@ -2397,8 +2473,36 @@ export function apply(ctx) {
   }
   /** Where the rolling pre-write copy lives: ALWAYS next to the store (crash recovery). */
   const localBackupPath = () => storePath + BACKUP_FILE_SUFFIX
+  /**
+   * The backup directory the WRITE path may use, or '' when the configured one
+   * must be ignored.
+   *
+   * `setOptions` and `exportToDir` each check the subtree rule, but they are
+   * not the only writers: every save also drops a `.bak` and a history
+   * snapshot into this directory. A store hand-edited to point outside
+   * `$DSH_HOME` therefore escaped the fence on the very next save, which
+   * contradicted the promise that every write stays inside the harness home.
+   * The same rule now runs where the writes actually happen; the refusal is
+   * disclosed once per process instead of silently relocated.
+   */
+  let refusedBackupDir = null
+  const effectiveBackupDir = () => {
+    const configured = backupDirOf()
+    if (configured === '') return ''
+    if (allowExternalBackup() || isInsideDshRoot(configured)) return configured
+    if (refusedBackupDir !== configured) {
+      refusedBackupDir = configured
+      state.storageWarning = '备份位置 ' + displayPath(configured) + ' 不在 DSH 主目录内，已忽略（备份与历史快照一律写回默认位置）；'
+        + '要使用其他磁盘请设置 ' + ALLOW_EXTERNAL_BACKUP_ENV + '=1 后重启宿主'
+      logInfo('ignoring backupDir outside the harness home: ' + configured)
+    }
+    return ''
+  }
   /** The user-facing copy under a custom backup location, or null (F18). */
-  const customBackupPath = () => (backupDirOf() !== '' ? join(backupDirOf(), basename(storePath) + BACKUP_FILE_SUFFIX) : null)
+  const customBackupPath = () => {
+    const dir = effectiveBackupDir()
+    return dir !== '' ? join(dir, basename(storePath) + BACKUP_FILE_SUFFIX) : null
+  }
   /**
    * History snapshots live in a `history/` SUBDIRECTORY of the backup location
    * (default: the store directory). Two reasons for the subdirectory:
@@ -2409,7 +2513,10 @@ export function apply(ctx) {
    *   2. a custom (e.g. cloud-synced) backup directory stays tidy: one known
    *      folder holds the history, nothing else is touched.
    */
-  const historyDirPath = () => join(backupDirOf() !== '' ? backupDirOf() : dirname(storePath), HISTORY_DIR_NAME)
+  const historyDirPath = () => {
+    const dir = effectiveBackupDir()
+    return join(dir !== '' ? dir : dirname(storePath), HISTORY_DIR_NAME)
+  }
 
   /**
    * Cross-process write lock: a `memory.json.lock` marker created exclusively
@@ -2459,12 +2566,22 @@ export function apply(ctx) {
         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.
-          // A failed unlink must not become a tight loop, so every attempt
-          // still sleeps below.
-          await unlink(lockPath).catch(() => {})
+          // Confirm the marker we are about to delete is STILL the one we just
+          // judged stale. Between the stat above and the unlink a live holder
+          // can release it and a new owner can create a fresh marker; deleting
+          // THAT would unlock a live writer, the same TOCTOU the token closed
+          // on release. The mtime+size re-check makes the sweep ownership-safe
+          // without needing to know the dead holder's token.
+          const after = await stat(lockPath).catch(() => null)
+          if (after !== null && after.mtimeMs === info.mtimeMs && after.size === info.size
+            && Date.now() - after.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.
+            // A failed unlink must not become a tight loop, so every attempt
+            // still sleeps below.
+            await unlink(lockPath).catch(() => {})
+          }
         }
         await new Promise((resolve) => setTimeout(resolve, 50))
       }
@@ -2545,14 +2662,22 @@ export function apply(ctx) {
   let lastPersistedKey = null
 
   /**
-   * Enforce the per-device retention policy: the count and byte ceilings from
-   * planHistoryPrune(). Grouping by the device tag inside the filename is
-   * deliberate: two machines sharing one backup folder (the documented F18
-   * setup) each keep their OWN budget, so one device can never prune the
-   * other's history away. Files that do not match our naming pattern are never
-   * touched. Sizes come from stat() rather than a maintained index because the
-   * directory is shared with other processes and a stale index would prune the
-   * wrong files.
+   * Enforce the retention policy: the count and byte ceilings from
+   * planHistoryPrune(), applied PER DEVICE first. Grouping by the device tag
+   * inside the filename is deliberate: two machines sharing one backup folder
+   * (the documented F18 setup) each keep their OWN budget, so a device that
+   * saves a lot cannot prune a quiet device's history.
+   *
+   * The GLOBAL byte ceiling afterwards is the documented exception to that:
+   * per-device budgets multiply by the number of machines (ten machines = ten
+   * × 32 MB), so the folder as a whole is also bounded, and that pass deletes
+   * the oldest snapshots whichever device they came from. It is disclosed
+   * rather than hidden — the name ordering is chronological across devices
+   * because the stamp is fixed-width UTC.
+   *
+   * Files that do not match our naming pattern are never touched. Sizes come
+   * from stat() rather than a maintained index because the directory is shared
+   * with other processes and a stale index would prune the wrong files.
    */
   const pruneHistory = async (dir) => {
     const names = (await readdir(dir)).filter((name) => HISTORY_FILE_PATTERN.test(name))
@@ -2652,7 +2777,19 @@ export function apply(ctx) {
       const source = await readFile(fileURLToPath(new URL('../' + SCHEMA_FILE_NAME, import.meta.url)), 'utf8')
       const target = join(dirname(storePath), SCHEMA_FILE_NAME)
       const existing = await readFile(target, 'utf8').catch(() => null)
-      if (existing !== source) await writeFile(target, source, 'utf8')
+      if (existing !== source) {
+        // Atomic like the store itself: a crash mid-copy must not leave a
+        // truncated schema for the user's editor to validate against, and the
+        // 0600 bit matches every other file this plugin writes.
+        const tmp = target + '.tmp-' + randomUUID()
+        try {
+          await writeFile(tmp, source, { encoding: 'utf8', mode: 0o600 })
+          await rename(tmp, target)
+        } catch (err) {
+          await unlink(tmp).catch(() => {})
+          throw err
+        }
+      }
     } catch {
       // Best effort by design.
     }
@@ -2673,6 +2810,21 @@ export function apply(ctx) {
     }
   }
 
+  /**
+   * Best-effort durability fence. `rename` is atomic against a crash but NOT
+   * durable on its own: without an fsync the directory entry can reach disk
+   * after the data does, so power loss may leave the previous file or a 0-byte
+   * one even though the save reported success. A failure here is deliberately
+   * not a save failure (the bytes are already in the page cache, and Windows
+   * refuses to open directories at all), so it degrades durability only.
+   */
+  const syncPath = async (target) => {
+    try {
+      const fh = await open(target, 'r')
+      try { await fh.sync() } finally { await fh.close() }
+    } catch { /* unsupported here: durability degrades, correctness does not */ }
+  }
+
   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
@@ -2687,7 +2839,13 @@ export function apply(ctx) {
     // user's memory while their real data sat untouched in .bak. Copying keeps
     // the primary in place until the atomic replace succeeds, so a failure at
     // any step leaves the previous store readable at its own path.
-    const tmpPath = storePath + '.tmp'
+    // A UNIQUE tmp name per attempt: two processes sharing a $DSH_HOME must
+    // never interleave their writes into one temp file. The fixed
+    // `storePath + '.tmp'` meant the second writer's rename could publish a
+    // half-written mix of both serialisations. The lock narrows the window; a
+    // per-attempt name removes the shared resource, so the window cannot
+    // corrupt anything even when the lock is unavailable.
+    const tmpPath = storePath + '.tmp-' + process.pid + '-' + randomUUID()
     let lock = null
     let previousRev = null
     try {
@@ -2730,6 +2888,10 @@ export function apply(ctx) {
       const contentKey = JSON.stringify({ ...persistableData(), rev: 0 })
       if (state.storeExists && lastPersistedKey !== null && contentKey === lastPersistedKey) {
         logDebug('save skipped: the store content did not change')
+        // The caller's "上次保存" clock reports the last successful SAVE, and
+        // this call is one, even though the bytes were already correct. Leaving
+        // it untouched made the panel look stalled after a no-op save.
+        state.savedAt = Date.now()
         return true
       }
       // The rev is bumped before serialising so the file on disk and the state
@@ -2747,7 +2909,15 @@ export function apply(ctx) {
       // user profile) personal notes, so on a multi-user POSIX host it must not
       // land world-readable the way a bare writeFile (0666 & ~umask = 0644)
       // would. Windows ignores the bit and inherits the directory ACL instead.
-      await writeFile(tmpPath, text, { encoding: 'utf8', mode: 0o600 })
+      const tmpHandle = await open(tmpPath, 'w', 0o600)
+      try {
+        await tmpHandle.writeFile(text, 'utf8')
+        // Flush the temp file BEFORE the rename publishes it: otherwise a
+        // power cut can leave the new name pointing at unwritten blocks.
+        await tmpHandle.sync()
+      } finally {
+        await tmpHandle.close()
+      }
       // Both rolling copies stand for the PREVIOUS good version, so both are
       // taken before the atomic replace, and neither may ever be renamed into
       // place (see the long note above).
@@ -2762,8 +2932,22 @@ export function apply(ctx) {
       // discloses it (the .bak may be stale, and the panel says so).
       let hadPrevious = true
       try {
-        await readStoreFile(storePath)
+        const previous = await readStoreFile(storePath)
+        // "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
+        // backup: that is exactly what turns a recoverable state into a
+        // permanent one.
+        const previousShape = storeShapeVerdict(previous)
+        if (previousShape === 'not-object' || previousShape === 'not-store') {
+          const shapeError = new Error('memory.json is not a store (' + previousShape + ')')
+          shapeError.code = NOT_A_STORE_CODE
+          throw shapeError
+        }
         await copyFile(storePath, localBackupPath())
+        // The recovery copy exists to survive a crash; an unflushed copy may
+        // roll back with the very crash it is meant to answer.
+        await syncPath(localBackupPath())
         state.backupError = null
       } catch (err) {
         if (err !== null && err !== undefined && err.code === 'ENOENT') {
@@ -2772,6 +2956,12 @@ export function apply(ctx) {
           // would adopt as an "empty store" — the trap this guard exists for.
           hadPrevious = false
           state.backupError = null
+        } else if (err !== null && err !== undefined && err.code === NOT_A_STORE_CODE) {
+          hadPrevious = false
+          const previous = await stat(localBackupPath()).catch(() => null)
+          state.backupError = previous !== null && previous.size > 0
+            ? 'memory.json 的内容不是记忆存储，已保留上一版备份 ' + localBackupPath() + ' 不被覆盖'
+            : 'memory.json 的内容不是记忆存储，且没有可用的上一版备份'
         } else {
           hadPrevious = false
           const previous = await stat(localBackupPath()).catch(() => null)
@@ -2800,6 +2990,9 @@ export function apply(ctx) {
         await unlink(tmpPath).catch(() => {})
         throw err
       }
+      // Make the directory entry itself durable: without this the rename can be
+      // lost on power failure even though the file contents were flushed.
+      await syncPath(dirname(storePath))
       state.storagePath = storePath
       state.storageDisplay = storePath
       state.storageError = null
@@ -2816,6 +3009,9 @@ export function apply(ctx) {
       // committed, and the store is on disk whatever happens next.
       await writeHistorySnapshot(text, contentKey)
       lastPersistedKey = contentKey
+      // The disk holds a store again, so a "primary is not a store" refusal no
+      // longer describes reality — this is the one place that can prove it.
+      state.shapeRejected = false
       await ensureSchemaFile()
       logDebug('store written: ' + storePath + ' bytes=' + text.length
         + ' entries=' + state.data.entries.length + ' rev=' + state.data.rev
@@ -2891,6 +3087,13 @@ export function apply(ctx) {
     state.storeExists = false
     state.versionRejected = false
     state.rejectedVersion = null
+    state.shapeRejected = false
+    // A reload replaces what "the last persisted content" means. Leaving the
+    // old identity in place made a later save that happened to match the
+    // PRE-reload content skip the write while reporting saved:true, so the disk
+    // and the panel silently disagreed. Forcing the next save to write is the
+    // cheap side of that trade.
+    lastPersistedKey = null
 
     /**
      * A store declaring an unsupported format version: adopt nothing, write
@@ -2908,12 +3111,66 @@ export function apply(ctx) {
     const rejectVersion = (version, source) => {
       state.versionRejected = true
       state.rejectedVersion = version
-      state.storageError = '存储文件声明为格式版本 ' + version + '，本插件支持的格式版本为 ' + SUPPORTED_VERSIONS.join(' / ')
+      // A string that spells a supported number ("2") produced the absurd
+      // "declared version 2, supported versions 1 / 2". The TYPE is the
+      // problem, so say that instead of comparing it to the list.
+      state.storageError = (typeof version === 'number'
+        ? '存储文件声明为格式版本 ' + version + '，本插件支持的格式版本为 ' + SUPPORTED_VERSIONS.join(' / ')
+        : '存储文件的 version 字段类型不正确：必须是数字，当前是 ' + JSON.stringify(version === undefined ? null : version)
+          + '；本插件支持的格式版本为 ' + SUPPORTED_VERSIONS.join(' / '))
         + '；已拒绝载入以防数据损坏，原文件已保留，修改操作已暂停。请升级插件，或手动将文件改回受支持的版本后点「重新载入」'
       state.loadedFrom = source + ' (unsupported version ' + version + ')'
       state.storeExists = true
     }
 
+    /**
+     * The primary parses as JSON but is not a store (an array, a scalar, or
+     * another tool's object). Adopt NOTHING from it: the in-memory data — a
+     * freshly booted empty store, or whatever this process already had — stays
+     * authoritative, ordinary edits are refused, and both files stay on disk.
+     * The repair doors (history restore, restore-from-backup, import, source
+     * mode) remain open and clear the flag on the first successful write.
+     */
+    const rejectShape = (describe) => {
+      state.shapeRejected = true
+      state.storageError = 'memory.json 的内容不是本插件的记忆存储：' + describe
+        + '。已暂停写入以免覆盖原文件（原文件已保留）。请用「历史回滚」或「用备份整体替换」恢复，或修正该文件后点「重新载入」'
+      state.loadedFrom = 'memory.json (not a store; writes paused)'
+      state.storeExists = true
+    }
+
+    /**
+     * A primary that is not a store still leaves the rolling backup intact, so
+     * the last good version is usually one file away. Promote it into memory
+     * (never back onto disk here) and disclose both facts: the primary is
+     * foreign, and the panel is temporarily showing the backup.
+     */
+    const recoverFromForeignPrimary = async (shape) => {
+      state.storeExists = true
+      const describe = shape === 'not-object'
+        ? '顶层不是对象（是数组或标量）'
+        : '顶层对象里没有 entries / sets / version 等记忆字段'
+      try {
+        const backup = await readStoreFile(storePath + '.bak')
+        if (backup !== null && storeShapeVerdict(backup) === 'store') {
+          const loaded = normalizeData(backup)
+          if (loaded.rejectedVersion !== undefined) {
+            rejectVersion(loaded.rejectedVersion, 'memory.json.bak')
+            return
+          }
+          state.data = loaded.data
+          const warnings = loadWarnings(loaded)
+          state.storageWarning = (warnings !== null ? warnings + '；' : '')
+            + 'memory.json ' + describe + '，不是本插件的记忆存储（原文件已保留）；已临时回退到最近备份 memory.json.bak'
+          state.loadedFrom = 'memory.json.bak (primary is not a store)'
+          return
+        }
+      } catch {
+        // No usable backup either; refuse rather than guess.
+      }
+      rejectShape(describe)
+    }
+
     // 1. The canonical location under the harness home.
     try {
       const parsed = await readStoreFile(storePath)
@@ -2923,6 +3180,14 @@ export function apply(ctx) {
           rejectVersion(loaded.rejectedVersion, 'memory.json')
           return false
         }
+        // Parsing is not the same as being a store: an array or a foreign
+        // object used to be adopted as "empty memory" with no warning, and the
+        // next save wrote that emptiness back. Never adopt it.
+        const shape = storeShapeVerdict(parsed)
+        if (shape === 'not-object' || shape === 'not-store') {
+          await recoverFromForeignPrimary(shape)
+          return false
+        }
         state.data = loaded.data
         state.storageWarning = loadWarnings(loaded)
         state.loadedFrom = 'memory.json'
@@ -2964,7 +3229,7 @@ export function apply(ctx) {
             : 'memory.json 解析失败（' + describeErrorSafe(err) + '）'
           try {
             const backup = await readStoreFile(storePath + '.bak')
-            if (backup !== null) {
+            if (backup !== null && storeShapeVerdict(backup) === 'store') {
               const loaded = normalizeData(backup)
               if (loaded.rejectedVersion !== undefined) {
                 rejectVersion(loaded.rejectedVersion, 'memory.json.bak')
@@ -3001,7 +3266,7 @@ export function apply(ctx) {
     //     canonical path so the next boot finds it normally.
     try {
       const backup = await readStoreFile(storePath + '.bak')
-      if (backup !== null) {
+      if (backup !== null && storeShapeVerdict(backup) === 'store') {
         const loaded = normalizeData(backup)
         if (loaded.rejectedVersion !== undefined) {
           rejectVersion(loaded.rejectedVersion, 'memory.json.bak')
@@ -3026,22 +3291,29 @@ export function apply(ctx) {
     try {
       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 = 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(() => {})
+        const legacyShape = storeShapeVerdict(parsed)
+        if (legacyShape === 'not-object' || legacyShape === 'not-store') {
+          // Some other program's JSON beside the old store path is not a store
+          // to migrate, and must never become memory.json.
+          state.storageError = '旧位置文件不是本插件的记忆存储，已忽略'
+        } else {
+          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 = 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 migrated
         }
-        state.loadedFrom = 'legacy cwd file (migrated)'
-        return migrated
       }
     } catch (err) {
       // A missing or unreadable legacy file must never block a fresh store.
@@ -3243,6 +3515,13 @@ export function apply(ctx) {
          * to say which of the two situations it is looking at.
          */
         authFence: connectionGate !== null,
+        /**
+         * How many hostnames DSH_INSTRUCTION_MEMORY_TRUSTED_HOSTS widened the
+         * Host/Origin check to. The list relaxes a HOSTNAME rule; it is not an
+         * identity check, so the panel must be able to say when a widened
+         * allow-list is the only thing standing in front of a fence-less route.
+         */
+        trustedHostCount: trustedHosts.length,
       },
       /**
        * F12: load-side diagnostics that used to be log-only. `loadedFrom` says
@@ -3301,9 +3580,16 @@ export function apply(ctx) {
          * Persona section detail: rendered profiles (id/name/chars, in order)
          * and their total size. `entryChars` is the instruction half alone,
          * which is what the budget meter measures; `chars` above stays the
-         * whole section (personas + instructions) for diagnostics.
+         * whole section (personas + instructions) for diagnostics. `truncated`
+         * mirrors the entry list: a persona cut by the injection ceiling has to
+         * be DISCLOSED, or the panel shows full text the model never received.
          */
-        profiles: plan.profiles.map((item) => ({ id: item.id, name: item.name, chars: item.chars })),
+        profiles: plan.profiles.map((item) => ({
+          id: item.id,
+          name: item.name,
+          chars: item.chars,
+          truncated: item.truncated === true,
+        })),
         profileChars: plan.profileChars,
         entryChars: plan.entryChars,
         /**
@@ -3394,6 +3680,20 @@ export function apply(ctx) {
     snapshot: snapshot(),
   })
 
+  /**
+   * Refusal while memory.json parses as JSON but is not a store at all (an
+   * array, a scalar, another tool's object). Same reason as versionRefusal:
+   * a save would rewrite the file in this build's format over content this
+   * build never understood. The repair doors stay open — that is what
+   * `shapeRejected` is for, and why they deliberately skip this check.
+   */
+  const shapeRefusal = () => ({
+    ok: false,
+    saved: false,
+    message: 'memory.json 的内容不是本插件的记忆存储，修改已暂停以免覆盖原文件。请用「历史回滚」或「用备份整体替换」恢复，或修正该文件后点「重新载入」',
+    snapshot: snapshot(),
+  })
+
   /**
    * Adopt a whole parsed store — the shared core of 源码模式 (F16) and the
    * 整体替换 restore (F14). Both hand the user the SAME safety story as every
@@ -3407,17 +3707,23 @@ export function apply(ctx) {
    * before the path existed — must not silently redirect where backups go.
    */
   const adoptParsedStore = (parsed) => {
-    const looksLikeStore = parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
-      && ['version', 'rev', 'enabled', 'budgetChars', 'backupDir', 'activeSetId', 'sets', 'entries', 'profiles']
-        .some((key) => key in parsed)
-    if (!looksLikeStore) {
+    // Version first. `{"version":3}` is a FUTURE store, and the honest answer
+    // is "unsupported version", not "not a store" — an unsupported version is
+    // by definition not a shape this build recognises, so the shape test below
+    // would mislabel it.
+    const loaded = normalizeData(parsed)
+    if (loaded.rejectedVersion !== undefined) return { rejectedVersion: loaded.rejectedVersion }
+    // Then shape, with the loader's own verdict rather than a looser one. A
+    // file carrying a single stray option key (`{"version":2}`,
+    // `{"enabled":false}`) is NOT a store to adopt wholesale: on the
+    // import/restore path that would replace real memory with near-nothing and
+    // report saved:true.
+    if (storeShapeVerdict(parsed) !== 'store') {
       return {
-        error: '内容不像本插件的存储文件：顶层需要是对象，且至少包含 entries / profiles / sets / version 之一。'
+        error: '内容不像本插件的存储文件：顶层需要是对象，且必须包含 entries / sets 数组（或受支持的 version）。'
           + '若要清空记忆，请使用界面上的删除操作，而不是保存一个空对象',
       }
     }
-    const loaded = normalizeData(parsed)
-    if (loaded.rejectedVersion !== undefined) return { rejectedVersion: loaded.rejectedVersion }
     loaded.data.backupDir = backupDirOf()
     return { loaded }
   }
@@ -3489,6 +3795,7 @@ export function apply(ctx) {
 
   const saveEntry = (raw, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     const entry = sanitizeEntry(raw)
     if (entry === null) return { ok: false, saved: false, message: '标题与指令内容不能同时为空', snapshot: snapshot() }
@@ -3540,6 +3847,7 @@ export function apply(ctx) {
 
   const deleteEntry = (id, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     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
@@ -3562,6 +3870,7 @@ export function apply(ctx) {
 
   const setOptions = (patch, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     // The custom backup location (F18) is validated BEFORE anything is queued
     // into the store: an unusable path must be refused with a reason, not
@@ -3587,7 +3896,7 @@ export function apply(ctx) {
           return {
             ok: false,
             saved: false,
-            message: '备份位置必须位于 DSH 主目录内（' + dshRootPath() + '）；要使用其他磁盘请设置环境变量 '
+            message: '备份位置必须位于 DSH 主目录内（' + displayPath(dshRootPath()) + '）；要使用其他磁盘请设置环境变量 '
               + ALLOW_EXTERNAL_BACKUP_ENV + '=1 后重启宿主',
             snapshot: snapshot(),
           }
@@ -3711,6 +4020,7 @@ export function apply(ctx) {
    */
   const batchEntries = (op, ids, value, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     if (typeof op !== 'string' || !BATCH_OPS.includes(op)) {
       return { ok: false, saved: false, message: '未知的批量操作：' + String(op), snapshot: snapshot() }
@@ -3818,6 +4128,7 @@ export function apply(ctx) {
 
   const saveProfile = (raw, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     const profile = sanitizeProfile(raw)
     if (profile === null) return { ok: false, saved: false, message: '形象名称与内容不能同时为空', snapshot: snapshot() }
@@ -3848,6 +4159,7 @@ export function apply(ctx) {
 
   const deleteProfile = (id, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     // Mirror deleteEntry: an absent id changes nothing and must not touch disk,
     // and an id belonging to a different set is not this panel's to delete.
@@ -3875,6 +4187,7 @@ export function apply(ctx) {
    */
   const saveSet = (raw, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     const wanted = sanitizeSet(raw)
     if (wanted === null) {
@@ -3915,6 +4228,7 @@ export function apply(ctx) {
    */
   const deleteSet = (id, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     const index = state.data.sets.findIndex((set) => set.id === id)
     if (index < 0) {
@@ -3943,6 +4257,7 @@ export function apply(ctx) {
    */
   const setActiveSet = (id, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     const target = state.data.sets.find((set) => set.id === id)
     if (target === undefined) {
@@ -3964,6 +4279,7 @@ export function apply(ctx) {
    */
   const duplicateSet = (id, name, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    if (state.shapeRejected) return shapeRefusal()
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     const source = state.data.sets.find((set) => set.id === id)
     if (source === undefined) {
@@ -4093,13 +4409,28 @@ export function apply(ctx) {
    */
   const historyRestore = (name, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    // Deliberately NOT gated on shapeRejected: restoring a snapshot is the
+    // repair door for a primary that is not a store.
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     if (typeof name !== 'string' || !HISTORY_FILE_PATTERN.test(name)) {
       return { ok: false, saved: false, message: '历史快照名称无效', snapshot: snapshot() }
     }
     let parsed = null
+    const snapshotPath = join(historyDirPath(), name)
     try {
-      parsed = JSON.parse(await readFile(join(historyDirPath(), name), 'utf8'))
+      // Bounded read: stat first, so an absurd file in a shared backup folder
+      // (or a corrupted one) is refused instead of pulled into memory whole.
+      const info = await stat(snapshotPath)
+      if (!info.isFile()) throw new Error('不是普通文件')
+      if (info.size > MAX_HISTORY_FILE_BYTES) {
+        return {
+          ok: false,
+          saved: false,
+          message: '该历史快照过大（' + info.size + ' 字节，上限 ' + MAX_HISTORY_FILE_BYTES + ' 字节），已拒绝读取',
+          snapshot: snapshot(),
+        }
+      }
+      parsed = JSON.parse(await readFile(snapshotPath, 'utf8'))
     } catch (err) {
       return { ok: false, saved: false, message: '无法读取该历史快照：' + describeErrorSafe(err), snapshot: snapshot() }
     }
@@ -4199,7 +4530,7 @@ export function apply(ctx) {
       return {
         ok: false,
         saved: false,
-        message: '导出目录必须位于 DSH 主目录内（' + dshRootPath() + '）；要写入其他磁盘请设置环境变量 '
+        message: '导出目录必须位于 DSH 主目录内（' + displayPath(dshRootPath()) + '）；要写入其他磁盘请设置环境变量 '
           + ALLOW_EXTERNAL_BACKUP_ENV + '=1 后重启宿主',
         snapshot: snapshot(),
       }
@@ -4294,6 +4625,8 @@ export function apply(ctx) {
 
   const writeSource = (text, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    // Deliberately NOT gated on shapeRejected: hand-editing the source is how
+    // a user repairs a primary that is not a store.
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     if (typeof text !== 'string') {
       return { ok: false, saved: false, message: '源码必须是 JSON 文本', snapshot: snapshot() }
@@ -4324,6 +4657,8 @@ export function apply(ctx) {
    */
   const restoreData = (payload, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    // Deliberately NOT gated on shapeRejected: wholesale replacement from a
+    // backup is the repair door for a primary that is not a store.
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     if (payload === null || typeof payload !== 'object') {
       return { ok: false, saved: false, message: '恢复内容不是有效的 JSON 对象', snapshot: snapshot() }
@@ -4337,6 +4672,8 @@ export function apply(ctx) {
 
   const importData = (payload, baseRev) => enqueue(async () => {
     if (state.versionRejected) return versionRefusal()
+    // Deliberately NOT gated on shapeRejected: importing a real store is a
+    // repair path for a primary that is not one.
     if (isStaleBaseRev(baseRev)) return conflictResponse()
     if (payload === null || typeof payload !== 'object') {
       return { ok: false, saved: false, message: '导入内容不是有效的 JSON 对象', snapshot: snapshot() }
@@ -4624,6 +4961,14 @@ export function apply(ctx) {
   const readFeedbackConfigFile = async (path) => {
     let text
     try {
+      // Bounded read: this file is operator-authored, but a wrong path (a log,
+      // a database) must not be dragged into memory just because the send
+      // button was pressed.
+      const info = await stat(path)
+      if (!info.isFile()) throw new Error('不是普通文件')
+      if (info.size > MAX_FEEDBACK_CONFIG_BYTES) {
+        throw new Error('文件过大（' + info.size + ' 字节，上限 ' + MAX_FEEDBACK_CONFIG_BYTES + ' 字节）')
+      }
       text = await readFile(path, 'utf8')
     } catch (err) {
       if (err !== null && typeof err === 'object' && err.code === 'ENOENT') return null
@@ -5005,9 +5350,16 @@ export function apply(ctx) {
         logInfo('connection fence threw, refusing the request: ' + describeError(err))
         rejection = 401
       }
-      if (typeof rejection === 'number' && rejection >= 400) {
-        logInfo('route refused an unauthenticated request (' + rejection + ')')
-        res.writeHead(rejection, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+      // Only the documented "admit" values pass. Anything else — a future
+      // `{status:401}`, an Error, a string — is treated as a refusal, because
+      // an authentication gate that silently opens on an unexpected shape is
+      // not a gate. The numeric status is preserved when it is plausible.
+      const admitted = rejection === undefined || rejection === null || rejection === false
+      if (!admitted) {
+        const status = typeof rejection === 'number' && rejection >= 400 && rejection <= 599 ? rejection : 401
+        logInfo('route refused a request (' + status + ', fence returned '
+          + (typeof rejection === 'number' ? rejection : typeof rejection) + ')')
+        res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
         res.end(JSON.stringify({
           ok: false,
           message: rejection === 403