@modusensus/dsh-mneme 0.9.0 → 0.9.2

package/src/api.js

@@ -1,5 +1,6 @@
 import { URL } from "node:url";
 import { isAbsolute } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
 import { timingSafeEqual, randomBytes } from "node:crypto";
 import { FEATURE_FLAG_SPEC } from "./settings.js";
 import { TYPES } from "./store.js";
@@ -12,7 +13,10 @@ import { describeLocalRuntime, publicRuntimeStatus } from "./runtime/loader.js";
 import { hostModulesDir, provisionRuntime } from "./runtime/provision.js";
 import { classify, fetchLatestVersion, PACKAGE_VERSION } from "./version-check.js";
 import { parseReclaimQuery, parseReclaimJson, readReclaimFields, reclaimReply, RECLAIM_UNAVAILABLE } from "./reclaim-http.js";
-import { readPipelineDoc } from "./pipeline.js";
+import { readPipelineDoc, loadPipelines, projectPipelineDir } from "./pipeline.js";
+import { loadRunsById, runsDir, RUNS_SUFFIX } from "./pipeline-runs.js";
+import { observationDir, loadObservationsById } from "./pipeline-observations.js";
+import { projectKey } from "./candidates.js";
 import { readCandidateDoc } from "./candidates.js";
 
 // headers：少数端点（/export 附件下载）需要追加 Content-Disposition 等响应头。
@@ -37,6 +41,16 @@ function sendAttachment(res, status, contentType, filename, body) {
 // defaults in config.js (externalApiPort / externalApiHost).
 const EXTERNAL_API_DEFAULTS = { enabled: false, port: 8790, host: "127.0.0.1" };
 
+// 请求体上限（防御，不是功能）：readBody 只累加字符串，不设上限时一个超大 body
+// 就能把进程内存拉到 Content-Length 那个量级。4 MiB 远高于任何真实写入（记忆
+// 正文、导入的 markdown、面板 patch 都远小于它）。
+const MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
+// 分页上界（防御）：list/search 的参数直接进 SQL LIMIT，无上界时
+// ?limit=100000 会让一次免鉴权 GET 把全库序列化出来（2026-10 审计：免鉴权读面
+// + 浏览器简单请求 = 廉价 DoS）。1000/200 远高于面板与 CLI 的任何真实用法。
+const MAX_PAGE_LIMIT = 1000;
+const MAX_SEARCH_TOP_K = 200;
+
 /** Merge persisted external-api kv over the defaults for client display. */
 function fullExternalConfig(kv = {}) {
   return {
@@ -70,22 +84,82 @@ function isAuthorized(req, apiToken) {
 }
 
 /**
- * Reject a request with 401 when auth is enabled and the token is missing or
- * wrong. Returns true when the request may proceed.
+ * 路由鉴权策略（2026-10 审计的结构性修法）。三条：
+ *   open        永不鉴权——「公开读面」，必须写进 SECURITY.md 的安全模型表
+ *   token       配置了 apiToken 就整条要带（写路由 + 敏感读）
+ *   token-write 只有非 GET/HEAD 才要 token（面板要读、只有写才有副作用）
+ *
+ * 少声明不是「默认开放」：register 直接抛错，插件起不来。这是本方案的要点——
+ * 「新增路由忘了加鉴权」从运行期静默漏洞变成装配期硬失败，不依赖谁记得写、也
+ * 不依赖测试有没有覆盖到（/export 就是这么漏的，见 2026-10 审计 P0）。
  */
-function requireAuth(req, res, apiToken) {
-  if (isAuthorized(req, apiToken)) return true;
-  sendJson(res, 401, { error: "unauthorized" });
-  return false;
+export const ROUTE_POLICIES = Object.freeze(["open", "token", "token-write"]);
+
+/** True when this request must present the apiToken under the route's policy. */
+function needsToken(req, policy, apiToken) {
+  if (policy === "open") return false;
+  const method = String(req.method || "GET").toUpperCase();
+  if (policy === "token-write" && (method === "GET" || method === "HEAD")) return false;
+  return !isAuthorized(req, apiToken);
+}
+
+/**
+ * 唯一的登记入口：校验 policy、拒绝重复路径、把 handler 包上鉴权。
+ * 返回的 count() 供 createApi 汇报真实路由数（此前的字面量 36 已经和现实脱节）。
+ */
+export function createRouteRegistrar(webServer, apiToken, disposers) {
+  const seen = new Set();
+  const register = (route) => {
+    if (!ROUTE_POLICIES.includes(route.policy)) {
+      throw new Error(
+        `[dsh-mneme] 路由 ${route.path} 必须声明 policy（${ROUTE_POLICIES.join(" / ")}），` +
+        `实际是 ${JSON.stringify(route.policy)}。先想清楚它属于哪一类，再同步 SECURITY.md 的安全模型表。`
+      );
+    }
+    const key = `${route.kind}:${route.path}`;
+    if (seen.has(key)) throw new Error(`[dsh-mneme] 路由 ${key} 被重复登记`);
+    seen.add(key);
+    const inner = route.handler;
+    const handler = (req, res) => {
+      if (!needsToken(req, route.policy, apiToken)) return inner(req, res);
+      sendJson(res, 401, { error: "unauthorized" });
+      return undefined;
+    };
+    disposers.push(webServer.register({ ...route, handler }));
+  };
+  return { register, count: () => seen.size };
 }
 
-/** Collect the request body as text (tolerant of empty/invalid bodies). */
-function readBody(req) {
+
+/**
+ * Collect the request body as text, or null when it exceeds the cap.
+ *
+ * 超限时**必须回 null 而不是空串**：空串经 parseBody 变成 {}，而 /profile、
+ * /rules、/persona 的 PUT 会把「字段缺失」当成「用户要清空」——一个 5 MiB 的
+ * 请求就能把画像/规则/人格静默清掉。返回 null 让调用点在碰任何 store 之前
+ * 直接 413（2026-10 评审指出的数据损坏路径）。
+ * 连接不 destroy：调用方要能收到明确的 413，而不是被掐断。
+ */
+function readBody(req, res) {
   return new Promise((resolve) => {
     let body = "";
-    req.on("data", (chunk) => { body += chunk; });
-    req.on("end", () => resolve(body));
-    req.on("error", () => resolve(""));
+    let bytes = 0;
+    let overflow = false;
+    req.on("data", (chunk) => {
+      if (overflow) return;
+      bytes += chunk.length;
+      if (bytes > MAX_REQUEST_BODY_BYTES) {
+        overflow = true;
+        body = "";
+        sendJson(res, 413, { error: "payload-too-large", limit: MAX_REQUEST_BODY_BYTES });
+        return;
+      }
+      body += chunk;
+    });
+    req.on("end", () => resolve(overflow ? null : body));
+    // 超限后再来 transport error 也必须保留超限状态：否则调用点会拿着空串
+    // 继续往 store 写（PUT /persona 把 "" 解析成 {}，覆盖既有设置）。
+    req.on("error", () => resolve(overflow ? null : ""));
   });
 }
 
@@ -133,6 +207,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   // feature flags 快照（GET/PUT 共用）：overrides 是持久化的用户显式覆盖；
   // effective 是启动配置在白名单键上被 overrides 覆盖后的最终值。config 缺席
   // （旧调用方直连、未传 cfg）时只报被覆盖的键，不把不存在的默认值编造给前端。
+  //
+  // pendingRestart 回答的是第三个问题：「我改的开关，现在真的生效了吗？」
+  // 功能开关的生效节奏与 panel_mode 相同——启动时由 index.js 合并进 cfg，运行中
+  // 那份 cfg 是冻结的（见 index.js 装配处的注释）。于是面板显示「已改」不等于
+  // 运行时已改：#481 实测人格总闸正是这样，面板开着、人格段却不注入，用户只能
+  // 靠反复试错发现。effective 表达的是「运行时取什么值」（overrides 优先），
+  // **反推不出待重启**，必须另比一次冻结值——这是本字段存在的唯一理由。
+  // 只报「显式覆盖 ≠ 冻结值」的键：未被覆盖的键运行时值就是 cfg 值，不存在落差；
+  // config 缺席（旧调用方直连、未传 cfg）时无从比较，返回空数组而不编造。
   const flagKeys = [
     ...FEATURE_FLAG_SPEC.booleans,
     ...Object.keys(FEATURE_FLAG_SPEC.ints),
@@ -158,7 +241,11 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     // Issue #399：蒸馏原文留存 + 溯源。两个键都是嵌套子字段（enabled 开关 +
     // retentionDays 整数），漏登记的后果同上——effective 静默缺键。
     "distillRecords.enabled": ["distillRecords", "enabled"],
-    "distillRecords.retentionDays": ["distillRecords", "retentionDays"]
+    "distillRecords.retentionDays": ["distillRecords", "retentionDays"],
+    // Issue #471：政策轴——作用域级可逆闸门。两个键都是嵌套子字段，漏登记的后果
+    // 同上（effective 静默缺键、面板读不到也 PUT 不进）。
+    "scopeState.enabled": ["scopeState", "enabled"],
+    "scopeState.enforce": ["scopeState", "enforce"]
     // sensitiveScanEnabled（#164 A2）是顶层扁平键，不需要进这张表——走 configFlagValue
     // 的默认分支即可。
   };
@@ -167,6 +254,19 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     if (path) return config?.[path[0]]?.[path[1]];
     return config?.[key];
   }
+  // 「显式覆盖 ≠ 冻结值」的键。用 Object.is 比而不是 !==：NaN 与 ±0 的边角上
+  // 两者会给出相反的结论（Object.is(NaN, NaN) 为真、Object.is(0, -0) 为假），
+  // 开关值里虽然不该出现它们，但比较语义与「值是否相同」对齐更省心。
+  // 未被覆盖的键不看：它的运行时值本来就取自 cfg，不存在落差。
+  function pendingRestartKeys(overrides) {
+    if (!config) return [];
+    const pending = [];
+    for (const key of flagKeys) {
+      if (overrides[key] === undefined) continue;
+      if (!Object.is(overrides[key], configFlagValue(key))) pending.push(key);
+    }
+    return pending;
+  }
   function featureSnapshot() {
     const overrides = settings.getFeatureFlags();
     const effective = {};
@@ -177,7 +277,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         if (value !== undefined) effective[key] = value;
       }
     }
-    return { overrides, effective };
+    return { overrides, effective, pendingRestart: pendingRestartKeys(overrides) };
   }
 
   // Ensure the service has an embedder when the API layer was handed one
@@ -187,14 +287,14 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     service.setEmbedder(embedder);
   }
 
-  const register = (route) => {
-    disposers.push(webServer.register(route));
-  };
+  // 所有路由都经这一处登记：policy 必填、鉴权在这里统一判定（见 createRouteRegistrar）。
+  const { register, count: countRoutes } = createRouteRegistrar(webServer, apiToken, disposers);
 
   // /api/dsh-mneme prefix fallback → 404 JSON for unknown sub-paths
   register({
     kind: "prefix",
     path: "/api/dsh-mneme",
+    policy: "open",
     handler(req, res) {
       sendJson(res, 404, { error: "not-found" });
     }
@@ -205,6 +305,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/info",
+    policy: "open",
     handler(req, res) {
       sendJson(res, 200, { version: PACKAGE_VERSION });
     }
@@ -217,6 +318,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/version-check",
+    policy: "open",
     handler(req, res) {
       if (req.method !== "GET") {
         sendJson(res, 404, { error: "not-found" });
@@ -236,11 +338,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/list",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
         const type = url.searchParams.get("type") ?? undefined;
-        const limit = Number(url.searchParams.get("limit") ?? 50);
+        // 上界是防御：参数直接进 SQL LIMIT（见 MAX_PAGE_LIMIT 注释）。
+        const limit = Math.min(Number(url.searchParams.get("limit") ?? 50), MAX_PAGE_LIMIT);
         const offset = Number(url.searchParams.get("offset") ?? 0);
         // order=chrono: pure newest-first for paged browsing; default keeps
         // the importance-ranked order other callers rely on.
@@ -292,6 +396,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/recall-stats",
+    policy: "open",
     handler(req, res) {
       if (req.method !== "GET") {
         sendJson(res, 404, { error: "not-found" });
@@ -311,11 +416,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/search",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
         const q = url.searchParams.get("q") ?? "";
-        const limit = Number(url.searchParams.get("topK") ?? url.searchParams.get("limit") ?? 20);
+        // 上界是防御：topK 直接进召回（见 MAX_SEARCH_TOP_K 注释）。
+        const limit = Math.min(Number(url.searchParams.get("topK") ?? url.searchParams.get("limit") ?? 20), MAX_SEARCH_TOP_K);
         // mode selects the recall strategy (defaults to auto):
         //   auto    (default) keyword first, vector fills remaining slots
         //   hybrid  vector first, keyword fills remaining slots; scores of
@@ -355,11 +462,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/profile",
+    policy: "token-write",
     handler(req, res) {
       try {
         if (req.method === "PUT" || req.method === "POST") {
-          if (!requireAuth(req, res, apiToken)) return;
-          return readBody(req).then((text) => {
+          return readBody(req, res).then((text) => {
+            if (text === null) return;
             const body = parseBody(text);
             settings.setProfile(typeof body.profile === "string" ? body.profile : "");
             sendJson(res, 200, { profile: settings.getProfile() });
@@ -372,6 +480,44 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- agent persona（人格定义页，beta） -------------------------------------
+  // 形状照抄 /profile 路由（设计稿②）：写方法走 requireAuth + readBody + parseBody。
+  // v1.2 多卡：GET 回全量 { default, byAgent }；PUT 双形——单对象形（旧面板）只更新
+  // default 且 byAgent 保留（合并语义，settings.setPersona 内判形状），多卡形全量
+  // 替换。坏体守卫：jsonOk=false 时保值回显，不清空库内现值。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/persona",
+    policy: "token-write",
+    handler(req, res) {
+      try {
+        if (req.method === "PUT" || req.method === "POST") {
+          return readBody(req, res).then((text) => {
+            if (text === null) return;
+            // parseBody 对坏 JSON 回 {}（容错不抛），所以这里的守卫必须把
+            // 「坏体解析成的 {}」与「真的传了 {persona:{}}」区分开：文本解析
+            // 失败的体不该把人格清空。jsonOk=false 时保持库内现值原样回显。
+            let body;
+            let jsonOk = true;
+            try {
+              body = JSON.parse(text || "{}");
+            } catch {
+              body = {};
+              jsonOk = false;
+            }
+            if (jsonOk && body && typeof body === "object") {
+              settings.setPersona(body.persona && typeof body.persona === "object" ? body.persona : body);
+            }
+            sendJson(res, 200, { persona: settings.getPersona() });
+          });
+        }
+        sendJson(res, 200, { persona: settings.getPersona() });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- dream/sleep 模型连通性 + 模型发现（settings 面板）----------------------
   // Connectivity probe for a dream/sleep model route: runs one minimal LLM call
   // through the same harness path the consolidation uses and reports success /
@@ -471,6 +617,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/llm-providers",
+    policy: "open",
     handler(req, res) {
       try {
         const llm = ctx.llm;
@@ -499,11 +646,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/test-model",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method !== "POST") return sendJson(res, 404, { error: "not-found" });
-        if (!requireAuth(req, res, apiToken)) return;
-        return readBody(req).then(async (text) => {
+        return readBody(req, res).then(async (text) => {
+          if (text === null) return;
           const body = parseBody(text);
           let provider = typeof body.provider === "string" ? body.provider.trim() : "";
           let model = typeof body.model === "string" ? body.model.trim() : "";
@@ -534,14 +682,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/delete",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method !== "POST") {
           sendJson(res, 404, { error: "not-found" });
           return;
         }
-        if (!requireAuth(req, res, apiToken)) return;
-        return readBody(req).then((text) => {
+        return readBody(req, res).then((text) => {
+          if (text === null) return;
           const body = parseBody(text);
           const id = typeof body.id === "string" ? body.id.trim() : "";
           if (!id) {
@@ -571,14 +720,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/update",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method !== "POST") {
           sendJson(res, 404, { error: "not-found" });
           return;
         }
-        if (!requireAuth(req, res, apiToken)) return;
-        return readBody(req).then((text) => {
+        return readBody(req, res).then((text) => {
+          if (text === null) return;
           const body = parseBody(text);
           const id = typeof body.id === "string" ? body.id.trim() : "";
           if (!id) {
@@ -677,14 +827,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/create",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method !== "POST") {
           sendJson(res, 404, { error: "not-found" });
           return;
         }
-        if (!requireAuth(req, res, apiToken)) return;
-        return readBody(req).then((text) => {
+        return readBody(req, res).then((text) => {
+          if (text === null) return;
           const body = parseBody(text);
           if (!TYPES.has(body.type)) {
             sendJson(res, 400, { error: "invalid-type" });
@@ -759,10 +910,10 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/maintenance/reclaim",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method === "GET") {
-          if (!requireAuth(req, res, apiToken)) return;
           if (!maintenance) {
             sendJson(res, 503, { error: RECLAIM_UNAVAILABLE });
             return;
@@ -785,8 +936,8 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           sendJson(res, 404, { error: "not-found" });
           return;
         }
-        if (!requireAuth(req, res, apiToken)) return;
-        return readBody(req).then((text) => {
+        return readBody(req, res).then((text) => {
+          if (text === null) return;
           const parsed = parseReclaimJson(text);
           if (!parsed.ok) {
             sendJson(res, 400, { error: parsed.error });
@@ -821,11 +972,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/rules",
+    policy: "token-write",
     handler(req, res) {
       try {
         if (req.method === "PUT" || req.method === "POST") {
-          if (!requireAuth(req, res, apiToken)) return;
-          return readBody(req).then((text) => {
+          return readBody(req, res).then((text) => {
+            if (text === null) return;
             const body = parseBody(text);
             settings.setRules(Array.isArray(body.rules) ? body.rules : []);
             sendJson(res, 200, { rules: settings.getRules() });
@@ -842,12 +994,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/vector-config",
+    policy: "token",
     handler(req, res) {
       try {
         // Secret-bearing endpoint: fully protected when apiToken is set.
-        if (!requireAuth(req, res, apiToken)) return;
         if (req.method === "PUT" || req.method === "POST") {
-          return readBody(req).then((text) => {
+          return readBody(req, res).then((text) => {
+            if (text === null) return;
             const body = parseBody(text);
             // An empty apiKey, or one that already looks masked (round-trips
             // through maskApiKey unchanged), means "keep the existing key".
@@ -879,9 +1032,9 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/vector-reindex",
+    policy: "token",
     handler(req, res) {
       try {
-        if (!requireAuth(req, res, apiToken)) return;
         if (!embedder) {
           sendJson(res, 200, { indexed: 0, skipped: 0, error: "vector-unavailable" });
           return;
@@ -911,6 +1064,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/semantic",
+    policy: "open",
     handler(req, res) {
       try {
         const stats = semantic?.vectorIndex?.getStats?.() ?? null;
@@ -926,6 +1080,25 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         const configured = embedder ? (typeof embedder.configured === "boolean" ? embedder.configured : true) : null;
         const embedded = Number(stats?.embeddedCount ?? 0);
         const total = Number(stats?.totalCount ?? 0);
+        // Per-model / per-dimension provenance of stored vectors. "embedded"
+        // counts rows with any vector; rows whose dimension differs from the
+        // current embedder output are skipped by searchVector, so the honest
+        // retrievable number is the current-dimension slice. modelBreakdown
+        // groups by row-level embedding_model ('' = unknown origin).
+        const dimensionBreakdown = typeof service.embeddingDimensionBreakdown === "function"
+          ? service.embeddingDimensionBreakdown()
+          : null;
+        const currentDim = embedder?.dimension != null ? String(embedder.dimension) : null;
+        const byDimension = dimensionBreakdown
+          ? [...dimensionBreakdown.entries()].map(([dim, c]) => ({ dimension: dim === "" ? null : Number(dim), count: c }))
+          : [];
+        const unsearchable = (currentDim && dimensionBreakdown)
+          ? [...dimensionBreakdown.entries()]
+              .filter(([dim]) => dim !== currentDim)
+              .reduce((s, [, c]) => s + c, 0)
+          : 0;        const modelBreakdown = typeof service.embeddingModelBreakdown === "function"
+          ? service.embeddingModelBreakdown().map((r) => ({ model: r.model === "" ? null : r.model, count: r.c }))
+          : [];
         sendJson(res, 200, {
           ready,
           configured,
@@ -936,6 +1109,16 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
                 : null,
           // 空库时 ratio 必须是 null 而非 0 —— 0 会被读成「一条都没嵌上」。
           coverage: { embedded, total, ratio: total > 0 ? embedded / total : null },
+          // distill-tx-embed-gap 后续：向量「存在」≠「可检索」。unsearchable =
+          // 维度与当前 embedder 输出不同的行数（searchVector 会跳过它们），
+          // retrievable = 与当前维度同维、真正参与召回的行数。两者差值非零时
+          // 面板必须能说出「有 N 条向量不可检索」，而不是只给一个虚高的 coverage。
+          vectors: {
+            byDimension,
+            byModel: modelBreakdown,
+            unsearchable,
+            retrievable: currentDim ? (dimensionBreakdown.get(currentDim) ?? 0) : null,
+          },
           // 配了、库里有东西可嵌、却一条都没嵌上 = 真的降级（本机此前长期
           // 处于 ready:true + embeddedCount:0，面板却显示正常）。
           degraded: configured === true && total > 0 && embedded === 0,
@@ -971,14 +1154,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/runtime/provision",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method !== "POST") {
           sendJson(res, 405, { error: "method-not-allowed" });
           return;
         }
-        if (!requireAuth(req, res, apiToken)) return;
-        return readBody(req).then(async (text) => {
+        return readBody(req, res).then(async (text) => {
+          if (text === null) return;
           const body = parseBody(text);
           const runtimeDir = config?.runtimeDir ?? "";
           // 三档来源依次尝试（收编本机 node_modules → 本地 .tgz 目录 → registry）。
@@ -1008,6 +1192,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/semantic/llm-audit",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
@@ -1030,6 +1215,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/semantic/llm-audit/stats",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
@@ -1053,6 +1239,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/semantic/graph/ego",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
@@ -1130,6 +1317,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/semantic/graph/entity-attrs",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
@@ -1168,6 +1356,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/entities",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
@@ -1187,6 +1376,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/memories/entities",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
@@ -1217,8 +1407,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/export",
+    policy: "token",
     handler(req, res) {
       try {
+        // 导出是「全库 + 含 archived/forgotten 的全字段」的一次读，敏感度不低于
+        // 写面：它必须与写路由同门。历史漏项——这条路由长期没有鉴权分支，配了
+        // apiToken 也照旧对任何调用方开放（2026-10 审计 P0）。
         const url = new URL(req.url, "http://localhost");
         const format = url.searchParams.get("format") ?? "json";
         if (format !== "json" && format !== "markdown") {
@@ -1267,14 +1461,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/import",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method !== "POST") {
           sendJson(res, 404, { error: "not-found" });
           return;
         }
-        if (!requireAuth(req, res, apiToken)) return;
-        return readBody(req).then((text) => {
+        return readBody(req, res).then((text) => {
+          if (text === null) return;
           const body = parseBody(text);
           if (typeof body.type !== "string" || !Object.hasOwn(TYPE_FILE, body.type)) {
             sendJson(res, 400, { error: "invalid-type" });
@@ -1308,6 +1503,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/dream-status",
+    policy: "open",
     handler(req, res) {
       try {
         const runs = (service.listDreamRuns?.({ limit: 5 }) ?? []).map((r) => ({
@@ -1352,13 +1548,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/conflicts",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method !== "GET") {
           sendJson(res, 404, { error: "not-found" });
           return;
         }
-        if (!requireAuth(req, res, apiToken)) return;
         const url = new URL(req.url, "http://localhost");
         const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit") ?? 50) || 50));
         const offset = Math.max(0, Number(url.searchParams.get("offset") ?? 0) || 0);
@@ -1373,14 +1569,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/conflicts/resolve",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method !== "POST") {
           sendJson(res, 404, { error: "not-found" });
           return;
         }
-        if (!requireAuth(req, res, apiToken)) return;
-        return readBody(req).then((text) => {
+        return readBody(req, res).then((text) => {
+          if (text === null) return;
           let body = {};
           try { body = JSON.parse(text || "{}"); } catch { /* 坏 JSON → 走缺参分支 */ }
           const id = typeof body.id === "string" ? body.id.trim() : "";
@@ -1410,8 +1607,8 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/health",
+    policy: "token",
     handler(req, res) {
-      if (!requireAuth(req, res, apiToken)) return;
       let state = null;
       try {
         state = service.getMirrorHealth?.() ?? null;
@@ -1459,11 +1656,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/mode",
+    policy: "token-write",
     handler(req, res) {
       try {
         if (req.method === "PUT" || req.method === "POST") {
-          if (!requireAuth(req, res, apiToken)) return;
-          return readBody(req).then((text) => {
+          return readBody(req, res).then((text) => {
+            if (text === null) return;
             const body = parseBody(text);
             if (body.mode !== "light" && body.mode !== "standard") {
               sendJson(res, 400, { error: "invalid-mode" });
@@ -1484,11 +1682,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/external-api",
+    policy: "token",
     handler(req, res) {
       try {
         if (req.method === "PUT" || req.method === "POST") {
-          if (!requireAuth(req, res, apiToken)) return;
-          return readBody(req).then((text) => {
+          return readBody(req, res).then((text) => {
+            if (text === null) return;
             const body = parseBody(text);
             const patch = {};
             if (body.enabled !== undefined) patch.enabled = body.enabled === true;
@@ -1511,9 +1710,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
             sendJson(res, 200, { config: fullExternalConfig(settings.setExternalApi(patch)) });
           });
         }
-        // GET: always hand back a token — the standalone server generates its
-        // own on first enabled boot, but the panel displays it before that,
-        // so materialize and persist one here.
+        // GET 回的是能解锁整个 8790 数据面的 Bearer，敏感度等同写面：必须与
+        // PUT 同门。未配置 apiToken 时 isAuthorized 恒真（既有的 fail-open 模型，
+        // 见 SECURITY.md「安全模型」一节），所以默认配置下面板仍旧即装即用。
+        // GET: hand back a token — the standalone server generates its own on
+        // first enabled boot, but the panel displays it before that, so
+        // materialize and persist one here. 只有通过上面那道门才会走到这里，
+        // 否则「未鉴权的 GET 顺手写库」就是一条不需要凭证的写路径。
         const kv = settings.getExternalApi() ?? {};
         if (!kv.token) {
           kv.token = randomBytes(24).toString("base64url");
@@ -1535,11 +1738,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/features",
+    policy: "token-write",
     handler(req, res) {
       try {
         if (req.method === "PUT" || req.method === "POST") {
-          if (!requireAuth(req, res, apiToken)) return;
-          return readBody(req).then((text) => {
+          return readBody(req, res).then((text) => {
+            if (text === null) return;
             const body = parseBody(text);
             if (typeof body !== "object" || body === null || Array.isArray(body) || Object.keys(body).length === 0) {
               sendJson(res, 400, { error: "invalid-patch" });
@@ -1569,6 +1773,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/inject-status",
+    policy: "open",
     handler(req, res) {
       try {
         if (req.method !== "GET") {
@@ -1593,6 +1798,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/inject-preview",
+    policy: "open",
     handler(req, res) {
       try {
         if (req.method !== "GET") {
@@ -1610,11 +1816,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/commands",
+    policy: "token-write",
     handler(req, res) {
       try {
         if (req.method === "POST") {
-          if (!requireAuth(req, res, apiToken)) return;
-          return readBody(req).then((text) => {
+          return readBody(req, res).then((text) => {
+            if (text === null) return;
             const body = parseBody(text);
             try {
               const command = commands.add({
@@ -1629,7 +1836,6 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           });
         }
         if (req.method === "DELETE") {
-          if (!requireAuth(req, res, apiToken)) return;
           const url = new URL(req.url, "http://localhost");
           const id = url.searchParams.get("id");
           const removed = id ? commands.remove(id) : false;
@@ -1647,11 +1853,15 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   // 只读端点，读的是**项目里**的 `<项目>/.mneme/pipelines/*.json`（文件头在
   // src/pipeline.js），项目层优先、插件包里那份降级成全局层；投影成
   // mneme.pipeline/v1 交给面板与 agent——两边读同一份，画面只是它的投影。
+  // 运行账（`<id>.runs.jsonl`，文件头在 src/pipeline-runs.js）也在这里读：**没有账，
+  // 读侧算不出任何状态**（`tallyRuns` 拿空数组时全体节点恒为 candidate），所以喂不喂
+  // runs 决定的是「面板上有没有一句实话」，不是多一个可选装饰。
   // 刻意不做旗标闸门：旗标管的是**客户端座位**（关=一个座位都不注册），不是数据面；
   // 多一个只读端点不会让任何人看见它，而给它加闸门只会让「为什么面板打不开」多一种成因。
   register({
     kind: "exact",
     path: "/api/dsh-mneme/pipeline",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
@@ -1665,7 +1875,76 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           sendJson(res, 400, { error: "project-not-absolute", detail: project });
           return;
         }
-        sendJson(res, 200, readPipelineDoc({ projectRoot: project, id }));
+
+        // 只读**账本目录**来定「哪些 id 有账」：最新一条 run 可能属于一条刚被删掉或
+        // 还没写完的 .json，这时工作流目录里问不到它的 id，而账本还在盘上。
+        // runIds 必须在 handler 级声明：下面观察旁挂块（同函数的另一个 if 分支）也按
+        // 这份 id 列表取观察——之前声明在账本分支的块级作用域里，旁挂块一引用就
+        // ReferenceError，被 catch 静默吞成「没有观察」（CodeRabbit #458 F1，
+        // 复盘注释见下方旁挂块）。
+        let runIds = [];
+        let runsResult = { runsById: {}, errors: [], statesById: {} };
+        if (project !== null) {
+          const where = runsDir(project);
+          runIds = existsSync(where)
+            ? readdirSync(where)
+                .filter((f) => f.endsWith(RUNS_SUFFIX))
+                .sort()
+                .map((f) => f.slice(0, -RUNS_SUFFIX.length))
+            : [];
+          if (runIds.length) {
+            // step id 闸门：账本里出现「图上没有的 step id」时，credit 会落在一个没有节点的
+            // 地方——**记了、数得出来、面板上永远看不见**，症状与「从没跑过」同形。
+            // 这里把每条工作流的步骤表读出来当白名单，让那种行变成看得见的噪音。
+            let stepIdsById = null;
+            try {
+              stepIdsById = Object.create(null);
+              for (const p of loadPipelines(projectPipelineDir(project), { scope: "project" })) {
+                stepIdsById[p.id] = p.steps.map((s) => s.id);
+              }
+            } catch {
+              // 项目层有坏 .json 时 readPipelineDoc 会把它记进 `unreadable`；这里不重复报，
+              // 也绝不因此让整个面板打不开——闸门退化成「没有白名单」，账本照读。
+              stepIdsById = null;
+            }
+            runsResult = loadRunsById(project, runIds, { expectedStepIdsById: stepIdsById });
+          }
+        }
+        const { runsById, errors: runsErrors, statesById } = runsResult;
+
+        // P3 投影的燃料：观察旁挂（与 /candidates 的 memoryDir 同源同默认）。
+        // 失败不连累图——旁挂是可再生的辅助数据，读不到就当没有，提议少一类而已。
+        let observationsById = {};
+        if (project !== null) {
+          try {
+            const memoryDir = (config && typeof config.memoryDir === "string" && config.memoryDir.trim() !== "")
+              ? config.memoryDir
+              : "~/.dsh/memory";
+            const odir = observationDir({ memoryDir, projectKey: projectKey(project) });
+            if (odir) {
+              observationsById = loadObservationsById(odir, runIds.filter(Boolean));
+            }
+          } catch {
+            // 读旁挂失败不算账本问题：如实降级成「没有观察」，fix-step-tool 少发而已
+          }
+        }
+
+        const doc = readPipelineDoc({ projectRoot: project, id, runsById, observationsById });
+
+        // 「读不出来」与「还没跑过」在节点状态上完全同形（都是全体 candidate），而且
+        // **不带 id 的默认视图没有兜底**——那正是用户打开时看到的那一屏。所以状态按
+        // pipeline 逐条显式带出去（清单行的 `runsState` 与选中那条的顶层 `runsState`），
+        // 客户端不必靠顶层噪音猜。也刻意**不再**对坏账本回 500：那会让客户端把它当成
+        // 「离线」，还顺手吞掉本来读得出来的那张图（账本坏了，工作流本身没坏）。
+        // 没有项目根时账本层无从读起，如实给 null，而不是谎称「没有账本文件」。
+        const chosenId = doc.pipeline ? doc.pipeline.id : null;
+        const runsState = project !== null && chosenId !== null ? statesById[chosenId] || "absent" : null;
+        const available =
+          project === null
+            ? doc.available
+            : doc.available.map((row) => ({ ...row, runsState: statesById[row.id] || "absent" }));
+
+        sendJson(res, 200, { ...doc, available, runsState, runsErrors });
       } catch (error) {
         // 工作流是人手写的 JSON，报错本身就是给人看的：说清哪一条、坏在哪，
         // 而不是回一句 internal 让人去翻日志。
@@ -1690,6 +1969,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   register({
     kind: "exact",
     path: "/api/dsh-mneme/candidates",
+    policy: "open",
     handler(req, res) {
       try {
         const url = new URL(req.url, "http://localhost");
@@ -1713,7 +1993,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   });
 
   return {
-    routes: 36,
+    routes: countRoutes(),
     dispose: () => {
       for (const dispose of disposers) dispose();
     }