@modusensus/dsh-mneme 0.12.0 → 0.13.0

package/src/api.js

@@ -7,6 +7,9 @@ import { timingSafeEqual, randomBytes } from "node:crypto";
 import { TYPES } from "./store.js";
 import { TYPE_FILE, renderMirrorText, renderFileHeader, parseHumanEdits, MIRROR_READONLY_TYPES } from "./mirror.js";
 import { langOf } from "./lang.js";
+// issue #607：面板空态要显示「能直接粘贴就跑」的命令，而面板 bundle 拿不到
+// CLI 入口路径（独立 bundle 不能 import src）——所以由这条路由把命令算好发给它。
+import { choroCliCommandFrom } from "./wiki/cli-hint.js";
 // op 形状谓词单一份（评审 P3：两份皮会让形状修洞漏一边）。
 import { isValidFactOps } from "./profile-facts.js";
 import { computeHeat } from "./heat.js";
@@ -15,6 +18,7 @@ import { EFFORT_REJECT_RE, describeStreamFailure, resolveRoute, withEffortFallba
 // decisions.js，与产生这些 error 的校验器同一文件，避免措辞漂移）。
 import { summarizeSkipped } from "./dream/decisions.js";
 import { getInjectionSnapshot } from "./inject.js";
+import { invalidPeakSpecs } from "./peak-hours.js";
 import { renderUserSettingsBlock } from "./user-settings.js";
 import { parseProvenanceSelector, provenanceReply } from "./provenance-http.js";
 import { describeLocalRuntime, publicRuntimeStatus } from "./runtime/loader.js";
@@ -30,10 +34,23 @@ import { bootstrapFromDirectory } from "./bootstrap.js";
 // 这里引的是同一份（不是照抄），谁改白名单都对得上。
 import { describeConfigKeys, flagKeysFromSpec } from "./config-keys.js";
 import { parseShareBody, shareReply, shareFilename, parseReceiveBody, receiveReply, parseUndoBody, undoReply } from "./share-http.js";
+// 知识库第二层（契约 §3.6）：路径表与 handler 全在 kb/routes.js 里，本文件只负责
+// 把 kbGate 与基础设施递进去。**不在这里登记任何 /kb/* 路径**——registrar 对重复的
+// kind+path 直接抛，插件会起不来。
+import { registerKbRoutes } from "./kb/routes.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";
+// 日记本（v0.13）：读侧三件（列表/正文/账本）在 diary/index.js 里都是纯函数级的小实现，
+// 路由只做参数校验与闸门——把口径写在这里会让「面板与 CLI 读的是同一份」破功。
+import {
+  diaryDir, listDiaries, readDiary, exportDiary,
+  // 跨桶清单（左侧「ta 的日记」面板）：它拿不到当前会话的项目，只能整体读。
+  // isBucketName 也走同一处：清单与单篇读取必须用同一道判据，否则会出现
+  // 「列得出来、点进去 400」。
+  listDiaryLibrary, readLibraryEntry, isBucketName
+} from "./diary/index.js";
 import { readCandidateDoc } from "./candidates.js";
 // M.O. 自动沉淀：/nudge 是 pipeline-nudge.js 的第一个运行时消费者（此前它只有测试在用，
 // 是个孤儿模块——「不能自动沉淀工作流」的根因）。
@@ -44,6 +61,10 @@ import {
   NUDGE_AUTO_BUDGET_MS
 } from "./pipeline-nudge.js";
 
+// 面板空态与 409 hint 共用的 CLI 命令串（#607）：本文件在 src/ 与 lib/ 同一层，
+// 模块加载时推导一次。推导不出时为 null，两处各自退回通用说法。
+const CHORO_CLI = choroCliCommandFrom(import.meta.url, "<repo>");
+
 // headers：少数端点（/export 附件下载）需要追加 Content-Disposition 等响应头。
 function sendJson(res, status, payload, headers = {}) {
   res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", ...headers });
@@ -202,7 +223,13 @@ function parseBody(text) {
 // choro（M1）：chorography 读侧查询对象（createChoroQueries 产物）。缺省 null =
 // 宿主内 API 在 headless/测试环境没有接 queries，choro 路由回 503。它与 service
 // 刻意分开传——chorography 的所有权模型与记忆域相反（spec §3），不塞进 service。
-export function createApi(ctx, service, settings, commands, embedder, semantic = null, apiToken = "", config = null, maintenance = null, profileExtract = null, choro = null, facts = null) {
+// kb（第二层）：知识库装配对象（createKb 产物）。缺省 null = 这个宿主没装它，
+// /kb/* 一律 503（装配缺件），与开关关着的 409（用户没开）是两件事。
+// diary（v0.13）是第 14 个位置参数，缺省 null：旧调用点（测试里 14 处）继续工作，
+// 不传时日记路由一律 503 diary-unavailable（装配缺件），而不是伪装成「用户没开」。
+// 与 choro 同一套 503/409 分叉：#497 定下「503 = 环境缺件，409 = 用户没开」。
+// 顺序是刻意的：kb 先占第 13 位（它先合进 main），diary 追加在其后，谁先合谁靠前。
+export function createApi(ctx, service, settings, commands, embedder, semantic = null, apiToken = "", config = null, maintenance = null, profileExtract = null, choro = null, facts = null, kb = null, diary = null) {
   const disposers = [];
 
   // #182 注入状态探测：面板状态页的「极简模式下注入按宿主设计关闭」提示需要
@@ -213,12 +240,28 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   // 的 SessionHeader，降级 requestHeader().config；agentPreset 取不到留 null，
   // 面板对 null 静默）。任何失败静默：纯可观测性，不新增故障面。
   let lastAgentPreset = null;
+  // 会话 → 身份名的账本（人格页与手动写日记用）。lastAgentPreset 只记「最近一次」，
+  // 而手动写日记必须知道「这个会话是谁」，否则只能落 default 卡——那正是
+  // 「设定好人格的 agent 只以这个人格的口吻写日记」这条需求的缺口。
+  // 只存 id → 身份名，容量封顶：会话对象不进这里，避免把大对象挂住。
+  const agentBySession = new Map();
+  const AGENT_BY_SESSION_MAX = 200;
   try {
     const unsubscribe = ctx.on?.("session/event", (session) => {
       try {
         const header = session?.header ?? session?.requestHeader?.()?.config ?? null;
         const preset = header?.agentPreset;
-        lastAgentPreset = typeof preset === "string" && preset.trim() ? preset.trim() : null;
+        const name = typeof preset === "string" && preset.trim() ? preset.trim() : null;
+        lastAgentPreset = name;
+        const id = typeof session?.id === "string" ? session.id.trim() : "";
+        if (id) {
+          // 先删再插：Map 的迭代顺序即「最近活跃」，满了就淘汰最旧的键。
+          agentBySession.delete(id);
+          agentBySession.set(id, name);
+          while (agentBySession.size > AGENT_BY_SESSION_MAX) {
+            agentBySession.delete(agentBySession.keys().next().value);
+          }
+        }
       } catch { /* 观测失败不影响会话流 */ }
     });
     if (typeof unsubscribe === "function") disposers.push(unsubscribe);
@@ -269,7 +312,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     // Issue #471：政策轴——作用域级可逆闸门。两个键都是嵌套子字段，漏登记的后果
     // 同上（effective 静默缺键、面板读不到也 PUT 不进）。
     "scopeState.enabled": ["scopeState", "enabled"],
-    "scopeState.enforce": ["scopeState", "enforce"]
+    "scopeState.enforce": ["scopeState", "enforce"],
+    // #275 容量预警：三个阈值都是嵌套子字段（两个整数走 INT_RANGES、一个浮点走
+    // NUMBER_RANGES），漏登记的后果同上——effective 静默缺键、面板读不到也 PUT 不进。
+    "capacityWarning.dbSizeWarnMb": ["capacityWarning", "dbSizeWarnMb"],
+    "capacityWarning.archivedRowsWarn": ["capacityWarning", "archivedRowsWarn"],
+    "capacityWarning.archivedRatioWarn": ["capacityWarning", "archivedRatioWarn"]
     // sensitiveScanEnabled（#164 A2）是顶层扁平键，不需要进这张表——走 configFlagValue
     // 的默认分支即可。
   };
@@ -301,7 +349,14 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         if (value !== undefined) effective[key] = value;
       }
     }
-    return { overrides, effective, pendingRestart: pendingRestartKeys(overrides) };
+    // #622 可观测性：错峰时段串解析失败的面板可见化。校验在这里（服务端）做而不在
+    // 面板做——parsePeakSpec 只许有一份，面板是独立 bundle 复制一份解析器必然漂移；
+    // 与 config-keys 卡「分类在服务端算好、面板只渲染」同一纪律。校验对象是
+    // effective（overrides 压过 cfg 后的最终值）：输入框显示的就是它，提示行跟它
+    // 对齐——改完保存（PUT 也走 featureSnapshot）提示立即跟着换。GET 与 PUT 共用
+    // 本函数，两个字段自动同源。
+    const invalidPeakHours = Object.keys(invalidPeakSpecs(effective));
+    return { overrides, effective, invalidPeakHours, pendingRestart: pendingRestartKeys(overrides) };
   }
 
   // Ensure the service has an embedder when the API layer was handed one
@@ -392,7 +447,16 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         // merge/update verdict ∪ source=dream 直写）——状态页「查看全部」
         // 与记忆库的「沉淀」筛选 chip 共用这个视图。
         const depositedOnly = url.searchParams.get("deposited") === "only";
-        const rows = service.list({ type, limit, offset, order, minImportance, source, updatedFrom, updatedTo, onlyArchived, depositedOnly });
+        // id: 按主键取单条（含归档行）。面板打开/保存前要拿「这一条」的最新值，
+        // 分页扫列表最多只能看到前 1000 条，已归档的更不在默认视图里；扫不到就
+        // 只能拿陈旧缓存去比对 updated_at，等于没有版本检查。
+        const idFilter = (url.searchParams.get("id") ?? "").trim();
+        const rows = idFilter === ""
+          ? service.list({ type, limit, offset, order, minImportance, source, updatedFrom, updatedTo, onlyArchived, depositedOnly })
+          // getById 是裸 SELECT，没有 forgotten 谓词；这条路由是 open 的，
+          // 不过滤等于让本机任意进程按 id 读到已遗忘记忆的全文（评审 #1）。
+          // 归档行仍要放行：归档 ≠ 遗忘，面板保存前要用它比对 updated_at。
+          : [service.getById(idFilter)].filter((memo) => memo && !memo.forgotten);
         // 面板行在 wire DTO 之上补 archived/quality_score——模型工具的输出
         // schema 严格复用 toApiList，扩展只发生在 HTTP 层。
         // heat 投影（阶段二前端数据源）：仅 heatEnabled=true 时下发逐条热度
@@ -415,8 +479,16 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         }));
         // Total honors the same filters as the rows, or the pager's
         // has-more math breaks whenever minImportance/source/updated-at
-        // bounds are active.
-        sendJson(res, 200, { items, total: service.count(type, { minImportance, source, updatedFrom, updatedTo, onlyArchived, depositedOnly }) });
+        // bounds are active. 按 id 取单条时总数就是命中的行数。
+        const listCountFilters = { minImportance, source, updatedFrom, updatedTo, onlyArchived, depositedOnly };
+        const total = idFilter === ""
+          ? service.count(type, listCountFilters)
+          : rows.length;
+        // #597：全库分布（同一份筛选、**不带 type**——带 type 的页数不出其它类）。
+        // 面板分类栏的数字源；按 id 取单条时 total 就是行数、分布无意义，这一格
+        // 缺省（客户端据此降级回退到页内数）。
+        const typeCounts = idFilter === "" ? service.countByType(listCountFilters) : undefined;
+        sendJson(res, 200, { items, total, ...(typeCounts ? { typeCounts } : {}) });
       } catch {
         sendJson(res, 500, { error: "internal" });
       }
@@ -591,7 +663,8 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         // 预览（面板「Agent 眼中的画像」用）：由注入器同一个渲染函数产出，前端只显示
         // 返回的文本——以前端自己拼列表冒充「生效文本」是这个面板最容易漂的地方。
         // ?agent=<身份> 让面板能逐张卡预览：传了就按那个身份寻址，没传按「解析不到身份」
-        // 走（也就是 default 卡的受众）。
+        // 走（也就是 default 卡的受众）。?session=<会话 id>（#606）同理作用于绑会话卡，
+        // 优先级高于 ?agent——与 resolvePersonaCard 的寻址次序一致，预览不许比注入更乐观。
         // 这里不加鉴权是有意的：画像、规则、人格三处在同一条开放读面上本来就能各读一次
         // （GET /profile 与 GET /persona 都无 token 可读），本字段只是把同样的内容拼成
         // 模型实际看到的形状，没有新增可达面；真要锁，配 apiToken（写面与它同源）。
@@ -599,6 +672,10 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           settings,
           config,
           agentId: url.searchParams.get("agent"),
+          sessionId: url.searchParams.get("session"),
+          // 父会话 id（子 agent 继承人格卡用）：面板若要复现子代理看到的那一帧，
+          // 传父会话 id 即可，与注入器同一寻址次序——预览不许比注入更乐观。
+          parentSessionId: url.searchParams.get("parent"),
           // 事实段与注入共用同一渲染函数（user-settings.js 的同源纪律）：装配了
           // profile-facts 就传读口，开关与有无的判定在渲染函数内部（关=零读数）。
           factsProvider: typeof facts?.factsProvider === "function" ? facts.factsProvider : null
@@ -1237,7 +1314,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     handler(req, res) {
       try {
         if (!embedder) {
-          sendJson(res, 200, { indexed: 0, skipped: 0, error: "vector-unavailable" });
+          sendJson(res, 200, { indexed: 0, failed: 0, skipped: 0, error: "vector-unavailable" });
           return;
         }
         const url = new URL(req.url, "http://localhost");
@@ -1247,13 +1324,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         const viaIndex = semantic?.vectorIndex && semantic?.vectorIndex.rebuildIndex;
         const task = viaIndex
           ? semantic.vectorIndex.rebuildIndex(embedder, { limit })
-          : embedder.reindexMissing ? embedder.reindexMissing(limit) : Promise.resolve({ indexed: 0, skipped: 0, error: "vector-unavailable" });
+          : embedder.reindexMissing ? embedder.reindexMissing(limit) : Promise.resolve({ indexed: 0, failed: 0, skipped: 0, error: "vector-unavailable" });
         // Return the chain so awaiting callers (tests/health checks) observe the
         // finished response rather than racing the async backfill.
         return task.then((result) => {
           sendJson(res, 200, result);
         }).catch(() => {
-          sendJson(res, 200, { indexed: 0, skipped: 0, error: "vector-failed" });
+          sendJson(res, 200, { indexed: 0, failed: 0, skipped: 0, error: "vector-failed" });
         });
       } catch {
         sendJson(res, 500, { error: "internal" });
@@ -1330,6 +1407,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           dimension: embedder?.dimension ?? null,
           reranker: semantic?.reranker ? "ready" : null,
           index: stats,
+          // #604：回填与写入两条嵌入路径的诊断。此前 backfillStatus() 与
+          // embedReceipts() 都已经算好了，但没有任何出口 —— 面板能看到的只有
+          // 「已索引 N 条」，看不出「上一轮撞了 cap」「最近一次嵌入为什么失败」。
+          // 两个字段都是只读快照，不查库、不触发推理。
+          embeddings: typeof semantic?.embeddingDiagnostics === "function"
+            ? semantic.embeddingDiagnostics()
+            : null,
           // issue #131 / PR-A：自管运行时的状态。无论当前 provider 是不是 local
           // 都报 —— 面板需要区分「已收编但没启用」和「要用本地却没收编」。
           // 这里只做结构检查（不跑推理），失败降级成状态对象，不会让本端点 500。
@@ -1689,7 +1773,11 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
       try {
         const url = new URL(req.url, "http://localhost");
         const limit = Math.min(1000, Math.max(1, Number(url.searchParams.get("limit") ?? 500) || 500));
-        const entities = service.listEntities?.({ limit }) ?? [];
+        // q = 名字过滤。必须下推到 store：面板此前取回 limit 条再本地过滤，
+        // 排在 limit 之后的实体永远搜不到（评审 #9）。老宿主没有这个形参时
+        // 多传一个键不会报错，只是过滤失效——与 limit 的处理一致。
+        const q = url.searchParams.get("q") ?? "";
+        const entities = service.listEntities?.({ limit, q }) ?? [];
         // total 是**全库**实体数，不是本次切片长度：目录带 limit，面板拿它当
         // 「一共抽出多少实体」，填切片长度会让 1.6 万实体永远显示成 500。
         // 老宿主（service 上没有 countEntities）回落到切片长度，不抛。计数本身失败也
@@ -2169,7 +2257,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
-  // --- health: mirror sync state (F-NEW-03 / v0.3.6) ---
+  // --- health: mirror sync state (F-NEW-03 / v0.3.6) + capacity (#275) ---
   // Auth-gated; only returns a sanitized error code (never raw last_error which
   // may leak paths/token-like strings/internal hosts). On state read failure it
   // reports unknown/degraded (fail-closed) instead of a false dirty=false.
@@ -2178,23 +2266,34 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     path: "/api/dsh-mneme/health",
     policy: "token",
     handler(req, res) {
+      // 容量预警（#275 空间维度）：与镜像状态同面但**互相独立**——镜像读失败不该
+      // 把容量数字一起藏掉，所以每个分支都带上。getCapacityHealth 自身 fail-safe
+      // （读失败回 status:"unknown"）；?.() 兜住没接线的老 mock service（此时显式
+      // capacity:null，面板渲染成「未知」，不冒充正常）。
+      let capacity = null;
+      try {
+        capacity = service.getCapacityHealth?.() ?? null;
+      } catch {
+        capacity = null;
+      }
       let state = null;
       try {
         state = service.getMirrorHealth?.() ?? null;
       } catch {
         // read failure is itself a health signal: do not report a false clean
-        sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
+        sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null }, capacity });
         return;
       }
       if (!state) {
-        sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
+        sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null }, capacity });
         return;
       }
       // Real read failure surfaces as dirty === null (peer blocker 5): report
       // unknown explicitly instead of collapsing into a false "ok"/"degraded".
       if (state.dirty === null) {
         sendJson(res, 200, {
-          mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null }
+          mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null },
+          capacity
         });
         return;
       }
@@ -2212,7 +2311,8 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           last_error: code,
           last_attempt: state.last_attempt ?? null,
           success_at: state.success_at ?? null
-        }
+        },
+        capacity
       });
     }
   });
@@ -2287,11 +2387,17 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         // materialize and persist one here. 只有通过上面那道门才会走到这里，
         // 否则「未鉴权的 GET 顺手写库」就是一条不需要凭证的写路径。
         const kv = settings.getExternalApi() ?? {};
-        if (!kv.token) {
+        // ?token=omit：只读配置、不生成也不落库 Bearer。
+        // 手机端面板（src/dsh-go）只需要 enabled/port/host 来渲染表单，而默认的
+        // GET 会顺手 materialize 一个 token 写进 user_settings —— 一次纯读请求
+        // 变成写路径，既污染审计也违反「面板不显示明文令牌」的承诺。带上这个
+        // 参数时 token 字段一律留空；不传的老客户端行为完全不变。
+        const omitToken = new URL(req.url, "http://localhost").searchParams.get("token") === "omit";
+        if (!omitToken && !kv.token) {
           kv.token = randomBytes(24).toString("base64url");
           settings.setExternalApi({ token: kv.token });
         }
-        sendJson(res, 200, { config: fullExternalConfig(kv) });
+        sendJson(res, 200, { config: fullExternalConfig(omitToken ? { ...kv, token: "" } : kv) });
       } catch {
         sendJson(res, 500, { error: "internal" });
       }
@@ -2671,6 +2777,232 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- QQ 日记本（v0.13）-----------------------------------------------
+  // 五条路由，闸门分两层：
+  // - **装配缺件**（diary 参数没传 / headless 宿主）→ 503 diary-unavailable；
+  // - **用户没开**（diaryEnabled=false）→ 409 disabled（#497 定下的 503/409 分叉）。
+  // 读侧三条 policy "open"（与 /pipeline、/candidates 同级：只读、不写盘、宿主围栏统一
+  // 鉴权）；写侧两条 "token-write"——它们会落盘：/diary/compose 调模型写正文，
+  // /diary/export 往**用户项目目录**复制文件。写盘面一律受门控。
+  //
+  // project 参数照 /pipeline 的规矩：不是绝对路径就 400，**不能忽略**——服务端没有
+  // 「当前项目」这个概念，忽略它就静默退成「全局」，而全局看起来一切正常。
+  function diaryGate(req, res) {
+    if (!diary) {
+      sendJson(res, 503, { error: "unavailable", reason: "diary-unavailable" });
+      return false;
+    }
+    if (!config || config.diaryEnabled !== true) {
+      sendJson(res, 409, { error: "disabled", reason: "diary-not-enabled" });
+      return false;
+    }
+    return true;
+  }
+  function diaryProject(req, res) {
+    const project = new URL(req.url, "http://localhost").searchParams.get("project");
+    if (project === null || project === "") {
+      // 读侧不给 project 会退成「合并所有项目」——那正是要避免的静默全局。
+      sendJson(res, 400, { error: "project-required" });
+      return null;
+    }
+    if (!isAbsolute(project)) {
+      sendJson(res, 400, { error: "project-not-absolute", detail: project });
+      return null;
+    }
+    return project;
+  }
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/diary",
+    policy: "open",
+    handler(req, res) {
+      if (!diaryGate(req, res)) return;
+      const project = diaryProject(req, res);
+      if (!project) return;
+      try {
+        const dir = diaryDir({ memoryDir: config.memoryDir, projectRoot: project, configured: config.diaryDir });
+        // 账本一起带走：面板要回答「今天为什么没有日记」时必须读它，不能靠猜。
+        const audit = diary.readAudit({ projectRoot: project, limit: 20 });
+        sendJson(res, 200, { contract: "mneme.diary/v1", project, dir, diaries: listDiaries(dir), audit });
+      } catch (error) {
+        sendJson(res, 500, { error: "diary-unreadable", detail: String((error && error.message) || error) });
+      }
+    }
+  });
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/diary/entry",
+    policy: "open",
+    handler(req, res) {
+      if (!diaryGate(req, res)) return;
+      const project = diaryProject(req, res);
+      if (!project) return;
+      const date = new URL(req.url, "http://localhost").searchParams.get("date");
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date ?? ""))) {
+        sendJson(res, 400, { error: "date-required" });
+        return;
+      }
+      try {
+        const dir = diaryDir({ memoryDir: config.memoryDir, projectRoot: project, configured: config.diaryDir });
+        const text = readDiary(dir, date);
+        if (text === null) {
+          // 404 而不是空串：面板据此区分「这一篇还没写」与「写了但是空的」。
+          sendJson(res, 404, { error: "diary-not-found", date });
+          return;
+        }
+        sendJson(res, 200, { contract: "mneme.diary/v1", date, path: `${dir}/${date}.md`, text });
+      } catch (error) {
+        sendJson(res, 500, { error: "diary-unreadable", detail: String((error && error.message) || error) });
+      }
+    }
+  });
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/diary/compose",
+    policy: "token-write",
+    handler(req, res) {
+      if (!diaryGate(req, res)) return;
+      const method = String(req.method || "GET").toUpperCase();
+      if (method === "GET" || method === "HEAD") {
+        // 手动「写一篇」是会调模型的写动作，必须 POST——GET 会被浏览器预取、
+        // 被面板刷新反复调用，等于每刷一次烧一次模型（/nudge 同款教训）。
+        sendJson(res, 405, { error: "method-not-allowed", allow: "POST" }, { Allow: "POST" });
+        return;
+      }
+      const project = diaryProject(req, res);
+      if (!project) return;
+      // 会话身份（「设定好人格的 agent 只以这个人格的口吻写日记」）：手动「写一篇」
+      // 以前不传 agentId，于是永远落 default 卡——自动轮传了、手动轮没传，同一天
+      // 从两个入口写出来的日记会用两张人格卡，这是最难发现的一类不一致。
+      //
+      // 身份来源只认两处，且**不带身份就不猜**：查询参数 ?agent= 是前端从会话行
+      // 上读到的 agentPreset（与它算 project 用的是同一条快照），?session= 则让
+      // 服务端按自己那份「会话 → 身份」账本反查。两处都空就照旧落 default 卡，
+      // 但那是「不知道是谁」，不是「以为是 default」——frontmatter 的 persona 字段
+      // 会如实写成 default 卡的名字，面板读得出来。
+      const q = new URL(req.url, "http://localhost").searchParams;
+      const rawAgent = typeof q.get("agent") === "string" ? q.get("agent").trim() : "";
+      const rawSession = typeof q.get("session") === "string" ? q.get("session").trim() : "";
+      const agentId = rawAgent || (rawSession ? (agentBySession.get(rawSession) || "") : "");
+      Promise.resolve(diary.compose({
+        trigger: "manual",
+        projectRoot: project,
+        agentId: agentId || null
+      }))
+        .then((result) => {
+          // skip 不是错：already-written / no-material 都是关于这个项目的答案，回 200。
+          const status = result && result.ok === false ? 500 : 200;
+          sendJson(res, status, { contract: "mneme.diary/v1", ...result });
+        })
+        .catch((error) => {
+          sendJson(res, 500, { error: "diary-compose-failed", detail: String((error && error.message) || error) });
+        });
+    }
+  });
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/diary/export",
+    policy: "token-write",
+    handler(req, res) {
+      if (!diaryGate(req, res)) return;
+      const method = String(req.method || "GET").toUpperCase();
+      if (method === "GET" || method === "HEAD") {
+        sendJson(res, 405, { error: "method-not-allowed", allow: "POST" }, { Allow: "POST" });
+        return;
+      }
+      const project = diaryProject(req, res);
+      if (!project) return;
+      readBody(req, res).then((text) => {
+        if (text === null) return;
+        const body = parseBody(text);
+        const date = String(body.date ?? "");
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+          sendJson(res, 400, { error: "date-required" });
+          return;
+        }
+        try {
+          const dir = diaryDir({ memoryDir: config.memoryDir, projectRoot: project, configured: config.diaryDir });
+          const result = exportDiary({ sourceDir: dir, projectRoot: project, date, overwrite: body.overwrite === true });
+          const status = result.ok ? 200 : result.error === "target-exists" ? 409 : result.error === "no-diary" ? 404 : 500;
+          sendJson(res, status, { contract: "mneme.diary/v1", ...result });
+        } catch (error) {
+          sendJson(res, 500, { error: "diary-export-failed", detail: String((error && error.message) || error) });
+        }
+      });
+    }
+  });
+
+  // --- 日记库（左侧「ta 的日记」面板）-----------------------------------
+  // 与上面五条**按项目定位**的日记路由是两件事：
+  // 左侧面板长在 `main` 座位上，宿主不给它 sessionId，所以它算不出
+  // 「当前会话的项目根」，也没法用 projectKey 定位单个桶。它要的是
+  // 「有哪些桶、各是谁写的、各有多少篇」——那只能整体扫 diaries 根目录。
+  //
+  // 两条都 policy "open"：只读、不写盘、不调模型，鉴权交宿主围栏。
+  // 闸门与上面同源（503 装配缺件 / 409 用户没开），否则会出现「右栏能读、
+  // 左栏 404」这种看起来像坏了的分叉。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/diary/library",
+    policy: "open",
+    handler(req, res) {
+      if (!diaryGate(req, res)) return;
+      try {
+        const { root, buckets } = listDiaryLibrary({
+          memoryDir: config.memoryDir,
+          configured: config.diaryDir
+        });
+        sendJson(res, 200, { contract: "mneme.diary/v1", root, buckets });
+      } catch (error) {
+        sendJson(res, 500, { error: "diary-unreadable", detail: String((error && error.message) || error) });
+      }
+    }
+  });
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/diary/library/entry",
+    policy: "open",
+    handler(req, res) {
+      if (!diaryGate(req, res)) return;
+      const params = new URL(req.url, "http://localhost").searchParams;
+      const bucket = params.get("bucket");
+      const date = params.get("date");
+      // 桶名与日期都要校验：这条路径直接拼文件系统路径，`..` 必须在这里挡住。
+      // 用的就是 library.js 那道 `isBucketName`——两层不能各写一份规则，否则
+      // 会出现「清单里列得出来、点进去 400」：历史上真有保留中文的桶
+      // （`QQ对话-4f061790`），ASCII 白名单会把它列出来却读不到，用户看到的是
+      // 点了没反应。真正的越界由 `readLibraryEntry` 里的真实路径解析兜底。
+      if (!bucket || !isBucketName(bucket)) {
+        sendJson(res, 400, { error: "bucket-required" });
+        return;
+      }
+      if (!date || !/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        sendJson(res, 400, { error: "date-required" });
+        return;
+      }
+      try {
+        const text = readLibraryEntry({
+          memoryDir: config.memoryDir,
+          configured: config.diaryDir,
+          bucket,
+          date
+        });
+        if (text === null) {
+          sendJson(res, 404, { error: "diary-not-found", bucket, date });
+          return;
+        }
+        sendJson(res, 200, { contract: "mneme.diary/v1", bucket, date, text });
+      } catch (error) {
+        sendJson(res, 500, { error: "diary-unreadable", detail: String((error && error.message) || error) });
+      }
+    }
+  });
+
   // --- chorography（仓库地志）M1 读侧路由 -------------------------------
   // spec §7 消费面的面板数据源。四条全 policy "open"：只读、宿主围栏统一鉴权
   // （与 /list、/version-check 同级）；**chorographyEnabled 关闭时一律 409
@@ -2704,13 +3036,63 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     return repo;
   }
 
+  // 读侧自动重跑（chorographyAutoRefresh）。面板的语义是「读地志页时发现仓库代码
+  // 变了就顺手重跑一次 T0」——T0 是零模型的确定性扫描，成本只在磁盘；但它会重写
+  // 仓库里的 .chorography/**，所以默认关，且一次请求最多刷一个仓库。
+  //
+  // 为什么失败不 500：读是主诉求、刷新是附赠。git rev-parse 偶发失败或磁盘只读时，
+  // 把整张仓库列表打成 500 等于「因为顺手的事没办成，连正式的事都不给办了」。
+  // 错误塞进 autoRefreshError 让面板能说清，数据照发。
+  //
+  // 为什么要 caller 指定 repo：一次面板加载若把 5 个 stale 仓库全扫一遍，用户只是
+  // 打开一个页面却付了 5 次全仓扫描；列表路径只在 ?repo= 明确点名时才刷。
+  function autoRefreshOne(repoId, facts) {
+    const result = { autoRefreshed: false, autoRefreshError: undefined, repo: facts };
+    if (!config || config.chorographyAutoRefresh !== true) return result;
+    if (!facts || facts.staleReason !== "git") return result;
+    if (typeof choro.runT0Apply !== "function") return result;
+    try {
+      choro.runT0Apply({ repoRoot: facts.rootPath });
+      result.autoRefreshed = true;
+      // 重跑之后基线推进了，回执里的 stale 必须按新基线说话：沿用旧行的判定会让
+      // 面板刚刷完就显示「代码已变」，也就是谎报一次失败。
+      const fresh = typeof choro.repoFactsById === "function" ? choro.repoFactsById(repoId) : null;
+      if (fresh) result.repo = fresh;
+    } catch (err) {
+      result.autoRefreshError = String(err?.message ?? err);
+      ctx.logger?.warn?.(`dsh-mneme: choro auto refresh failed for repo ${repoId}: ${result.autoRefreshError}`);
+    }
+    return result;
+  }
+
   register({
     kind: "exact",
     path: "/api/dsh-mneme/choro/repos",
     policy: "open",
     handler(req, res) {
       if (!choroGate(req, res)) return;
-      sendJson(res, 200, { repos: choro.listRepos() });
+      // 契约 §3.2 的字段（stale / staleReason / lastRunAt / legacy / claims）由
+      // queries 层的 listRepoFacts 出；这里留 fallback 是因为既有测试与工具层会
+      // 用裸对象冒充 choro（只实现 runT0Apply），缺一个方法就 500 是没必要的脆。
+      const repos = typeof choro.listRepoFacts === "function" ? choro.listRepoFacts() : choro.listRepos();
+      const repoParam = new URL(req.url, "http://localhost").searchParams.get("repo");
+      let autoRefreshed = false;
+      let autoRefreshError;
+      if (repoParam !== null && repoParam !== "") {
+        const target = choro.resolveRepo(repoParam);
+        if (target && !target.ambiguous) {
+          const idx = repos.findIndex((r) => Number(r.id) === Number(target.id));
+          if (idx >= 0) {
+            const refreshed = autoRefreshOne(target.id, repos[idx]);
+            autoRefreshed = refreshed.autoRefreshed;
+            autoRefreshError = refreshed.autoRefreshError;
+            if (refreshed.repo) repos[idx] = refreshed.repo;
+          }
+        }
+      }
+      // cliCommand（#607）：面板空态直接把它贴出来，用户复制即用。推导不出
+      // 入口时为 null，面板据此退回通用说法（不硬编一个假路径）。
+      sendJson(res, 200, { repos, autoRefreshed, autoRefreshError, cliCommand: CHORO_CLI });
     }
   });
 
@@ -2744,7 +3126,16 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         sendJson(res, 400, { error: "slug-required" });
         return;
       }
+      // 读页是面板的主路径，也正是「读地志页时发现代码变了就重跑」这句文案对应的
+      // 那一刻——自动刷新优先挂在这里（/choro/repos 只在 ?repo= 点名时才刷）。
+      // 刷新必须在 readPage 之前：T0 会重写页文件，先读后刷会把刚被替换掉的旧正文
+      // 回给面板，用户下一次刷新才看到新内容，看起来就像「刷了没用」。
+      const before = typeof choro.repoFactsById === "function" ? choro.repoFactsById(repo.id) : null;
+      const refreshed = autoRefreshOne(repo.id, before);
       const page = choro.readPage(repo.id, slug);
+      // 顶栏「代码已变」徽章读 state.repo.stale：这一份 repo 必须和 page 同源同刻，
+      // 否则刚刷完还会亮着旧徽章。
+      const repoNow = refreshed.repo ?? before;
       if (!page) {
         sendJson(res, 404, { error: "page-not-found", slug });
         return;
@@ -2756,12 +3147,25 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           slug: page.slug,
           relPath: page.relPath,
           hint: page.error === "page-missing"
-            ? "run `dsh-mneme-choro <repo> --apply` to rebuild"
+            ? `run ${CHORO_CLI ? `\`${CHORO_CLI}\`` : "`dsh-mneme-choro <repo> --apply`"} to rebuild`
             : "check the local file and its permissions"
         });
         return;
       }
-      sendJson(res, 200, { page });
+      sendJson(res, 200, {
+        page,
+        repo: repoNow ? {
+          id: repoNow.id,
+          name: repoNow.name,
+          rootPath: repoNow.rootPath,
+          stale: repoNow.stale,
+          staleReason: repoNow.staleReason,
+          legacy: repoNow.legacy,
+          lastRunAt: repoNow.lastRunAt
+        } : { id: repo.id, name: repo.name },
+        autoRefreshed: refreshed.autoRefreshed,
+        autoRefreshError: refreshed.autoRefreshError
+      });
     }
   });
 
@@ -2797,9 +3201,13 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
-  // 面板重建入口（收尾档 P34）：T0 apply 秒级同步回执；**T1 不上 HTTP**——单模块
-  // 30–240s 起步的长任务不适合挂死面板请求，CLI（--t1）仍是 T1 唯一入口。
+  // 面板重建入口（收尾档 P34）：T0 apply 秒级同步回执。
   // policy token-write：写的是仓库磁盘的 .chorography/**，属数据面写。
+  //
+  // 扩容（契约 §3.2，607 修复）：body 支持 { repo?, path? | rootPath?, refresh? }。
+  // 必须支持按**绝对路径**登记新仓库，否则「一个仓库都没登记」的空态面板永远出不来
+  // ——面板没有 id 可传，只能给路径。已登记路径则复用既有 id（T0 的 upsertChoroRepo
+  // 按 root_path 冲突更新，本来就不会重号）。
   register({
     kind: "exact",
     path: "/api/dsh-mneme/choro/run",
@@ -2815,6 +3223,100 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         if (text === null) return; // readBody 已回 413
         const body = parseBody(text);
         const repoRef = body && typeof body === "object" ? body.repo : null;
+        const rootInput = body && typeof body === "object"
+          ? (typeof body.path === "string" ? body.path : (typeof body.rootPath === "string" ? body.rootPath : null))
+          : null;
+        // refresh 是「我要求重建」的意图标记，不是「需要额外再刷一次」的开关：
+        // 这条路由本身就是显式重建，T0 会在自己那次 apply 里把 git 基线推进到当前
+        // HEAD，之后没有第二件事可做。保留字段是为了让面板把「用户点了重建」与
+        // 「读侧顺手刷新」两种来源区分开——回执里 autoRefreshed 因此恒为 false，
+        // 它不是失败信号，而是「这次没人替你偷偷刷」。
+        const refresh = body && typeof body === "object" ? body.refresh === true : false;
+
+        let repoRoot;
+        if (typeof rootInput === "string" && rootInput.trim() !== "") {
+          // 路径必须绝对：相对路径的语义取决于宿主进程的 cwd，同一个请求在 CLI 与
+          // 面板里会落到不同目录——那种「有时行有时不行」最难查。
+          if (!isAbsolute(rootInput.trim())) {
+            sendJson(res, 400, { error: "path-not-absolute", path: rootInput });
+            return;
+          }
+          repoRoot = rootInput.trim();
+        } else {
+          const repo = choro.resolveRepo(repoRef);
+          if (!repo || repo.ambiguous) {
+            sendJson(res, repo && repo.ambiguous ? 400 : 404, {
+              error: repo && repo.ambiguous ? "repo-ambiguous" : "repo-not-found",
+              repos: repo && repo.ambiguous ? repo.ambiguous : undefined
+            });
+            return;
+          }
+          repoRoot = repo.root_path;
+        }
+
+        try {
+          const receipt = choro.runT0Apply({ repoRoot });
+          // autoRefreshed 恒 false：显式重建已经是最强的刷新，没有「额外自动刷新」
+          // 这回事。写成常量而不是省略字段，是为了让面板的两种来源（显式 / 顺手）
+          // 共用同一个回执形状，不必按路由分支判 undefined。
+          sendJson(res, 200, { ok: true, autoRefreshed: false, refresh, receipt });
+        } catch (err) {
+          // 结构化分叉而不是 500 一锅烩：路径不存在 / 不是 git 仓库都是「用户给错了
+          // 东西」，面板要能据此说人话并让他改路径，而不是显示「服务端错误，重试」。
+          // 判据走 err.code 字符串（ChoroRefusal.code / PlanInvalidError.name），
+          // 因为 api.js 刻意不 import src/wiki/*（不让 HTTP 面依赖编排层）。
+          const code = err && typeof err.code === "string" ? err.code : null;
+          if (code === "no-such-dir") {
+            sendJson(res, 400, { error: "path-not-found", path: repoRoot, detail: String((err && err.message) || err) });
+            return;
+          }
+          if (code === "not-git") {
+            sendJson(res, 409, { error: "not-a-git-repo", path: repoRoot, detail: String((err && err.message) || err) });
+            return;
+          }
+          if (err && err.name === "PlanInvalidError") {
+            sendJson(res, 409, {
+              error: "plan-invalid",
+              path: repoRoot,
+              detail: String((err && err.message) || err),
+              issues: Array.isArray(err.issues) ? err.issues : undefined
+            });
+            return;
+          }
+          sendJson(res, 500, { error: "t0-failed", detail: String((err && err.message) || err) });
+        }
+      });
+    }
+  });
+
+  // T1 后台任务（契约 §3.2 / 面板 §3.5）。**不在这里 spawn**：进程账住在
+  // wiki/t1-jobs.js（api.js 不 import child_process），这里只做参数解析、闸门与
+  // 409 分叉。choro.startT1Job 缺席（CLI / 测试装配）→ 503，与读侧同一条语义：
+  // 503 = 环境缺件，409 = 用户没开。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/choro/t1",
+    policy: "token-write",
+    handler(req, res) {
+      if (req.method !== "POST") {
+        sendJson(res, 405, { error: "method-not-allowed", allow: "POST" }, { Allow: "POST" });
+        return;
+      }
+      if (!choroGate(req, res)) return;
+      if (typeof choro.startT1Job !== "function") {
+        sendJson(res, 503, { error: "unavailable", reason: "t1-jobs-unavailable" });
+        return;
+      }
+      // T1 花模型额度，所以除了总闸之外还有一道单独的用户闸（契约 §3.1 的理由：
+      // 关总闸等于整个子系统不可见，而只想关「面板能不能花钱」的人需要更细的闸）。
+      if (!config || config.chorographyT1FromPanel !== true) {
+        sendJson(res, 409, { error: "disabled", reason: "t1-from-panel-disabled" });
+        return;
+      }
+      return readBody(req, res).then((text) => {
+        if (text === null) return;
+        const body = parseBody(text);
+        const repoRef = body && typeof body === "object" ? body.repo : null;
         const repo = choro.resolveRepo(repoRef);
         if (!repo || repo.ambiguous) {
           sendJson(res, repo && repo.ambiguous ? 400 : 404, {
@@ -2823,16 +3325,66 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
           });
           return;
         }
-        try {
-          const receipt = choro.runT0Apply({ repoRoot: repo.root_path });
-          sendJson(res, 200, { ok: true, receipt });
-        } catch (err) {
-          sendJson(res, 500, { error: "t0-failed", detail: String((err && err.message) || err) });
+        const started = choro.startT1Job({
+          repo,
+          module: body && typeof body.module === "string" && body.module.trim() !== "" ? body.module.trim() : null,
+          retryFailed: body && typeof body === "object" ? body.retryFailed === true : false
+        });
+        if (!started || started.started !== true) {
+          // 同一仓库并发跑 T1 会把两个进程写进同一批页面（claims 交错），必须挡。
+          const errCode = started && started.code === "job-running" ? "job-running" : "t1-start-failed";
+          sendJson(res, errCode === "job-running" ? 409 : 500, {
+            error: errCode,
+            jobId: started && started.jobId ? started.jobId : undefined
+          });
+          return;
         }
+        sendJson(res, 200, { jobId: started.jobId, started: true });
       });
     }
   });
 
+  // 任务状态轮询（面板 2s 一次）。jobId 未知 → 404：任务记录只在内存里，宿主重启
+  // 后旧 id 必然查不到，回 404 让面板回到「没有正在跑的任务」而不是假装 running。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/choro/t1/status",
+    policy: "token-write",
+    handler(req, res) {
+      if (!choroGate(req, res)) return;
+      if (typeof choro.t1JobStatus !== "function") {
+        sendJson(res, 503, { error: "unavailable", reason: "t1-jobs-unavailable" });
+        return;
+      }
+      const jobId = new URL(req.url, "http://localhost").searchParams.get("jobId");
+      if (!jobId) {
+        sendJson(res, 400, { error: "jobId-required" });
+        return;
+      }
+      const job = choro.t1JobStatus(jobId);
+      if (!job) {
+        sendJson(res, 404, { error: "job-not-found", jobId });
+        return;
+      }
+      sendJson(res, 200, job);
+    }
+  });
+
+  // 知识库第二层（契约 §3.6）。闸与 choro 同款分叉：装配缺件 503 / 用户没开 409。
+  // 这里只判开关，不判「有没有集合」——空知识库是合法状态（面板要能显示空态）。
+  function kbGate(req, res) {
+    if (!kb) {
+      sendJson(res, 503, { error: "unavailable", reason: "kb-unavailable" });
+      return false;
+    }
+    if (!config || config.kbEnabled !== true) {
+      sendJson(res, 409, { error: "disabled", reason: "kb-not-enabled" });
+      return false;
+    }
+    return true;
+  }
+  registerKbRoutes(register, { kb, cfg: config ?? {}, sendJson, readBody, parseBody, gate: kbGate });
+
   return {
     routes: countRoutes(),
     dispose: () => {