dsh-instruction-memory 1.0.9 → 1.0.11

package/README.md

@@ -64,13 +64,106 @@ DSH 就会得到第二份空记忆，看起来像"记忆消失"。
 > 首次启动新版本时会自动迁移到上述位置，并把原文件改名为 `*.migrated` 保留。
 
 该文件可手工编辑，改完点设置页的「重新载入」即可读回。每次保存先写临时文件再原子替换，
-进程崩溃不会留下损坏的半截 `memory.json`；保存时上一版会保留为 `memory.json.bak`，
-若 `memory.json` 解析失败会自动临时回退到该备份并明确提示。若手工编辑后的文件有条目为空
-或超过 200 条上限，设置页会明确提示哪些条目未能载入（它们将在下次保存时从文件中移除），
-不会静默丢弃。
+进程崩溃不会留下损坏的半截 `memory.json`；保存前把上一版**复制**为 `memory.json.bak`，
+若 `memory.json` 解析失败会自动临时回退到该备份并明确提示。
+
+> **备份为什么是"复制"而不是"改名"**：曾经的做法是先把 `memory.json` 改名成 `.bak`、
+> 再改名临时文件顶上。这两步之间 `memory.json` 是不存在的——只要第二步失败（文件被占用、
+> 磁盘满、杀软扫描），主路径就一直空着，下次启动找不到文件就会**建一份空存储**，用户的
+> 记忆看起来凭空消失，而真实数据其实好好躺在 `.bak` 里。改为复制后主文件在原子替换成功
+> 前始终待在原位；同时启动时若发现 `memory.json` 缺失而 `.bak` 可用，会**从备份恢复并写回**
+> 主路径，而不是从零开始。
+
+若手工编辑后的文件有条目为空或超过 200 条上限，设置页会明确提示哪些条目未能载入
+（它们将在下次保存时从文件中移除），不会静默丢弃。导入时若某条超出长度上限
+（标题 120 / 内容 6000 / 适用场景 200 字符），会明确提示**有几条、哪个字段**被截断，
+而不是悄悄改短。
 
 设置页支持**导出 / 导入**：导出为自带说明的 JSON 文件；导入采用**合并语义**——按 id 与
-「标题+内容」去重，只新增、绝不覆盖或清空现有条目。
+「标题+内容」去重，只新增、绝不覆盖或清空现有条目。请求体上限由条目上限推导
+（`MAX_ENTRIES × (MAX_CONTENT + MAX_TITLE + MAX_WHEN + 200) × 2 + 100000`），保证**本插件
+导出的文件一定能被自己导回**——早先写死的 1,000,000 小于满配导出（200 × 6000 = 1.2 M 字符），
+导致满配记忆导出后无法导入。
+
+### 首次运行不写文件（惰性创建）
+
+全新安装、尚无任何记忆时，插件**不会**在宿主启动那一刻创建空的 `memory.json`。
+
+> 这里曾主动物化一份空存储，只为让设置页有个真实路径可显示。但那意味着插件在**进程启动、
+> 零会话、零任务**的状态下执行了一次磁盘写入——这正是行为审计中唯一能被正当称为
+> "没活干还在动"的副作用。现在文件由**第一个真正需要它的动作**创建：一次保存、一次导入，
+> 或设置页读取 `state`（面板打开时就会读）。
+
+在这之前：`storage.path` 仍会显示路径，但 `storage.onDisk` 为 `false`，设置页显示
+「尚未写入磁盘」（该文案本就存在），`state.injection.registered === false`，`pulls === 0`。
+挂载日志相应为 `from=first run (no store on disk yet) onDisk=no`。
+
+**不受影响**：从 `.bak` 恢复、以及从旧位置迁移——这两条分支只有在**磁盘上已有真实数据**时才会走，
+它们仍然会立即写回。
+
+## 无 Web 服务器时依然生效
+
+`systemPrompt` 是本插件唯一的硬依赖。**Web 服务器不是前置条件**：设置页那部分路由通过
+非阻塞的 `ctx.inject(['webServer'], …)` 子 fiber 注册，服务出现时自动挂上；没有 Web 服务器
+的 profile（`headless`、`tui`）里，系统提示词注入照常工作，只是设置页不可用。
+
+> 这里曾声明 `inject = ['systemPrompt', 'webServer']`。声明式依赖是**前置条件**，于是没有
+> Web 服务器的 profile 里整行插件永远停在 pending、`apply()` 根本不执行——用户同时失去设置页
+> **和**记忆注入，而记忆本身根本不需要 Web 服务器。非阻塞注册同时把最初那个竞态修得更彻底：
+> 回调在服务发布时就会执行，而不只是在它"抢在插件挂载之前"发布时才生效。
+
+## 诊断日志
+
+插件此前**只有失败才有输出**：每次载入、保存、注入成功都不留任何记录，只有失败分支走
+`console.error`。于是"记忆到底有没有在干活"完全无法从日志回答。现在它挂载时写一行
+`info`，过程细节写 `debug`（走宿主的 `ctx.logger`）：
+
+```
+[instruction-memory] mounted: store=<DSH_HOME>\instruction-memory\memory.json from=memory.json onDisk=yes entries=2 enabled=true section=437 chars (pending assembly) pulls=0
+```
+
+挂载行含**数据来源**（`memory.json` / `memory.json.bak (main file missing)` / `memory.json.bak (main file corrupt)`
+/ `legacy cwd file (migrated)` / `first run (no store on disk yet)`）、**是否已在磁盘上**（`onDisk`）、
+条目数、总开关状态、段落就绪时的字符数，以及 `pulls`。
+
+### 为什么是 `section=… (pending assembly)` 而不是 `injected=…`
+
+**「段落已就绪」≠「已经注入」。** 注入发生在宿主装配提示词时；插件在挂载那一刻**什么都没注入过**，
+打印 `injected=437 chars` 会让人误以为记忆已经进入了某个提示词。这是本插件此前一处会误导排查的措辞。
+
+真正的"到达了提示词"的信号是 **`pulls`**：宿主每次对这段做装配，插件注册的那个 thunk 就被求值一次，
+计数器加一。因此
+
+- `pulls=0` = 已准备、**从未装配**（进程刚起来、或会话空闲）；
+- `pulls=N` = 已被拉进提示词 N 次。
+
+插件看不到会话或轮次，**不会**报告 `sessions=` 之类的数字——那会是编造。它只报告自己能真正观测到的东西。
+`pulls` 同时出现在路由的 `state` 快照里（`injection.pulls`）。每次拉取另有一条 `debug` 行：
+`section pulled into a prompt (pull #N)`。
+
+**这是纯日志，绝不影响注入内容**：同一份存储在"有 logger"和"没有 logger"下渲染出的文本
+**逐字节相同**（`verify.mjs` 有断言锁定这一点）。`debug` 级别由宿主日志级别过滤；
+没有 logger 服务的环境下需要 `DSH_INSTRUCTION_MEMORY_DEBUG=1` 才会输出到标准错误。
+
+## 请求来源防护（Host / Origin）
+
+设置页路由之所以要求 `content-type: application/json`，是因为 HTML 表单无法伪造 JSON body，
+而跨源 `fetch` 带 JSON 会先在 preflight 失败。**这两条防线都建立在"浏览器认为这是跨源"之上，
+DNS 重绑定恰好推翻了它**：`evil.com` 解析到 `127.0.0.1` 之后，页面与服务器在浏览器眼里是
+**同源**——不发 preflight、JSON 也合法，于是任何网页都能改写用户那份"注入到此后每一轮
+对话"的长期指令。此时唯一无法伪造的就是浏览器发出的 `Host` 头。
+
+因此当服务器绑定在回环地址（默认）时，路由**要求 `Host` 是回环**，另外校验 `Origin`（若存在）
+与 `Host` 同源。命中即 **403**，并记一行日志：
+
+```
+[instruction-memory] route rejected a request: Host 头不是回环地址（可能是 DNS 重绑定攻击）：evil.com:8080
+```
+
+- 绑定 `--host 0.0.0.0`（主动对所有网卡开放）时 Host 校验**自动关闭**——那种情况下无法预知合法
+  Host，强行限制只会打断所有正常客户端；`Origin` 校验仍然生效。
+- 无 `Host` 的 HTTP/1.1 请求由 Node 的 HTTP 解析器先以 400 拒掉，根本到不了路由。
+- 端口不参与 `Origin` 比对（反向代理可能改写端口），主机名才是重绑定攻击的对象。
 
 ## 兼容性
 
@@ -101,8 +194,25 @@ major.minor.patch 且自身带预发布标签的比较符"。这条规则是**
 ⚠️ **一个必须知道的上限**：**未声明的未来 minor 的预发布版本，无法被任何范围覆盖。**
 `0.1.8-rc.1` 这类版本 tuple 与所有比较符都不同，在 npm 语义下**永远匹配不到**——与
 `^0.1.0` 无法匹配 `0.1.8-rc.1` 是同一个限制。正式版（`0.1.8`、`0.2.0`、`1.0.0` 等）不受影响。
-DSH 发布新的预发布 minor 时需追加一段，例如 `|| >=0.1.8-alpha.0 <0.2.0-0`；
-`host-range-test.mjs` 的**实时守卫**会把这类缺口暴露出来（它直接读本机安装的宿主版本）。
+
+**这个限制无法用代码消除，但它的后果已经被消掉了。** 范围现在是**生成出来的**：
+`host-range-test.mjs` 顶部的 `COVERED_LINES` 是唯一事实来源，package.json 里那串长字符串必须
+逐字节等于由它生成的结果（有专门的漂移断言），所以手改长串导致"枚举漏了一段"这类错误不可能
+再发生——DSH 发新 minor 时只需在列表末尾加一行。
+
+同时**实时守卫**（直接读本机实际安装的宿主版本）在发现未覆盖的宿主时，会打印**精确到行**的
+修复配方，并且在打印前**先验证该配方真的能让那个版本被放行**：
+
+```
+FAIL  LIVE GUARD: the installed host 0.1.8-rc.1 is admitted by both modes  -> ...
+      Fix: append { floor: '0.1.8-alpha.0', below: '0.2.0-0' } to COVERED_LINES
+           and set the preceding line's below to '0.1.8-0'
+      [verified: that edit admits 0.1.8-rc.1]
+```
+
+这份配方本身也有测试：`host-range-test.mjs` 会拿 `0.1.8-rc.1` 走一遍"确认当前范围拒收 →
+套用配方 → 确认放行 → 确认下方版本仍被拒收 → 确认所有已覆盖版本仍被放行"。配方失效会先失败在
+测试里，而不是失败在用户的安装上。
 
 **历史修复说明**（同一个 bug 出现过两次，值得记下来）：
 
@@ -110,6 +220,8 @@ DSH 发布新的预发布 minor 时需追加一段，例如 `|| >=0.1.8-alpha.0
   被判为**不兼容**（预发布门禁要求 tuple 相同：`0.1.5 ≠ 0.1.6`，`>=` 的大小比较根本走不到）。
 - 1.0.8 改为逐段枚举，但只枚举到 `0.1.6`。DSH 随后发布 `0.1.7-rc.2`，**同一个假阴性再次出现**：
   范围里最后一个预发布 tuple 是 `0.1.6`，而 `0.1.7 ≠ 0.1.6`。1.0.9 补上 `0.1.7` 段。
+- 1.0.10 把枚举抽成 `COVERED_LINES` 单一事实来源 + 漂移/可达/递增断言，并让实时守卫给出
+  **自验证**的修复配方——这个 bug 的**成因**（手改长串）从此被消掉。
 
 两次都因为插件市场传入 `includePrerelease: true` 而侥幸放行，但任何标准 semver 判定
 （`npm` / `pnpm` 的依赖解析）都会拒绝。现在 `host-range-test.mjs` 同时具备固定矩阵与实时守卫。

package/lib/client.js

@@ -122,7 +122,19 @@ window.__ModuleLoader__.load({
           body: JSON.stringify({ method, args: args === undefined ? null : args }),
           signal: controller !== null ? controller.signal : undefined,
         })
-        if (!response.ok) throw new Error('宿主返回 HTTP ' + response.status)
+        if (!response.ok) {
+          // 413/415 carry a readable reason in the JSON body. Reporting only the
+          // status code left the user staring at "宿主返回 HTTP 413" with no
+          // hint that the import file was simply too large.
+          let detail = ''
+          try {
+            const body = await response.json()
+            if (body !== null && typeof body === 'object' && typeof body.message === 'string') detail = body.message
+          } catch (err) {
+            // A non-JSON error body leaves the status code as the only clue.
+          }
+          throw new Error('宿主返回 HTTP ' + response.status + (detail === '' ? '' : '：' + detail))
+        }
         return await response.json()
       } catch (err) {
         if (controller !== null && controller.signal.aborted) throw new Error('请求宿主超时（15 秒无响应）')

package/lib/index.js

@@ -10,26 +10,35 @@
  * plugin's fiber, so unmounting the row removes all of them.
  */
 
-import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { copyFile, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 
 export const name = 'instruction-memory'
 
 /**
- * Hard dependencies, declared rather than probed.
+ * `systemPrompt` is the one hard dependency: without it there is nothing to
+ * inject into. `webServer` deliberately is NOT declared here any more.
  *
- * This row mounts early — before the web server has published — so a one-shot
- * `ctx.get('webServer')` at apply time resolves `undefined` and the route is
- * lost for the life of the process. Declaring it here makes Cordis hold the row
- * until the service exists.
+ * It used to be, to fix a real race — this row mounts early, before the web
+ * server has published, so a one-shot `ctx.get('webServer')` at apply time
+ * resolved `undefined` and the route was lost for the life of the process. But
+ * declaring it made the web server a *precondition for the whole plugin*: in a
+ * profile that has no web server at all (headless, tui) the row stays pending
+ * forever, `apply()` never runs, and the user silently loses BOTH the settings
+ * page and the prompt injection — even though `apply()` has always been able to
+ * serve memory without any web server. Memory must not be gated on the UI.
+ *
+ * The route is now registered from a non-blocking `ctx.inject(['webServer'], …)`
+ * child fiber, which solves the original race properly: the callback runs
+ * whenever the service is published, not only if it beat this row to it.
  *
  * The harness `fs` service is deliberately NOT used. Its default base is the
  * host process cwd, which is exactly what `@deepseek-ai/dsh-home-paths` warns
  * against: a user relaunching DSH from another directory would silently get a
  * second, empty store. Plugin-owned data belongs under the harness home.
  */
-export const inject = ['systemPrompt', 'webServer']
+export const inject = ['systemPrompt']
 
 const STORE_DIR_NAME = 'instruction-memory'
 const STORE_FILE_NAME = 'memory.json'
@@ -59,8 +68,6 @@ const SECTION_NAME = 'instruction-memory'
  */
 const SECTION_ORDER = 950
 const API_PREFIX = '/instruction-memory/api'
-/** Request body ceiling for the settings-page route; anything larger is rejected. */
-const MAX_BODY_CHARS = 1_000_000
 
 /**
  * Resolve this plugin's data file under the harness home.
@@ -83,6 +90,21 @@ const MAX_TITLE = 120
 const MAX_CONTENT = 6000
 const MAX_WHEN = 200
 
+/**
+ * Request body ceiling for the settings-page route; anything larger is refused
+ * with a clean 413.
+ *
+ * Derived from the entry limits instead of hard-coded, because the two must not
+ * drift apart. A fixed 1,000,000 sat BELOW the largest legal payload — 200
+ * entries carrying 6,000 characters each is already 1.2 M characters of body —
+ * so a maximal store could be exported by this plugin and then never imported
+ * back into it: the route rejected the plugin's own export with 413. The factor
+ * of two covers JSON string escaping (a `"` or a newline costs two characters);
+ * the flat slack covers the `{method,args:{payload:{app,…,data:{entries:[…]}}}}`
+ * wrapper.
+ */
+export const MAX_BODY_CHARS = MAX_ENTRIES * (MAX_CONTENT + MAX_TITLE + MAX_WHEN + 200) * 2 + 100_000
+
 /* ------------------------------------------------------------------ *
  * Pure helpers (no ctx, fully unit-testable)
  * ------------------------------------------------------------------ */
@@ -143,6 +165,28 @@ export function sanitizeEntry(raw) {
   }
 }
 
+/**
+ * Which fields of a raw entry had to be cut to fit the stored limits.
+ *
+ * `sanitizeEntry` silently enforces MAX_TITLE / MAX_CONTENT / MAX_WHEN, which
+ * is fine for the editor (its inputs carry the same maxLength) but wrong for
+ * import and hand-edited payloads: a 7,000-character instruction came back
+ * stored as 6,000 with no indication that anything was lost, contradicting the
+ * plugin's stated rule of never discarding user text without saying so. Callers
+ * use this to disclose the cut; the sanitizer itself stays pure and unchanged.
+ *
+ * @returns the names of the fields that were shortened, in field order.
+ */
+export function truncatedFields(raw) {
+  if (raw === null || typeof raw !== 'object') return []
+  const cut = []
+  const unlimited = Number.MAX_SAFE_INTEGER
+  if (typeof raw.title === 'string' && singleLine(raw.title, unlimited) !== singleLine(raw.title, MAX_TITLE)) cut.push('标题')
+  if (typeof raw.content === 'string' && cleanText(raw.content, unlimited) !== cleanText(raw.content, MAX_CONTENT)) cut.push('内容')
+  if (typeof raw.when === 'string' && singleLine(raw.when, unlimited) !== singleLine(raw.when, MAX_WHEN)) cut.push('适用场景')
+  return cut
+}
+
 /**
  * Load a parsed memory file. Returns the sanitized data plus how many array
  * items were discarded (blank entries, or valid ones past the cap). The count
@@ -175,11 +219,107 @@ function normalizeData(raw) {
   return { data, dropped }
 }
 
+/**
+ * A structural copy of the store, shallow per entry.
+ *
+ * The mutating commands edit `state.data` in place (push, filter, field
+ * assignment), so holding a plain reference is not enough to undo one — the
+ * "previous" value would already have changed with it. Entries are flat
+ * objects, so one spread per entry is a complete copy, and at the 200-entry cap
+ * that is a trivial cost on a path that is already doing a disk write.
+ */
+function cloneData(data) {
+  return {
+    version: 1,
+    enabled: data.enabled === true,
+    budgetChars: data.budgetChars,
+    entries: (Array.isArray(data.entries) ? data.entries : []).map((entry) => ({ ...entry })),
+  }
+}
+
 const droppedEntriesMessage = (count) =>
   count > 0
     ? '存储文件中有 ' + count + ' 条条目未能载入（内容为空或超过 ' + MAX_ENTRIES + ' 条上限）；下次保存时它们将从文件中移除'
     : null
 
+/**
+ * Hostnames a loopback-bound server may legitimately be reached by.
+ *
+ * `localhost` is included for people who open the GUI that way; the IPv4-mapped
+ * form covers a dual-stack listener reporting the client as `::ffff:127.0.0.1`.
+ */
+const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '::1', '::ffff:127.0.0.1'])
+
+/**
+ * The hostname part of a `Host` header, lower-cased and without its port.
+ *
+ * `127.0.0.1:8080` -> `127.0.0.1`; `[::1]:8080` -> `::1`; `localhost` -> `localhost`.
+ * Exported so the parsing itself can be pinned by tests.
+ */
+export function hostnameOf(value) {
+  if (typeof value !== 'string') return ''
+  const trimmed = value.trim().toLowerCase()
+  if (trimmed === '') return ''
+  if (trimmed.startsWith('[')) {
+    const end = trimmed.indexOf(']')
+    return end === -1 ? trimmed : trimmed.slice(1, end)
+  }
+  const colon = trimmed.lastIndexOf(':')
+  return colon === -1 ? trimmed : trimmed.slice(0, colon)
+}
+
+/**
+ * Why the settings-page route checks `Host` and `Origin` at all, when it already
+ * refuses any content-type that is not `application/json`.
+ *
+ * The content-type rule stops a cross-site form post, and no CORS headers are
+ * sent so a cross-origin `fetch` with a JSON body dies in preflight. Both
+ * defences assume the browser sees the request as *cross-origin*. DNS
+ * rebinding removes that assumption: a page served from `evil.com` whose DNS
+ * is re-pointed at 127.0.0.1 is, to the browser, same-origin with the server it
+ * then talks to — so no preflight happens, the JSON content-type is allowed,
+ * and the plugin would happily rewrite the user's long-lived instructions,
+ * which are injected into every later prompt. The one thing the attacker cannot
+ * change is the `Host` header the browser sends: it still carries `evil.com`.
+ *
+ * So when the server is bound to loopback (the default) the route requires a
+ * loopback `Host`. An operator who binds `0.0.0.0` has deliberately published
+ * the whole server on every interface, where no Host value can be known in
+ * advance — the check is disabled there rather than breaking every legitimate
+ * client, and that trade-off is documented in the README.
+ */
+export function requestOriginVerdict(headers, guarded) {
+  const read = (name) => {
+    if (headers === null || typeof headers !== 'object') return ''
+    const value = headers[name]
+    return typeof value === 'string' ? value : ''
+  }
+  const requestHost = read('host').trim().toLowerCase()
+  const requestHostname = hostnameOf(requestHost)
+
+  if (guarded && !LOOPBACK_HOSTNAMES.has(requestHostname)) {
+    return { ok: false, reason: 'Host 头不是回环地址（可能是 DNS 重绑定攻击）：' + (requestHost === '' ? '(缺失)' : requestHost) }
+  }
+
+  const origin = read('origin').trim()
+  if (origin !== '') {
+    let originHostname = ''
+    try {
+      originHostname = new URL(origin).hostname.toLowerCase()
+    } catch {
+      originHostname = ''
+    }
+    // Compare hostnames, not host:port: a proxy may rewrite the port, and the
+    // hostname is the part rebinding actually attacks. `Origin: null`
+    // (sandboxed iframe, file://) parses to no hostname and is refused.
+    if (originHostname === '' || originHostname !== requestHostname) {
+      return { ok: false, reason: 'Origin 与 Host 不同源：' + origin }
+    }
+  }
+
+  return { ok: true, reason: null }
+}
+
 function formatEntry(entry, tag) {
   const lines = ['[' + tag + '｜优先级 ' + priorityLabel(entry.priority) + '] ' + entry.title]
   if (entry.mode === 'auto' && entry.when !== '') lines.push('适用场景：' + entry.when)
@@ -282,7 +422,6 @@ export function buildBlock(data) {
 
 export function apply(ctx) {
   const systemPrompt = ctx.systemPrompt
-  const webServer = ctx.get('webServer')
 
   const state = {
     data: { version: 1, enabled: true, budgetChars: DEFAULT_BUDGET, entries: [] },
@@ -290,13 +429,39 @@ export function apply(ctx) {
     storageDisplay: null,
     storageError: null,
     storageWarning: null,
+    /** A failed rolling-backup refresh, shown only when no load warning wins. */
+    backupError: null,
+    /** Which branch of the load actually produced the current data (diagnostics). */
+    loadedFrom: null,
     savedAt: null,
     migratedFrom: null,
     sectionRegistered: false,
     sectionError: null,
+    /** Whether a store file is actually present on disk (diagnostics + the panel). */
+    storeExists: false,
   }
   let sectionDispose = null
 
+  /**
+   * A first run deliberately writes NOTHING (see readFromDisk step 3). This flag
+   * remembers that the store has not been materialised yet, so the file is
+   * created by the first action that genuinely needs it — a save, or the
+   * settings page asking for `state` — instead of by the bare act of the host
+   * booting with no session and no task.
+   */
+  let needsMaterialize = false
+
+  /**
+   * How many times the host has pulled this section into a prompt, since boot.
+   *
+   * The plugin cannot see sessions or turns; it only knows that the harness
+   * evaluated the thunk it registered. That is still the honest answer to "did
+   * this actually reach a prompt?", and it is the thing the previous log line
+   * could not distinguish: a registered section with pulls=0 has been prepared
+   * but never injected.
+   */
+  let sectionPulls = 0
+
   const describeError = (err) => {
     if (err === null || err === undefined) return '未知错误'
     if (typeof err === 'string') return err
@@ -304,6 +469,56 @@ export function apply(ctx) {
     return String(err)
   }
 
+  /* ---------------- diagnostics ---------------- */
+
+  /**
+   * The plugin used to be completely silent on success: every load, save and
+   * injection produced no record at all, and only failures reached
+   * `console.error`. "Is memory actually doing anything?" was therefore
+   * unanswerable from logs — verifying it meant substituting route snapshots
+   * and transcript forensics for real evidence.
+   *
+   * This adds an opt-in diagnostic channel on the harness logger. It is
+   * log-only: it never touches what gets injected, so the rendered block stays
+   * byte-identical with it on or off.
+   *
+   *   info  — one line per mount (where the store is, how much is injected)
+   *   debug — per-operation detail, including the ones the route guards reject
+   *
+   * With no logger service (the offline harnesses) debug needs
+   * DSH_INSTRUCTION_MEMORY_DEBUG=1; info always falls back to console.error so
+   * a mount failure is never swallowed.
+   */
+  const logger = (() => {
+    try {
+      const candidate = typeof ctx.logger === 'function' ? ctx.logger('instruction-memory') : ctx.logger
+      if (candidate !== null && candidate !== undefined && typeof candidate.info === 'function') return candidate
+    } catch {
+      // A context without a logger service must never break the plugin.
+    }
+    return null
+  })()
+
+  const debugToConsole = (() => {
+    const raw = typeof process.env.DSH_INSTRUCTION_MEMORY_DEBUG === 'string'
+      ? process.env.DSH_INSTRUCTION_MEMORY_DEBUG.trim().toLowerCase()
+      : ''
+    return raw === '1' || raw === 'true' || raw === 'yes'
+  })()
+
+  const logInfo = (message) => {
+    if (logger !== null) logger.info(message)
+    else console.error('[instruction-memory] ' + message)
+  }
+
+  const logDebug = (message) => {
+    if (logger !== null) {
+      if (typeof logger.debug === 'function') logger.debug(message)
+      return
+    }
+    if (debugToConsole) console.error('[instruction-memory] ' + message)
+  }
+
   const sectionText = () => {
     try {
       return buildBlock(state.data)
@@ -313,6 +528,21 @@ export function apply(ctx) {
     }
   }
 
+  /**
+   * The thunk handed to the harness.
+   *
+   * It is deliberately NOT `sectionText` itself: wrapping it lets the plugin
+   * count the pulls the host performs (`assembled`), which is the only
+   * first-hand evidence of "this reached a prompt" available on this side of the
+   * API. The returned text is untouched — the render stays byte-identical
+   * (verify.mjs pins that with and without a logger attached).
+   */
+  const assembledSectionText = () => {
+    sectionPulls += 1
+    logDebug('section pulled into a prompt (pull #' + sectionPulls + ')')
+    return sectionText()
+  }
+
   /**
    * Keep the registered section exactly in step with the stored data: present
    * when something must be injected, absent otherwise. An empty memory must
@@ -322,9 +552,10 @@ export function apply(ctx) {
     const wanted = sectionText() !== ''
     if (wanted && sectionDispose === null) {
       try {
-        sectionDispose = systemPrompt.section({ name: SECTION_NAME, order: SECTION_ORDER, text: sectionText })
+        sectionDispose = systemPrompt.section({ name: SECTION_NAME, order: SECTION_ORDER, text: assembledSectionText })
         state.sectionRegistered = true
         state.sectionError = null
+        logDebug('prompt section registered: order=' + SECTION_ORDER + ' chars=' + sectionText().length)
       } catch (err) {
         sectionDispose = null
         state.sectionRegistered = false
@@ -339,6 +570,7 @@ export function apply(ctx) {
         sectionDispose = null
         try {
           dispose()
+          logDebug('prompt section disposed (nothing to inject)')
         } catch (err) {
           console.error('[instruction-memory] section dispose failed:', err)
         }
@@ -371,16 +603,33 @@ export function apply(ctx) {
     // one-version backup: a crash mid-write must never leave a truncated
     // memory.json, and an edit the user regrets must still be recoverable
     // from memory.json.bak. The .bak holds the previous good version.
+    //
+    // The backup is a COPY, not a rename. Renaming the live file out of the way
+    // first opened a window in which memory.json did not exist: if the rename
+    // that followed failed (a lock, a full disk, an indexer holding the file)
+    // the primary path stayed missing, and the next boot — finding no
+    // memory.json — materialised an EMPTY store and silently discarded the
+    // 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'
     const bakPath = storePath + '.bak'
     try {
       await mkdir(dirname(storePath), { recursive: true })
-      await writeFile(tmpPath, serialize(), 'utf8')
+      const text = serialize()
+      await writeFile(tmpPath, text, 'utf8')
       try {
-        await rename(storePath, bakPath)
+        await copyFile(storePath, bakPath)
+        state.backupError = null
       } catch (err) {
-        // No previous version on the very first save; anything else is real.
-        if (err.code !== 'ENOENT') throw err
+        // ENOENT is simply the very first save: there is no previous version
+        // to roll. Any other failure means the promised rolling backup did not
+        // happen — non-fatal for this save, because the primary is still intact
+        // and the replace below is the real gate, but it must be disclosed
+        // rather than swallowed.
+        state.backupError = err.code === 'ENOENT'
+          ? null
+          : '上一版未能保留为 memory.json.bak：' + describeError(err)
       }
       try {
         await rename(tmpPath, storePath)
@@ -391,7 +640,14 @@ export function apply(ctx) {
       state.storagePath = storePath
       state.storageDisplay = storePath
       state.storageError = null
+      state.storeExists = true
+      // A successful write is the one thing that makes the file real, so it is
+      // also what clears the "not materialised yet" flag set by a first run.
+      needsMaterialize = false
       state.savedAt = Date.now()
+      logDebug('store written: ' + storePath + ' bytes=' + text.length
+        + ' entries=' + state.data.entries.length
+        + (state.backupError === null ? ' backup=refreshed' : ' backup=FAILED'))
       return true
     } catch (err) {
       state.storageError = '保存失败：' + describeError(err)
@@ -408,6 +664,8 @@ export function apply(ctx) {
     state.storagePath = storePath
     state.storageDisplay = storePath
     state.storageWarning = null
+    state.loadedFrom = null
+    state.storeExists = false
 
     // 1. The canonical location under the harness home.
     try {
@@ -416,6 +674,8 @@ export function apply(ctx) {
         const loaded = normalizeData(parsed)
         state.data = loaded.data
         state.storageWarning = droppedEntriesMessage(loaded.dropped)
+        state.loadedFrom = 'memory.json'
+        state.storeExists = true
       }
       state.storageError = null
       return
@@ -435,6 +695,7 @@ export function apply(ctx) {
               state.storageWarning = (droppedEntriesMessage(loaded.dropped) || '')
                 + (loaded.dropped > 0 ? '；' : '')
                 + 'memory.json 解析失败（' + describeError(err) + '），已临时回退到最近备份 memory.json.bak；损坏文件已保留，下次保存时会覆盖它'
+              state.loadedFrom = 'memory.json.bak (main file corrupt)'
               return
             }
           } catch {
@@ -449,6 +710,31 @@ export function apply(ctx) {
       }
     }
 
+    // 1b. The primary file is gone but a rolling backup survives. That is the
+    //     state an interrupted save leaves behind (the backup step used to
+    //     rename the primary out of the way before the replace), and it is also
+    //     what a stray delete looks like. Falling through to "first run" here
+    //     would materialise an EMPTY store and silently present the user with
+    //     no memory at all while their previous version sat right there in
+    //     .bak — so recover it, and promote the recovered data back to the
+    //     canonical path so the next boot finds it normally.
+    try {
+      const backup = await readStoreFile(storePath + '.bak')
+      if (backup !== null) {
+        const loaded = normalizeData(backup)
+        state.data = loaded.data
+        const promoted = await writeToDisk()
+        state.storageWarning = (droppedEntriesMessage(loaded.dropped) || '')
+          + (loaded.dropped > 0 ? '；' : '')
+          + 'memory.json 不存在，已从最近备份 memory.json.bak 恢复'
+          + (promoted ? '，并已写回 memory.json' : '；写回 memory.json 失败，下次保存时会重试')
+        state.loadedFrom = 'memory.json.bak (main file missing)'
+        return
+      }
+    } catch {
+      // An unusable backup must never block a fresh store; fall through.
+    }
+
     // 2. Migrate the pre-release location (host process cwd). This is the only
     //    reason the legacy name is still known to this plugin.
     const legacyPath = join(process.cwd(), LEGACY_FILE_NAME)
@@ -463,6 +749,7 @@ export function apply(ctx) {
           // Keep the original as evidence instead of deleting user data.
           await rename(legacyPath, legacyPath + '.migrated').catch(() => {})
         }
+        state.loadedFrom = 'legacy cwd file (migrated)'
         return
       }
     } catch (err) {
@@ -470,9 +757,31 @@ export function apply(ctx) {
       if (err instanceof SyntaxError) state.storageError = '旧位置文件解析失败，已忽略：' + describeError(err)
     }
 
-    // 3. First run: materialise an empty store so the path is real and the
-    //    settings page can show it.
-    await writeToDisk()
+    // 3. First run: there is no store anywhere. Deliberately write NOTHING.
+    //
+    //    This used to materialise an empty memory.json so the settings page had
+    //    a real path to show. That made the plugin perform a disk write at
+    //    process boot — i.e. with no session, no turn and no task — which is the
+    //    one side effect that a behaviour audit can legitimately call "running
+    //    with nothing to do". The file is now created by the first action that
+    //    genuinely needs it: a save, an import, or the settings page reading
+    //    `state` (see ensureStoreMaterialized). Until then the panel shows
+    //    "尚未写入磁盘", a state its UI already renders.
+    needsMaterialize = true
+    state.loadedFrom = 'first run (no store on disk yet)'
+    state.storeExists = false
+  }
+
+  /**
+   * Write the empty store, once, the first time something actually needs the
+   * file to exist. A failed attempt leaves the flag set so the next caller
+   * retries instead of silently pretending the file is there.
+   *
+   * @returns whether a write was performed and succeeded.
+   */
+  const ensureStoreMaterialized = async () => {
+    if (!needsMaterialize) return false
+    return writeToDisk()
   }
 
   /* ---------------- boot ---------------- */
@@ -486,6 +795,20 @@ export function apply(ctx) {
     })
     .then(() => {
       syncSection()
+      // The one always-on line: it answers "is memory mounted, where does it
+      // live, and how much is being injected?" without any further digging.
+      // 措辞很重要：`section=` 说的是"这个段落已就绪、若被装配会产出多少字符"，
+      // 而不是"已经注入"。在零会话时打印 `injected=` 会让人误以为记忆已经进入
+      // 了某个提示词。真正的注入证据是 pulls：宿主每拉取一次加一（初始必为 0）。
+      const chars = sectionText().length
+      logInfo('mounted: store=' + storePath
+        + ' from=' + String(state.loadedFrom)
+        + ' onDisk=' + (state.storeExists ? 'yes' : 'no')
+        + ' entries=' + state.data.entries.length
+        + ' enabled=' + (state.data.enabled === true)
+        + ' section=' + (chars > 0 ? chars + ' chars (pending assembly)' : 'nothing to inject')
+        + ' pulls=' + sectionPulls
+        + (state.storageError !== null ? ' error=' + state.storageError : ''))
     })
 
   /**
@@ -517,15 +840,23 @@ export function apply(ctx) {
       storage: {
         path: state.storageDisplay !== null ? state.storageDisplay : state.storagePath,
         error: state.storageError,
-        warning: state.storageWarning,
+        warning: state.storageWarning !== null ? state.storageWarning : state.backupError,
         savedAt: state.savedAt,
         migratedFrom: state.migratedFrom,
+        /** false until the store file has actually been written (see readFromDisk step 3). */
+        onDisk: state.storeExists,
       },
       injection: {
         registered: state.sectionRegistered,
         available: true,
         error: state.sectionError,
         chars: preview.length,
+        /**
+         * How many times the harness has pulled this section into a prompt since
+         * boot. 0 means "prepared, never assembled" — the distinction the old
+         * `injected=` log line could not make.
+         */
+        pulls: sectionPulls,
       },
       preview,
       limits: { minBudget: MIN_BUDGET, maxBudget: MAX_BUDGET, maxEntries: MAX_ENTRIES },
@@ -541,46 +872,78 @@ export function apply(ctx) {
 
   /* ---------------- commands (shared by route and callers) ---------------- */
 
+  /**
+   * Apply an in-memory mutation, persist it, and UNDO it when the write fails.
+   *
+   * Every mutating command used to edit `state.data`, re-register the prompt
+   * section, and only then find out that the disk write had failed. The panel
+   * said 保存失败 and memory.json was correctly left alone — but the injected
+   * system prompt kept carrying the unsaved edit for the rest of the process
+   * lifetime, so the model went on obeying an instruction the user had just
+   * been told was not saved. The successful write is the commit point: fail it
+   * and the in-memory state, the prompt section and the panel roll back
+   * together.
+   *
+   * @returns whether the store was persisted.
+   */
+  const commit = async (mutate) => {
+    const previousData = cloneData(state.data)
+    const previousWarning = state.storageWarning
+    mutate()
+    syncSection()
+    if (await writeToDisk()) {
+      // A successful save has rewritten the file to match memory, so a
+      // dropped-entries warning from load time ("they will be removed on the
+      // next save") has played out and must not keep showing.
+      state.storageWarning = null
+      return true
+    }
+    logDebug('commit rolled back: the disk write failed, in-memory state restored')
+    state.data = previousData
+    state.storageWarning = previousWarning
+    syncSection()
+    return false
+  }
+
   const saveEntry = (raw) => enqueue(async () => {
     const entry = sanitizeEntry(raw)
     if (entry === null) return { ok: false, saved: false, message: '标题与指令内容不能同时为空', snapshot: snapshot() }
     entry.updatedAt = Date.now()
-    const list = state.data.entries
-    const index = list.findIndex((candidate) => candidate.id === entry.id)
-    if (index >= 0) list[index] = entry
-    else {
-      if (list.length >= MAX_ENTRIES) {
-        return { ok: false, saved: false, message: '最多保存 ' + MAX_ENTRIES + ' 条指令', snapshot: snapshot() }
-      }
-      list.push(entry)
+    // Resolved before the mutation so a refusal can return a response instead
+    // of being swallowed as an early exit inside it.
+    const replacesExisting = state.data.entries.some((candidate) => candidate.id === entry.id)
+    if (!replacesExisting && state.data.entries.length >= MAX_ENTRIES) {
+      return { ok: false, saved: false, message: '最多保存 ' + MAX_ENTRIES + ' 条指令', snapshot: snapshot() }
     }
-    syncSection()
-    const saved = await writeToDisk()
-    // A successful save has rewritten the file to match memory, so a
-    // dropped-entries warning from load time ("they will be removed on the
-    // next save") has played out and must not keep showing.
-    if (saved) state.storageWarning = null
-    return settle(null, saved)
+    const cut = truncatedFields(raw)
+    const saved = await commit(() => {
+      const list = state.data.entries
+      const index = list.findIndex((candidate) => candidate.id === entry.id)
+      if (index >= 0) list[index] = entry
+      else list.push(entry)
+    })
+    const note = cut.length > 0
+      ? '已保存；' + cut.join('、') + '超过长度上限（标题 ' + MAX_TITLE + ' / 内容 ' + MAX_CONTENT + ' / 适用场景 ' + MAX_WHEN + ' 字符），超出部分已被截断'
+      : null
+    return settle(note, saved)
   })
 
   const deleteEntry = (id) => enqueue(async () => {
-    state.data.entries = state.data.entries.filter((entry) => entry.id !== id)
-    syncSection()
-    const saved = await writeToDisk()
-    if (saved) state.storageWarning = null
+    const saved = await commit(() => {
+      state.data.entries = state.data.entries.filter((entry) => entry.id !== id)
+    })
     return settle(null, saved)
   })
 
   const setOptions = (patch) => enqueue(async () => {
-    if (patch !== null && typeof patch === 'object') {
-      if (typeof patch.enabled === 'boolean') state.data.enabled = patch.enabled
-      if (typeof patch.budgetChars === 'number' && Number.isFinite(patch.budgetChars)) {
-        state.data.budgetChars = clampBudget(patch.budgetChars)
+    const saved = await commit(() => {
+      if (patch !== null && typeof patch === 'object') {
+        if (typeof patch.enabled === 'boolean') state.data.enabled = patch.enabled
+        if (typeof patch.budgetChars === 'number' && Number.isFinite(patch.budgetChars)) {
+          state.data.budgetChars = clampBudget(patch.budgetChars)
+        }
       }
-    }
-    syncSection()
-    const saved = await writeToDisk()
-    if (saved) state.storageWarning = null
+    })
     return settle(null, saved)
   })
 
@@ -617,10 +980,15 @@ export function apply(ctx) {
     // Merge, never replace: importing must not be able to wipe what is here.
     // Duplicates (same id, or same title+content) and invalid items are
     // skipped and counted, not silently dropped.
+    //
+    // The whole plan is computed BEFORE the store is touched, so the merge and
+    // its counters cannot disagree with what actually gets appended.
     const existing = state.data.entries
     const seenIds = new Set(existing.map((entry) => entry.id))
     const seenBodies = new Set(existing.map((entry) => entry.title + '\u0000' + entry.content))
-    let imported = 0
+    const accepted = []
+    const cutFields = new Set()
+    let truncatedCount = 0
     let skipped = 0
     for (const candidate of rawEntries) {
       const entry = sanitizeEntry(candidate)
@@ -628,32 +996,52 @@ export function apply(ctx) {
         skipped += 1
         continue
       }
-      if (existing.length >= MAX_ENTRIES) {
+      if (existing.length + accepted.length >= MAX_ENTRIES) {
         skipped += 1
         continue
       }
+      const cut = truncatedFields(candidate)
+      if (cut.length > 0) {
+        // sanitizeEntry enforces the limits silently, which is fine for the
+        // editor (its inputs carry the same maxLength) but wrong here: an
+        // imported 7,000-character instruction would come back as 6,000 with
+        // nothing said about the loss.
+        truncatedCount += 1
+        for (const field of cut) cutFields.add(field)
+      }
       entry.updatedAt = Date.now()
-      existing.push(entry)
+      accepted.push(entry)
       seenIds.add(entry.id)
       seenBodies.add(entry.title + '\u0000' + entry.content)
-      imported += 1
     }
-    if (imported === 0) {
-      return { ok: true, saved: true, message: '没有新增条目：' + skipped + ' 条已存在或无效', snapshot: snapshot() }
+    if (accepted.length === 0) {
+      // Nothing was written to disk, so claiming saved:true would be a lie the
+      // panel cannot distinguish from a real save.
+      return { ok: true, saved: false, message: '没有新增条目：' + skipped + ' 条已存在或无效', snapshot: snapshot() }
     }
-    syncSection()
-    const saved = await writeToDisk()
-    if (saved) state.storageWarning = null
-    return settle('导入完成：新增 ' + imported + ' 条，跳过 ' + skipped + ' 条（已存在或无效）', saved)
+    const saved = await commit(() => {
+      state.data.entries.push(...accepted)
+    })
+    const truncated = truncatedCount > 0
+      ? '；其中 ' + truncatedCount + ' 条超过长度上限，' + [...cutFields].join('、') + '已被截断'
+      : ''
+    return settle('导入完成：新增 ' + accepted.length + ' 条，跳过 ' + skipped + ' 条（已存在或无效）' + truncated, saved)
   })
 
   const dispatch = async (method, args) => {
     await boot
     switch (method) {
-      case 'state':
+      case 'state': {
+        // The settings page is the first thing that needs a real file on disk —
+        // it displays the absolute path, and the user may then hand-edit it.
+        // A first run writes nothing at boot (readFromDisk step 3), so the
+        // materialisation happens here, on a deliberate user action, instead of
+        // as a side effect of the host merely starting up.
+        await ensureStoreMaterialized()
         // Same envelope as every other method. One response shape means the
         // Client can never again be handed a payload it silently ignores.
         return { ok: true, saved: true, message: null, snapshot: snapshot() }
+      }
       case 'save-entry':
         return saveEntry(args !== null && typeof args === 'object' ? args.entry : null)
       case 'delete-entry':
@@ -673,84 +1061,119 @@ export function apply(ctx) {
 
   /* ---------------- same-origin JSON route for the Client half ---------------- */
 
+  // Which Host values this route accepts. Set when the route is registered,
+  // from the address the web server is actually bound to (see the long note on
+  // requestOriginVerdict). Until then the route does not exist at all, so the
+  // default only matters if something registers it out of band.
+  let guardHost = true
+
   let routeDispose = null
-  if (webServer !== undefined && typeof webServer.register === 'function') {
-    const handler = (req, res) => {
-      if (req.method !== 'POST') {
-        res.writeHead(405, { 'content-type': 'application/json; charset=utf-8' })
-        res.end(JSON.stringify({ ok: false, message: 'only POST is supported' }))
-        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
-      // readable 415 instead of a confusing parse failure.
-      const contentType = String(
-        (req.headers !== null && typeof req.headers === 'object') ? (req.headers['content-type'] || '') : '',
-      )
-      if (contentType.indexOf('application/json') === -1) {
-        res.writeHead(415, { 'content-type': 'application/json; charset=utf-8' })
-        res.end(JSON.stringify({ ok: false, message: 'content-type 必须是 application/json' }))
-        return
+  const handler = (req, res) => {
+    if (req.method !== 'POST') {
+      res.writeHead(405, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: false, message: 'only POST is supported' }))
+      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)
+    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
+    }
+    // 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
+    // readable 415 instead of a confusing parse failure.
+    const contentType = String(
+      (req.headers !== null && typeof req.headers === 'object') ? (req.headers['content-type'] || '') : '',
+    )
+    if (contentType.indexOf('application/json') === -1) {
+      res.writeHead(415, { 'content-type': 'application/json; charset=utf-8' })
+      res.end(JSON.stringify({ ok: false, message: 'content-type 必须是 application/json' }))
+      return
+    }
+    // A call aborted mid-flight (settings page closed, tab navigated away)
+    // makes these streams emit 'error'. A server stream with no error
+    // listener turns that into an uncaught exception — i.e. it would take
+    // the whole host process down over one dead HTTP request.
+    req.on('error', () => {})
+    res.on('error', () => {})
+    let body = ''
+    // Over the ceiling we stop accumulating but keep draining, so the
+    // response can go out as a clean 413 instead of a destroyed socket the
+    // Client can only report as a generic network failure.
+    let overflow = false
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      if (overflow) return
+      body += chunk
+      if (body.length > MAX_BODY_CHARS) {
+        overflow = true
+        body = ''
       }
-      // A call aborted mid-flight (settings page closed, tab navigated away)
-      // makes these streams emit 'error'. A server stream with no error
-      // listener turns that into an uncaught exception — i.e. it would take
-      // the whole host process down over one dead HTTP request.
-      req.on('error', () => {})
-      res.on('error', () => {})
-      let body = ''
-      // Over the ceiling we stop accumulating but keep draining, so the
-      // response can go out as a clean 413 instead of a destroyed socket the
-      // Client can only report as a generic network failure.
-      let overflow = false
-      req.setEncoding('utf8')
-      req.on('data', (chunk) => {
-        if (overflow) return
-        body += chunk
-        if (body.length > MAX_BODY_CHARS) {
-          overflow = true
-          body = ''
+    })
+    req.on('end', () => {
+      void (async () => {
+        if (overflow) {
+          res.writeHead(413, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+          res.end(JSON.stringify({ ok: false, message: '请求体超过 ' + MAX_BODY_CHARS + ' 字符上限' }))
+          return
         }
-      })
-      req.on('end', () => {
-        void (async () => {
-          if (overflow) {
-            res.writeHead(413, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
-            res.end(JSON.stringify({ ok: false, message: '请求体超过 ' + MAX_BODY_CHARS + ' 字符上限' }))
-            return
-          }
-          let result
-          try {
-            const payload = body === '' ? {} : JSON.parse(body)
-            result = await dispatch(payload.method, payload.args === undefined ? null : payload.args)
-          } catch (err) {
-            result = { ok: false, saved: false, message: describeError(err), snapshot: snapshot() }
-          }
-          res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
-          res.end(JSON.stringify(result))
-        })()
-      })
+        let result
+        try {
+          const payload = body === '' ? {} : JSON.parse(body)
+          result = await dispatch(payload.method, payload.args === undefined ? null : payload.args)
+        } catch (err) {
+          result = { ok: false, saved: false, message: describeError(err), snapshot: snapshot() }
+        }
+        res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+        res.end(JSON.stringify(result))
+      })()
+    })
+  }
+
+  // Register the settings-page route from a NON-BLOCKING child fiber. A web
+  // server must not be a precondition for this plugin: in a profile without one
+  // (headless, tui) a blocking dependency would keep the whole row pending,
+  // 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.
+  ctx.inject(['webServer'], (scope) => {
+    const webServer = scope.webServer
+    if (webServer === undefined || typeof webServer.register !== 'function') {
+      console.error('[instruction-memory] webServer published without a register(); the settings page cannot reach the host')
+      return
     }
+    // The Host allowlist only makes sense when the operator bound the server to
+    // loopback. `0.0.0.0` means they deliberately published it on every
+    // interface, where no Host value can be known in advance — enforcing a
+    // loopback allowlist there would break every legitimate client, so the
+    // check is disabled and the trade-off is documented in the README.
+    const boundHost = typeof webServer.host === 'string' ? webServer.host.trim().toLowerCase() : '127.0.0.1'
+    guardHost = boundHost !== '0.0.0.0'
     try {
       routeDispose = webServer.register({ kind: 'prefix', path: API_PREFIX, handler })
+      logDebug('settings route registered at ' + API_PREFIX + ' (boundHost=' + boundHost + ', hostGuard=' + guardHost + ')')
     } catch (err) {
       console.error('[instruction-memory] route registration failed:', err)
       routeDispose = null
     }
-  } else {
-    console.error('[instruction-memory] webServer unavailable: settings page will not be able to reach the host')
-  }
-
-  ctx.effect(() => () => {
-    if (routeDispose !== null) {
-      const dispose = routeDispose
-      routeDispose = null
-      try {
-        dispose()
-      } catch (err) {
-        console.error('[instruction-memory] route dispose failed:', err)
+    // The child fiber is owned by this one, so unmounting the plugin still
+    // disposes the route even though it was registered here.
+    scope.effect(() => () => {
+      if (routeDispose !== null) {
+        const dispose = routeDispose
+        routeDispose = null
+        try {
+          dispose()
+        } catch (err) {
+          console.error('[instruction-memory] route dispose failed:', err)
+        }
       }
-    }
+    })
   })
 }

package/package.json

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