dsh-instruction-memory 1.4.7 → 1.5.0

package/lib/index.js

@@ -25,12 +25,12 @@
  * user-chosen backup directory (F18).
  */
 
-import { copyFile, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
-import { readFileSync, watch } from 'node:fs'
+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'
 import { homedir, hostname } from 'node:os'
-import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import {
   FEEDBACK_ENV,
@@ -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
@@ -148,6 +159,35 @@ const BACKUP_FILE_SUFFIX = '.bak'
  */
 const SECTION_ORDER = 950
 const API_PREFIX = '/instruction-memory/api'
+/**
+ * Extra hostnames this route accepts, comma separated (F19).
+ *
+ * A loopback bind normally only answers to `127.0.0.1`/`localhost`, which is
+ * what makes the DNS-rebinding guard meaningful — but it also made the route
+ * unusable behind a reverse proxy that forwards the public `Host` (nginx's
+ * default `proxy_set_header Host $host`). Listing the published hostname here
+ * re-opens exactly that one name and nothing else: the loopback rule still
+ * applies to everything else, and `Origin`/`Sec-Fetch-Site` are still enforced.
+ */
+const TRUSTED_HOSTS_ENV = 'DSH_INSTRUCTION_MEMORY_TRUSTED_HOSTS'
+/**
+ * Escape hatch for F18 backups outside `$DSH_HOME` (F19). The default refuses
+ * them: an unauthenticated route that can create directories anywhere the host
+ * process can write is a disk-fill primitive. Setting this to `1` restores the
+ * old permissive behaviour for operators who really keep backups on another
+ * volume.
+ */
+const ALLOW_EXTERNAL_BACKUP_ENV = 'DSH_INSTRUCTION_MEMORY_ALLOW_EXTERNAL_BACKUP'
+/**
+ * How often the store file is stat-ed as a fallback for `fs.watch` (F19).
+ *
+ * Inotify/FSEvents/ReadDirectoryChangesW are reliable on a native filesystem
+ * and silently dead on DrvFs (`/mnt/c`, `/mnt/d`), SMB and some container
+ * overlays — there the watcher installs without error and then never fires, so
+ * an external edit to memory.json was simply invisible until a restart. A
+ * 5 s stat of one path costs nothing and turns that silence into a reload.
+ */
+const WATCH_POLL_MS = 5000
 /**
  * Feedback mail: the optional config file next to the store. Kept OUT of
  * the repository on purpose — the operator's SMTP credentials must never be
@@ -175,13 +215,19 @@ const PLUGIN_VERSION = (() => {
 })()
 
 /**
- * Resolve this plugin's data file under the harness home.
+ * The harness home: the directory this plugin's data lives under.
  *
  * Precedence mirrors `@deepseek-ai/dsh-home-paths`: an explicit `$DSH_HOME`,
  * then `~/.dsh`. A blank override counts as unset and must never resolve to the
  * current working directory. Exported so tests can pin it.
+ *
+ * Resolved here rather than derived from the store path. `dirname(dirname(
+ * storePath))` happens to equal this today, but it is a guess about the layout:
+ * one extra directory level (or a store moved up a level) would quietly widen
+ * the "may I write outside the harness home" fence to the harness home's
+ * PARENT. A guard that guesses its own root is not a guard.
  */
-export function resolveStorePath(env = process.env, home = homedir()) {
+export function resolveDshRoot(env = process.env, home = homedir()) {
   const configured = typeof env.DSH_HOME === 'string' ? env.DSH_HOME.trim() : ''
   // A relative override (`DSH_HOME=./data`) is resolved ONCE against the
   // process cwd. Without this the store path stayed relative for the whole
@@ -190,8 +236,12 @@ export function resolveStorePath(env = process.env, home = homedir()) {
   // how the path was spelled. Resolving does not make a relative override
   // cwd-independent — it cannot be — but it pins one absolute location for
   // this process and keeps every displayed path absolute.
-  const root = configured !== '' ? resolve(configured) : join(home, '.dsh')
-  return join(root, STORE_DIR_NAME, STORE_FILE_NAME)
+  return configured !== '' ? resolve(configured) : join(home, '.dsh')
+}
+
+/** Resolve this plugin's data file under the harness home. */
+export function resolveStorePath(env = process.env, home = homedir()) {
+  return join(resolveDshRoot(env, home), STORE_DIR_NAME, STORE_FILE_NAME)
 }
 
 /**
@@ -249,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
@@ -332,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. */
@@ -736,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,
@@ -751,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)
@@ -1163,7 +1271,51 @@ export function isWildcardBindHost(value) {
  * `Host: attacker.example` plus `Origin: attacker.example`. Wildcard binds keep
  * the old comparison, because the address the client used is unknowable then.
  */
-export function requestOriginVerdict(headers, guarded, expectedHostname = '') {
+/**
+ * Parse the trusted-host list into canonical hostnames.
+ *
+ * Accepts what an operator actually types: a bare `app.example`, a full
+ * origin (`https://app.example:8443`), bracketed IPv6, comma or whitespace
+ * separated. Everything is folded to the same lowercase, bracket-free,
+ * port-free form `hostnameOf()`/`normalizeHostname()` produce, so a trusted
+ * entry compares equal to a parsed `Host` or `Origin` without further work.
+ *
+ * @param {string|string[]} value raw environment value or an array.
+ * @returns {string[]} canonical hostnames, deduplicated, order preserved.
+ */
+export function normalizeTrustedHosts(value) {
+  const raw = Array.isArray(value) ? value.join(',') : typeof value === 'string' ? value : ''
+  const out = []
+  for (const piece of raw.split(',')) {
+    let text = piece.trim()
+    if (text === '') continue
+    // A full origin is common in copy-pasted docs; keep only its host.
+    const scheme = text.indexOf('://')
+    if (scheme !== -1) {
+      try {
+        text = new URL(text).hostname
+      } catch {
+        text = text.slice(scheme + 3)
+      }
+    }
+    text = text.replace(/^\/+/, '')
+    const slash = text.indexOf('/')
+    if (slash !== -1) text = text.slice(0, slash)
+    // hostnameOf() already drops a port and the IPv6 brackets.
+    const name = hostnameOf(text)
+    if (name === '') continue
+    if (!out.includes(name)) out.push(name)
+  }
+  return out
+}
+
+/** Is this canonical hostname one the operator explicitly trusted? */
+function isTrustedHostName(name, trusted) {
+  return name !== '' && Array.isArray(trusted) && trusted.includes(name)
+}
+
+export function requestOriginVerdict(headers, guarded, expectedHostname = '', trustedHosts = []) {
+  const trusted = Array.isArray(trustedHosts) ? trustedHosts : []
   const read = (name) => {
     if (headers === null || typeof headers !== 'object') return ''
     const value = headers[name]
@@ -1172,7 +1324,7 @@ export function requestOriginVerdict(headers, guarded, expectedHostname = '') {
   const requestHost = read('host').trim().toLowerCase()
   const requestHostname = hostnameOf(requestHost)
 
-  if (guarded && !isLoopbackName(requestHostname)) {
+  if (guarded && !isLoopbackName(requestHostname) && !isTrustedHostName(requestHostname, trusted)) {
     return { ok: false, reason: 'Host 头不是回环地址（可能是 DNS 重绑定攻击）：' + (requestHost === '' ? '(缺失)' : requestHost) }
   }
 
@@ -1213,7 +1365,7 @@ export function requestOriginVerdict(headers, guarded, expectedHostname = '') {
     // is what keeps those spellings working (the mapped/hex forms canonicalise).
     const expected = !guarded && typeof expectedHostname === 'string' ? expectedHostname : ''
     const authority = expected !== '' ? expected : requestHostname
-    if (originHostname === '' || !sameHostname(originHostname, authority)) {
+    if (originHostname === '' || (!sameHostname(originHostname, authority) && !isTrustedHostName(originHostname, trusted))) {
       return {
         ok: false,
         reason: expected !== ''
@@ -1360,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
@@ -1392,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))
@@ -1665,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). */
@@ -1688,6 +1847,13 @@ export function apply(ctx) {
    * temporal-dead-zone hazard (F12 publishes it as `security.hostGuarded`).
    */
   let guardHost = true
+  /**
+   * F19: hostnames the operator explicitly allowed (see TRUSTED_HOSTS_ENV).
+   * Read once at mount from the environment; a restart is required to change it,
+   * which keeps the allowlist out of the settings page (a route that can widen
+   * its own trust boundary is not a boundary).
+   */
+  const trustedHosts = normalizeTrustedHosts(process.env[TRUSTED_HOSTS_ENV])
   /**
    * The authority a browser had to use to reach this route, when the bind
    * address is concrete (`192.168.1.5`, `[::1]`). Empty for a wildcard/unknown
@@ -1747,6 +1913,13 @@ export function apply(ctx) {
     let text = describeError(err)
     const storeDir = dirname(storePath)
     if (storeDir !== '' && storeDir !== '.') text = text.split(storeDir).join('<记忆目录>')
+    // F19: a custom backup location is just as revealing (it is usually a
+    // cloud-sync path with an account name in it) and used to survive the fold
+    // whenever it was not under the home directory.
+    const configuredBackup = typeof state.data.backupDir === 'string' ? state.data.backupDir.trim() : ''
+    if (configuredBackup !== '' && configuredBackup !== storeDir) {
+      text = text.split(configuredBackup).join('<备份目录>')
+    }
     try {
       const home = homedir()
       // Same token as `displayPath` so a folded path looks identical wherever
@@ -1802,6 +1975,41 @@ export function apply(ctx) {
     else console.error('[instruction-memory] ' + message)
   }
 
+  /**
+   * Create (or repair) a directory this plugin owns and make sure it is 0700.
+   *
+   * `mkdir(..., {mode: 0o700})` only sets the mode on a directory it actually
+   * creates: a store first written by 1.4.7 stays 0755 forever, because every
+   * later start just resolves the path that already exists. The snapshots in
+   * `history/` were therefore still listable by other local users after the
+   * mode fix shipped, which the review called out as a real (if minor) gap.
+   * The chmod is deliberately best effort: a directory owned by someone else,
+   * or a filesystem without POSIX modes (Windows, some network mounts), must
+   * not turn a save or a boot into a failure.
+   */
+  const repairDirMode = async (dir) => {
+    if (process.platform === 'win32') return
+    try {
+      const info = await stat(dir)
+      if ((info.mode & 0o777) === 0o700) return
+      await chmod(dir, 0o700)
+      logInfo('tightened ' + displayPath(dir) + ' to 0700 (was ' + (info.mode & 0o777).toString(8) + ')')
+    } catch {
+      // Not our directory, or no POSIX modes here: the write itself matters more.
+    }
+  }
+
+  /**
+   * Create the directory if needed and make sure it ends up 0700. Boot-time
+   * repair deliberately uses `repairDirMode` alone: a first run must not create
+   * the store directory just to look at it (pinned by the "booting does not
+   * even create the store directory" contract).
+   */
+  const hardenDir = async (dir) => {
+    await mkdir(dir, { recursive: true, mode: 0o700 })
+    await repairDirMode(dir)
+  }
+
   const logDebug = (message) => {
     if (logger !== null) {
       if (typeof logger.debug === 'function') logger.debug(message)
@@ -1849,7 +2057,14 @@ export function apply(ctx) {
    */
   const assembledSectionText = () => {
     sectionPulls += 1
-    logDebug('section pulled into a prompt (pull #' + sectionPulls + ')')
+    // The host calls this while assembling the prompt and does NOT wrap it in
+    // try/catch, so a throwing logger would abort the whole turn. Counting the
+    // pull is diagnostics; it must never be the reason a prompt fails.
+    try {
+      logDebug('section pulled into a prompt (pull #' + sectionPulls + ')')
+    } catch {
+      // Diagnostics only.
+    }
     return sectionText()
   }
 
@@ -1889,6 +2104,29 @@ export function apply(ctx) {
    * when something must be injected, absent otherwise. An empty memory must
    * leave the prompt byte-identical to a deployment without this plugin.
    */
+  /**
+   * Where the host wants this section to sit, asked of the host itself.
+   *
+   * `950` is the documented gap between FILE_REFERENCE (900) and TOOL_BASH
+   * (1000) in `dsh-system-prompt`'s central `SECTION_ORDERS` table. Hardcoding
+   * it works until that table grows an entry at 950 — then the placement is a
+   * silent tie, decided by dictionary order, and nothing reports it. The
+   * service exposes `getSectionOrder(name)`, so take the midpoint of the two
+   * neighbours we actually anchor against and fall back to 950 if the method
+   * is gone or answers something unusable.
+   */
+  const resolveSectionOrder = () => {
+    try {
+      if (systemPrompt === null || typeof systemPrompt.getSectionOrder !== 'function') return SECTION_ORDER
+      const lo = systemPrompt.getSectionOrder('FILE_REFERENCE')
+      const hi = systemPrompt.getSectionOrder('TOOL_BASH')
+      if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi <= lo) return SECTION_ORDER
+      return lo + (hi - lo) / 2
+    } catch {
+      return SECTION_ORDER
+    }
+  }
+
   const syncSection = () => {
     if (disposed) return
     const wanted = sectionText() !== ''
@@ -1902,15 +2140,16 @@ export function apply(ctx) {
         // template or any `{{…}}` pair — so the default would abort the whole
         // agent turn at renderPrompt(). This section is literal text and never
         // references a host variable, so opt out explicitly.
+        const order = resolveSectionOrder()
         sectionDispose = systemPrompt.section({
           name: SECTION_NAME,
-          order: SECTION_ORDER,
+          order,
           text: assembledSectionText,
           interpolate: false,
         })
         state.sectionRegistered = true
         state.sectionError = null
-        logDebug('prompt section registered: order=' + SECTION_ORDER + ' chars=' + sectionText().length)
+        logDebug('prompt section registered: order=' + order + ' chars=' + sectionText().length)
       } catch (err) {
         sectionDispose = null
         state.sectionRegistered = false
@@ -1968,6 +2207,13 @@ export function apply(ctx) {
   const sseStreams = new Map()
   let storeWatcher = null
   let watchDebounce = null
+  /**
+   * Fallback poller for filesystems where `fs.watch` installs but never fires
+   * (DrvFs `/mnt/*`, SMB/NFS, some overlays). Null when not running.
+   */
+  let storePoll = null
+  /** Last `size:mtime:ino` signature the poller saw, so it only reacts to a change. */
+  let storeSignature = ''
 
   const pushSnapshot = () => {
     if (disposed || sseStreams.size === 0) return
@@ -2042,11 +2288,51 @@ export function apply(ctx) {
     }, WATCH_DEBOUNCE_MS)
   }
 
+  /** The stat signature a poller compares, or '' when the file is absent. */
+  const currentStoreSignature = () => {
+    try {
+      const info = statSync(storePath)
+      return String(info.size) + ':' + String(info.mtimeMs) + ':' + String(info.ino)
+    } catch {
+      return ''
+    }
+  }
+
+  /**
+   * Start the fallback poller (idempotent).
+   *
+   * It is ALWAYS started alongside the watcher, not only after a failure: an
+   * `fs.watch` that never fires cannot be distinguished from a quiet store, so
+   * there is no event to trigger a downgrade. On a native filesystem the poller
+   * finds the same signature the watcher just acted on and does nothing —
+   * `onStoreFileEvent` already drops no-op reloads by comparing content.
+   */
+  const startPolling = () => {
+    if (disposed || storePoll !== null) return
+    storeSignature = currentStoreSignature()
+    storePoll = setInterval(() => {
+      if (disposed) return
+      const signature = currentStoreSignature()
+      if (signature === storeSignature) return
+      storeSignature = signature
+      // A vanished file is not an edit; the next save recreates it.
+      if (signature === '') return
+      onStoreFileEvent()
+    }, WATCH_POLL_MS)
+    // A background timer must never be a reason for the host process to stay
+    // alive after the plugin is unmounted.
+    if (typeof storePoll.unref === 'function') storePoll.unref()
+  }
+
   const stopWatching = () => {
     if (watchDebounce !== null) {
       clearTimeout(watchDebounce)
       watchDebounce = null
     }
+    if (storePoll !== null) {
+      clearInterval(storePoll)
+      storePoll = null
+    }
     if (storeWatcher !== null) {
       const watcher = storeWatcher
       storeWatcher = null
@@ -2075,10 +2361,20 @@ export function apply(ctx) {
         if (typeof filename === 'string' && filename !== basename(storePath)) return
         onStoreFileEvent()
       })
-      storeWatcher.on('error', () => stopWatching())
+      storeWatcher.on('error', (err) => {
+        // Losing the OS watcher is survivable (the poller below still notices
+        // 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()
+      })
     } catch {
       storeWatcher = null
     }
+    // Started whether or not the watcher attached: on a filesystem where the
+    // watch handle exists but never fires this is the ONLY reload signal, and
+    // on a healthy one it is a cheap no-op.
+    startPolling()
   }
 
   const disposeStreams = () => {
@@ -2117,6 +2413,64 @@ export function apply(ctx) {
   /* ---------------- backup location + history snapshots (F14 / F18) ---------------- */
 
   const backupDirOf = () => (typeof state.data.backupDir === 'string' ? state.data.backupDir : '')
+  /** The harness home this plugin's data lives under (`$DSH_HOME` or `~/.dsh`). */
+  const dshRootPath = () => resolveDshRoot()
+  /**
+   * F19: are we allowed to write outside `$DSH_HOME`?
+   *
+   * The settings route can be reached without a login on profiles with no
+   * `connection` service, and `backupDir` used to accept ANY absolute path (it
+   * was probe-written on set and then created on every save). That is a
+   * disk-fill primitive, so the default is now "inside the harness home only";
+   * an operator who really keeps backups on another volume opts in explicitly.
+   */
+  const allowExternalBackup = () => {
+    const raw = process.env[ALLOW_EXTERNAL_BACKUP_ENV]
+    return typeof raw === 'string' && raw.trim() === '1'
+  }
+  /** `path`'s real location, or null when it (or a parent) is unavailable. */
+  const realPathOrNull = (path) => {
+    try {
+      return realpathSync(path)
+    } catch {
+      return null
+    }
+  }
+  /** Is `inner` the same as `root` or below it? */
+  const containsPath = (root, inner) => {
+    const rel = relative(root, inner)
+    return rel === '' || (!rel.startsWith('..' + sep) && rel !== '..' && !isAbsolute(rel))
+  }
+  /**
+   * Is `target` inside `$DSH_HOME` (equal to it counts)?
+   *
+   * Spelling alone is not containment. A junction or symlink INSIDE the
+   * harness home can point anywhere — on Windows a junction needs no privilege
+   * at all — so the lexical check answers "does this text start with the root"
+   * while the write lands in another volume. Both ends are therefore compared
+   * by real path; a target that does not exist yet is judged by the real path
+   * of its deepest existing ancestor plus the part still to be created.
+   */
+  const isInsideDshRoot = (target) => {
+    if (typeof target !== 'string' || target === '') return false
+    const root = dshRootPath()
+    const absolute = resolve(target)
+    if (!containsPath(root, absolute)) return false
+    const realRoot = realPathOrNull(root)
+    if (realRoot === null) return true
+    let existing = absolute
+    for (let depth = 0; depth < 64; depth += 1) {
+      const realExisting = realPathOrNull(existing)
+      if (realExisting !== null) {
+        const rest = absolute.slice(existing.length)
+        return containsPath(realRoot, rest === '' ? realExisting : join(realExisting, rest))
+      }
+      const parent = dirname(existing)
+      if (parent === existing) return false
+      existing = parent
+    }
+    return false
+  }
   /** Where the rolling pre-write copy lives: ALWAYS next to the store (crash recovery). */
   const localBackupPath = () => storePath + BACKUP_FILE_SUFFIX
   /** The user-facing copy under a custom backup location, or null (F18). */
@@ -2181,12 +2535,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))
       }
@@ -2267,14 +2631,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))
@@ -2339,7 +2711,7 @@ export function apply(ctx) {
     if (typeof text !== 'string' || text === '' || identity === lastHistoryKey) return
     try {
       const dir = historyDirPath()
-      await mkdir(dir, { recursive: true })
+      await hardenDir(dir)
       const epoch = Date.now()
       let written = false
       // `wx` never overwrites: same-millisecond saves (two rapid bulk actions)
@@ -2374,7 +2746,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.
     }
@@ -2395,6 +2779,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
@@ -2409,11 +2808,17 @@ 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 {
-      await mkdir(dirname(storePath), { recursive: true })
+      await hardenDir(dirname(storePath))
       lock = await acquireStoreLock()
       if (lock === null) {
         // The lock could not be taken within the wait. That is either a stale
@@ -2452,6 +2857,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
@@ -2469,7 +2878,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).
@@ -2484,8 +2901,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') {
@@ -2494,6 +2925,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)
@@ -2522,6 +2959,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
@@ -2538,6 +2978,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
@@ -2613,6 +3056,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
@@ -2636,6 +3086,54 @@ export function apply(ctx) {
       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)
@@ -2645,6 +3143,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'
@@ -2686,7 +3192,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')
@@ -2723,7 +3229,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')
@@ -2748,22 +3254,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.
@@ -2845,6 +3358,11 @@ export function apply(ctx) {
     })
     .then(async () => {
       bootSettled = true
+      // Upgrade path: directories created by an older version keep their old
+      // mode because `mkdir` never re-applies it to an existing path. Repair
+      // them on every start; a failure here is a warning, never a boot error.
+      await repairDirMode(dirname(storePath))
+      await repairDirMode(historyDirPath())
       syncSection()
       await refreshHistoryCount()
       // The one always-on line: it answers "is memory mounted, where does it
@@ -2932,6 +3450,14 @@ export function apply(ctx) {
           profiles: state.data.profiles.filter((profile) => belongsTo(profile, set.id)).length,
         })),
       },
+      /**
+       * The running plugin version. The panel renders it in the mount-failure
+       * notice, which is the one place a user reads a number off the screen
+       * when the settings page never appears — reading it from the store would
+       * be wrong (the store survives upgrades) and the client cannot import
+       * package.json.
+       */
+      pluginVersion: PLUGIN_VERSION,
       /**
        * F12: the one security signal the panel was missing. `hostGuarded` is
        * the SAME flag the route enforces on every request — false means the
@@ -2943,6 +3469,15 @@ export function apply(ctx) {
       security: {
         hostGuarded: guardHost === true,
         boundHost: state.boundHost,
+        /**
+         * F19 follow-up: whether the harness authentication fence is attached
+         * RIGHT NOW. `hostGuarded === false` on its own reads as "no
+         * authentication at all", which is only true when this is false too:
+         * with the fence attached the route still requires a logged-in browser
+         * session (`connection.requestRejection`), and the panel must be able
+         * to say which of the two situations it is looking at.
+         */
+        authFence: connectionGate !== null,
       },
       /**
        * F12: load-side diagnostics that used to be log-only. `loadedFrom` says
@@ -3001,9 +3536,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,
         /**
@@ -3094,6 +3636,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
@@ -3107,17 +3663,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 }
   }
@@ -3189,6 +3751,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() }
@@ -3240,6 +3803,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
@@ -3262,6 +3826,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
@@ -3280,6 +3845,18 @@ export function apply(ctx) {
             snapshot: snapshot(),
           }
         }
+        // F19: an unauthenticated caller must not be able to create
+        // directories outside the harness home. Checked BEFORE the probe, so a
+        // refused path is never touched at all.
+        if (!allowExternalBackup() && !isInsideDshRoot(wanted)) {
+          return {
+            ok: false,
+            saved: false,
+            message: '备份位置必须位于 DSH 主目录内（' + dshRootPath() + '）；要使用其他磁盘请设置环境变量 '
+              + ALLOW_EXTERNAL_BACKUP_ENV + '=1 后重启宿主',
+            snapshot: snapshot(),
+          }
+        }
         const problem = await probeBackupDir(wanted)
         if (problem !== null) {
           return { ok: false, saved: false, message: '备份位置不可用（' + problem + '）：' + wanted, snapshot: snapshot() }
@@ -3399,6 +3976,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() }
@@ -3506,6 +4084,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() }
@@ -3536,6 +4115,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.
@@ -3563,6 +4143,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) {
@@ -3603,6 +4184,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) {
@@ -3631,6 +4213,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) {
@@ -3652,6 +4235,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) {
@@ -3781,13 +4365,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() }
     }
@@ -3868,6 +4467,11 @@ export function apply(ctx) {
     snapshot: snapshot(),
   }))
 
+  /** F19: timestamp of the last export-to-dir, for the frequency guard. */
+  let lastExportAt = 0
+  /** F19: minimum spacing between export-to-dir writes. */
+  const EXPORT_COOLDOWN_MS = 2000
+
   /**
    * Write an export straight into the backup directory (F18) — the "land the
    * backup in my cloud-synced folder" button. The default directory is the
@@ -3875,9 +4479,34 @@ export function apply(ctx) {
    */
   const exportToDir = () => enqueue(async () => {
     const dir = backupDirOf() !== '' ? backupDirOf() : dirname(storePath)
-    const target = join(dir, exportFileName(Date.now()))
+    // F19: the same subtree rule the setting enforces, re-checked at write
+    // time — a store hand-edited to point elsewhere must not become a way to
+    // create arbitrary directories through this route either.
+    if (!allowExternalBackup() && !isInsideDshRoot(dir)) {
+      return {
+        ok: false,
+        saved: false,
+        message: '导出目录必须位于 DSH 主目录内（' + dshRootPath() + '）；要写入其他磁盘请设置环境变量 '
+          + ALLOW_EXTERNAL_BACKUP_ENV + '=1 后重启宿主',
+        snapshot: snapshot(),
+      }
+    }
+    // Each export writes a fixed-name JSON file of the whole store. Refusing a
+    // second export inside the cooldown keeps a script from using the button
+    // as a disk-fill loop.
+    const now = Date.now()
+    if (now - lastExportAt < EXPORT_COOLDOWN_MS) {
+      return {
+        ok: false,
+        saved: false,
+        message: '导出过于频繁，请 ' + Math.ceil((EXPORT_COOLDOWN_MS - (now - lastExportAt)) / 1000) + ' 秒后重试',
+        snapshot: snapshot(),
+      }
+    }
+    lastExportAt = now
+    const target = join(dir, exportFileName(now))
     try {
-      await mkdir(dir, { recursive: true })
+      await hardenDir(dir)
       await writeFile(target, JSON.stringify(exportEnvelope(), null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
     } catch (err) {
       return { ok: false, saved: false, message: '写入备份目录失败：' + describeErrorSafe(err), snapshot: snapshot() }
@@ -3952,6 +4581,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() }
@@ -3982,6 +4613,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() }
@@ -3995,6 +4628,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() }
@@ -4282,11 +4917,29 @@ 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
       throw new Error('无法读取反馈配置文件 ' + path + '：' + describeErrorSafe(err))
     }
+    // This file can hold SMTP credentials. The plugin does not create it (the
+    // operator does), so it cannot set its mode — it can only say something
+    // when the mode is wrong, which is the part that used to be silent.
+    if (process.platform !== 'win32') {
+      const info = await stat(path).catch(() => null)
+      if (info !== null && (info.mode & 0o077) !== 0) {
+        logInfo('feedback config ' + displayPath(path) + ' is readable by group/others (mode '
+          + (info.mode & 0o777).toString(8) + '); it may hold SMTP credentials')
+      }
+    }
     try {
       return JSON.parse(text)
     } catch (err) {
@@ -4504,6 +5157,21 @@ export function apply(ctx) {
   // `security.hostGuarded`); only `routeDispose` lives here.
 
   let routeDispose = null
+  /**
+   * F19: the composition's `connection` service, when the profile has one.
+   *
+   * It is the harness's single authentication fence: `requestRejection(req)`
+   * applies the Host/Origin trust check AND requires the browser login cookie
+   * (the same gate that makes `/api` answer 401 to an anonymous caller). This
+   * route used to rely on the Origin guesswork below alone, which left it as
+   * the only unauthenticated read/write endpoint on the instance — a stored
+   * prompt-injection primitive for any local process.
+   *
+   * Read through a NON-BLOCKING child fiber for the same reason `webServer` is
+   * (headless/tui profiles must still inject the prompt), and kept nullable:
+   * when the service is absent the loopback-only rule below still applies.
+   */
+  let connectionGate = null
 
   /**
    * Does this stream subscriber want lightweight frames?
@@ -4543,13 +5211,11 @@ export function apply(ctx) {
    * `?lite=1` gets `{ rev, lite: true }` frames instead (see pushSnapshot).
    */
   const handleEventStream = (req, res) => {
-    const verdict = requestOriginVerdict(req.headers, guardHost, expectedOriginHostname)
-    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
-    }
+    // Same fence as the POST path: an EventSource carries the login cookie, so
+    // an authenticated stream keeps working while an anonymous one is refused.
+    const fence = rejectUntrustedCaller(req, res)
+    if (fence === 'rejected') return
+    if (originVerdictRefuses(req, res, fence)) return
     // Every subscriber holds a Map entry, a `req.on('close')` listener and a
     // live socket until it disconnects. A tab that is duplicated, a client that
     // never closes, or a script that opens streams in a loop would otherwise
@@ -4609,7 +5275,94 @@ export function apply(ctx) {
     }
   }
 
+  /**
+   * F19: refuse a caller the harness has not authenticated.
+   *
+   * Order matters. The harness fence runs FIRST when it exists: it is the only
+   * check that knows about the browser login cookie, and it also owns the
+   * Host/Origin trust rules for every other route on the instance. The
+   * hand-rolled Origin verdict below stays as the second line of defence (it
+   * covers profiles that publish a web server without a `connection` service).
+   *
+   * When there is no fence at all, a NON-loopback bind fails closed: publishing
+   * an unauthenticated endpoint that can rewrite the instructions injected into
+   * every later turn is not a trade-off worth defaulting to. The loopback bind
+   * keeps working, which is the documented deployment (and what the Android
+   * build's route-guard patch assumes).
+   *
+   * @returns 'rejected' when this handler already answered the request (401,
+   *   403 or 503 and the response is complete), 'gate' when the harness fence
+   *   accepted it (so the Host/Origin question is already settled and the
+   *   plugin's own Origin verdict must NOT run again), 'open' when there is no
+   *   fence and the caller still has to pass the local Origin rules.
+   */
+  const rejectUntrustedCaller = (req, res) => {
+    if (connectionGate !== null) {
+      let rejection
+      try {
+        rejection = connectionGate.requestRejection(req)
+      } catch (err) {
+        // A throwing fence must not become an open door: treat it as 401.
+        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' })
+        res.end(JSON.stringify({
+          ok: false,
+          message: rejection === 403
+            ? '请求未被宿主信任（Host/Origin 校验失败）'
+            : '需要登录 DSH 后的浏览器会话才能访问该路由',
+        }))
+        return 'rejected'
+      }
+      return 'gate'
+    }
+    if (!guardHost) {
+      logInfo('route refused a request: non-loopback bind without an authentication fence')
+      res.writeHead(503, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+      res.end(JSON.stringify({
+        ok: false,
+        message: '该路由在非回环绑定下需要宿主的 connection 服务提供鉴权；当前 profile 没有该服务，已拒绝请求',
+      }))
+      return 'rejected'
+    }
+    return 'open'
+  }
+
+  /**
+   * Run the plugin's OWN Origin/Host verdict, but only when the harness fence
+   * did not already answer the same question (F19 follow-up).
+   *
+   * Order: the fence runs first. When it accepts a request it has already
+   * applied the host's Host / `Origin` / `Sec-Fetch-Site` rules AND verified
+   * the browser login cookie (`dsh-client-connection`: `isTrustedApiRequest`
+   * then `browserAuth`). It also knows the deployment's public name. This
+   * plugin knows only its bind address, so re-judging `Origin` here produced a
+   * false 403 for every legitimate reverse-proxy client: the proxy forwards
+   * `Host: dsh.example.com`, the listener binds `192.168.1.5`, and the Origin
+   * host could never equal the bind IP. The local verdict stays as the second
+   * line of defence for profiles that publish a web server WITHOUT a
+   * `connection` service — there it is the only fence there is.
+   *
+   * @returns true when the request was answered with 403 and must not continue.
+   */
+  const originVerdictRefuses = (req, res, fence) => {
+    if (fence === 'gate') return false
+    const verdict = requestOriginVerdict(req.headers, guardHost, expectedOriginHostname, trustedHosts)
+    if (verdict.ok) return false
+    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 true
+  }
+
   const handler = (req, res) => {
+    // Authentication before anything else: not the method, not the body, not
+    // the size. A rejection must not leak which methods exist.
+    const fence = rejectUntrustedCaller(req, res)
+    if (fence === 'rejected') return
     if (req.method === 'GET') {
       const accept = String(
         (req.headers !== null && typeof req.headers === 'object') ? (req.headers.accept || '') : '',
@@ -4649,16 +5402,9 @@ export function apply(ctx) {
         return
       }
     }
-    // Origin/Host guard, before anything else is read. See
-    // requestOriginVerdict() for why the content-type rule below is not enough
-    // on its own.
-    const verdict = requestOriginVerdict(req.headers, guardHost, expectedOriginHostname)
-    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
-    }
+    // Origin/Host guard, before anything else is read. Skipped when the host
+    // fence already accepted this request — see originVerdictRefuses().
+    if (originVerdictRefuses(req, res, fence)) return
     // The settings page always posts application/json. Enforcing it turns
     // the anti-CSRF coincidence (a plain HTML form cannot fabricate a JSON
     // body) into a hard rule: a cross-site or malformed post now gets a
@@ -4736,6 +5482,30 @@ export function apply(ctx) {
   // losing the prompt injection along with the settings page. The callback also
   // fixes the original race properly — it runs whenever the service is
   // published, not only if it happened to beat this row to the mount.
+  // F19: take the harness authentication fence when the profile has one.
+  // Same non-blocking shape as the web server below — a profile without a
+  // browser never publishes `connection`, and the prompt injection must not
+  // wait for one.
+  ctx.inject(['connection'], (scope) => {
+    const service = scope.connection
+    if (service === undefined || service === null || typeof service.requestRejection !== 'function') {
+      logDebug('no connection service; the route falls back to the loopback-only rule')
+      return
+    }
+    connectionGate = service
+    logDebug('connection fence attached; the route now requires an authenticated browser session')
+    scope.effect(() => () => {
+      if (connectionGate !== service) return
+      connectionGate = null
+      // A host that republishes (or disposes) the service would otherwise let
+      // the route fall back to the loopback-only rule with nothing said about
+      // it. That is not an open door on a loopback bind, but it IS a silent
+      // authentication downgrade, and `snapshot.security.authFence` now shows
+      // it for as long as it lasts.
+      logInfo('connection fence detached while the plugin stayed mounted; the route falls back to the loopback-only rule until the service is published again')
+    })
+  })
+
   ctx.inject(['webServer'], (scope) => {
     const webServer = scope.webServer
     if (webServer === undefined || typeof webServer.register !== 'function') {