@gavinc-cn/touchstone-dsh 0.2.0 → 0.3.0

package/dsh-plugin/lib/pack-closure.mjs

@@ -0,0 +1,291 @@
+/**
+ * 发包闭包计算 —— 「npm 包里必须有哪些文件」的**唯一一份**算法（零依赖，只用 `node:`）。
+ *
+ * 为什么要有它：`package.json` 的 `files` 是**白名单**，漏一条就是「发出去的包起不来」，
+ * 而漏的形态是静默的 —— 2026-10-15 实测 `@gavinc-cn/touchstone-dsh@0.1.1` 的 105 个文件里
+ * **没有 `backend/routes/` 的 11 个文件**（白名单只写了 `backend/server.js` / `backend/lib` /
+ * `backend/schema`），解包后 `node backend/server.js` 当场
+ * `ERR_MODULE_NOT_FOUND: .../backend/routes/index.js`（`backend/server.js:61` 就 import 它）
+ * 并 exit 1。手写清单（`dsh-plugin/scripts/prepack-check.mjs` 的 `REQUIRED`）挡不住这种漏，
+ * 因为它只查「我记得的那些」；这里改成**从入口正推**：包内必需 = 两个入口的**静态 import
+ * 闭包** + 运行时时按路径读的数据根。新增一个 `backend/routes/xxx.js` 而忘了改白名单 ⇒
+ * 闭包自动长大 ⇒ 判据变红。
+ *
+ * 两个入口（`package.json` 的 `main` + Node 后端入口，见 `dsh-plugin/lib/index.js:117-118`）:
+ *   - `dsh-plugin/lib/index.js` —— dsh 插件壳，宿主 `require`/`import` 的就是它；
+ *   - `backend/server.js`      —— 薄壳 spawn 的 Node 后端进程。
+ * 只解析**相对说明符**（`./` / `../`）：`node:*` 内建与裸包名不是包内文件，一律记为
+ * `unresolved` 供人看（不参与判据 —— 把裸包名当必需会把判据搞成假红）。
+ *
+ * 数据根（`RUNTIME_RESOURCES`）是**手写的**，条目都带「谁在哪一行读它」的证据；递归 import
+ * 扫描器看不到这些「按路径拼出来的读」，所以只能人工登记 —— 但每条都写清理由，不写「大概
+ * 需要」。注意 `backend/schema/fixtures/*` **不在**闭包里：它只被 `backend/test/db.test.mjs`、
+ * `tools/parity/db-run.mjs`、`tools/export_schema.py` 读（测试/量具），运行时没人读
+ * （实测 `grep -rn fixtures backend/lib backend/routes` 无命中）—— 别凭印象往里塞。
+ *
+ * 白名单展开（`expandFilesEntries`）按 npm 的 `files` 语义实现最小规则，行为经实测校准
+ * （`npm pack --dry-run --json`，见下），不是照文档猜的：
+ *   - 条目相对包根；`*` 不跨 `/`（实测 `files:["*.py","*.md"]` 只收根级的 a.py/top.md，
+ *     子目录 `sub/b.py` 不收 ⇒ **没有** matchBase 语义），`**` 跨目录；
+ *   - 条目指到目录 ⇒ 递归含其内容（`backend/lib`、`webui/dist-plugin` 都是这个形态）；
+ *   - `package.json` / `README*` / `LICENSE*`（含 `LICENCE*`）恒含。
+ * 有意**不**建模 `.gitignore`：本仓 `.gitignore` 里有 `webui/dist-plugin/`，但它照进包
+ * （实测 3 个文件都在）—— 说明显式 `files` 条目压过忽略规则。副作用写在文件末尾「已知缺口」。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** 包根（本文件在 `<包根>/dsh-plugin/lib/` 下, 上溯三级） */
+export const PKG_ROOT = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+
+/** 闭包的两个入口（相对包根，posix 分隔） */
+export const ENTRIES = Object.freeze([
+  'dsh-plugin/lib/index.js',
+  'backend/server.js',
+]);
+
+/**
+ * 运行时时**按路径读**的数据根（静态扫描看不到；每条都要有证据行号）。
+ * `files` 列出「精确文件」（测试夹具不算，别往里塞）；`dirs` 列出「整个目录都要」——
+ * 目录内容在判据里**当场递归枚举**，所以往里新增数据文件也自动进入闭包。
+ */
+export const RUNTIME_RESOURCES = Object.freeze({
+  files: Object.freeze([
+    { rel: 'backend/schema/schema.sql', why: 'backend/lib/db.js:59 initDb 启动即读（目标 DDL）' },
+    { rel: 'backend/schema/schema.json', why: 'backend/lib/db.js:60 收敛器按它补列/建索引' },
+    { rel: 'backend/schema/migrations.json', why: 'backend/lib/db.js:61 声明式迁移清单，启动即执行' },
+  ]),
+  dirs: Object.freeze([
+    { rel: 'builtin_prompts/free_style', why: 'backend/lib/prompts.js:237 _ASSET_DIR，运行时读流程文档与文件模板' },
+    { rel: 'extensions', why: 'backend/lib/builtin-assets.js:262 DEFAULT_EXT_DIR，资产清单扫描根（routes/assets.js 的端点）' },
+    { rel: 'webui/dist-plugin', why: 'server 静态服务目录（薄壳启动参数 --web-dir 传的就是它，dsh-plugin/lib/index.js）' },
+  ]),
+});
+
+/** 目录递归枚举时跳过的东西（不进包，也不需要进闭包） */
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.run', '__pycache__']);
+
+/** 相对说明符扫描（见文件头：锚在行首，避开注释里的散文；多行 import 靠 `[^'"]` 跨行） */
+const IMPORT_FROM_RE = /^[ \t]*import\s+[^'"]*?\bfrom\s*['"]([^'"]+)['"]/gm;
+const IMPORT_SIDE_EFFECT_RE = /^[ \t]*import\s*['"]([^'"]+)['"]/gm;
+const EXPORT_FROM_RE = /^[ \t]*export\s+(?:\*|\{[^}]*\})\s*from\s*['"]([^'"]+)['"]/gm;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+/** posix 化（判据字符串一律用 `/`，Windows 上跑出来的也必须一样） */
+export function toPosix(rel) {
+  return rel.split(path.sep).join('/');
+}
+
+/** 目录清单缓存：同一进程内按 root 复用（判据是只读的静态检查，进程内不假设文件树会变） */
+const LIST_CACHE = new Map();
+
+/** 递归列出 root 下所有**文件**（相对包根，posix 分隔，排序）；结果按 root 缓存 */
+export function listFiles(root = PKG_ROOT) {
+  const cached = LIST_CACHE.get(root);
+  if (cached) return cached;
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;                       // 读不动就当不存在（判据自己会报缺）
+    }
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        walk(abs);
+      } else if (entry.isFile()) {
+        out.push(toPosix(path.relative(root, abs)));
+      }
+    }
+  };
+  walk(root);
+  out.sort();
+  LIST_CACHE.set(root, out);
+  return out;
+}
+
+/** 抽一个源文件里的相对说明符（去重、保持出现顺序） */
+export function scanRelativeSpecifiers(source) {
+  const found = [];
+  const add = (spec) => {
+    if (!spec) return;
+    if (!spec.startsWith('./') && !spec.startsWith('../')) return;
+    if (!found.includes(spec)) found.push(spec);
+  };
+  for (const re of [IMPORT_FROM_RE, IMPORT_SIDE_EFFECT_RE, EXPORT_FROM_RE, DYNAMIC_IMPORT_RE]) {
+    re.lastIndex = 0;
+    for (const m of source.matchAll(re)) add(m[1]);
+  }
+  return found;
+}
+
+/**
+ * 解析相对说明符 → 包内文件（posix 相对路径）；解析不到返回 null。
+ * 支持无扩展名（补 `.js`、`/index.js`），与 Node 的 ESM 解析口径近似（本仓无扩展名导入）。
+ */
+export function resolveSpecifier(fromRel, spec, root = PKG_ROOT) {
+  const baseDir = path.posix.dirname(fromRel);
+  const joined = path.posix.normalize(path.posix.join(baseDir, spec));
+  const candidates = [joined, `${joined}.js`, `${joined}.mjs`, path.posix.join(joined, 'index.js')];
+  for (const rel of candidates) {
+    if (rel.startsWith('..')) continue;              // 跑出包根：不是包内文件
+    const abs = path.join(root, rel);
+    try {
+      if (fs.statSync(abs).isFile()) return rel;
+    } catch { /* 不存在的候选，继续试下一个 */ }
+  }
+  return null;
+}
+
+/**
+ * 计算运行时闭包：两个入口的静态 import 闭包 + `RUNTIME_RESOURCES`。
+ * @returns {{files: string[], unresolved: Array<{from: string, spec: string}>,
+ *            entries: string[], resources: string[]}}
+ *   `files` 排序去重；`unresolved` 是相对说明符解析不到（或裸包名/`node:`）的清单，
+ *   只报不用（避免把裸包名当必需导致假红）。
+ */
+export function computeClosure(root = PKG_ROOT) {
+  const files = new Set();
+  const unresolved = [];
+  const queue = [...ENTRIES];
+  const seen = new Set();
+  while (queue.length > 0) {
+    const rel = queue.shift();
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    const abs = path.join(root, rel);
+    let source;
+    try {
+      source = fs.readFileSync(abs, 'utf8');
+    } catch {
+      unresolved.push({ from: rel, spec: '(入口本身读不到)' });
+      continue;
+    }
+    files.add(rel);
+    for (const spec of scanRelativeSpecifiers(source)) {
+      const resolved = resolveSpecifier(rel, spec, root);
+      if (resolved === null) unresolved.push({ from: rel, spec });
+      else queue.push(resolved);
+    }
+  }
+  const resources = [];
+  for (const item of RUNTIME_RESOURCES.files) {
+    files.add(item.rel);
+    resources.push(item.rel);
+  }
+  for (const item of RUNTIME_RESOURCES.dirs) {
+    const abs = path.join(root, item.rel);
+    if (!fs.existsSync(abs)) { unresolved.push({ from: '(资源根)', spec: item.rel }); continue; }
+    for (const rel of listFiles(abs)) {
+      const full = `${item.rel}/${rel}`;
+      files.add(full);
+      resources.push(full);
+    }
+  }
+  return {
+    files: [...files].sort(),
+    unresolved,
+    entries: [...ENTRIES],
+    resources: resources.sort(),
+  };
+}
+
+/** glob → 正则（npm `files` 最小语义：`**` 跨 `/`，`*`/`?` 不跨 `/`） */
+function globToRegExp(pattern) {
+  let re = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        i++;
+        if (pattern[i + 1] === '/') { i++; re += '(?:.*/)?'; }   // `**/` 也匹配零层
+        else re += '.*';
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else if ('\\^$.|+()[]{}'.includes(ch)) {
+      re += `\\${ch}`;
+    } else {
+      re += ch;
+    }
+  }
+  return new RegExp(`${re}$`);
+}
+
+/**
+ * npm 恒含的文件（`files` 白名单管不着）—— **只在包根**，实测校准过：
+ * `files:["a.txt"]` 时 `sub/README.md` / `sub/deep/LICENSE` 都不进包，
+ * 而根级 `package.json` 恒在。别把这条写成「任意层级的 README/LICENSE」（会假绿：
+ * 例如 `tests/README.md` 会被误判成包内 —— 实测它不在 105 个文件里）。
+ */
+function isAlwaysIncluded(rel) {
+  if (rel === 'package.json') return true;
+  if (rel.includes('/')) return false;
+  return /^(README|LICENSE|LICENCE)(\..*)?$/i.test(rel);
+}
+
+/**
+ * 展开 `files` 白名单 → 包内文件集合（最小 npm 语义，见文件头）。
+ * @param {string[]} entries package.json 的 files 数组
+ * @param {{root?: string, allFiles?: string[]}} [opts] 便于测试注入（负对照就在内存里换 entries）
+ * @returns {Set<string>} posix 相对路径集合
+ */
+export function expandFilesEntries(entries, opts = {}) {
+  const root = opts.root || PKG_ROOT;
+  const all = opts.allFiles || listFiles(root);
+  const packed = new Set();
+  for (const rel of all) if (isAlwaysIncluded(rel)) packed.add(rel);
+  for (const raw of entries) {
+    const entry = path.posix.normalize(String(raw).replace(/^\.\//, '').replace(/\/+$/, ''));
+    if (!entry || entry.startsWith('..')) continue;
+    const abs = path.join(root, entry);
+    let stat = null;
+    try { stat = fs.statSync(abs); } catch { /* 不存在：当 glob 处理 */ }
+    if (stat && stat.isDirectory()) {
+      for (const rel of listFiles(abs)) packed.add(`${entry}/${rel}`);
+      continue;
+    }
+    if (stat && stat.isFile()) { packed.add(entry); continue; }
+    const re = globToRegExp(entry);
+    for (const rel of all) if (re.test(rel)) packed.add(rel);
+  }
+  return packed;
+}
+
+/**
+ * 判据本体：闭包里但包内没有的文件（空数组 = 过）。
+ * @param {string[]} closureFiles `computeClosure().files`
+ * @param {Iterable<string>} packedFiles `expandFilesEntries(...)`
+ */
+export function findUnpacked(closureFiles, packedFiles) {
+  const packed = packedFiles instanceof Set ? packedFiles : new Set(packedFiles);
+  return closureFiles.filter((rel) => !packed.has(rel));
+}
+
+/**
+ * 读仓库 `package.json` 的 `files` 并跑完整判据（`prepack-check.mjs` 与单测共用）。
+ * @returns {{ok: boolean, missing: string[], closure: object, packedCount: number, files: string[]}}
+ */
+export function checkPackClosure(root = PKG_ROOT) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  const entries = Array.isArray(pkg.files) ? pkg.files : [];
+  const closure = computeClosure(root);
+  const packed = expandFilesEntries(entries, { root });
+  const missing = findUnpacked(closure.files, packed);
+  return { ok: missing.length === 0, missing, closure, packedCount: packed.size, files: entries };
+}
+
+/**
+ * 已知缺口（写在这里，不装作没有）:
+ *   ① `.gitignore` / `.npmignore` 未建模 —— 若将来某个运行时文件恰好落在被忽略的目录里、
+ *      而白名单**没有**显式列出它，本判据会假绿（今天不会：闭包里的路径全部由显式条目覆盖）。
+ *   ② npm 的 `files` 对**符号链接**、`.npmrc`、`bundledDependencies` 有额外规则，本判据不管。
+ *   ③ 运行时**动态拼**出来的路径（例如按用户输入拼文件名）静态看不到，只能靠人工登记进
+ *      `RUNTIME_RESOURCES`；登记漏了就是假绿。
+ */

package/dsh-plugin/scripts/prepack-check.mjs

@@ -1,13 +1,20 @@
 /**
  * 发包前自检 —— package.json 的 `prepack` 钩子（`npm pack` / `npm publish` 前自动执行）。
  *
- * 两道检查:
+ * 三道检查:
  *  ① **必需文件在不在**：本包是自包含的（插件壳 + Python 平台 + 预构建 webui/dist-plugin +
  *     内置提示词/内置资产），少任何一块装到 profile 里都跑不起来；
  *  ② **三处「包名」逐字一致**：包根 package.json 的 `name`、`dsh-plugin/cordis.patch.yml`
  *     里 insert 行的 `name`、`dsh-plugin/lib/client.bundle.js` 里 `__ModuleLoader__.load({id})`
  *     的 id —— dsh 宿主按注册行的包名给浏览器半预留模块槽，三者不一致时页面报
  *     "loaded without registering"（2026-10-07 改名 @gavinc-cn/touchstone-dsh 时踩过）。
+ *  ③ **闭包 ⊆ 白名单**（2026-10-15 新增）：从两个入口（`backend/server.js`、
+ *     `dsh-plugin/lib/index.js`）正推运行时闭包（静态 import 图 + 运行时按路径读的数据根），
+ *     与 `files` 展开结果比对。①的手写清单挡不住「新加了一个文件、忘了改白名单」——
+ *     实测 0.1.1 发出去的包里 `backend/routes/` 11 个文件全缺，解包后
+ *     `node backend/server.js` 直接 ERR_MODULE_NOT_FOUND（`backend/server.js:61` import 它）。
+ *     算法在 `dsh-plugin/lib/pack-closure.mjs`（与 `tools/parity/test/pack-closure.test.mjs`
+ *     **同一份**，不是一个抄一个）；这里只读文件、**绝不递归调用 `npm pack`**（会被自己再触发）。
  *
  * 任一项不过就非 0 退出，让 `npm pack` / `npm publish` 直接中断：宁可发不出去，不可发出坏包。
  * 用法: node dsh-plugin/scripts/prepack-check.mjs
@@ -16,6 +23,8 @@ import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { checkPackClosure } from '../lib/pack-closure.mjs';
+
 /** 包根（本脚本在 <包根>/dsh-plugin/scripts/ 下, 上溯三级） */
 const PKG_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 
@@ -24,6 +33,15 @@ const REQUIRED = [
   'package.json',
   'server.py',
   'requirements.txt',
+  // Node 后端骨架（2026-10-11 M0）：profile 里配 `backend: node` 时薄壳拉起的就是它，
+  // 缺了等于「开关一打开就起不来」——必须在发包自检里挡住。
+  'backend/server.js',
+  'backend/lib',
+  // 数据层共享契约（2026-10-11 M1）：`backend/lib/db.js` 启动即读 schema.sql /
+  // schema.json / migrations.json，缺了就是「Node 后端起不来」——同样必须在发包自检里挡住。
+  'backend/schema/schema.sql',
+  'backend/schema/schema.json',
+  'backend/schema/migrations.json',
   'builtin_prompts',
   'extensions/dsh-autocommit/asset.json',
   'webui/dist-plugin/index.html',
@@ -53,9 +71,19 @@ if (!bundle.includes(`id: ${JSON.stringify(pkg.name)}`)) {
 }
 if (pkg.private === true) failures.push('package.json 里 private: true, 发不出去（发布前删掉）');
 
+// 闭包 ⊆ 白名单: 从入口正推运行时必需文件, 逐条要求在 files 展开结果里
+// （算法见 dsh-plugin/lib/pack-closure.mjs；只读文件, 不跑 npm pack ⇒ 可以安全地待在 prepack 里）
+const closure = checkPackClosure(PKG_ROOT);
+if (!closure.ok) {
+  failures.push(`files 白名单漏了 ${closure.missing.length} 个运行时必需文件`
+    + `（新增运行时文件/目录后忘了改 package.json 的 files 就会这样）:`);
+  for (const rel of closure.missing) failures.push(`files 缺: ${rel}`);
+}
+
 if (failures.length > 0) {
   console.error(`prepack 自检未通过（${failures.length} 项）:`);
   for (const line of failures) console.error(`  - ${line}`);
   process.exit(1);
 }
-console.log(`prepack 自检通过: ${pkg.name}@${pkg.version}, ${REQUIRED.length} 个必需路径齐全, 包名三处一致`);
+console.log(`prepack 自检通过: ${pkg.name}@${pkg.version}, ${REQUIRED.length} 个必需路径齐全, 包名三处一致, `
+  + `运行时闭包 ${closure.closure.files.length} 个文件全在白名单内`);

package/lifecycle.py

@@ -20,8 +20,14 @@ Python 后端是 dsh 宿主进程 spawn 的子进程。宿主退出/崩溃/被 `
      父还活着（例如 stdin 不是管道、或管道被无关方关闭）只记日志不自杀。
 
 2. **同库单实例** `SingleInstance`
-   - `<db>.lock` 排它锁（`platcompat.lock_fd`）+ `<db>.pid` 记录
-     `{pid, ppid, repo_dir, parent_watch, started_at}`。
+   - `<db>.lock` 上**两道锁**：`flock` 排它（`platcompat.lock_fd`）+ 同一文件上的
+     **SQLite 排它锁**（`locking_mode=EXCLUSIVE` + 一次写事务，持锁到进程结束）；
+     再写 `<db>.pid` 记录 `{pid, ppid, repo_dir, parent_watch, started_at}`。
+     - 为什么要两道（2026-10-11，Node 后端 M1）：flock 只有 Python 侧有（Node 无
+       stdlib flock），Node 版改用 SQLite 自身的排它锁，两种锁**互不相干**
+       ⇒ 只靠 flock 挡不住 Node 版实例（实测：Node 持锁时 Python 的 flock 照样
+       成功）。两边都取 SQLite 锁后，同语言与跨语言互斥都成立，且 `kill -9` 后
+       由内核/文件锁自动释放，无需清理残留。
    - 锁被占时：读 pid 记录——若记录进程**由父死感知托管**（`parent_watch=true`）
      且其父已死 ⇒ 判定为**存量孤儿**（升级前的强杀残留），SIGTERM 后重试拿锁；
      否则视为真·另一实例，明确报错退出（防双写同库）。
@@ -39,6 +45,7 @@ Python 后端是 dsh 宿主进程 spawn 的子进程。宿主退出/崩溃/被 `
 import json
 import os
 import signal
+import sqlite3
 import sys
 import threading
 import time
@@ -225,6 +232,8 @@ class SingleInstance:
         self.reason = ""
         self.reaped_pid = 0
         self._fd = None
+        # SQLite 排它锁的连接（第二道闸，M1）；持锁期间常驻，release 时关闭
+        self._lock_conn = None
 
     # ---------- 记录读写 ----------
 
@@ -259,17 +268,21 @@ class SingleInstance:
 
     @staticmethod
     def _looks_like_server(pid):
-        """粗校验 pid 是否是 touchstone 的 server.py（防 PID 复用误杀）。
+        """粗校验 pid 是否是 touchstone 的后端（防 PID 复用误杀）。
 
+        两版后端的命令行都要认：Python 是 `server.py`，Node 是 `backend/server.js`
+        （2026-10-11 M1 起 Node 版也走同一套 `.pid` 记录与孤儿收口）。
         读不到命令行时返回 True（宁可不杀——见 acquire 的调用点：仅在
         「pid 记录声明 parent_watch 且其父已死」时才走到这里）。
         """
         try:
             if sys.platform.startswith("linux"):
                 with open(f"/proc/{int(pid)}/cmdline", "rb") as f:
-                    return b"server.py" in f.read()
+                    cmdline = f.read()
+                return b"server.py" in cmdline or b"server.js" in cmdline
             import psutil
-            return any("server.py" in str(a) for a in psutil.Process(int(pid)).cmdline())
+            argv = [str(a) for a in psutil.Process(int(pid)).cmdline()]
+            return any("server.py" in a or "server.js" in a for a in argv)
         except Exception:                        # noqa: BLE001
             return True
 
@@ -308,12 +321,93 @@ class SingleInstance:
 
     # ---------- 加锁 ----------
 
+    def _acquire_sqlite_lock(self):
+        """第二道闸：同一锁文件上的 SQLite 排它锁（M1，2026-10-11）。
+
+        Node 版没有 stdlib `flock`，改用 SQLite 自身的排它锁：在 `<db>.lock` 上
+        `PRAGMA locking_mode=EXCLUSIVE` + 一次写事务，锁持有到进程/连接结束
+        （`kill -9` 由内核释放，无残留文件要清理）。两种锁机制**互不相干**，所以
+        两边都要取这一道，跨语言互斥才成立（实测：Node 持锁时 Python 的 flock
+        照样能拿到）。
+
+        返回 `(状态, 文案)`：
+          - `("ok", "")`      拿到（连接挂在 `self._lock_conn`）
+          - `("busy", "")`    被占用（调用方报「另一实例」并退出）
+          - `("unusable", 文案)` 锁文件本身不可用（损坏/是目录/打不开）——
+            **不再降级放行**（2026-10-11 评审 P1）：降级等于互斥无声消失，
+            实测「先起 Python 再起 Node」双方都能就绪 ⇒ 同库双写。
+        """
+        try:
+            conn = sqlite3.connect(self.lock_path, timeout=0)
+        except sqlite3.Error as e:
+            return "unusable", self._unusable_reason(e)
+        try:
+            conn.execute("PRAGMA busy_timeout=0")
+            conn.execute("PRAGMA locking_mode=EXCLUSIVE")
+            # 必须真写一次：EXCLUSIVE 模式在首个写事务时取锁并一直持有
+            conn.execute("CREATE TABLE IF NOT EXISTS lock_holder ("
+                         " id INTEGER PRIMARY KEY CHECK (id = 1),"
+                         " pid INTEGER NOT NULL, started_at INTEGER NOT NULL)")
+            conn.execute("INSERT OR REPLACE INTO lock_holder(id, pid, started_at)"
+                         " VALUES(1, ?, ?)", (os.getpid(), int(time.time())))
+            conn.commit()
+        except sqlite3.Error as e:
+            try:
+                conn.close()
+            except sqlite3.Error:
+                pass
+            if "locked" in str(e) or "busy" in str(e):
+                return "busy", ""
+            return "unusable", self._unusable_reason(e)
+        self._lock_conn = conn
+        return "ok", ""
+
+    def _unusable_reason(self, error):
+        """锁文件不可用的报错文案（与 Node `lock.js:unusableLockReason` 同义）。"""
+        return (f"单实例锁文件不可用：{self.lock_path}（库 {self.db_file}）。原因：{error}。"
+                f"该文件应为 SQLite 库或 0 字节空文件；内容损坏/被换成目录时无法建立互斥，"
+                f"继续启动会与另一版后端同库双写（任务重复执行、队列行被抢）。"
+                f"修复：确认没有实例在跑之后把它移走再启动"
+                f"（mv {self.lock_path} {self.lock_path}.broken）；"
+                f"或显式 --allow-shared-db 自担双写风险。")
+
+    def _release_sqlite_lock(self):
+        """释放 SQLite 排它锁（幂等）。"""
+        conn, self._lock_conn = self._lock_conn, None
+        if conn is None:
+            return
+        try:
+            conn.close()
+        except sqlite3.Error:
+            pass
+
+    def _try_take_locks(self):
+        """两道锁的状态：`("ok"|"busy"|"unusable", 文案)`。
+
+        flock 拿到但 SQLite 被占/不可用时**回退 flock**：留着不放会挡住下一个 Python
+        实例去走「孤儿收口 → 重试」的路径（它只看到 flock 被占），把可恢复的孤儿变成死锁。
+        """
+        if not platcompat.lock_fd(self._fd, blocking=False):
+            return "busy", ""
+        state, detail = self._acquire_sqlite_lock()
+        if state == "ok":
+            return "ok", ""
+        try:
+            platcompat.unlock_fd(self._fd)
+        except OSError:
+            pass
+        return state, detail
+
     def acquire(self):
-        """拿同库单实例锁。True=拿到（已写 pid 记录）；False=被真·另一实例占用。
+        """拿同库单实例锁。True=拿到（已写 pid 记录）；False=不能独占（`reason` 说明原因）。
 
         非阻塞试锁 + 存量孤儿收口：拿到即写记录返回；拿不到先读 pid 记录——
         若记录进程由父死感知托管且其父已死，判为存量孤儿，SIGTERM 后在
         `stale_wait` 内重试；否则立即返回 False 并给出可执行的报错文案。
+
+        **不再有「降级为无锁运行」分支**（2026-10-11 评审 P1）：锁文件打不开/损坏时
+        返回 False（调用方 exit 3）并给修复步骤——静默降级会让互斥无声消失、同库双写，
+        那比「启动被拒」严重得多。
         """
         os.makedirs(os.path.dirname(self.lock_path), exist_ok=True)
         if self.allow_shared:
@@ -322,15 +416,18 @@ class SingleInstance:
         try:
             fd = os.open(self.lock_path, os.O_RDWR | os.O_CREAT, 0o644)
         except OSError as e:
-            self.log(f"[lifecycle] 锁文件打开失败（降级为无锁运行）: {e}")
-            return True
+            self.reason = self._unusable_reason(e)
+            return False
         self._fd = fd
-        deadline = time.time() + max(self.stale_wait, 0.5) + 1.0
         reaped = False
         while True:
-            if platcompat.lock_fd(fd, blocking=False):
+            state, detail = self._try_take_locks()
+            if state == "ok":
                 self._write_record(os.getpid())
                 return True
+            if state == "unusable":
+                self.reason = detail
+                return False
             rec = self._read_record()
             if rec and not reaped and self._reap_stale(rec):
                 reaped = True                   # 孤儿已收口：其锁随进程退出释放，再试
@@ -343,9 +440,14 @@ class SingleInstance:
                     f"（TOUCHSTONE_DB / 插件 extraEnv.TOUCHSTONE_DB），"
                     f"或显式 --allow-shared-db 自担双写风险。")
             else:
-                self.reason = (f"锁文件被占用且无归属记录：{self.lock_path}"
-                               f"（库 {self.db_file}）。若确认无实例在跑，"
-                               f"删除该锁文件后重试。")
+                # 无归属记录时**不要**教用户删锁文件：删掉后新实例会在新 inode 上取锁，
+                # 与仍在运行的占用者双写（flock 与 SQLite 锁同理）。给安全的两个出口。
+                self.reason = (
+                    f"锁文件被占用且无归属记录：{self.lock_path}"
+                    f"（库 {self.db_file}）。占用者可能是另一版后端的异常窗口"
+                    f"（Node 版取锁后、写 .pid 前被杀）或残留的第三方进程；"
+                    f"如需并行请用独立库（TOUCHSTONE_DB / 插件 extraEnv.TOUCHSTONE_DB），"
+                    f"或显式 --allow-shared-db 自担双写风险。")
             return False
         # 不可达：while True 内所有分支都 return（保静态检查可读性）
 
@@ -354,6 +456,7 @@ class SingleInstance:
         rec = self._read_record()
         if rec and int(rec.get("pid") or 0) == os.getpid():
             self._remove_record()
+        self._release_sqlite_lock()
         if self._fd is not None:
             platcompat.unlock_fd(self._fd)
             try:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavinc-cn/touchstone-dsh",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AI-agent-driven automated testing platform for DeepSeek Harness (dsh): Markdown case library, bug reports, per-project serial queue, development board and built-in load testing.",
   "license": "MIT",
   "author": "Touchstone contributors",
@@ -27,6 +27,10 @@
   "files": [
     "*.py",
     "requirements.txt",
+    "backend/server.js",
+    "backend/lib",
+    "backend/routes",
+    "backend/schema",
     "builtin_prompts",
     "extensions",
     "dsh-plugin/cordis.patch.yml",
@@ -55,6 +59,7 @@
   },
   "scripts": {
     "build:client": "node dsh-plugin/scripts/build.mjs",
+    "test:backend": "node --test \"backend/test/**/*.test.mjs\"",
     "prepack": "node dsh-plugin/scripts/prepack-check.mjs"
   },
   "repository": {