@modusensus/dsh-mneme 0.11.0 → 0.13.0

package/src/wiki/queries.js

@@ -1,12 +1,49 @@
 // dsh-mneme/src/wiki/queries.js
 // chorography 的读侧（M1）：仓库列表 / 模块图 / 页面正文 / 关键词检索。
-// 只读，零写路径——写入口只有 M0 的 t0.js（红线 3：模型侧一个写工具都不注册）。
+// 收尾档追加：向量检索（P37–P39，惰性物化 + cosine）。
+// 检索读侧零写路径的例外只有一处——向量物化写 choro_vectors（P37：检索时惰性
+// 补嵌，host 侧才有 embedder；那是向量账本，不是页面真源）。
 //
 // 真源纪律（spec §4 / P12）：页面正文永远读仓库磁盘的 MD（root_path + DB 里的
 // rel_path），库里的表只是索引与状态账。slug 只从 DB 白名单解析，路径拼装零用户
 // 输入——面板与工具传进来的 slug 查不到模块行就返回 null，绝不用它拼路径。
 import { readFileSync, existsSync, realpathSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
+// 过期判定复用既有三件真源（t0 的 gitHead、plan 的指纹、render 的模板版本），
+// 面板侧不另造一套判据——两套判据迟早会对同一仓库给出两个答案。
+import { gitHead } from "./t0.js";
+import { loadPlanFromRepo } from "./plan.js";
+import { TEMPLATE_VERSION } from "./render.js";
+
+// 页正文去 frontmatter / CHORO 标记行后作为嵌入文本（P40：嵌页级全文）。
+function pageEmbedText(content) {
+  const lines = String(content ?? "").split("\n");
+  let start = 0;
+  if (lines[0]?.trim() === "---") {
+    start = 1;
+    while (start < lines.length && lines[start].trim() !== "---") start++;
+    start++;
+  }
+  return lines
+    .slice(start)
+    .filter((l) => !l.startsWith("<!-- CHORO:T1:") && !l.startsWith("<!-- CHORO:HUMAN:"))
+    .join("\n")
+    .trim();
+}
+
+function cosine(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
 
 export function createChoroQueries({ store }) {
   const db = store.db;
@@ -17,12 +54,114 @@ export function createChoroQueries({ store }) {
       `SELECT r.id, r.root_path, r.name, r.plan_fingerprint, r.git_baseline, r.updated_at,
               (SELECT COUNT(*) FROM choro_modules m WHERE m.repo_id = r.id) AS module_count,
               (SELECT COUNT(*) FROM choro_pages p JOIN choro_modules m2 ON p.module_id = m2.id
-                 WHERE m2.repo_id = r.id) AS page_count
+                 WHERE m2.repo_id = r.id) AS page_count,
+              (SELECT COUNT(*) FROM choro_claims c
+                 JOIN choro_pages p2 ON c.page_id = p2.id
+                 JOIN choro_modules m3 ON p2.module_id = m3.id
+                WHERE m3.repo_id = r.id) AS claim_count
          FROM choro_repos r ORDER BY r.id`
     ).all();
     return rows;
   }
 
+  /**
+   * 面板仓库列表（契约 §3.2）：在 listRepos 的行上补契约要求的字段。
+   *
+   * 为什么另开一个函数而不是改 listRepos 的返回形状：listRepos 的
+   * module_count / page_count 被工具层与查询层测试锁着（下划线命名），改名就是
+   * 破坏既有调用方；而契约要的是 modules / pages 这样的对外字段。两套名字并存
+   * 难看，但改名的连带面比难看贵得多——装饰层把它包一层，工具层照旧读原始行。
+   *
+   * 每个仓库都要 fork 一次 git 判过期：这是用户点开面板才走的路（不是每轮注入的
+   * 热路径），一次 rev-parse 几十毫秒在交互里不可感知。
+   */
+  /**
+   * 契约字段的仓库对象（stale 由调用方决定是否重算）。
+   *
+   * 注意区分两个入口：repoFacts 每次都会 fork git 判过期；repoFromRow 是纯行投影，
+   * 给「已经知道过期原因、手上有判定结果」的调用方用（例如自动重跑之后要紧着按
+   * 新基线说话，不能再拿旧行算一遍）。混用会得到自相矛盾的回执。
+   */
+  function repoFromRow(row) {
+    const rootPath = String(row.root_path ?? "");
+    return {
+      id: row.id,
+      name: row.name,
+      rootPath,
+      modules: Number(row.module_count ?? 0),
+      pages: Number(row.page_count ?? 0),
+      claims: Number(row.claim_count ?? 0),
+      // legacy = 这个仓库里有页面是用旧模板（或 M0 的 NULL）渲染的：重跑一次 T0 就
+      // 会把它们升级成当前模板，面板据此提示「建议重建」而不是让用户自己比对版本。
+      legacy: legacyPages(row.id) > 0,
+      lastRunAt: row.updated_at ?? null
+    };
+  }
+
+  function legacyPages(repoId) {
+    const hit = db.prepare(
+      `SELECT COUNT(*) AS n FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id
+        WHERE m.repo_id = ? AND (p.template_version IS NULL OR p.template_version <> ?)`
+    ).get(repoId, TEMPLATE_VERSION);
+    return Number(hit?.n ?? 0);
+  }
+
+  function repoFacts(row) {
+    const rootPath = String(row.root_path ?? "");
+    // git 优先：代码变了是更硬的「该重跑」信号，plan 变了才退而求其次——两者同时
+    // 成立时面板只说一句话，说「git」比说「plan」更贴近用户看到的现象（他刚改了码）。
+    const head = rootPath === "" ? null : gitHead(rootPath);
+    const baseline = String(row.git_baseline ?? "").trim();
+    let staleReason = null;
+    if (head && head !== baseline) {
+      staleReason = "git";
+    } else if (rootPath !== "") {
+      // 读不到 git（head 为 null）时不直接判「没过期」：plan.yaml 可能已经被改过，
+      // 那条判据不依赖 git，仍能给出答案。
+      let planFingerprintNow = null;
+      try { planFingerprintNow = loadPlanFromRepo(rootPath).fingerprint; } catch { planFingerprintNow = null; }
+      // plan.yaml 校验不过时 loadPlanFromRepo 会抛——那是「现在读不出结论」，不是
+      // 「过期了」，所以落 null 保持 stale=false，让重建按钮自己去报那条 YAML 错误。
+      if (planFingerprintNow && planFingerprintNow !== String(row.plan_fingerprint ?? "")) {
+        staleReason = "plan";
+      }
+    }
+    return {
+      ...repoFromRow(row),
+      stale: staleReason !== null,
+      staleReason
+    };
+  }
+
+  /** 单仓的原始 listRepos 行（自动重跑之后要拿推进过的基线，不能再用旧行）。 */
+  function listRepoRow(repoId) {
+    return listRepos().find((r) => Number(r.id) === Number(repoId)) ?? null;
+  }
+
+  /** 契约形状的仓库列表：listRepos 的原始行 → 对外字段。 */
+  function listRepoFacts() {
+    return listRepos().map((row) => repoFacts(row));
+  }
+
+  /** 仓库的契约字段（按 id/name，给 /choro/page 这类已知单仓的读路径用）。 */
+  function repoFactsById(repoId) {
+    const row = listRepoRow(repoId);
+    return row ? repoFacts(row) : null;
+  }
+
+  /**
+   * 按绝对路径找已登记仓库（面板「选目录 → 生成」必需）：T0 apply 落库时存的是
+   * realpath，所以这里也必须先 realpath 再比，否则 Windows 上盘符大小写/短名/符号
+   * 链接会让同一个目录被当成新仓库重复登记一次。
+   */
+  function repoByRoot(rootPath) {
+    const raw = String(rootPath ?? "").trim();
+    if (raw === "") return null;
+    let normalized;
+    try { normalized = realpathSync(resolve(raw)); } catch { return null; }
+    return db.prepare("SELECT * FROM choro_repos WHERE root_path = ?").get(normalized) ?? null;
+  }
+
   /** repo 解析：数字 id 或显示名（root_path 是本机私有路径，不作为对外键）。 */
   function resolveRepo(ref) {
     if (ref === undefined || ref === null || ref === "") {
@@ -50,12 +189,18 @@ export function createChoroQueries({ store }) {
       `SELECT from_slug, to_slug, weight FROM choro_edges WHERE repo_id = ?
         ORDER BY from_slug, to_slug`
     ).all(repoId);
+    // 纯加法补一个 camelCase 的 relPath：面板从地志页导入知识点要拼「根路径 + 页相对
+    // 路径」，而这里历史上直出 SQL 行的 snake_case（page_rel_path）。C 线按契约读的是
+    // mod.relPath，字段一缺就恒 undefined，用户选完模块点导入只会看到「请先选模块」。
+    // 原字段一律保留——src/tools.js 的 render 与 choro-command 都还在吃 file_count /
+    // page_status，改形状会波及它们；outline() 里的同名映射是这件事的正确写法。
+    for (const m of modules) m.relPath = m.page_rel_path ?? null;
     return { modules, edges };
   }
 
   /**
-   * 读一页正文。slug 必须命中 DB 的模块行（P12：路径零用户输入）；磁盘文件被手删
-   * 时返回 { error: "page-missing" }（索引还没重算，读侧如实报缺，不伪造内容）。
+   * 读一页正文。slug 必须命中 DB 的模块行（P12：路径零用户输入）；索引仍在但
+   * 文件缺失或不可读时带回相对路径，让调用方给出对应的恢复提示。
    */
   function readPage(repoId, slug) {
     const row = db.prepare(
@@ -67,7 +212,13 @@ export function createChoroQueries({ store }) {
     if (!row) return null;
     const repo = db.prepare("SELECT root_path, name FROM choro_repos WHERE id = ?").get(repoId);
     const abs = join(repo.root_path, row.rel_path);
-    if (!existsSync(abs)) return { error: "page-missing", slug: row.slug, relPath: row.rel_path };
+    let content;
+    try {
+      content = readFileSync(abs, "utf8");
+    } catch (cause) {
+      const error = cause.code === "ENOENT" || cause.code === "ENOTDIR" ? "page-missing" : "page-unreadable";
+      return { error, slug: row.slug, relPath: row.rel_path };
+    }
     return {
       slug: row.slug,
       title: row.title,
@@ -79,16 +230,17 @@ export function createChoroQueries({ store }) {
       humanBlockCount: row.human_block_count,
       repoName: repo.name,
       relPath: row.rel_path,
-      content: readFileSync(abs, "utf8"),
+      content,
     };
   }
 
   /**
    * 关键词检索（P10）：按 `## ` 分节做大小写不敏感子串匹配，命中返回页 slug、
    * 节标题、起始行号与摘录。只扫 DB 里登记过的页面文件（不是全目录 glob——
-   * 划分变更后未重算的孤儿文件不该被搜出来）。q 为空返回空数组不报错。
+   * 划分变更后未重算的孤儿文件不该被搜出来）。需要提示检索不完整的调用方可接收
+   * 不可读的页 slug。q 为空返回空数组不报错。
    */
-  function search(repoId, q, { moduleSlug = null, limit = 20 } = {}) {
+  function search(repoId, q, { moduleSlug = null, limit = 20, onUnreadablePage } = {}) {
     const needle = String(q ?? "").trim().toLowerCase();
     if (needle === "") return [];
     const cap = Math.max(1, Math.min(100, Number(limit) || 20));
@@ -102,11 +254,11 @@ export function createChoroQueries({ store }) {
     const hits = [];
     for (const page of pages) {
       const abs = join(repo.root_path, page.rel_path);
-      if (!existsSync(abs)) continue;
       let text;
       try {
         text = readFileSync(abs, "utf8");
       } catch {
+        onUnreadablePage?.(page.slug);
         continue;
       }
       const lines = text.split("\n");
@@ -216,5 +368,107 @@ export function createChoroQueries({ store }) {
     };
   }
 
-  return { listRepos, resolveRepo, moduleMap, readPage, search, repoByCwd, outline };
+  // --- chorography 向量（收尾档 P37–P39）---------------------------------
+  // 惰性物化（P37）：只在 host 侧检索路径调用（embedder 由 index.js 注入）；
+  // CLI 环境没有 embedder → 向量永不物化，检索退关键词。staleness 两维：
+  // 页 generated_at 变了（内容变了）、行 dim ≠ 本次查询向量 dim（换 embedder
+  // 模型了，P38）→ 重嵌。dim 失配是全表性的，遇到一次就把整仓重嵌（几十页）。
+  async function embedPageVectors(repoId, embedder, { limit = 200, expectDim = null } = {}) {
+    const pages = db.prepare(
+      `SELECT p.id, p.generated_at, m.slug, m.title, p.rel_path
+         FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id
+        WHERE m.repo_id = ? ORDER BY m.slug`
+    ).all(repoId);
+    const repo = db.prepare("SELECT root_path FROM choro_repos WHERE id = ?").get(repoId);
+    const embedOne = embedder.embedSingle ? (t) => embedder.embedSingle(t) : (t) => embedder.embed(t);
+    const rows = store.getChoroPageVectors(repoId);
+    const bySlug = new Map(rows.map((r) => [r.slug, r]));
+    const result = { embedded: 0, skipped: 0, stale: 0, failed: [], dimMismatch: false };
+    // dim 失配的全量重嵌（P38）：expectDim 来自查询向量（调用方先嵌查询再物化，
+    // 维度免费拿到）。expectDim 与任何现存行失配 → 本轮 fresh 检查失效，全量重嵌；
+    // 没给 expectDim（无查询场景）退化为只按 generated_at 判 staleness。
+    const dimDrift = expectDim !== null && rows.some((r) => r.dim !== expectDim);
+    if (dimDrift) result.dimMismatch = true;
+    for (const page of pages) {
+      if (result.embedded >= limit) break;
+      const row = bySlug.get(page.slug);
+      const fresh = !dimDrift && row && row.source_generated_at === page.generated_at && row.vector;
+      if (fresh) { result.skipped++; continue; }
+      if (row && row.vector) result.stale++;
+      const abs = join(repo.root_path, page.rel_path);
+      if (!existsSync(abs)) continue;
+      let text;
+      try {
+        text = pageEmbedText(readFileSync(abs, "utf8"));
+      } catch {
+        result.failed.push({ slug: page.slug, reason: "page-unreadable" });
+        continue;
+      }
+      if (text.trim() === "") { result.skipped++; continue; }
+      let vector;
+      try {
+        vector = await embedOne(text);
+      } catch (err) {
+        result.failed.push({ slug: page.slug, reason: String(err?.message ?? err).slice(0, 120) });
+        continue;
+      }
+      if (!Array.isArray(vector) || vector.length === 0) {
+        result.failed.push({ slug: page.slug, reason: "embedder-returned-no-vector" });
+        continue;
+      }
+      if (row && row.dim !== vector.length) result.dimMismatch = true;
+      store.saveChoroPageVector(page.id, {
+        vector,
+        dim: vector.length,
+        model: String(embedder.model ?? "choro"),
+        sourceGeneratedAt: page.generated_at,
+        createdAt: new Date().toISOString(),
+      });
+      result.embedded++;
+    }
+    return result;
+  }
+
+  /** 嵌查询文本（宿主侧）。embedder 缺席 / 不可用 → null。 */
+  async function embedQueryText(embedder, q) {
+    if (!embedder) return null;
+    const embedOne = embedder.embedSingle ? (t) => embedder.embedSingle(t) : (t) => embedder.embed(t);
+    try {
+      const v = await embedOne(String(q ?? ""));
+      return Array.isArray(v) && v.length > 0 ? v : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** 纯余弦 Top-N：向量已给定时零嵌入。行 dim 与查询失配的行过滤掉（P38）。 */
+  function semanticTopN(repoId, queryVector, { limit = 10 } = {}) {
+    if (!Array.isArray(queryVector) || queryVector.length === 0) return [];
+    const rows = store.getChoroPageVectors(repoId).filter((r) => r.vector && r.dim === queryVector.length);
+    return rows
+      .map((r) => ({
+        slug: r.slug,
+        title: r.title,
+        score: Number(cosine(queryVector, JSON.parse(r.vector)).toFixed(4)),
+      }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, Math.max(1, Math.min(50, Number(limit) || 10)));
+  }
+
+  /** 便捷组合：嵌查询 + Top-N（P39：独立数组，不与 keyword hits 混排序）。
+   * 空查询 → []（空白查询的「语义」是噪声，面板逐键触发时尤其如此）；
+   * embedder 缺席 → null（调用方退纯关键词）。 */
+  async function searchSemantic(repoId, embedder, q, { limit = 10 } = {}) {
+    if (!embedder) return null;
+    if (String(q ?? "").trim() === "") return [];
+    const queryVector = await embedQueryText(embedder, q);
+    if (!queryVector) return [];
+    return semanticTopN(repoId, queryVector, { limit });
+  }
+
+  return {
+    listRepos, listRepoFacts, repoFacts, repoFactsById, repoFromRow, listRepoRow, repoByRoot,
+    resolveRepo, moduleMap, readPage, search, repoByCwd, outline,
+    embedPageVectors, searchSemantic, embedQueryText, semanticTopN,
+  };
 }

package/src/wiki/t1-jobs.js

@@ -0,0 +1,232 @@
+// dsh-mneme/src/wiki/t1-jobs.js
+// T1 面板后台任务的进程账与状态机（契约 §3.2）。
+//
+// 为什么住在这里而不是 api.js：T1 要 spawn 子进程，而 api.js 刻意只依赖少数 node
+// 内置（不 import child_process）——HTTP 面只做参数解析与闸门分叉，进程生命周期与
+// 状态账归 wiki 层。副作用是单测可以在 API 侧注入假 job 对象，永不真跑一次 T1
+// （真跑要花模型额度，测试里花钱是不可接受的）。
+//
+// 为什么 spawn CLI 而不是宿主进程内直接 createT1()：单模块 30–240s，挂在宿主事件
+// 循环上会拖住整个插件；而 bin/dsh-mneme-choro.mjs --t1 已经是那条唯一收费入口，
+// 面板再走一遍编排逻辑等于造第二条路径，两边迟早不一致（收据形状、降级语义都会漂）。
+//
+// stdout 契约（防一类回归）：CLI 的 --json 用 JSON.stringify(receipt, null, 2) 输出
+// ——**多行 JSON，不是 NDJSON**。所以 ring buffer 按行收（面板要的是人能看的日志尾巴），
+// 回执解析另留一份可截断的全文，别指望从 200 行里拼出完整 JSON。
+import { spawn as nodeSpawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// lib/wiki/t1-jobs.js 与 src/wiki/t1-jobs.js 到 bin/ 都是上两级：sync 只换目录名，
+// 深度不变，所以这里可以硬编码相对位置。
+const DEFAULT_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "bin", "dsh-mneme-choro.mjs");
+
+// 日志尾巴的上限取 200 行：面板是个窄弹层，再多也没人往下翻；而上限存在的真理由
+// 是长任务会往 stdout 泼几万行，不封顶就是内存泄漏。
+const DEFAULT_RING = 200;
+// 已完成任务保留条数：status 要能被反复轮询（面板 2s 一次），但也不能无限留。
+const DEFAULT_FINISHED = 20;
+
+/** 逐行切分：chunk 边界可能落在一行中间，所以每路各留一个未完成余量。 */
+function makeLineSplitter(onLine) {
+  let rest = "";
+  return {
+    push(chunk) {
+      rest += chunk;
+      const parts = rest.split(/\r?\n/);
+      rest = parts.pop() ?? "";
+      for (const line of parts) onLine(line);
+    },
+    flush() {
+      if (rest !== "") { onLine(rest); rest = ""; }
+    }
+  };
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.store createStore 产物（只需要它来定位 bin 之外的路径时用；目前不读库）
+ * @param {Function} [opts.spawn] 注入的 spawn（测试注假实现，绝不真起进程）
+ * @param {string} [opts.nodePath] 跑脚本的解释器，缺省 process.execPath
+ * @param {string} [opts.scriptPath] CLI 路径，缺省按 lib/src 同深度推导
+ * @param {string|null} [opts.dbPath] 透传 --db；不传则 CLI 用自己的缺省记忆库
+ * @param {() => string} [opts.now]
+ * @param {number} [opts.ringLimit]
+ * @param {number} [opts.maxFinished]
+ */
+export function createT1Jobs({
+  store = null,
+  spawn: spawnFn = nodeSpawn,
+  nodePath = process.execPath,
+  scriptPath = DEFAULT_SCRIPT,
+  dbPath = null,
+  now = () => new Date().toISOString(),
+  ringLimit = DEFAULT_RING,
+  maxFinished = DEFAULT_FINISHED,
+  env = process.env
+} = {}) {
+  const jobs = new Map();
+  // 同一个仓库同时只许一个 T1：两个进程同时往同一批页面写，claims 与 status 会
+  // 交错成没人能解释的中间态（T1 的写路径没有跨进程锁，这是硬事实不是保守）。
+  const runningByRepo = new Map();
+
+  function pushLine(job, line) {
+    job.logTail.push(line);
+    if (job.logTail.length > ringLimit) job.logTail.splice(0, job.logTail.length - ringLimit);
+  }
+
+  /** 回执解析：只认 JSON.parsable 的完整 stdout；解析不出来就保持 0/0/0 不瞎猜。 */
+  function readCounts(job) {
+    const text = job.stdoutAll.trim();
+    if (text === "") return null;
+    let receipt;
+    try { receipt = JSON.parse(text); } catch { return null; }
+    if (!receipt || typeof receipt !== "object") return null;
+    if (Array.isArray(receipt.enriched) || Array.isArray(receipt.failed)) {
+      const done = Array.isArray(receipt.enriched) ? receipt.enriched.length : 0;
+      const failed = Array.isArray(receipt.failed) ? receipt.failed.length : 0;
+      return { total: done + failed, done, failed };
+    }
+    if (Array.isArray(receipt.candidates)) {
+      return { total: receipt.candidates.length, done: 0, failed: 0 };
+    }
+    return null;
+  }
+
+  function trimFinished() {
+    const finished = [...jobs.values()].filter((j) => j.state !== "running");
+    if (finished.length <= maxFinished) return;
+    finished.sort((a, b) => String(a.finishedAt).localeCompare(String(b.finishedAt)));
+    for (const job of finished.slice(0, finished.length - maxFinished)) jobs.delete(job.jobId);
+  }
+
+  function finish(job, state, error) {
+    if (job.state !== "running") return; // close 与 error 可能都到，只认第一次结算
+    job.state = state;
+    job.finishedAt = now();
+    if (error) job.error = error;
+    const counts = readCounts(job);
+    if (counts) job.modules = counts;
+    const key = String(job.repoKey);
+    if (runningByRepo.get(key) === job.jobId) runningByRepo.delete(key);
+    trimFinished();
+  }
+
+  /**
+   * 起一个后台 T1。返回 {started:true, jobId} 或 {started:false, code, jobId?}——
+   * 路由据此分叉 200 / 409，本层不碰 HTTP。
+   */
+  function start({ repo = null, module = null, retryFailed = false } = {}) {
+    const rootPath = typeof repo?.root_path === "string" ? repo.root_path : "";
+    if (rootPath === "") return { started: false, code: "repo-invalid" };
+    const repoKey = String(repo.id ?? rootPath);
+    const existing = runningByRepo.get(repoKey);
+    if (existing) {
+      const job = jobs.get(existing);
+      // runningByRepo 里还留着但 job 已经结算（理论不可达）时不该把它当占用，
+      // 否则这个仓库会被一条幽灵记录永久锁死。
+      if (job && job.state === "running") return { started: false, code: "job-running", jobId: existing };
+      runningByRepo.delete(repoKey);
+    }
+
+    const jobId = randomUUID();
+    const job = {
+      jobId,
+      repoKey,
+      repo: { id: repo.id ?? null, name: repo.name ?? null, rootPath },
+      state: "running",
+      startedAt: now(),
+      finishedAt: null,
+      modules: { total: 0, done: 0, failed: 0 },
+      logTail: [],
+      error: null,
+      stdoutAll: "",
+      stderrTail: []
+    };
+    jobs.set(jobId, job);
+    runningByRepo.set(repoKey, jobId);
+
+    const args = [scriptPath, rootPath, "--t1", "--apply", "--json"];
+    if (module) args.push("--module", String(module));
+    if (retryFailed === true) args.push("--retry-failed");
+    if (dbPath) args.push("--db", String(dbPath));
+
+    let child;
+    try {
+      child = spawnFn(nodePath, args, {
+        // Electron 宿主里 process.execPath 是 electron 本体；不设这个变量它会去开
+        // 窗口而不是跑 Node 脚本（t1.js 的真实 runner 用的是同一招）。
+        env: { ...env, ELECTRON_RUN_AS_NODE: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true
+      });
+    } catch (err) {
+      finish(job, "failed", String((err && err.message) || err));
+      return { started: true, jobId };
+    }
+    job.child = child;
+
+    const outLines = makeLineSplitter((line) => pushLine(job, line));
+    const errLines = makeLineSplitter((line) => {
+      job.stderrTail.push(line);
+      if (job.stderrTail.length > 20) job.stderrTail.shift();
+    });
+    child.stdout?.setEncoding?.("utf8");
+    child.stderr?.setEncoding?.("utf8");
+    child.stdout?.on?.("data", (chunk) => {
+      // 回执解析要完整 JSON，而 ring buffer 只留尾巴——所以另攒一份，封顶 256 KiB
+      // 防止一个跑飞的任务把宿主内存吃光。
+      if (job.stdoutAll.length < 256 * 1024) job.stdoutAll += chunk;
+      outLines.push(chunk);
+    });
+    child.stderr?.on?.("data", (chunk) => errLines.push(chunk));
+    child.on?.("error", (err) => {
+      outLines.flush();
+      errLines.flush();
+      finish(job, "failed", String((err && err.message) || err));
+    });
+    child.on?.("close", (code) => {
+      outLines.flush();
+      errLines.flush();
+      if (code === 0) {
+        finish(job, "done", null);
+      } else {
+        // CLI 的拒绝与异常都走 stderr + exit 1（bin:161-171）：只报 exit code 等于
+        // 让面板显示「失败了，不知道为啥」，所以把 stderr 尾巴当 error 带出去。
+        const tail = job.stderrTail.length > 0 ? job.stderrTail[job.stderrTail.length - 1] : "";
+        finish(job, "failed", tail || `exit code ${code}`);
+      }
+    });
+    return { started: true, jobId };
+  }
+
+  /** 状态快照（不含 child 等内部件）。未知 jobId → null。 */
+  function status(jobId) {
+    const job = jobs.get(String(jobId ?? ""));
+    if (!job) return null;
+    const view = {
+      jobId: job.jobId,
+      repo: job.repo,
+      state: job.state,
+      startedAt: job.startedAt,
+      modules: { ...job.modules },
+      logTail: job.logTail.slice()
+    };
+    if (job.finishedAt) view.finishedAt = job.finishedAt;
+    if (job.error) view.error = job.error;
+    return view;
+  }
+
+  function dispose() {
+    for (const job of jobs.values()) {
+      if (job.state === "running") {
+        try { job.child?.kill?.(); } catch { /* 进程可能已退出：dispose 不该抛 */ }
+      }
+    }
+    jobs.clear();
+    runningByRepo.clear();
+  }
+
+  return { start, status, dispose, scriptPath };
+}

package/src/wiki/t1.js

@@ -24,6 +24,9 @@ import { join, dirname, sep, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { realpathSync } from "node:fs";
 import { extractHumanBlocks, injectHumanBlocks, T1_SECTION_START, T1_SECTION_END } from "./render.js";
+// issue #607：拒绝文案里的 CLI 命令要给绝对路径入口（profile 装的插件没有全局
+// shim，光写 `dsh-mneme-choro` 用户照抄只会 command not found）。
+import { choroCliCommandFrom } from "./cli-hint.js";
 
 // 标记的单一来源在 render.js（页面格式的家）；这里转出去，调用方与测试继续从
 // t1.js 取，不必知道它住在哪。
@@ -31,6 +34,9 @@ export { T1_SECTION_START, T1_SECTION_END };
 export const T1_FAIL_THRESHOLD = 2;
 export const DEFAULT_T1_MODEL = "xdpool/deepseek-v4.1-flash";
 
+// #607：拒绝文案里的命令串推导一次（本文件在 src/wiki/ 与 lib/wiki/ 同一层）。
+const T1_CLI = choroCliCommandFrom(import.meta.url, "<repo>");
+
 // 三重上限缺省（实现计划 P15）：单模块预算——timeout 墙钟、工具调用次数、
 // 累计输出字节。真实成本实测见 V1（10s/次任务），这里给的是上限不是预期。
 export const DEFAULT_LIMITS = Object.freeze({
@@ -239,7 +245,7 @@ export function createT1({ store, runSession = null, limits = DEFAULT_LIMITS, no
     const rootPath = realpathSync(resolve(repoRoot));
     const repo = store.db.prepare("SELECT * FROM choro_repos WHERE root_path = ?").get(rootPath);
     if (!repo) {
-      throw new T1Refusal("not-registered", `${rootPath} 还没有登记：先跑一次 T0（dsh-mneme-choro <repo> --apply）`);
+      throw new T1Refusal("not-registered", `${rootPath} 还没有登记：先跑一次 T0（${T1_CLI ?? "dsh-mneme-choro <repo> --apply"}）`);
     }
 
     // 选模块：skeleton 必跑；failed 只在 retryFailed 时；enriched 跳过（重富化留待显式 --module）。