@modusensus/dsh-mneme 0.9.2 → 0.9.4

package/src/tools.js

@@ -677,6 +677,241 @@ export function createTools(ctx, service, config, embedder) {
       }
     }),
 
+    // #231 第二批：agent 主动整理接口的调用入口。引擎在 src/organize.js（PR #267），
+    // 当时刻意「不进工具列表、不加独立 opt-in 开关——#249 到位时只差注册工具一步」，
+    // 本条就是那一步。工具描述是 agent 侧唯一的协议说明，所以两步规则（apply 必须带
+    // 真实 run_id、筛除=discard 不删任何东西、archive 可恢复）都写在这里：本体已经
+    // 强制了这些，描述的作用是让第一次调用就成功，而不是靠被拒后试错。
+    defineTool({
+      name: "memory_organize",
+      description:
+        "Close out a stretch of work: compare candidate memories against the store first, then land only what you decide to keep. " +
+        "Two steps through one tool. mode=dryRun (default) takes `candidates` and answers one verdict per candidate — exact / near / new — with the " +
+        "matched row when there is one; it writes NO memories, only an audit receipt. mode=apply takes that report's `run_id` plus one decision per " +
+        "candidate (save | discard) and may archive a row the report flagged as superseded (action=archive with that matched id). " +
+        "apply is rejected without a real run_id, and a report can be applied only once: candidates that were never compared cannot be written, and " +
+        "a row the report never matched cannot be archived. Discard keeps a candidate out and deletes nothing; archive is recoverable and never " +
+        "physically removes a row. This tool exists only when organizeEnabled is on (off by default, and off in lightweight mode) — if it is missing " +
+        "from your tool list the user has not enabled it. For a single write use memory_save instead.",
+      parameters: {
+        mode: { type: "string", description: '"dryRun" (default: compare and report, writes nothing) or "apply" (land the decisions of a reported dryRun)' },
+        candidates: {
+          type: "array",
+          // 宿主强制的 JSON Schema 子集要求 object 显式声明 additionalProperties，
+          // 所以候选字段在这里逐键写死：scope **来源**两列（*_scope_source）故意不给
+          // ——那是可信调用层盖的章，不是模型可自选的内容。
+          items: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              type: { type: "string", required: true, description: "Memory type (project / preference / constraint / ... ; 'document' is rejected here — it is minted by memory_register_document)" },
+              title: { type: "string", required: true, description: "Short stable title — part of the dedupe key (type + title + scope)" },
+              content: { type: "string", required: true, description: "The body that would be stored" },
+              importance: { type: "integer", description: "1-5 (default 3)" },
+              tags: { type: "array", items: { type: "string" }, description: "Optional tags" },
+              sensitivity: { type: "string", description: "Optional per-candidate sensitivity, overriding the payload-level default" },
+              agent_scope: { type: "string", description: "Optional per-candidate agent scope, overriding the payload-level default" },
+              workspace_scope: { type: "string", description: "Optional per-candidate workspace scope, overriding the payload-level default" }
+            }
+          },
+          description: "dryRun only: candidates to compare (hard cap 50 per call — this is for closing out a work stretch, not bulk import). Candidates missing type/title/content, or of type document, come back in `skipped`."
+        },
+        run_id: { type: "string", description: "apply only: the run_id returned by the dryRun report you are acting on" },
+        decisions: {
+          type: "array",
+          items: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              action: { type: "string", required: true, enum: ["save", "discard", "archive"], description: 'save writes the candidate at `index` through the normal dedupe path (an existing row with the same key is merged, not duplicated); discard keeps it out and deletes nothing; archive hides the row at `id` (recoverable, and only legal for a row this report matched)' },
+              index: { type: "integer", description: "save | discard: the candidate index from the dryRun report" },
+              id: { type: "string", description: "archive: id of the matched row to archive" }
+            }
+          },
+          description: "apply only: one entry per candidate you judged. Entries whose index the dryRun never accepted are reported in `skipped`."
+        },
+        sensitivity: { type: "string", description: "dryRun only: payload-level default sensitivity label for candidates that do not set their own (also the scope dimension the comparison runs within)" },
+        agent_scope: { type: "string", description: "dryRun only: payload-level default agent scope for candidates that do not set their own. 'global' or '*' widens visibility to every agent; any other value narrows it. Defaults to this session's auto-stamped agent label when scope labeling is on (same rule as memory_save)." },
+        workspace_scope: { type: "string", description: "dryRun only: payload-level default workspace scope for candidates that do not set their own. 'global' or '*' widens visibility to every workspace; any other value narrows it. Defaults to this session's auto-stamped workspace label when scope labeling is on." }
+      },
+      output: {
+        schema: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            // mode 是判别键：两种分支的返回键集不同，渲染与调用方都要靠它分流。
+            mode: { type: "string", required: true, enum: ["dryRun", "apply"] },
+            run_id: { type: "string", required: true },
+            status: { type: "string", required: true },
+            skipped: {
+              type: "array",
+              required: true,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  index: { type: "integer", required: true },
+                  action: { type: "string" },
+                  error: { type: "string", required: true },
+                  ids: { type: "array", items: { type: "string" } }
+                }
+              }
+            },
+            // --- dryRun 分支 ---
+            created_at: { type: "string" },
+            counts: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                total: { type: "integer", required: true },
+                exact: { type: "integer", required: true },
+                near: { type: "integer", required: true },
+                new: { type: "integer", required: true },
+                skipped: { type: "integer", required: true },
+                truncated: { type: "integer", required: true }
+              }
+            },
+            items: {
+              type: "array",
+              items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  index: { type: "integer", required: true },
+                  type: { type: "string", required: true },
+                  title: { type: "string", required: true },
+                  verdict: { type: "string", required: true, enum: ["exact", "near", "new"] },
+                  // match.sim 只在向量档命中时出现（exact 档无相似度可报）；
+                  // 归档目标必须是报告里出现过的 id，所以这条链接就是 archive 的凭据。
+                  match: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                      id: { type: "string", required: true },
+                      title: { type: "string", required: true },
+                      sim: { type: "number" }
+                    }
+                  }
+                }
+              }
+            },
+            // --- apply 分支 ---
+            dry_run_id: { type: "string" },
+            saved: { type: "integer" },
+            merged: { type: "integer" },
+            discarded: { type: "integer" },
+            archived: { type: "integer" },
+            memory_ids: { type: "array", items: { type: "string" } },
+            degraded: { type: "boolean" }
+          }
+        },
+        render: (_args, value) => {
+          if (value.mode === "apply") {
+            return TEXT_OUTPUT(
+              `organize applied (${value.run_id}, report ${value.dry_run_id}): ${value.saved} saved, ${value.merged} merged, ` +
+              `${value.archived} archived, ${value.discarded} discarded${value.skipped.length ? ` | ${value.skipped.length} skipped` : ""}.`
+            );
+          }
+          const c = value.counts;
+          return TEXT_OUTPUT(
+            `organize dryRun ${value.run_id}: ${c.total} compared — ${c.new} new, ${c.exact} exact, ${c.near} near` +
+            `${c.skipped ? `, ${c.skipped} rejected` : ""}${c.truncated ? `, ${c.truncated} over the cap not compared` : ""}. ` +
+            `Nothing was written; pass this run_id with your decisions to memory_organize mode=apply.`
+          );
+        }
+      },
+      async execute(args, exec) {
+        const mode = String(args?.mode ?? "dryRun").trim();
+        const scope = resolveSessionScope(exec);
+        const autoStamping = config?.scopeEnabled === true;
+        // 载荷级缺省与 memory_save 同源：显式参数盖 explicit 章，否则吃会话自动标注
+        // 盖 auto 章。少了这一步，整理接口就成了第二条「写进库却不带 scope」的通道
+        // ——candidates 会全部落在未标注（全局可见）那一档。
+        const agentLabel = args.agent_scope !== undefined
+          ? { value: normalizeExplicitScope(args.agent_scope), source: "explicit" }
+          : autoStamping && scope ? { value: scope.agent_scope, source: "auto" } : null;
+        const workspaceLabel = args.workspace_scope !== undefined
+          ? { value: normalizeExplicitScope(args.workspace_scope), source: "explicit" }
+          : autoStamping && scope ? { value: scope.workspace_scope, source: "auto" } : null;
+        const hiddenIds = [];
+        if (mode === "apply" && config?.strictScope === true && scope && Array.isArray(args.decisions)) {
+          // #170 复核项 4 的口径延伸（register_document 的 hiddenEvidenceIds 同形）：
+          // 他 scope 的 explicit 行按「不存在」处理，由**可信调用层**算好传入，绝不
+          // 取 payload 里的字段——那是调用方可自选的内容，不是授权。少了这一段，
+          // archive 就成了第二条绕过 scope 治理的改库通道。
+          for (const decision of args.decisions) {
+            if (String(decision?.action ?? "").trim() !== "archive") continue;
+            const id = String(decision?.id ?? "").trim();
+            if (!id) continue;
+            const row = service.getById(id);
+            if (row && !service.isVisibleInScope(row, scope)) hiddenIds.push(id);
+          }
+        }
+        const result = await service.organize(
+          {
+            mode,
+            ...(args.candidates !== undefined ? { candidates: args.candidates } : {}),
+            ...(args.run_id !== undefined ? { run_id: args.run_id } : {}),
+            ...(args.decisions !== undefined ? { decisions: args.decisions } : {}),
+            ...(args.sensitivity !== undefined ? { sensitivity: args.sensitivity } : {}),
+            ...(agentLabel ? { agent_scope: agentLabel.value, agent_scope_source: agentLabel.source } : {}),
+            ...(workspaceLabel ? { workspace_scope: workspaceLabel.value, workspace_scope_source: workspaceLabel.source } : {})
+          },
+          { hiddenIds }
+        );
+        if (mode === "apply") {
+          return {
+            mode: "apply",
+            run_id: result.run_id,
+            dry_run_id: result.dry_run_id,
+            status: result.status,
+            saved: result.saved,
+            merged: result.merged,
+            discarded: result.discarded,
+            archived: result.archived,
+            memory_ids: result.memory_ids,
+            skipped: result.skipped,
+            degraded: result.degraded
+          };
+        }
+        // dryRun 的落点必须过一遍调用方的可见性。`agent_scope` / `workspace_scope`
+        // 是模型自己给的参数，而 `organize.dryRun` 的比对只看三列**值**（不看
+        // `*_scope_source`、不调 `isVisibleInScope`）——不过这一关，dryRun 就成了
+        // 「那一档有没有这个标题」的探测口：#170 复核项 4 给 memory_get / memory_delete
+        // 的口径是「不存在」，这里也按不存在说，落点一个键都不带。
+        // counts 跟着重算：留着引擎那份计数，`exact: 1` 配一个不带 match 的条目本身就是
+        // 存在性oracle，等于把泄露从 id 挪到计数器。审计行仍存原始落点（那是给操作者看的
+        // 证据面），apply 侧另有 hiddenIds 挡归档。
+        const visibleItems = result.items.map((item) => {
+          const match = item.match && visibleUnderStrictScope(service.getById(item.match.id), exec) ? item.match : null;
+          return {
+            index: item.index,
+            type: item.type,
+            title: item.title,
+            verdict: match ? item.verdict : "new",
+            ...(match ? { match: { id: match.id, title: match.title, ...(match.sim != null ? { sim: match.sim } : {}) } } : {})
+          };
+        });
+        const verdictCount = (verdict) => visibleItems.filter((i) => i.verdict === verdict).length;
+        return {
+          mode: "dryRun",
+          run_id: result.run_id,
+          created_at: result.created_at,
+          status: result.status,
+          counts: {
+            total: visibleItems.length,
+            exact: verdictCount("exact"),
+            near: verdictCount("near"),
+            new: verdictCount("new"),
+            skipped: result.counts.skipped,
+            truncated: result.counts.truncated
+          },
+          items: visibleItems,
+          skipped: result.skipped
+        };
+      }
+    }),
+
     // 运行时口子（issue #131 / PR-C）。
     //
     // 为什么要有这个工具：mneme 的取向是「本体保持完善但轻量；重的功能存在、默认不开、不被依赖」。
@@ -805,10 +1040,14 @@ export function createTools(ctx, service, config, embedder) {
   const hiddenTools = new Set();
   if (config?.disableMemorySearch === true) hiddenTools.add("memory_search");
   if (config?.disableMemoryArchive === true) hiddenTools.add("memory_archive");
+  // #231 第二批是**反向**语义：memory_organize 默认不在场，organizeEnabled 打开才
+  // 注册。仍走同一个闸门而不是在数组里条件展开——模型看不到就不会调，这比在描述里
+  // 劝它别用可靠（上面那段 v0.8.5 的定性对两个方向都成立）。
+  if (config?.organizeEnabled !== true) hiddenTools.add("memory_organize");
 
   for (const tool of tools) {
     if (hiddenTools.has(tool.name)) {
-      ctx.logger?.info?.(`[dsh-mneme] tool "${tool.name}" hidden by config (disableMemorySearch/disableMemoryArchive)`);
+      ctx.logger?.info?.(`[dsh-mneme] tool "${tool.name}" hidden by config (disableMemorySearch/disableMemoryArchive/organizeEnabled)`);
       continue;
     }
     if (registeredTools.has(tool.name)) {

package/src/user-settings.js

@@ -0,0 +1,78 @@
+// dsh-mneme/src/user-settings.js
+// 「用户设置」注入块（人格 / 画像 / 规则）的唯一渲染处。
+//
+// 为什么要单独成模块：面板「Agent 眼中的画像」那张卡原本自己在前端拼了一份 profile +
+// rules 的列表，注释写着「注入生效文本」——但它没有表头、没有「- 用户画像：」前缀，
+// 也完全没有人格三行。两处渲染代码各写各的，就一定会漂；而漂了没人报错，因为两边都
+// 「看着像」。现在注入器与预览路由调同一个函数，前端只显示后端给的文本。
+//
+// 顺序是设计口径（人格设计稿⑥）：特化指令（人格）先出，画像与规则后出、后写覆盖占
+// 上风，rules 恒最硬。改这个顺序等于改提示词权重，别顺手调。
+
+import { STR, langOf } from "./lang.js";
+
+/**
+ * 提示词变量转义：宿主模板插值对 `{{`/`}}` 会按变量名解析并在缺失时抛错，整轮崩掉。
+ * 所以把 2 个以上连续花括号逐字符插 `\`，让任何 `{{`/`}}` 子串都不残留；转换幂等，
+ * 单花括号原样通过。`config.escapePromptVariables === false` 时退回原文。
+ *
+ * 住在这里是刻意的：预览必须与注入共用同一个转义，否则「同源」又是假的。
+ * `src/inject.js` 的同名闭包函数只是薄薄一层委托，其余调用点不动。
+ */
+export function escapePromptVars(config, text) {
+  if (config?.escapePromptVariables === false) return String(text);
+  return String(text).replace(/[{}]{2,}/g, (run) => run.split("").join("\\"));
+}
+
+/**
+ * 按会话身份取人格卡。返回 `{ card, source }`，`source` 是给面板解释「用的哪张卡」的
+ * 读数，不参与判定。
+ *
+ * `strict`（config.personaStrictAddressing，默认关）决定「有身份、没这张身份的卡」
+ * 与「这张卡被显式关掉」这两种情况：
+ * - 关（现状）：落 default 卡。default 于是变成「所有没建卡的 agent 都能拿到它」，
+ *   包括宿主里跑的外部 bot——它自带身份与设定，两处「你是谁」撞在同一帧里。
+ * - 开：不注入人格（`source: "none"`）。default 退回它的本意：只兜「这一帧解析不到
+ *   身份」的会话（无名会话本来就是 default 卡的受众）。
+ * 默认关是有意的：这是一次口径变更，不能让老用户的注入文本在升级后静默变化。
+ */
+export function resolvePersonaCard(settings, agentId, { strict = false } = {}) {
+  const store = settings.getPersona();
+  const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+  const card = id ? store.byAgent[id] : null;
+  if (card && card.enabled === true) return { card, source: "byAgent" };
+  if (id && strict) return { card: {}, source: "none" };
+  return { card: store.default, source: "default" };
+}
+
+/**
+ * 渲染整块「用户设置」。`agentId` 是会话身份（解析不到传 null → 走 default 兜底）。
+ * 返回 `{ text, source, agent, configGate }`：`text` 为最终注入文本（全空时 ""），
+ * `configGate` 是 personaEnabled 的现值——面板要靠它解释「卡开着为什么没生效」。
+ */
+export function renderUserSettingsBlock({ settings, config, agentId = null }) {
+  const language = langOf(config);
+  const profile = settings.getProfile().trim();
+  const rules = settings.getRules();
+  const enabled = config?.personaEnabled === true;
+  const resolved = enabled
+    ? resolvePersonaCard(settings, agentId, { strict: config?.personaStrictAddressing === true })
+    : { card: {}, source: "default" };
+  const persona = resolved.card;
+  const personaLines = persona?.enabled === true
+    ? [
+        ...(typeof persona.name === "string" && persona.name.trim() ? [STR.personaNameLine[language](persona.name.trim())] : []),
+        ...(typeof persona.personality === "string" && persona.personality.trim() ? [STR.personaPersonalityLine[language](persona.personality.trim())] : []),
+        ...(typeof persona.replyStyle === "string" && persona.replyStyle.trim() ? [STR.personaReplyStyleLine[language](persona.replyStyle.trim())] : [])
+      ]
+    : [];
+  const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : null;
+  if (!profile && !rules.length && !personaLines.length) {
+    return { text: "", source: resolved.source, agent: id, configGate: enabled };
+  }
+  const lines = [STR.userSettingsHeader[language]];
+  lines.push(...personaLines);
+  if (profile) lines.push(STR.profileLine[language](profile));
+  for (const rule of rules) lines.push(STR.ruleLine[language](rule));
+  return { text: escapePromptVars(config, lines.join("\n")), source: resolved.source, agent: id, configGate: enabled };
+}

package/test/api-nudge-route.test.js

@@ -0,0 +1,259 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import zlib from "node:zlib";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createApi } from "../src/api.js";
+import { createSettings } from "../src/settings.js";
+
+// /api/dsh-mneme/nudge 的接线锁。三件事分开守，因为它们混在一起时各自的失败长得一样：
+//   1. policy 是 token-write —— GET 免 token（面板每刷一次就 GET 一次），POST 要 token（会写盘）；
+//   2. 「读不到」与「确实没有」必须回不同状态码（503 vs 200），否则故障会被当成答案；
+//   3. GET 是预览、不许落盘 —— 这一条是接线时发现真 bug 的地方：nudgeFromSessions
+//      原先只要算得出项目键就无条件写提议，而面板刷新一次就是一次 GET。
+
+function tmpDir() {
+  return mkdtempSync(join(tmpdir(), "mneme-nudge-route-"));
+}
+
+async function withDir(fn) {
+  const dir = tmpDir();
+  try {
+    return await fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** 一行会话日志，形状照 DSH 会话文件：data.message.content[] 里是 tool-call。 */
+function sessionLine(calls) {
+  const content = calls.map((c) => ({ type: "tool-call", name: c.name, arguments: JSON.stringify(c.args || {}) }));
+  return JSON.stringify({ time: 1700000000000, data: { turn: 1, message: { content } } });
+}
+
+/** 造一份会话日志：sessions/<桶>/<会话>/session.v4.jsonl.zstd，头行带 cwd。 */
+function writeSession(dshHome, { bucket, sessionId, cwd, calls }) {
+  const sub = join(dshHome, "sessions", bucket, sessionId);
+  mkdirSync(sub, { recursive: true });
+  const head = JSON.stringify({ time: 1700000000000, cwd });
+  const body = sessionLine(calls);
+  writeFileSync(join(sub, "session.v4.jsonl.zstd"), zlib.zstdCompressSync(Buffer.from([head, body].join("\n"), "utf8")));
+}
+
+class FakeRes extends EventEmitter {
+  constructor() { super(); this.statusCode = 200; this.body = ""; }
+  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
+  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
+}
+
+/**
+ * POST 分支返回的是「已排进微任务的 promise」，不是自己的 promise：handler 直接
+ * `return;`（src/api.js:2069-2075）。所以拿到 FakeRes 不够，必须等它真的 end，
+ * 否则断言跑在正文还没写之前——第一次写这个文件就是在这里被 200 !== 400 骗了。
+ */
+function awaitEnd(res) {
+  return new Promise((resolve) => res.once("end", resolve));
+}
+
+function req(path, method = "GET", body = null, headers = {}) {
+  const r = new EventEmitter();
+  r.url = path;
+  r.method = method;
+  r.headers = headers;
+  if (body !== null) {
+    process.nextTick(() => {
+      r.emit("data", Buffer.from(JSON.stringify(body)));
+      r.emit("end");
+    });
+  }
+  return r;
+}
+
+function setup({ apiToken = "", memoryDir = null } = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const commands = { add: () => {}, remove: () => {}, list: () => [] };
+  const routes = [];
+  const ctx = { webServer: { register(route) { routes.push(route); return () => {}; } } };
+  createApi(ctx, service, settings, commands, null, undefined, apiToken, { memoryDir });
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/nudge");
+  assert.ok(route, "路由没注册");
+  return { route, store };
+}
+
+test("/nudge：policy 是 token-write —— GET 免 token，POST 要 token", async () => {
+  const { route } = setup({ apiToken: "secret-token" });
+
+  // GET 是预览（只读），与 /pipeline、/candidates 同级：不带 token 也要能读。
+  // 面板每次展开 M.O. 都会 GET 一次，要 token 等于让预览永远 401。
+  const get = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/nudge?project=relative"), get);
+  assert.notEqual(get.statusCode, 401, "GET 不该要 token");
+
+  // POST 会真写盘（落提议），一律受门控。没有这道闸，任何能打开面板的页面
+  // 都能往记忆库里塞文件。
+  const post = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/nudge?project=relative", "POST", {}), post);
+  assert.equal(post.statusCode, 401);
+  assert.equal(JSON.parse(post.body).error, "unauthorized");
+
+  // 带 token 才放行到业务判断（这里 project 是相对路径，应当由业务层回 400）。
+  const ok = new FakeRes();
+  const okDone = awaitEnd(ok);
+  route.handler(req("/api/dsh-mneme/nudge?project=relative", "POST", {}, { authorization: "Bearer secret-token" }), ok);
+  await okDone;
+  assert.equal(ok.statusCode, 400);
+});
+
+test("/nudge：project 必须是绝对路径，相对路径拒掉而不是静默退成全局", async () => {
+  // 与 /pipeline、/candidates 同一条规矩。忽略相对路径会静默退成「全局」，
+  // 而全局看起来一切正常——那是最难查的一类错。
+  return withDir((dir) => {
+    const { route } = setup({ memoryDir: join(dir, "memory") });
+    const res = new FakeRes();
+    route.handler(req("/api/dsh-mneme/nudge?project=dsh-mneme", "GET"), res);
+    assert.equal(res.statusCode, 400);
+    assert.equal(JSON.parse(res.body).error, "project-not-absolute");
+  });
+});
+
+test("/nudge：「读不到会话」回 503，「这个项目确实没有」回 200", async () => {
+  // 两者在候选列表上都表现为空。混成一个状态码，调用方就只能瞎猜是「没东西」还是「坏了」。
+  await withDir((dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    const { route } = setup({ memoryDir: join(dir, "memory") });
+
+    const prev = process.env.DSH_HOME;
+    // 会话根根本不存在 → 新机器 / 路径配错，是**环境问题**。
+    process.env.DSH_HOME = join(dir, "home-missing");
+    try {
+      const broken = new FakeRes();
+      route.handler(req("/api/dsh-mneme/nudge?project=" + encodeURIComponent(projectRoot), "GET"), broken);
+      assert.equal(broken.statusCode, 503);
+      const brokenDoc = JSON.parse(broken.body);
+      assert.equal(brokenDoc.error, "nudge-sessions-unreadable");
+      assert.equal(brokenDoc.skipped, true);
+      assert.equal(brokenDoc.counts.candidates, 0);
+
+      // 有一个桶，但 cwd 指向别处 → 关于这个项目的**答案**：它还没跑过会话。
+      const home = join(dir, "home-other");
+      writeSession(home, {
+        bucket: "other-bucket",
+        sessionId: "sess-x",
+        cwd: join(dir, "somewhere-else"),
+        calls: [{ name: "skill", args: { name: "alpha" } }]
+      });
+      process.env.DSH_HOME = home;
+      const none = new FakeRes();
+      route.handler(req("/api/dsh-mneme/nudge?project=" + encodeURIComponent(projectRoot), "GET"), none);
+      assert.equal(none.statusCode, 200);
+      const noneDoc = JSON.parse(none.body);
+      assert.equal(noneDoc.skipped, true);
+      assert.equal(noneDoc.skippedReason, "no-session-attribution");
+      assert.equal(noneDoc.attribution.reason, "no-bucket");
+      // 跳过与跑完必须是同一句边界话术（同一个 NUDGE_BOUNDARIES 常量）。
+      assert.equal(noneDoc.boundaries.autoActivate, false);
+      assert.equal(noneDoc.boundaries.writesOnlyDrafts, true);
+    } finally {
+      if (prev === undefined) delete process.env.DSH_HOME;
+      else process.env.DSH_HOME = prev;
+    }
+  });
+});
+
+test("/nudge：GET 只预览不落盘，POST 才写提议；materialize 默认关", async () => {
+  // 这条是接线时抓到的真 bug：nudgeFromSessions 原先只要算得出项目键就无条件
+  // 写提议，而面板每刷一次就 GET 一次 —— 等于每刷新一次往记忆库塞一批文件。
+  await withDir(async (dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    const memoryDir = join(dir, "memory");
+    const dshHome = join(dir, "dsh-home");
+    const calls = [
+      { name: "skill", args: { name: "alpha" } },
+      { name: "skill", args: { name: "beta" } },
+      { name: "pwsh", args: { command: "npm test" } }
+    ];
+    writeSession(dshHome, { bucket: "ws-bucket", sessionId: "sess-a", cwd: projectRoot, calls });
+    // 两个会话走同一段序列才够 NUDGE_MIN_SUPPORT=2（数的是会话，不是次数）。
+    writeSession(dshHome, { bucket: "ws-bucket", sessionId: "sess-b", cwd: projectRoot, calls });
+
+    const prev = process.env.DSH_HOME;
+    process.env.DSH_HOME = dshHome;
+    try {
+      const { route } = setup({ memoryDir });
+
+      const preview = new FakeRes();
+      await route.handler(req("/api/dsh-mneme/nudge?project=" + encodeURIComponent(projectRoot), "GET"), preview);
+      assert.equal(preview.statusCode, 200);
+      const previewDoc = JSON.parse(preview.body);
+      assert.equal(previewDoc.skipped, false);
+      assert.equal(previewDoc.attribution.reason, "matched");
+      assert.ok(previewDoc.counts.candidates >= 1, "真数据里必须挖得出候选");
+      assert.equal(previewDoc.counts.savedProposals, 0, "预览不许落提议");
+      assert.equal(existsSync(join(memoryDir, "proposals")), false);
+
+      const real = new FakeRes();
+      const realDone = awaitEnd(real);
+      route.handler(req("/api/dsh-mneme/nudge?project=" + encodeURIComponent(projectRoot), "POST", {}), real);
+      await realDone;
+      assert.equal(real.statusCode, 200);
+      const realDoc = JSON.parse(real.body);
+      assert.equal(realDoc.counts.savedProposals, realDoc.counts.candidates);
+      assert.ok(existsSync(realDoc.proposalsDir));
+      // 落草稿是「往仓库里塞文件」，必须 body.materialize===true 才做；自动跑的
+      // 默认语义就是不碰仓库，端点必须与它一致。
+      assert.equal(realDoc.counts.draftsWritten, 0);
+      assert.equal(existsSync(join(projectRoot, ".mneme", "pipelines")), false);
+    } finally {
+      if (prev === undefined) delete process.env.DSH_HOME;
+      else process.env.DSH_HOME = prev;
+    }
+  });
+});
+
+test("/nudge：PATCH/DELETE 一律 405，绝不落进「不是 GET/HEAD 就算写」的分支", async () => {
+  // 这条是从评审里捞出来的真洞：persistProposals 按「method !== GET && !== HEAD」算，
+  // 而方法分流只拦 PUT/POST，于是带 token 的 PATCH/DELETE 会直落 run(null)、
+  // 当成写动作往 memoryDir 里落提议——一个不需要 body 的静默写盘口，正好打在
+  // 这个端点「GET 只预览、写动作一律要 POST」的卖点上。
+  await withDir(async (dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    const memoryDir = join(dir, "memory");
+    const dshHome = join(dir, "dsh-home");
+    const calls = [
+      { name: "skill", args: { name: "alpha" } },
+      { name: "skill", args: { name: "beta" } }
+    ];
+    writeSession(dshHome, { bucket: "ws-bucket", sessionId: "sess-a", cwd: projectRoot, calls });
+    writeSession(dshHome, { bucket: "ws-bucket", sessionId: "sess-b", cwd: projectRoot, calls });
+
+    const prev = process.env.DSH_HOME;
+    process.env.DSH_HOME = dshHome;
+    try {
+      const { route } = setup({ apiToken: "secret-token", memoryDir });
+      for (const verb of ["PATCH", "DELETE"]) {
+        const res = new FakeRes();
+        // 带合法 token：证明拦住它的是方法白名单，不是鉴权。
+        await route.handler(req("/api/dsh-mneme/nudge?project=" + encodeURIComponent(projectRoot), verb, {}, { authorization: "Bearer secret-token" }), res);
+        assert.equal(res.statusCode, 405, verb + " 必须回 405");
+        const doc = JSON.parse(res.body);
+        assert.equal(doc.error, "method-not-allowed");
+        assert.equal(doc.allow, "GET, HEAD, POST, PUT");
+        assert.equal(res.headers?.Allow, "GET, HEAD, POST, PUT", "405 要带 Allow 头");
+      }
+      // 最硬的一条：这里必须**一个文件都没落**。只看状态码会漏掉「先写再报错」。
+      assert.equal(existsSync(join(memoryDir, "proposals")), false, "PATCH/DELETE 不许落提议");
+    } finally {
+      if (prev === undefined) delete process.env.DSH_HOME;
+      else process.env.DSH_HOME = prev;
+    }
+  });
+});

package/test/api.test.js

@@ -747,7 +747,14 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   // 两个都是嵌套对象子字段，都进 NESTED_FLAG_PATHS）。
   // 合并 #451（人格页）后的真实计数：98（本批前）+ actionRunEnabled + personaEnabled = 99
   // #471 再 + 2 = 101。
-  assert.equal(Object.keys(data.effective).length, 101);
+  // v0.9.3 新增 actionNudgeEnabled（M.O. 自动沉淀；顶层扁平键）= 102。
+  // issue #493 新增 summarizeParseFailureMaxRetries（连续解析失败后放弃窗口的
+  // 护栏，int 键走 INT_RANGES 表）= 103。
+  // issue #231 第二批新增 organizeEnabled（memory_organize 的暴露闸；顶层扁平键，
+  // 不需要 NESTED_FLAG_PATHS 条目）= 104。
+  // 人格寻址口径新增 personaStrictAddressing（顶层扁平键，同上）= 105。
+  // issue #497 新增 profileExtractEnabled（画像提取草稿；顶层扁平键，同上）= 106。
+  assert.equal(Object.keys(data.effective).length, 106);
   assert.equal(data.effective.dreamSkipInvalid, true);
   assert.equal(data.effective.allowCrossTypeMerge, false);
   assert.equal(data.effective.dreamMergeGuard, true);
@@ -792,6 +799,17 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   assert.equal(data.effective.actionRunEnabled, false);
   // 人格页（beta）：注入总闸默认关，effective 必须能读到（同 #254 坑形防线）。
   assert.equal(data.effective.personaEnabled, false);
+  // 人格寻址口径：默认关 = 历史兜底行为不变（升级后不许有人格静默消失或新增）。
+  assert.equal(data.effective.personaStrictAddressing, false);
+  // 画像提取默认关：面板按钮在用户没开启前不该偷偷花一次 LLM 调用。
+  assert.equal(data.effective.profileExtractEnabled, false);
+  // v0.9.3：M.O. 自动沉淀的第三个键。与 actionPipelineEnabled（看图）、
+  // actionRunEnabled（记账）都不是一件事——它挂 session/event 并解压会话日志，
+  // 是三者里最重的一条，所以独立开关、默认关、且进 LIGHT_MODE_OFF。
+  assert.equal(data.effective.actionNudgeEnabled, false);
+  // issue #231 第二批：整理接口的暴露闸默认关（关 = memory_organize 根本不注册）。
+  // 面板要能读到这一格，否则用户开了也不见效、还以为是 bug。
+  assert.equal(data.effective.organizeEnabled, false);
   // 新增字符串 / URL / 枚举键
   assert.equal(data.effective.localEmbedModel, "Xenova/bge-small-zh-v1.5");
   assert.equal(data.effective.ollamaBaseUrl, "http://localhost:11434");