@gavinc-cn/touchstone-dsh 0.1.1 → 0.3.0

package/backend/lib/localbus.js

@@ -0,0 +1,164 @@
+/**
+ * 进程内变更总线（`localbus.py` 91 行的 Node 对应物，Node 后端 M2）。
+ *
+ * 用途（与 Python 侧逐字同）：看板/会话前端原先定时拉全量 payload；事件化后由本总线唤醒——
+ * 写路径（卡片增删改列、行收口）与 dsh 状态帧各发一次「值得重取」信号，前端在事件到达时
+ * 才重取，静置期零请求。
+ *
+ * 三条不变量（照抄 Python 模块头的设计要点，**改代码不得破坏**）：
+ *   ① **只发信号不带载荷**：topic ＝ `['board', projectId]`，载荷恒空。携带增量需要维护
+ *      增量协议与丢失补发，而 payload 本身很小——「信号 + 客户端重取」最简且不会错；
+ *   ② **序号单调**：每个 topic 一条从 1 开始的计数。订阅者记住自己上次看到的 seq，
+ *      `wait()` 等到变化或超时（超时用于发 keepalive）。序号单调 ⇒ **漏唤醒只晚一拍，
+ *      不会永久丢失**；
+ *   ③ **publish 绝不抛、O(1)**：发布点散布在 DB 写路径与 dsh 消费线程里，任何异常都必须
+ *      被吞掉（通知失败绝不能影响业务写）。
+ *
+ * 形态差异（Python → Node，唯一必要的差异，语义等价）：
+ *   - Python `wait(topic, since, timeout)` 是**条件变量阻塞**（`threading.Condition`）；
+ *     Node 是事件循环 ⇒ `wait(topic, since, timeoutMs)` 返回 **`Promise<number>`**，
+ *     resolve 值是「唤醒/超时时刻该 topic 的当前序号」。调用方拿返回值与 `since` 比较即可
+ *     判断「有无变化」（超时时两者相等）——与 Python 返回值口径完全一致。
+ *   - Python `notify_all()` 会唤醒**所有** topic 的等待者（被误唤醒者读回自己的 seq、值不变，
+ *     调用方本就按值判断）；Node 只 settle 该 topic 的等待者。少一次无意义唤醒，观感一致。
+ *   - topic 是数组（`['board', 7]`），而 Map/setTimeout 需要**稳定键** ⇒ 内部一律经
+ *     `topicKey()` 归一为字符串；`stats().seq` 的键就是这个字符串键（Python 是元组键）。
+ *   - `timeoutMs` 单位毫秒（Python 是秒）；省略即无限等待（Python 的 `timeout` 是必填位置
+ *     参数，调用方一律会传）。
+ */
+/** topic → 内部字符串键（JSON 文本；数组 topic 与字符串 topic 不会撞键）。
+ *  归一可能抛（如循环引用的 topic）——调用方 `publish()` 已把整段包进 try。 */
+export function topicKey(topic) {
+  return JSON.stringify(topic);
+}
+
+/**
+ * 按 topic 计数的进程内变更总线（对齐 `localbus.ChangeBus`）。
+ *
+ * 内部状态：
+ *   `_seq`     Map<key, number> —— 每个 topic 的单调序号（未发布过视为 0）；
+ *   `_waiters` Set<{key, since, resolve, timer}> —— 当前挂起的等待者（诊断用计数即它的 size）。
+ */
+export class ChangeBus {
+  constructor() {
+    this._seq = new Map();
+    this._waiters = new Set();
+  }
+
+  /**
+   * 发布一次变更：序号 +1 并唤醒该 topic 的等待者。**O(1) 且绝不抛**。
+   *
+   * 整段（含 topic 归一）包在 try 里：即使调用方递来无法序列化的 topic，也只是这一次通知
+   * 失败，业务写路径照常返回。
+   *
+   * @param {Array|string} topic
+   */
+  publish(topic) {
+    try {
+      const key = topicKey(topic);
+      this._seq.set(key, (this._seq.get(key) || 0) + 1);
+      this._wake(key);
+    } catch {
+      // noqa：通知失败绝不影响业务（对应 Python 侧的 except Exception: pass）
+    }
+  }
+
+  /**
+   * 当前序号（订阅者用它做「从这里之后的变化」的基准；未发布过为 0）。
+   *
+   * @param {Array|string} topic
+   * @returns {number}
+   */
+  seq(topic) {
+    return this._seq.get(topicKey(topic)) || 0;
+  }
+
+  /**
+   * 等到 `seq(topic) !== since` 或超时；resolve 当前序号。
+   *
+   * - 调用时就已经落后（`seq !== since`）⇒ **立即** resolve，不注册等待者；
+   * - 否则注册一个等待者，被 `publish` settle 或在 `timeoutMs` 后 settle（超时返回的序号
+   *   等于 `since`，调用方据此发 keepalive）；
+   * - `timeoutMs` 省略/非有限值 ⇒ 无限等待（只可能被 publish 唤醒）。
+   *
+   * @param {Array|string} topic
+   * @param {number} since 调用方上次看到的序号
+   * @param {number} [timeoutMs]
+   * @returns {Promise<number>}
+   */
+  wait(topic, since, timeoutMs) {
+    const key = topicKey(topic);
+    const current = this._seq.get(key) || 0;
+    if (current !== since) return Promise.resolve(current);
+    return new Promise((resolve) => {
+      const entry = { key, since, resolve, timer: null };
+      if (typeof timeoutMs === 'number' && Number.isFinite(timeoutMs)) {
+        entry.timer = setTimeout(() => this._settle(entry), Math.max(0, timeoutMs));
+      }
+      this._waiters.add(entry);
+    });
+  }
+
+  /** 诊断（健康检查、测试断言用）：`{topics, waiters, seq}`，seq 键为 `topicKey()` 口径 */
+  stats() {
+    const seq = {};
+    for (const [key, value] of this._seq) seq[key] = value;
+    return { topics: this._seq.size, waiters: this._waiters.size, seq };
+  }
+
+  /** 唤醒该 topic 上「序号已变化」的等待者（值未变的继续等，直到自己的超时） */
+  _wake(key) {
+    const current = this._seq.get(key) || 0;
+    for (const entry of [...this._waiters]) {
+      if (entry.key === key && entry.since !== current) this._settle(entry);
+    }
+  }
+
+  /** 结算一个等待者：清定时器 → 摘除 → resolve 当前序号（重复调用幂等） */
+  _settle(entry) {
+    if (!this._waiters.delete(entry)) return;
+    if (entry.timer) clearTimeout(entry.timer);
+    entry.resolve(this._seq.get(entry.key) || 0);
+  }
+}
+
+// 模块级单例：进程内唯一总线（server 与 db 共用）——对齐 Python 的 `BUS = ChangeBus()`
+export const BUS = new ChangeBus();
+
+/** 模块级发布（对齐 `localbus.publish`） */
+export function publish(topic) {
+  BUS.publish(topic);
+}
+
+/** 模块级读序号（对齐 `localbus.seq`） */
+export function seq(topic) {
+  return BUS.seq(topic);
+}
+
+/** 模块级等待（对齐 `localbus.wait`；返回 Promise 而非阻塞） */
+export function wait(topic, since, timeoutMs) {
+  return BUS.wait(topic, since, timeoutMs);
+}
+
+/**
+ * 看板 topic 构造（单一出口，防各处拼错）。
+ *
+ * Python `board_topic` 走 `int(project_id)` 归一（`"9"` 与 `9` 同 topic）；Node 用
+ * `Number()` 对齐（非数字得到 NaN，与 Python 的 ValueError 一样属于调用方错误）。
+ *
+ * @param {number|string} projectId
+ * @returns {Array} `['board', <number>]`
+ */
+export function boardTopic(projectId) {
+  return ['board', Number(projectId)];
+}
+
+/**
+ * 单会话 topic（会话窗口事件流用；sid 为字符串，逐字符可比）。
+ *
+ * @param {string|number} sessionId
+ * @returns {Array} `['session', '<sid>']`
+ */
+export function sessionTopic(sessionId) {
+  return ['session', String(sessionId)];
+}

package/backend/lib/lock.js

@@ -0,0 +1,405 @@
+/**
+ * 同库单实例锁（Node 后端对 `lifecycle.SingleInstance` 的等价实现，M1）。
+ *
+ * 背景：Python 后端与 Node 后端共用 `~/.touchstone/touchstone.db`（或 `TOUCHSTONE_DB`
+ * 指定的库），同库双实例会双写任务/队列行。Python 侧用 `<db>.lock` 的
+ * `flock(LOCK_EX|LOCK_NB)` 强制互斥，第二个实例 **exit 3** 并打印占用者。
+ *
+ * Node 没有 stdlib `flock`，改用 **SQLite 自身的排它锁**、落在**同一个 `<db>.lock` 路径**
+ * 上（2026-10-11 实测，方案 §附录 C③ / 风险 R4）：
+ *   ① `new DatabaseSync(lockPath, { timeout: 0 })` + `PRAGMA busy_timeout=0`
+ *      + `PRAGMA locking_mode=EXCLUSIVE`，再做一次写事务 ⇒ 排它锁**持有到连接关闭**
+ *      （`locking_mode=EXCLUSIVE` 的语义：首次写入后不再释放文件锁）；
+ *   ② 第二个进程（Node 的 `node:sqlite` 或 Python 的 `sqlite3`）再试同一操作 ⇒ **立即**
+ *      `database is locked`（Node：`code=ERR_SQLITE_ERROR errcode=5`；Python：`OperationalError`）；
+ *   ③ `kill -9` 持有者 ⇒ 内核释放文件锁，下一个进程随即拿到（**不需要任何清理动作**）；
+ *   ④ **跨语言互通**：flock 与 SQLite 锁互不相干，所以两边都要取 SQLite 锁才是真互斥
+ *      ——本文件是 Node 侧那一半。
+ *
+ * 语义（逐条对齐 `lifecycle.SingleInstance`，行号见该文件 205-364）：
+ *   - 拿不到锁 ⇒ 读 `<db>.pid`（JSON `{pid, ppid, repo_dir, parent_watch, started_at}`；
+ *     Node 版多写 `"backend": "node"` 便于排障）；
+ *   - 记录里 `parent_watch` 为真、其 `ppid` 已死、且 pid 命令行像本平台后端
+ *     （`server.py` **或** `backend/server.js`）⇒ 判为**存量孤儿**，只向**该单个 pid**
+ *     SIGTERM（绝不 killpg：孤儿常与宿主同组），在 `staleWaitMs` 内等它让出锁后**重试一次**；
+ *   - 否则返回失败与同义文案，由 server.js 打印并以 **exit 3** 退出；
+ *   - `--allow-shared-db`（`allowShared`）跳过整条锁流程，只打一条 warn；
+ *   - 锁文件打不开/不可写 ⇒ **降级为无锁运行**（warn 后继续），绝不因锁问题让后端起不来；
+ *   - `release()` 幂等：仅当 `.pid` 记录的 pid 仍是自己时删除记录，并关闭 SQLite 连接释放锁。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+import { isRunning, looksLikeBackend, pidAlive, terminatePid } from './proc.js';
+
+/** 存量孤儿 SIGTERM 后等待其让出锁的上限（毫秒）。对齐 `lifecycle.STALE_WAIT = 5.0s` */
+export const STALE_WAIT_MS = 5000;
+/** 等待孤儿退出的轮询间隔（毫秒）。对齐 Python 侧 `time.sleep(0.1)` */
+export const REAP_POLL_MS = 100;
+/** 库路径缺省值（与 `db.py:DB_OVERRIDE` 的缺省逐字相同） */
+export const DEFAULT_DB = '~/.touchstone/touchstone.db';
+/** 锁库里的归属表名（内容仅供参考/排障：判据是 SQLite 的排它锁本身，不是表里那一行） */
+const LOCK_TABLE = 'touchstone_instance_lock';
+
+/** 同步 sleep 用的共享缓冲（Atomics.wait：主线程可用的同步等待，不占 CPU） */
+const SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+
+/** 同步睡眠（毫秒）：收口等待是同步流程（对齐 Python 的 time.sleep） */
+function sleepMs(ms) {
+  if (ms > 0) Atomics.wait(SLEEP_BUF, 0, 0, ms);
+}
+
+/**
+ * 数据库文件路径（对齐 `db.py:db_path()`：`TOUCHSTONE_DB` 覆盖，缺省 `~/.touchstone/touchstone.db`，
+ * 且对取值做 `~` 展开——展开口径与 `backend/lib/db.js:defaultDbPath` 的 `expandUser` 逐条相同）。
+ *
+ * **不变量：锁路径必须与「数据层真正打开的那个库」同源**（`<db>.lock` 锁错文件等于没锁）。
+ * Node 侧数据层的权威解析口是 `db.js:defaultDbPath()`（M1 已落地）；本函数是**不依赖数据层**的
+ * 同口径实现，供入口与单测使用（放这里是为了让锁模块自包含、可脱离 schema 契约单独跑）。
+ * 两者对任意取值同口径（含 `TOUCHSTONE_DB=""`：按未设处理，与 `defaultDbPath` 的 `||` 一致；
+ * 该取值在 Python 侧会落到 `sqlite3.connect('')` 的临时库，本就不是可用配置）。
+ * M2 起 server.js 也可以直接改传
+ * `db.defaultDbPath()`，届时删除本函数即可（**不要**留两份各自演化的解析器）。
+ */
+export function resolveDbPath({ env = process.env, home = os.homedir() } = {}) {
+  // 空串按「未设」处理（与 `db.js:defaultDbPath` 的 `||` 同口径）：空串在 Python 侧会落到
+  // `sqlite3.connect('')` 的临时库（一个不可用的库），两侧都不该把它当成真路径。
+  const value = env && env.TOUCHSTONE_DB;
+  const raw = String(value ? value : DEFAULT_DB);
+  let expanded = raw;
+  if (raw === '~') expanded = home;
+  else if (raw.startsWith('~/') || raw.startsWith('~\\')) expanded = path.join(home, raw.slice(2));
+  return path.resolve(expanded);
+}
+
+/**
+ * 由库路径派生锁路径（对齐 `SingleInstance.__init__` 的两条 `+ ".lock"` / `+ ".pid"`）。
+ * `dbPath` 一律转绝对路径：Python 侧 `os.path.abspath(db_file)` 同款。
+ */
+export function lockPaths(dbPath) {
+  const abs = path.resolve(String(dbPath));
+  return { dbPath: abs, lockPath: `${abs}.lock`, pidPath: `${abs}.pid` };
+}
+
+/** 读 `.pid` 归属记录：不存在/坏 JSON/不是对象 ⇒ null（对齐 Python `_read_record`） */
+export function readPidRecord(pidPath) {
+  try {
+    const record = JSON.parse(fs.readFileSync(pidPath, 'utf8'));
+    if (!record || typeof record !== 'object' || Array.isArray(record)) return null;
+    return record;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 写 `.pid` 归属记录（临时文件 + rename 原子替换，对齐 Python `_write_record`）。
+ * 写不进去**不影响运行**（只是失去存量孤儿识别能力）：记一条日志返回 false。
+ */
+export function writePidRecord(pidPath, record, logger) {
+  const log = typeof logger === 'function' ? logger : () => {};
+  // 绝不覆写「活着的别家后端」的归属记录（2026-10-11 评审 P1）：那是对方的排障凭据，
+  // 实测被覆盖并删除过一次（Node 起在同一库上，旧版 Python 实例的 `.pid` 就消失了）。
+  // 自己写自己（同 pid）允许——重启/重入路径要用。判活 + 命令行像后端，扛 PID 复用。
+  const existing = readPidRecord(pidPath);
+  const existingPid = existing ? Number(existing.pid) : 0;
+  if (existingPid > 0 && existingPid !== Number(record.pid)
+      && pidAlive(existingPid) && looksLikeBackend(existingPid)) {
+    log(`[lock] 已有活着的后端归属记录 pid=${existingPid}，拒绝覆写 ${pidPath}`);
+    return false;
+  }
+  const tmp = `${pidPath}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(record), 'utf8');
+    fs.renameSync(tmp, pidPath);
+    return true;
+  } catch (error) {
+    log(`[lock] pid 记录写入失败（忽略）: ${(error && error.message) || error}`);
+    return false;
+  }
+}
+
+/** 删 `.pid` 归属记录：不存在或删不掉都安全忽略（对齐 Python `_remove_record`） */
+export function removePidRecord(pidPath) {
+  try {
+    fs.rmSync(pidPath, { force: true });
+  } catch {
+    /* 忽略：记录清理失败不影响锁（锁由内核在进程退出时释放） */
+  }
+}
+
+/**
+ * 父进程是否仍存活（对齐 `lifecycle.parent_alive`）：ppid 非法或 <=1 视为父已死
+ * （POSIX 孤儿被 init 收养 ⇒ ppid=1；Windows 不收养，但 Node 侧同样以非法值兜底）。
+ */
+export function parentAlive(ppid = process.ppid) {
+  const n = Number(ppid);
+  if (!Number.isInteger(n) || n <= 1) return false;
+  return pidAlive(n);
+}
+
+/** SQLITE_BUSY / "database is locked" 判定：区分「被别人占着」与「根本打不开」两类失败 */
+export function isBusyError(error) {
+  if (!error) return false;
+  if (error.errcode === 5) return true;                     // SQLITE_BUSY
+  return /database (is|table is) locked|SQLITE_BUSY/i.test(String(error.message || ''));
+}
+
+/**
+ * 在 `<db>.lock` 上取 SQLite 排它锁（本模块的核心机制，已实测；见文件头 ①②③④）。
+ * 成功返回**持有锁的连接**（调用方必须一直持有到进程退出/释放：关连接即释放锁）；
+ * 失败抛原错误（`isBusyError` 为真的 ⇒ 被占用；否则 ⇒ 打不开，调用方降级无锁）。
+ *
+ * 三件事的顺序不能变：`busy_timeout=0` 必须在任何语句前（否则会阻塞等待而不是立即报忙）；
+ * `locking_mode=EXCLUSIVE` 必须在第一次写入前（写后再设就晚了，锁会在事务结束时放开）。
+ */
+export function tryExclusiveLock(lockPath) {
+  const db = new DatabaseSync(lockPath, { timeout: 0 });    // 打开本身不加锁
+  try {
+    db.exec('PRAGMA busy_timeout=0');                       // 立即失败，绝不阻塞在锁上
+    db.exec('PRAGMA locking_mode=EXCLUSIVE');               // 首写后锁不释放（持有到连接关闭）
+    db.exec('BEGIN IMMEDIATE');
+    db.exec(`CREATE TABLE IF NOT EXISTS ${LOCK_TABLE} `
+      + '(id INTEGER PRIMARY KEY CHECK (id = 1), pid INTEGER, backend TEXT, acquired_at INTEGER)');
+    db.exec(`INSERT OR REPLACE INTO ${LOCK_TABLE} (id, pid, backend, acquired_at) `
+      + `VALUES (1, ${process.pid}, 'node', ${Math.floor(Date.now() / 1000)})`);
+    db.exec('COMMIT');
+    return db;
+  } catch (error) {
+    try {
+      db.close();
+    } catch {
+      /* 关闭失败无妨：进程退出时内核会释放所有文件锁 */
+    }
+    throw error;
+  }
+}
+
+/**
+ * 存量孤儿收口（对齐 `lifecycle.SingleInstance._reap_stale`，判定顺序逐条相同）。
+ * 返回被收口的 pid；未收口返回 0（记录过期 / 非父死感知托管 / 父仍活着 / 不像后端 / 等不到退出）。
+ *
+ * **只向该单个 pid 发 SIGTERM，绝不 killpg/杀进程组**：孤儿往往与它的宿主
+ * （甚至是正在启动我们的这个 dsh 进程）同组，整组终止会连带杀掉自己——Python 侧实测踩中。
+ */
+export function reapStale({ record, staleWaitMs = STALE_WAIT_MS, logger } = {}) {
+  const log = typeof logger === 'function' ? logger : () => {};
+  if (!record || typeof record !== 'object') return 0;
+  const pid = Number(record.pid);
+  if (!Number.isInteger(pid) || pid <= 0 || !pidAlive(pid)) return 0;   // 记录已过期：直接试锁
+  if (!record.parent_watch) return 0;                                   // 非父死感知托管：绝不代杀
+  if (parentAlive(record.ppid)) return 0;                               // 其父还活着：真·另一实例
+  if (!looksLikeBackend(pid)) {
+    log(`[lock] pid 记录 ${pid} 不像本平台后端（PID 复用？），不处置`);
+    return 0;
+  }
+  log(`[lock] 发现存量孤儿后端 pid=${pid}（父已死），SIGTERM 收口…`);
+  terminatePid(pid);                                                    // 只杀单个 pid
+  const deadline = Date.now() + Math.max(Number(staleWaitMs) || 0, 0);
+  // 判活用 isRunning（僵尸算已退出）：本循环是同步的（Atomics.wait 阻塞事件循环），
+  // 若孤儿恰好是本进程的子进程，父进程不 reap 它就一直 pidAlive=true，会白等满宽限。
+  // 僵尸不持有任何锁（内核已回收），按「已退出」处理既正确又不会误判存量实例。
+  while (isRunning(pid) && Date.now() < deadline) sleepMs(REAP_POLL_MS);
+  if (isRunning(pid)) {
+    log(`[lock] 孤儿 pid=${pid} 未在 ${staleWaitMs}ms 内退出，放弃收口`);
+    return 0;
+  }
+  log(`[lock] 存量孤儿 pid=${pid} 已收口`);
+  return pid;
+}
+
+/**
+ * 归属记录里的**活着的别家后端**（不是自己、进程存活、且命令行像后端）。返回记录或 null。
+ *
+ * 为什么需要这道额外检查（2026-10-11 评审 P1，**已在生产上实际发生过一次**）：Node 只有
+ * SQLite 那道锁，而 M1 之前的 Python 实例只持 flock（Node 看不见）⇒ Node 能起在同一库上，
+ * 实测还覆写并删掉了生产实例的 `.pid`。`looksLikeBackend` 用来扛 PID 复用误判。
+ * @param {string} pidPath
+ * @returns {object|null}
+ */
+export function liveForeignHolder(pidPath) {
+  const record = readPidRecord(pidPath);
+  if (!record) return null;
+  const pid = Number(record.pid);
+  if (!Number.isFinite(pid) || pid <= 0 || pid === process.pid) return null;
+  if (!pidAlive(pid)) return null;
+  if (!looksLikeBackend(pid)) return null;
+  return record;
+}
+
+/** 锁文件不可用（非「被占用」）的拒绝文案：说清现象、危害与两条可行修复路径 */
+export function unusableLockReason(lockPath, dbPath, error) {
+  return `单实例锁文件不可用：${lockPath}（库 ${dbPath}）。原因：`
+    + `${(error && error.message) || error}。`
+    + '该文件应为 SQLite 库或 0 字节空文件；内容损坏/被换成目录时无法建立互斥，'
+    + '继续启动会与另一版后端同库双写（任务重复执行、队列行被抢）。'
+    + '修复：确认没有实例在跑之后把它移走再启动'
+    + `（mv ${lockPath} ${lockPath}.broken）；`
+    + '或显式 --allow-shared-db 自担双写风险。';
+}
+
+/** 归属记录里已有活着的别家后端时的拒绝文案（含「未升级的旧版实例」这一真实成因） */
+export function foreignHolderReason(record, dbPath, pidPath) {
+  return `同一数据库已有运行中的实例：pid=${record.pid} ppid=${record.ppid} `
+    + `repo=${record.repo_dir || '-'}（库 ${dbPath}）。`
+    + '它可能是 M1 之前启动的旧版后端（只持 flock，本版看不见那道锁）。'
+    + '如需并行请用独立库（TOUCHSTONE_DB / 插件 extraEnv.TOUCHSTONE_DB），'
+    + `或先停掉它；确认记录已过期可删除 ${pidPath} 后重试。`;
+}
+
+/**
+ * 占用者明确时的失败文案（与 `lifecycle.py:339-344` **逐字同义**：
+ * pid/ppid/repo + 独立库出口 + `--allow-shared-db` 逃生口）。
+ */
+export function instanceBusyReason(record, dbPath) {
+  const ppid = record.ppid === undefined || record.ppid === null ? '-' : record.ppid;
+  return `同一数据库已有运行中的实例：pid=${record.pid} ppid=${ppid} repo=${record.repo_dir || '-'}`
+    + `（库 ${dbPath}）。如需并行请用独立库`
+    + `（TOUCHSTONE_DB / 插件 extraEnv.TOUCHSTONE_DB），`
+    + `或显式 --allow-shared-db 自担双写风险。`;
+}
+
+/**
+ * 锁被占但**没有归属记录**时的失败文案（与 Python `lifecycle.py` 的同名分支**同义**，
+ * 2026-10-11 两版对齐后的口径）：
+ *   - **绝不教用户「删除锁文件」**——删除会把 inode 换掉，新实例在新 inode 上取锁，
+ *     与仍在运行的占用者双写（flock 与 SQLite 锁同理），是危险的错误建议；
+ *   - 只给两个安全出口：独立库（TOUCHSTONE_DB / 插件 extraEnv.TOUCHSTONE_DB）与
+ *     `--allow-shared-db`（自担双写风险）——这也是 M1 对失败提示的硬要求。
+ * 可能出现的场景：另一版后端在「取锁成功、写 .pid 之前」被杀（Node 侧窗口），
+ * 或第三方进程占着同一把 SQLite 锁。
+ */
+export function lockBusyReason(lockPath, dbPath) {
+  return `锁文件被占用且无归属记录：${lockPath}`
+    + `（库 ${dbPath}）。占用者可能是另一版后端的异常窗口`
+    + `（取锁后、写 .pid 前被杀）或残留的第三方进程；`
+    + `如需并行请用独立库（TOUCHSTONE_DB / 插件 extraEnv.TOUCHSTONE_DB），`
+    + `或显式 --allow-shared-db 自担双写风险。`;
+}
+
+/**
+ * 取同库单实例锁（`lifecycle.SingleInstance.acquire` 的等价物）。
+ *
+ * @param {object}   opts
+ * @param {string}   opts.dbPath       库文件路径（锁 = `<dbPath>.lock`，记录 = `<dbPath>.pid`）
+ * @param {string}   [opts.repoDir]    写进归属记录的仓库目录（排障用）
+ * @param {boolean}  [opts.parentWatch] 本进程是否由父死感知托管（决定别家能否收口我们）
+ * @param {boolean}  [opts.allowShared] `--allow-shared-db`：跳过整条锁流程
+ * @param {Function} [opts.logger]     日志口（缺省 stderr）
+ * @param {number}   [opts.staleWaitMs] 存量孤儿等待上限（缺省 5s，单测可调小）
+ * @returns {{ok: boolean, reason: string, reapedPid: number, release: Function}}
+ *          `ok=false` 时 `reason` 是给用户的完整中文说明（server.js 打印后 exit 3）。
+ */
+export function acquireSingleInstance({
+  dbPath,
+  repoDir = '',
+  parentWatch = false,
+  allowShared = false,
+  logger,
+  staleWaitMs = STALE_WAIT_MS,
+} = {}) {
+  const log = typeof logger === 'function' ? logger : (msg) => console.error(msg);
+  // dbPath 必填：漏传会让 path.resolve(undefined) 落在进程 CWD（`undefined.lock` 这种
+  // 脏产物实测出现过——锁错文件 = 等于没锁，必须在入口挡掉而不是静默继续）
+  if (typeof dbPath !== 'string' || !dbPath) {
+    throw new Error('acquireSingleInstance 需要 dbPath（库文件路径，锁与归属记录都由它派生）');
+  }
+  const paths = lockPaths(dbPath);
+  const state = { handle: null, held: false, reapedPid: 0 };
+
+  /**
+   * 释放锁与归属记录（幂等）。仅当**本次真的持锁**且 `.pid` 记录的 pid 仍是自己时才删记录
+   * （对齐 Python `release`；比它多一道 `held` 闸：失败/降级/共享模式下调用 release 也绝不
+   * 误删别人的记录）。关连接 = 释放 SQLite 锁；进程被 kill 时不需要走到这里（内核释放）。
+   */
+  const release = () => {
+    if (!state.held && state.handle === null) return;
+    const record = readPidRecord(paths.pidPath);
+    if (state.held && record && Number(record.pid) === process.pid) removePidRecord(paths.pidPath);
+    if (state.handle) {
+      try {
+        state.handle.close();
+      } catch {
+        /* 已关闭/已释放：忽略 */
+      }
+      state.handle = null;
+    }
+    state.held = false;
+  };
+
+  if (allowShared) {
+    log('[lock] --allow-shared-db：跳过同库单实例锁（自担双写风险）');
+    return { ok: true, reason: '', reapedPid: 0, release };
+  }
+
+  // 目录先建出来（对齐 Python `os.makedirs(dirname, exist_ok=True)`）；建不出来不在这里报错，
+  // 下面打开锁文件时同样会失败，统一走「降级为无锁运行」分支。
+  try {
+    fs.mkdirSync(path.dirname(paths.dbPath), { recursive: true });
+  } catch {
+    /* 交给打开失败分支 */
+  }
+
+  let reaped = false;
+  for (;;) {
+    let handle = null;
+    try {
+      handle = tryExclusiveLock(paths.lockPath);
+    } catch (error) {
+      if (!isBusyError(error)) {
+        // **不再静默降级**（2026-10-11 评审 P1）：锁文件是垃圾内容/是目录/不可读时，
+        // 降级放行 = 跨语言互斥无声消失（Node 没有 flock 可兜底），实测「先起 Python
+        // 再起 Node」两边都能就绪 ⇒ 同库双写。锁不可用属于**环境损坏**，必须显式拒绝
+        // 并给出可操作修复步骤；确要自担风险可显式 --allow-shared-db。
+        return { ok: false, reapedPid: 0, release,
+          reason: unusableLockReason(paths.lockPath, paths.dbPath, error) };
+      }
+    }
+    if (handle) {
+      // 拿到 SQLite 锁还不够：**M1 之前的 Python 实例只持 flock**（那道锁 Node 看不见），
+      // 所以还要看归属记录里有没有活着的别家后端。同库双写比「启动被拒」严重得多。
+      const holder = liveForeignHolder(paths.pidPath);
+      if (holder) {
+        try { handle.close(); } catch { /* 已关闭：忽略 */ }
+        return { ok: false, reapedPid: state.reapedPid, release,
+          reason: foreignHolderReason(holder, paths.dbPath, paths.pidPath) };
+      }
+      state.handle = handle;
+      state.held = true;
+      const wrote = writePidRecord(paths.pidPath, {
+        pid: process.pid,
+        ppid: process.ppid,
+        repo_dir: repoDir,
+        parent_watch: Boolean(parentWatch),
+        started_at: Math.floor(Date.now() / 1000),
+        backend: 'node',                       // Node 侧独有键：排障时一眼看出占用者版本
+      }, log);
+      if (!wrote && liveForeignHolder(paths.pidPath)) {
+        // 记录写不进去且里面是活着的别家：极窄的竞态窗口（另一个实例刚好在我们取锁后写记录）
+        state.held = false;
+        try { handle.close(); } catch { /* 忽略 */ }
+        state.handle = null;
+        return { ok: false, reapedPid: state.reapedPid, release,
+          reason: foreignHolderReason(liveForeignHolder(paths.pidPath), paths.dbPath,
+            paths.pidPath) };
+      }
+      return { ok: true, reason: '', reapedPid: state.reapedPid, release };
+    }
+
+    const record = readPidRecord(paths.pidPath);
+    if (record && !reaped) {
+      const reapedPid = reapStale({ record, staleWaitMs, logger: log });
+      if (reapedPid > 0) {
+        reaped = true;                         // 孤儿已收口：其锁随进程退出释放，重试一次
+        state.reapedPid = reapedPid;
+        continue;
+      }
+    }
+    const reason = record
+      ? instanceBusyReason(record, paths.dbPath)
+      : lockBusyReason(paths.lockPath, paths.dbPath);
+    return { ok: false, reason, reapedPid: state.reapedPid, release };
+  }
+}