sillyspec 3.26.0 → 3.26.1

package/.sillyspec-platform.json

@@ -3,5 +3,5 @@
   "runtimeRoot": null,
   "workspaceId": null,
   "scanRunId": null,
-  "savedAt": "2026-08-10T17:33:41.549Z"
+  "savedAt": "2026-08-11T04:01:27.160Z"
 }

package/README.md

@@ -59,12 +59,10 @@ npx sillyspec init --interactive      # 完整引导
 
 ## 平台支持
 
-SillySpec 进度库使用 SQLite 持久化（基于 better-sqlite3 原生绑定）。安装支持情况如下：
+SillySpec 进度库使用 SQLite 持久化（基于 Node.js 内置的 `node:sqlite` 模块，纯 JS 无原生编译依赖）。
 
-- **主流平台（prebuilt 零编译安装）**：Node.js >= 18 的 Linux x64、macOS x64 / macOS arm64、Windows x64。安装时直接下载预编译二进制，无需本地 C++ 工具链。
-- **边缘平台不保证**：Alpine（musl libc）、Windows arm64、BSD 等平台可能没有对应的 prebuilt 二进制，安装时可能触发 node-gyp 从源码编译（此时需要本机具备 C++ 编译工具链）。
-
-如遇边缘平台编译失败，建议在受支持的平台或容器（如 Debian/Ubuntu 基镜像）中运行。
+- **Node.js 版本要求 >= 22.11.0**：`node:sqlite` 自 v22.11.0 起免 `--experimental-sqlite` flag 直接可用。支持 Linux x64、macOS x64 / arm64、Windows x64 等所有 Node.js 官方支持平台。
+- **零编译安装**：不依赖任何原生绑定 / node-gyp / C++ 工具链，npm install 即装即用，无平台编译失败风险。
 
 ## 从哪里开始
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.26.0",
+  "version": "3.26.1",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",
@@ -13,7 +13,7 @@
     "sillyspec": "bin/sillyspec.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.11.0"
   },
   "keywords": [
     "sillyspec",
@@ -29,7 +29,6 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.10.1",
-    "better-sqlite3": "^11.0.0",
     "chalk": "^5.6.2",
     "chokidar": "^4.0",
     "js-yaml": "^4.2.0",

package/src/db-engine.js

@@ -0,0 +1,55 @@
+// db-engine.js — node:sqlite DatabaseSync 引擎抽象层
+// 封装 node:sqlite 内置模块 + 消解 better-sqlite3 → node:sqlite 三缺口：
+//   pragma → exec / transaction → 手写 SAVEPOINT / pluck → Object.values 取首列
+// 供 db.js 与 doctor-diagnostics 共用（方案 B 单一换引擎点，D-002）。
+// node:sqlite 在 node v22.11.0+ 无需 --experimental-sqlite flag（仍发 ExperimentalWarning）。
+// Author: sillyspec execute W1 task-02
+// Created: 2026-08-11
+import { DatabaseSync } from 'node:sqlite';
+
+// 打开数据库。opts.readOnly（驼峰）透传 node:sqlite。
+// fileMustExist 语义由调用方 existsSync 前置门实现（node:sqlite 不拒缺失文件，不凭空建库由调用方保证）。
+export function openDatabase(dbPath, opts = {}) {
+  return new DatabaseSync(dbPath, { readOnly: !!opts.readOnly });
+}
+
+// 逐条 exec PRAGMA。entries: [['journal_mode','WAL'], ['busy_timeout','5000'], ...]
+// node:sqlite 无 .pragma()，统一走 .exec('PRAGMA key = value')。
+export function applyPragmas(db, entries) {
+  for (const [key, value] of entries) {
+    db.exec(`PRAGMA ${key} = ${value}`);
+  }
+}
+
+// 手写事务（node:sqlite 无 .transaction()）。
+// 统一用 SAVEPOINT/RELEASE/ROLLBACK TO —— SQLite 允许顶层 SAVEPOINT（等价事务），
+// 嵌套调用自动形成 savepoint 栈（better-sqlite3 嵌套自动 SAVEPOINT 的兼容实现）。
+// fn 抛错自动 ROLLBACK TO + RELEASE 且原错误上抛不吞。
+// 本函数不含 BUSY 重试（由 db.js wrapper 外层包裹）。
+export function runTransaction(db, fn) {
+  const sp = 'tx_sp_' + Math.random().toString(36).slice(2);
+  db.exec(`SAVEPOINT ${sp}`);
+  try {
+    const result = fn();
+    db.exec(`RELEASE ${sp}`);
+    return result;
+  } catch (err) {
+    try {
+      db.exec(`ROLLBACK TO ${sp}`);
+      db.exec(`RELEASE ${sp}`);
+    } catch { /* 回滚失败不掩盖原错误 */ }
+    throw err;
+  }
+}
+
+// pluck 替代：取第一行第一列，无行 undefined。
+// node:sqlite .get() 返回行对象（不像 better-sqlite3 pluck 返标量），故 Object.values 取首列。
+export function pluckGet(db, sql, ...params) {
+  const row = db.prepare(sql).get(...params);
+  return row === undefined ? undefined : Object.values(row)[0];
+}
+
+// pluck 替代：取所有行第一列成数组。
+export function pluckAll(db, sql, ...params) {
+  return db.prepare(sql).all(...params).map((row) => Object.values(row)[0]);
+}

package/src/db.js

@@ -1,13 +1,13 @@
-import Database from 'better-sqlite3';
+import { openDatabase, applyPragmas, runTransaction } from './db-engine.js';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { dirname } from 'path';
 
 // DB schema 版本（与 project.schema_version DEFAULT 对齐）。_createSchema 改动（加表/列/migration）时 bump，
 // 触发 .schema-version 戳失效 → 下次 init 重跑 _createSchema（W4-H：高频读路径 gate/derive/status
 // 每次 new ProgressManager 都过 init，靠版本戳跳过建表省开销）。
-// better-sqlite3 是原生 SQLite 引擎，打开即持久化（不像 sql.js 纯内存需整库 export 落盘），
+// node:sqlite（DatabaseSync）是原生 SQLite 引擎，打开即持久化（不像 sql.js 纯内存需整库 export 落盘），
 // _createSchema 内 DDL 直接落盘，无需额外 _save。
-const DB_SCHEMA_VERSION = 4;
+const DB_SCHEMA_VERSION = 5;
 
 // SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）：WAL 单写者模型，并发写第二者在
 // busy_timeout=5000（init PRAGMA）后抛 SQLITE_BUSY。busy_timeout 已在引擎层处理大部分等待；
@@ -20,7 +20,7 @@ const MAX_BUSY_RETRIES = 3;
 const BUSY_BACKOFF_MS = [50, 100, 200];
 
 /**
- * 同步阻塞 sleep（better-sqlite3 同步 API，BUSY 退避不能用 await）。
+ * 同步阻塞 sleep（node:sqlite 同步 API，BUSY 退避不能用 await）。
  * Atomics.wait 阻塞当前线程不占 CPU；SharedArrayBuffer 不可用的环境（受限 CSP / 旧 Node）
  * 退化为 busy-wait（退避时长 50-200ms 短，CPU 占用可接受）。仅在 transaction() 的 BUSY
  * 重试路径调用。
@@ -41,13 +41,13 @@ export class DB {
   }
 
   /**
-   * 同步初始化（better-sqlite3 是同步 API，无 async/await，与 sql.js 的 initSqlJs() 异步加载不同）：
-   *  - new Database(path) 同步打开/创建库文件（better-sqlite3 原生绑定，非 WASM）
-   *  - PRAGMA：journal_mode=WAL 真生效（better-sqlite3 直连原生 SQLite，WAL 落地；
+   * 同步初始化（node:sqlite DatabaseSync 是同步 API，无 async/await，与 sql.js 的 initSqlJs() 异步加载不同）：
+   *  - openDatabase(path) 同步打开/创建库文件（node:sqlite 原生绑定，非 WASM）
+   *  - PRAGMA：journal_mode=WAL 真生效（node:sqlite 直连原生 SQLite，WAL 落地；
    *    sql.js 是纯内存库，WAL 对它无意义），busy_timeout=5000 让写锁竞争时自动等待，
    *    foreign_keys=ON 启用外键级联，synchronous=NORMAL 在 WAL 下兼顾安全与性能
    *  - schema 戳检查：内容匹配 DB_SCHEMA_VERSION 则跳过 _createSchema，省建表开销
-   *  - better-sqlite3 打开即持久化，DDL/事务提交直接落盘，不需要 sql.js 时代的 _save()
+   *  - node:sqlite 打开即持久化，DDL/事务提交直接落盘，不需要 sql.js 时代的 _save()
    *
    * .bak 损坏回退由 _openWithFallback() 承担（task-04）：主库 → .bak → 全新/报错 逐级回退，
    * 语义对齐原 sql.js 的 _loadDatabase。
@@ -60,14 +60,16 @@ export class DB {
     // 2. 同步打开/创建数据库（主库 → .bak → 全新/报错 逐级回退，归 task-04）
     this.db = this._openWithFallback();
 
-    // 3. 设置 PRAGMA（better-sqlite3 走真 SQLite，journal_mode=WAL 真生效）
-    this.db.pragma('journal_mode = WAL');
-    this.db.pragma('busy_timeout = 5000');
-    this.db.pragma('foreign_keys = ON');
-    this.db.pragma('synchronous = NORMAL');
+    // 3. 设置 PRAGMA（node:sqlite 走真 SQLite，journal_mode=WAL 真生效；经 applyPragmas 逐条 exec）
+    applyPragmas(this.db, [
+      ['journal_mode', 'WAL'],
+      ['busy_timeout', '5000'],
+      ['foreign_keys', 'ON'],
+      ['synchronous', 'NORMAL'],
+    ]);
 
     // 4. 创建表结构（仅当 schema 版本戳不匹配时——W4-H）：
-    //    schema 已最新则跳过建表，省 DDL 开销。better-sqlite3 打开即持久化，
+    //    schema 已最新则跳过建表，省 DDL 开销。node:sqlite 打开即持久化，
     //    _createSchema 内 DDL 直接落盘，无需 _save。
     //    戳在但 db 缺表属"手动改 db"边角（SillySpec 不支持），不在本层兜底。
     const versionPath = `${this.dbPath}.schema-version`;
@@ -85,13 +87,13 @@ export class DB {
 
   /**
    * 打开数据库（主库 → .bak → 全新/报错 逐级回退）。
-   * 语义对齐原 sql.js 的 _loadDatabase，但 better-sqlite3 绑定文件路径无 _save，
+   * 语义对齐原 sql.js 的 _loadDatabase，但 node:sqlite 绑定文件路径无 _save，
    * .bak 回退时 copyFileSync 把 .bak 内容恢复到主库路径，统一用 dbPath。
    *  - 主库存在且有内容且可打开：直接用。
    *  - 主库缺失/为空/损坏：尝试 .bak；成功则 warn 原因后 copy 回主库使用。
    *  - 都不可用：主库不存在→建全新空库；主库曾存在(空/损坏)→fail-loud 抛错(不静默建空库吞进度)。
-   * better-sqlite3 打开 0 字节文件不抛错：主库须 statSync 显式判空（截断信号→走回退，防静默吞进度）；
-   * .bak 作为恢复源只要存在且能打开即用（含 0 字节空库——better-sqlite3 视其为合法空库，
+   * node:sqlite 打开 0 字节文件不抛错：主库须 statSync 显式判空（截断信号→走回退，防静默吞进度）；
+   * .bak 作为恢复源只要存在且能打开即用（含 0 字节空库——node:sqlite 视其为合法空库，
    * 生产环境 .bak 由原子写改名上一完整主库得来，永不为 0 字节，0 字节态仅出现在测试构造）。
    */
   _openWithFallback() {
@@ -101,10 +103,10 @@ export class DB {
       if (!existsSync(p)) return null;
       return statSync(p).size === 0 ? 'empty' : 'ok';
     };
-    // tryOpen: new Database(path) + prepare 探测双保险（防打开成功但内容非 SQLite）
+    // tryOpen: openDatabase(path) + prepare 探测双保险（防打开成功但内容非 SQLite）
     const tryOpen = (p) => {
       let db;
-      try { db = new Database(p); }
+      try { db = openDatabase(p); }
       catch { return null; }
       try { db.prepare('SELECT count(*) FROM sqlite_master').get(); return db; }
       catch { try { db.close(); } catch { /* 关闭失败忽略 */ } return null; }
@@ -117,7 +119,7 @@ export class DB {
     }
 
     // 2. .bak 回退（.bak 是恢复源：存在且能打开即用，含 0 字节空库；门禁只挡"不存在"，
-    //    避免 tryOpen 对不存在的路径触发 new Database 的副作用——会凭空创建文件）
+    //    避免 tryOpen 对不存在的路径触发 openDatabase 的副作用——会凭空创建文件）
     if (readValid(bakPath) !== null) {
       const bakDb = tryOpen(bakPath);
       if (bakDb) {
@@ -129,23 +131,23 @@ export class DB {
             : 'sillyspec.db 损坏';
         console.warn(`⚠️  ${reason}，已从 .bak 备份恢复。`);
         bakDb.close();
-        // better-sqlite3 绑定路径，无 _save：把 .bak 内容 copy 回主库，统一用 dbPath
+        // node:sqlite 绑定路径，无 _save：把 .bak 内容 copy 回主库，统一用 dbPath
         copyFileSync(bakPath, this.dbPath);
-        return new Database(this.dbPath);
+        return openDatabase(this.dbPath);
       }
     }
 
     // 3. 都不可用
     if (readValid(this.dbPath) === null) {
       // 主库与备份都不存在 → 全新项目，建空库
-      return new Database(this.dbPath);
+      return openDatabase(this.dbPath);
     }
     // 主库曾存在（空/损坏）但无法恢复 → 数据丢失，必须 fail-loud（不静默建空库吞进度）
     throw new Error('sillyspec.db 损坏且 .bak 备份不可用，无法恢复。请从版本控制或其他备份恢复 .sillyspec/.runtime/ 后重试。');
   }
 
   /**
-   * 关闭数据库。better-sqlite3 的 close() 自动做 WAL checkpoint（把 -wal/-shm 日志合并回主库），
+   * 关闭数据库。node:sqlite 的 close() 自动做 WAL checkpoint（把 -wal/-shm 日志合并回主库），
    * 不需要 sql.js 时代的 _save() 整库 export 落盘。
    */
   close() {
@@ -158,9 +160,10 @@ export class DB {
   /**
    * 原生事务 + SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）。
    *
-   * better-sqlite3 的 db.transaction(fn) 返回一个包装函数，调用时自动
-   * BEGIN/COMMIT/ROLLBACK（fn 抛错自动 ROLLBACK 且不吞错），嵌套调用自动用 SAVEPOINT。
-   * 无需手动 BEGIN/COMMIT/ROLLBACK，也无需 _save（better-sqlite3 提交即持久化）。
+   * node:sqlite 无 .transaction()，runTransaction(fn)（db-engine）用 SAVEPOINT/RELEASE/
+   * ROLLBACK TO 手写事务：fn 抛错自动回滚且不吞错，嵌套调用自动形成 savepoint 栈
+   * （对齐旧引擎嵌套自动 SAVEPOINT 的兼容实现）。无需手动 BEGIN/COMMIT/ROLLBACK，
+   * 也无需 _save（node:sqlite 提交即持久化）。
    *
    * SQLITE_BUSY 重试：WAL 单写者模型，并发写第二者在 busy_timeout=5000 后抛 BUSY。此处对
    * BUSY 加 MAX_BUSY_RETRIES 次递增退避（BUSY_BACKOFF_MS）；仅 BUSY 重试（其它异常直接上抛），
@@ -169,14 +172,13 @@ export class DB {
    */
   transaction(fn) {
     if (!this.db) throw new Error('DB not initialized');
-    const tx = this.db.transaction(fn);
     let attempt = 0;
     while (true) {
       try {
-        return tx();
+        return runTransaction(this.db, fn);
       } catch (err) {
-        // 仅 SQLITE_BUSY 重试（better-sqlite3 err.code 为 'SQLITE_BUSY'/5，message 含 'database is locked'）
-        const isBusy = err && (err.code === 'SQLITE_BUSY' || err.code === 5
+        // 仅 SQLITE_BUSY 重试（node:sqlite err.errcode 为 5 / err.code 为 'ERR_SQLITE_ERROR'，message 含 'database is locked'）
+        const isBusy = err && (err.code === 'SQLITE_BUSY' || err.code === 5 || err.errcode === 5
           || (typeof err.message === 'string' && /database is locked|SQLITE_BUSY/i.test(err.message)));
         if (!isBusy) throw err;
         if (attempt >= MAX_BUSY_RETRIES) throw err; // 达上限 fail-loud（不静默吞，防死循环）
@@ -186,13 +188,13 @@ export class DB {
     }
   }
 
-  /** 获取底层 db 对象（better-sqlite3 Database 实例，供 progress.js 直接使用） */
+  /** 获取底层 db 对象（node:sqlite DatabaseSync 实例，供 progress.js 直接使用） */
   getDb() {
     return this.db;
   }
 
   _createSchema() {
-    // better-sqlite3：exec() 执行多条 SQL/DDL（无返回）；prepare().run/get/all 用于 DML。
+    // node:sqlite：exec() 执行多条 SQL/DDL（无返回）；prepare().run/get/all 用于 DML。
     // sql.js 的 .run(sql) 在此换为 .exec(sql)。
 
     // project 表
@@ -310,11 +312,19 @@ export class DB {
     // last_synced_platform_ts NULL=首次同步（base_ts NULL 平台接受首次 push）。
     this._migrateAddColumn('changes', 'last_synced_platform_ts', 'TEXT');
     this._migrateAddColumn('changes', 'last_local_modified_ts', 'TEXT');
+
+    // changes 表加 title（人类可读中文标题）+ quicklog_id（关联 QUICKLOG ql-ID）两列：
+    // 让 quick-<hex> 这种机器 hash sessionId 命名的 change 行可读，DB↔QUICKLOG 可对账。
+    // quick 启动时回填（stage.js：title 从任务描述提取、quicklog_id 用分配的 qlId），
+    // --done 时从 step3「需求：」刷新 title（agent 可改）。完整流程 change 的 name 本身
+    // 已语义化，title/quicklog_id 留空。不纳入平台同步脏度（本地展示用元信息）。
+    this._migrateAddColumn('changes', 'title', 'TEXT');
+    this._migrateAddColumn('changes', 'quicklog_id', 'TEXT');
   }
 
   /**
    * 幂等地给表添加列（列已存在则跳过）。
-   * better-sqlite3：exec() 执行 ALTER TABLE DDL；列已存在抛错被 catch 静默跳过。
+   * node:sqlite：exec() 执行 ALTER TABLE DDL；列已存在抛错被 catch 静默跳过。
    * @private
    */
   _migrateAddColumn(table, column, type) {

package/src/doctor-diagnostics.js

@@ -11,7 +11,7 @@
  *     - safe_actions：只描述建议动作与风险等级，绝不自动执行
  *
  * 安全约束（硬性）：
- *   - 所有检测只读。DB 以 better-sqlite3 只读连接打开（readonly + fileMustExist），不调用
+ *   - 所有检测只读。DB 以 node:sqlite 只读连接打开（readOnly + existsSync 前置门），不调用
  *     export/writeFileSync，不跑建表/迁移，close 后丢弃——绝不写回原 db 文件。
  *   - 不删除/移动任何文件；orphan db 仅报告，处理交给后续 --dump-db / --confirm 流程。
  *   - execute-progress-plan-mismatch 维度同样只读：仅读 plan.md checkbox + 只读查 stages 表，
@@ -20,7 +20,7 @@
  * 风格对齐 scan-postcheck.js：checks 用 CHECK_SEVERITY，formatter 产出 schema_version JSON，
  * writer 落盘到 <authoritySpecDir>/.runtime/。
  */
-import Database from 'better-sqlite3';
+import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { CHECK_SEVERITY } from './constants.js';
@@ -68,16 +68,16 @@ function probeDb(dbPath) {
   }
   let db = null;
   try {
-    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    db = openDatabase(dbPath, { readOnly: true });
     const pick = (sql, fallback = null) => {
       try {
-        const r = db.prepare(sql).pluck().get();
+        const r = pluckGet(db, sql);
         return r === undefined ? fallback : r;
       } catch { return fallback; }
     };
     const pickCol = (sql) => {
       try {
-        return db.prepare(sql).pluck().all();
+        return pluckAll(db, sql);
       } catch { return []; }
     };
     // 每个 active change 的 execute stage status（只读查询；stages 表的 status 列）。
@@ -657,7 +657,7 @@ export async function dumpDb({ dbPath, cwd }) {
   }
   let db = null;
   try {
-    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    db = openDatabase(dbPath, { readOnly: true });
     const rows = (sql) => {
       try { return db.prepare(sql).all(); } catch { return []; }
     };

package/src/hooks/worktree-guard.js

@@ -12,7 +12,6 @@
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import path from 'path'
 import { execFileSync } from 'child_process'
-import { createRequire } from 'module'
 
 // ── 常量 ──
 
@@ -225,20 +224,19 @@ function isInsideWorktreeStorage(filePath, cwd) {
 /**
  * 同步只读查询 sillyspec.db 第一行第一列（不依赖外部 sqlite3 CLI）。
  *
- * 用子进程跑 better-sqlite3 同步原生绑定（execFileSync 等待）：
- * - 原生绑定经 hook 进程的 createRequire(import.meta.url).resolve('better-sqlite3') 解析出绝对路径，
- *   JSON.stringify 嵌入子进程脚本——子进程 cwd 是项目目录，裸 require('better-sqlite3') 找不到包
- *   （用户项目未必直接装了它）；绝对路径 Windows/Linux/macOS 均 require 直接可用，无需 file:// URL。
- * - readonly + fileMustExist 双 true 打开只读连接：绝不写库；WAL 并发读不阻塞主进程写，
- *   且原生绑定可看到已 commit 但未 checkpoint 的过渡态（修复旧 WASM 内存库裸读 .db
- *   看不见 WAL 的过渡态可见性窗口）。
+ * 用子进程跑 node:sqlite 的 DatabaseSync（execFileSync 等待）：
+ * - node:sqlite 是 Node 内置模块，子进程 require('node:sqlite') 直接可用，无需先 resolve 出
+ *   绝对路径再注入（旧方案需手动解析原生绑定路径，node:sqlite 无此步骤）。
+ * - readOnly 打开只读连接（替代旧方案 readonly/fileMustExist 语义）：绝不写库；WAL 并发读不阻塞主进程写，
+ *   且只读连接可看到已 commit 但未 checkpoint 的过渡态（修复旧 WASM 内存库裸读 .db
+ *   看不见 WAL 的过渡态可见性窗口）。db 缺失/损坏由 open 异常自然触发 fail-closed（外层 catch）。
  *
  * 环境假设（R-09）：WAL 模式下只读连接仍需在 .runtime/ 目录建/更新 -shm 索引文件，故 .runtime
  * 必须可写（与主进程一致）——“只读”指不改 DB 数据，不等于不对 -shm 加索引。
  *
- * fail-closed：better-sqlite3 resolve 失败 / db 文件不存在 / fileMustExist 打开失败 / 查询异常 /
- * 子进程超时或崩溃——一律 console.warn（含 e.stderr 详情）并返回 null，调用方
- *（readCurrentStage/isNoWorktreeMode）对 null 走 fail-closed，禁止 fail-open。
+ * fail-closed：db 文件不存在 / 子进程打开、查询异常 / 子进程超时或崩溃——一律 console.warn
+ * （含 e.stderr 详情）并返回 null，调用方（readCurrentStage/isNoWorktreeMode）对 null 走
+ * fail-closed，禁止 fail-open。
  */
 function queryDbFirstCell(cwd, sql) {
   const dbPath = path.join(cwd, '.sillyspec', '.runtime', 'sillyspec.db')
@@ -248,21 +246,15 @@ function queryDbFirstCell(cwd, sql) {
     console.warn('⚠️ sillyspec.db 不存在，hook 降级 fail-closed: ' + dbPath)
     return null
   }
-  let libPath
-  try {
-    libPath = createRequire(import.meta.url).resolve('better-sqlite3')
-  } catch (e) {
-    console.warn('⚠️ sillyspec.db 查询失败（better-sqlite3 未解析），hook 降级 fail-closed: ' + ((e && e.message) || e))
-    return null
-  }
-  // 子进程同步 require 绝对路径（better-sqlite3 是同步原生 API，无 async/import().then 包装）。
-  // pluck().get() 取第一行第一列原值，无行返回 undefined（写空 stdout → 父侧 trim 后 null）。
+  // 子进程同步内置 require('node:sqlite')（DatabaseSync 是同步 API，无 async/import().then 包装）。
+  // prepare(sql).get() 取第一行整行后取首列值，无行返回 undefined（写空 stdout → 父侧 trim 后 null）。
   const script =
-    "const D=require(" + JSON.stringify(libPath) + ")," +
+    "const {DatabaseSync}=require('node:sqlite')," +
     "dbPath=" + JSON.stringify(dbPath) + ",sql=" + JSON.stringify(sql) + ";" +
     "let db;" +
-    "try{db=new D(dbPath,{readonly:true,fileMustExist:true});" +
-    "const v=db.prepare(sql).pluck().get();" +
+    "try{db=new DatabaseSync(dbPath,{readOnly:true});" +
+    "const row=db.prepare(sql).get();" +
+    "const v=row===undefined?undefined:Object.values(row)[0];" +
     "if(v!==undefined)process.stdout.write(String(v??''));db.close()}" +
     "catch(e){process.stderr.write('hook db query failed: '+String(e&&e.message||e));process.exit(1)};"
   try {
@@ -270,7 +262,7 @@ function queryDbFirstCell(cwd, sql) {
       encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'],
     }).trim() || null
   } catch (e) {
-    // DB 查询失败（db 损坏 / fileMustExist 打开失败 / 子进程超时或崩溃）：降级返回 null，调用方
+    // DB 查询失败（db 损坏 / readOnly 打开失败 / 子进程超时或崩溃）：降级返回 null，调用方
     //（readCurrentStage 等）对 null 走 fail-closed。补 warn 让 doctor/agent 能看到根因，
     // 而非完全静默（子进程把诊断写到了 stderr，execFileSync 抛错时挂在 e.stderr 上）。
     const detail = (e && e.stderr ? String(e.stderr).trim() : '') || (e && e.message) || 'timeout/crash'
@@ -291,7 +283,7 @@ export {
  * @returns {string|null} 阶段名，null 表示无法确定
  */
 function readCurrentStage(cwd) {
-  // 直读 sillyspec.db（node + better-sqlite3 只读子进程，不依赖外部 sqlite3 CLI——Windows 默认没有）
+  // 直读 sillyspec.db（node + node:sqlite 只读子进程，不依赖外部 sqlite3 CLI——Windows 默认没有）
   const v = queryDbFirstCell(cwd, "SELECT current_stage FROM changes WHERE status='active' AND current_stage IN ('execute','quick') ORDER BY last_active DESC LIMIT 1")
   return v || null
 }
@@ -302,7 +294,7 @@ function readCurrentStage(cwd) {
  * @returns {boolean}
  */
 function isNoWorktreeMode(cwd) {
-  // 直读 sillyspec.db（node + better-sqlite3，同 readCurrentStage）
+  // 直读 sillyspec.db（node + node:sqlite，同 readCurrentStage）
   return queryDbFirstCell(cwd, "SELECT no_worktree FROM changes WHERE status='active' AND current_stage IN ('execute','quick') LIMIT 1") === '1'
 }
 

package/src/progress/change-registry.js

@@ -67,6 +67,34 @@ export class ChangeRegistry {
     }
   }
 
+  /**
+   * 更新变更的人类可读元信息（title / quicklog_id），让 quick-<hex> 行可读、DB↔QUICKLOG 可对账。
+   * quick 启动时回填（title 从任务描述、quicklog_id 用分配的 qlId）；--done 时从 step3「需求：」刷新 title。
+   * 部分更新（只传 title 不动 quicklog_id，反之亦然）。不调 _touchLocalModified：title/quicklog_id 是
+   * 本地展示用元信息，纳入脏度会扰动平台同步（平台 changes 表无此列）。
+   * @param {string} cwd
+   * @param {string} changeName
+   * @param {{ title?: string, quicklogId?: string }} meta
+   */
+  updateChangeMeta(cwd, changeName, meta) {
+    if (!changeName || !meta) return;
+    const db = this.pm._ensureDB(cwd);
+    try {
+      db.transaction(() => {
+        const sqlDb = db.getDb();
+        const sets = [];
+        const params = [];
+        if (meta.title !== undefined) { sets.push('title = ?'); params.push(meta.title); }
+        if (meta.quicklogId !== undefined) { sets.push('quicklog_id = ?'); params.push(meta.quicklogId); }
+        if (sets.length === 0) return;
+        params.push(changeName);
+        sqlDb.prepare(`UPDATE changes SET ${sets.join(', ')} WHERE name = ?`).run(...params);
+      });
+    } catch (err) {
+      console.warn('⚠️  更新 change 元信息失败:', err.message);
+    }
+  }
+
   /**
    * 读取变更的隔离状态
    * @param {string} cwd - 项目根目录

package/src/progress/shared.js

@@ -27,7 +27,7 @@ export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', '
 export const MAIN_FLOW_ORDER = ['brainstorm', 'plan', 'execute', 'verify', 'archive'];
 
 // progress 数据版本（v3 = SQLite；v4 = changes 加 base_ts / 本地脏度两列，platform-sync §8）
-export const CURRENT_VERSION = 4;
+export const CURRENT_VERSION = 5;
 
 // 空阶段骨架
 export function emptyStage() {

package/src/progress.js

@@ -347,7 +347,7 @@ export class ProgressManager {
     }
 
     const result = {
-      _version: 4,
+      _version: 5,
       project: projectName,
       currentChange: cName,
       currentStage: currentStage || '',
@@ -776,6 +776,8 @@ export class ProgressManager {
 
   unregisterChange(cwd, changeName) { return this._changeRegistry.unregisterChange(cwd, changeName); }
 
+  updateChangeMeta(cwd, changeName, meta) { return this._changeRegistry.updateChangeMeta(cwd, changeName, meta); }
+
   // ── CLI 命令 ──
 
   init(cwd) {
@@ -815,7 +817,7 @@ export class ProgressManager {
    * 初始化指定变更的 progress
    * SQL: INSERT changes + 批量 INSERT stages
    */
-  initChange(cwd, changeName) {
+  initChange(cwd, changeName, meta = {}) {
     if (!changeName) {
       console.warn('⚠️  initChange: changeName 为空，跳过');
       return null;
@@ -836,9 +838,9 @@ export class ProgressManager {
       if (existing === undefined) {
         // 插入 changes 行
         sqlDb.prepare(
-          `INSERT INTO changes (name, current_stage, status, created_at, last_active)
-           VALUES (?, 'scan', 'active', ?, ?)`
-        ).run(changeName, now, now);
+          `INSERT INTO changes (name, current_stage, status, created_at, last_active, title, quicklog_id)
+           VALUES (?, 'scan', 'active', ?, ?, ?, ?)`
+        ).run(changeName, now, now, meta.title || null, meta.quicklogId || null);
       }
 
       // 获取 change_id

package/src/quicklog.js

@@ -75,7 +75,7 @@ function nowDatetime(d = new Date()) {
 }
 
 // 描述压成一行、限长，避免破坏 QUICKLOG 条目结构
-function sanitizeDesc(description) {
+export function sanitizeDesc(description) {
   const s = String(description || '').replace(/[\r\n]+/g, ' ').trim()
   if (!s) return '(quick 任务)'
   return s.length > 120 ? s.slice(0, 120) + '…' : s
@@ -101,7 +101,7 @@ export function deriveTitleFromLinkedChange(specBase, change) {
 
 // 从 quick step3 --output 四字段提取「需求：」摘要，用于翻完成时刷新标题行
 // （覆盖启动时的占位/弱标题）。提取失败返回 ''（不刷新）。
-function extractTitleFromResult(result) {
+export function extractTitleFromResult(result) {
   if (!result) return ''
   const m = String(result).match(/需求：([^\n\r]*?)(?:\s+根因：|$)/)
   if (!m) return ''

package/src/run/complete-handlers.js

@@ -30,7 +30,7 @@ import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-d
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
 import { printQuickAuditReview } from './quick-audit.js'
-import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry } from '../quicklog.js'
+import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
 
@@ -774,6 +774,12 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         changedFiles: realFiles,
       })
       console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
+      // 刷新 DB title：从 step3「需求：」提取（agent 可改 title 的途径），覆盖启动时的兜底快照。
+      // 与 QUICKLOG 标题刷新（flipEntryInContent 内 extractTitleFromResult）同源，保持 DB↔QUICKLOG 一致。
+      try {
+        const refinedTitle = extractTitleFromResult(outputText || '');
+        if (refinedTitle) pm.updateChangeMeta(cwd, changeName, { title: refinedTitle });
+      } catch { /* title 刷新失败不阻断完成 */ }
     } catch (e) {
       console.warn(`⚠️ QUICKLOG 完成态写入失败: ${e.message}`)
     }

package/src/run/stage.js

@@ -22,7 +22,7 @@ import { writeAtomicSync } from '../fs-atomic.js'
 import { resolveSpecDir, resolveChangeDir, resolveRuntimeRoot, resolveQuickSessionsDir, triggerSync, safeGit, parsePorcelainPath, formatWaitOptions, checkApproval, getStageSteps } from './shared.js'
 import { computeScanProfile, applyScanProfileSteps, executeScanPreflight, executeScanPostcheck } from './scan-profile.js'
 import { outputStep } from './prompt.js'
-import { allocateQuicklogEntry, deriveTitleFromLinkedChange } from '../quicklog.js'
+import { allocateQuicklogEntry, deriveTitleFromLinkedChange, sanitizeDesc } from '../quicklog.js'
 import { checkTransition } from '../stage-contract.js'
 import { completeStageGates } from './gates.js'
 
@@ -288,6 +288,11 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
         if (allowNew) parts.push('允许新增文件')
         console.log(`🛡️ quick 变更边界已记录: ${parts.join(', ')}`)
         console.log(`📝 QUICKLOG 条目已创建: ${qlId}`)
+        // 回填 DB changes 行的 title + quicklog_id，让 quick-<hex> 可读、DB↔QUICKLOG 可对账。
+        // title 用 quickDesc（任务描述或关联变更标题）经 sanitizeDesc 压一行限长，与 QUICKLOG 条目标题同源。
+        try {
+          pm.updateChangeMeta(cwd, changeName, { title: sanitizeDesc(quickDesc), quicklogId: qlId });
+        } catch { /* 回填失败不阻断 quick 启动 */ }
         pm._write(cwd, progress, changeName)
       } catch (e) {
         console.warn(`⚠️ baseline 记录失败: ${e.message}`)