sillyspec 3.26.11 → 3.26.14

package/src/progress/step-store.js

@@ -150,7 +150,7 @@ export class StepStore {
       const tDb = db.getDb();
       const now = new Date().toISOString();
       if (status) {
-        tDb.prepare('UPDATE steps SET status = ?, completed_at = ? WHERE id = ? AND name = ?').run(status, now, stepId, stepName);
+        tDb.prepare('UPDATE steps SET status = ?, completed_at = ? WHERE id = ? AND name = ?').run(status, status === 'completed' ? now : null, stepId, stepName);
       }
       if (output !== undefined) {
         tDb.prepare('UPDATE steps SET output = ? WHERE id = ? AND name = ?').run(output, stepId, stepName);

package/src/progress.js

@@ -10,7 +10,7 @@
  * worktree-guard hook 直读 sillyspec.db，不再有 gate-status.json 缓存双源（task-10 废除）。
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, appendFileSync, copyFileSync, readdirSync, statSync } from 'fs';
 import { join, basename, dirname, resolve, sep } from 'path';
 import { tmpdir } from 'os';
 import { DB } from './db.js';
@@ -148,28 +148,13 @@ const CHANGES_SUBDIR = 'changes';
 // VALID_STAGES → ./progress/shared.js（W6 Step9c）
 // VALID_STATUSES → ./progress/step-store.js（updateStep 专用，本地化）
 
-// Stage statuses (superset of step statuses)
-const VALID_STAGE_STATUSES = ['pending', 'in-progress', 'completed', 'failed', 'blocked', 'revising', 'stale'];
-
-// STAGE_ORDER / MAIN_FLOW_ORDER → ./progress/shared.js（W6 Step9a：facade + 子模块共用）
-
-// STAGE_LABELS → ./progress/shared.js（W6 Step9c）
-
-// emptyStage → ./progress/shared.js（W6 Step9d）
-
-function makeInitialProgress(project) {
-  const stages = {};
-  for (const s of VALID_STAGES) stages[s] = emptyStage();
-  return { _version: CURRENT_VERSION, project: project || '', currentStage: '', currentChange: null, stages, lastActive: null };
-}
-
-function makeInitialGlobal(project) {
-  return { _version: CURRENT_VERSION, project: project || '', activeChanges: [] };
-}
 
 // ── ProgressManager ──
 
 export class ProgressManager {
+  /** 模块级 DB 连接池：Map<dbPath, DB>（SEC-09/PERF-10，见 _ensureDB 注释） */
+  static _dbPool = new Map();
+
   /**
    * @param {object} [opts]
    * @param {string} [opts.specDir] - 规范目录绝对路径（默认 cwd/.sillyspec）
@@ -215,11 +200,26 @@ export class ProgressManager {
     }
   }
 
-  /** 懒初始化 DB 连接，缓存在实例上（better-sqlite3 同步 API，init 无 async） */
+  /**
+   * 懒初始化 DB 连接，缓存在实例上（better-sqlite3 同步 API，init 无 async）。
+   *
+   * SEC-09/PERF-10（2026-08-20 体检）：连接额外进模块级 Map<dbPath, DB> 单例——
+   * 一条平台命令此前会 new 多个 ProgressManager（triggerPull / sync / import 各建），
+   * 同一 sillyspec.db 被 open 3-5 次，每次重跑 PRAGMA + schema 探测，且多连接
+   * 提升 SQLITE_BUSY 概率、Windows 残留句柄影响文件替换。CLI 短进程生命周期内
+   * dbPath 不变，进程退出由 OS 回收句柄（node:sqlite 无显式泄漏）；进程内共享
+   * 单连接后 WAL 写竞争面反而缩小。
+   */
   _ensureDB(cwd) {
     if (!this._db) {
-      this._db = new DB(this._runtimePath(cwd, 'sillyspec.db'));
-      this._db.init();
+      const dbPath = this._runtimePath(cwd, 'sillyspec.db');
+      let db = ProgressManager._dbPool.get(dbPath);
+      if (!db) {
+        db = new DB(dbPath);
+        db.init();
+        ProgressManager._dbPool.set(dbPath, db);
+      }
+      this._db = db;
     }
     return this._db;
   }
@@ -288,7 +288,7 @@ export class ProgressManager {
     for (const row of stageRows) {
       const { id: sId, stage, status, started_at: startedAt, completed_at: completedAt, revision, reopened_from_step: reopenedFromStep, reopened_at: reopenedAt, stale_reason: staleReason } = row;
       stageMap[stage] = { _dbId: sId, status, startedAt, completedAt,
-        ...(revision ? { revision } : {}),
+        ...(revision != null ? { revision } : {}),
         ...(reopenedFromStep ? { reopenedFromStep } : {}),
         ...(reopenedAt ? { reopenedAt } : {}),
         ...(staleReason ? { staleReason } : {}),
@@ -309,7 +309,7 @@ export class ProgressManager {
         if (!stepsByStage[stageId]) stepsByStage[stageId] = [];
         let waitAnswers = null;
         if (waitAnswersJson) {
-          try { waitAnswers = JSON.parse(waitAnswersJson); } catch {}
+          try { waitAnswers = JSON.parse(waitAnswersJson); } catch (e) { console.warn(`[progress] waitAnswers JSON 损坏，已跳过: ${e.message}`); }
         }
         stepsByStage[stageId].push({
           name, status, output, completedAt,
@@ -564,7 +564,17 @@ export class ProgressManager {
     }
     const bakTs = new Date().toISOString().replace(/[:.]/g, '-');
     const bakPath = this._runtimePath(cwd, `sillyspec.db.pre-import-${bakTs}.bak`);
+    // 体检 BUG-18：WAL 模式下最近已提交事务可能仍在 -wal 侧车，直接 copy 主库文件会拿到
+    // 缺尾部提交的快照（恢复时静默回退进度）。先尽力 checkpoint(TRUNCATE) 把 WAL 合并回主库；
+    // 他进程持连接致 checkpoint 不完全时，把 -wal 侧车一并备份，恢复侧才有完整提交
+    try {
+      this._ensureDB(cwd).getDb().exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    } catch { /* best-effort：失败退化为连 -wal 一起备份 */ }
     copyFileSync(dbPath, bakPath);
+    const walSidecar = `${dbPath}-wal`;
+    if (existsSync(walSidecar)) {
+      try { copyFileSync(walSidecar, `${bakPath}-wal`); } catch { /* 侧车消失=已 checkpoint，无碍 */ }
+    }
 
     const pushedAt = progressObj.pushed_at ?? null;
     const now = new Date().toISOString();
@@ -1002,22 +1012,25 @@ export class ProgressManager {
   // ── plan.md 对齐（doctor --align-execute-progress 入口）──
 
   /**
-   * 解析 changeDir/plan.md（回退 tasks.md）的 task checkbox 统计。
+   * 解析 changeDir/tasks.md（任务注册表唯一真相）的 task checkbox 统计。
+   * 2026-08-20-task-truth-unify：源从「plan.md 优先回退 tasks.md」改为 tasks.md 唯一源——
+   * 旧顺序下新契约 plan.md（纯 ID 引用行）恒 total=0，doctor --align-execute-progress 会静默失效。
+   * tasks.md 缺失时回退 plan.md（旧归档变更兼容读侧，不写侧迁移）。
    * 仅匹配 `- [ ] task-NN` / `- [x] task-NN` 形态的行（task- 前缀锚定，避免误捞非任务项）。
-   * @param {string} changeDir - 变更目录绝对路径（含 plan.md/tasks.md）
+   * @param {string} changeDir - 变更目录绝对路径（含 tasks.md/plan.md）
    * @returns {{ total: number, checked: number }}
    */
   readPlanCheckboxStatus(changeDir) {
     if (!changeDir || typeof changeDir !== 'string') {
       throw new Error('changeDir 不能为空');
     }
-    const planPath = join(changeDir, 'plan.md');
     const tasksPath = join(changeDir, 'tasks.md');
+    const planPath = join(changeDir, 'plan.md');
     let content = null;
-    if (existsSync(planPath)) {
-      content = readFileSync(planPath, 'utf8');
-    } else if (existsSync(tasksPath)) {
+    if (existsSync(tasksPath)) {
       content = readFileSync(tasksPath, 'utf8');
+    } else if (existsSync(planPath)) {
+      content = readFileSync(planPath, 'utf8');
     } else {
       return { total: 0, checked: 0 };
     }
@@ -1128,4 +1141,148 @@ export class ProgressManager {
 
     return { ok: true, aligned, skipped, planTotal, planChecked };
   }
+
+  // ── 只读 dump（task-01/02/03：daemon 进度读取）──
+
+  /**
+   * dump 输出的时间戳规范化：DB 内部两类形态（步骤推进时 JS Date 变量序列化
+   * 的 ISO 形态、部分历史路径写入的 `YYYY/M/D H:mm:ss` 斜杠形态）统一转 ISO。
+   * backend pydantic datetime 只吃 ISO（斜杠形态校验失败），斜杠 → new Date
+   * 可解析；解析失败原样返回（backend 侧按无效丢弃）。
+   */
+  _dumpIso(ts) {
+    if (!ts) return ts;
+    if (typeof ts === 'string' && /^\d{4}-\d{2}-\d{2}/.test(ts)) return ts;
+    const d = new Date(ts);
+    if (Number.isNaN(d.getTime())) return ts;
+    return d.toISOString();
+  }
+
+  /**
+   * 只读导出进度数据，供 daemon 通过 `sillyspec progress dump --json` 消费。
+   *
+   * 纯读路径：打开 DB 只读、读 user-inputs.md、列 artifacts 目录，不写任何状态。
+   * 无活跃变更或 DB 不存在时返回 null（不抛异常，daemon 按 null 处理空数据）。
+   *
+   * 输出字段 snake_case + ISO 时间戳（2026-08-19-runtime-live-daemon-read
+   * acceptance review P0 修复）：契约消费端 backend RuntimeProgress pydantic
+   * 是 snake_case（current_stage/last_active/started_at/size_bytes），
+   * dump 早期误用内部 camelCase；跨端字段名断裂会让 pydantic 静默忽略
+   * 未知字段导致前端核心字段全空。
+   *
+   * @param {string} cwd - specDir（`.sillyspec` 目录），由 CLI 层 --spec-dir 传入
+   * @returns {object|null} 结构化进度数据，格式见 design.md §6.2
+   */
+  dump(cwd) {
+    const specRoot = this._getSpecDir(cwd);
+    const dbPath = this._runtimePath(cwd, 'sillyspec.db');
+
+    // DB 不存在 → 返回 null（项目未初始化进度）
+    if (!existsSync(dbPath)) return null;
+
+    const db = this._ensureDB(cwd);
+    const sqlDb = db.getDb();
+
+    // 1. project 行
+    const projectRow = sqlDb.prepare('SELECT name FROM project WHERE id = 1').get();
+    if (projectRow === undefined) return null;
+    const projectName = projectRow.name;
+
+    // 2. 活跃变更（取 last_active 最新的一个）
+    // ql-20260821-003：多活跃仓（变更隔离是常态，单仓可同时存在 N 个 active）下
+    // 原 ORDER BY name 恒取字典序最前（通常是最老的变更），「当前变更/最后活动」
+    // 停留在历史数据。dump 语义是「当前工作流状态」→ 取最近活跃的那个。
+    const changeRows = sqlDb.prepare("SELECT id, name, current_stage, last_active FROM changes WHERE status = 'active' ORDER BY last_active DESC").all();
+    if (changeRows.length === 0) {
+      // 无活跃变更 → 返回仅含 project 的骨架
+      return {
+        project: projectName,
+        current_stage: null,
+        current_change: null,
+        last_active: null,
+        stages: {},
+        user_inputs: this._readUserInputs(cwd),
+        artifacts: this._listArtifacts(cwd),
+      };
+    }
+
+    const change = changeRows[0];
+    const { id: changeId, name: changeName, current_stage: currentStage, last_active: lastActive } = change;
+
+    // 3. stages
+    const stageRows = sqlDb.prepare(
+      'SELECT id, stage, status, started_at, completed_at, revision FROM stages WHERE change_id = ? ORDER BY id'
+    ).all(changeId);
+
+    const stages = {};
+    for (const s of VALID_STAGES) {
+      stages[s] = { status: 'pending', steps: [] };
+    }
+    // PERF-06：一次 IN (...) 批量取全部 steps 再按 stage_id 分组（原逐 stage 查询是 N+1，
+    // dump 是 daemon 轮询接口；与 read() :283-287 的批量读法对齐）
+    const stepsByStage = new Map();
+    if (stageRows.length > 0) {
+      const placeholders = stageRows.map(() => '?').join(', ');
+      const allStepRows = sqlDb.prepare(
+        `SELECT stage_id, name, status, output, completed_at FROM steps WHERE stage_id IN (${placeholders}) ORDER BY stage_id, ordering`
+      ).all(...stageRows.map(r => r.id));
+      for (const sr of allStepRows) {
+        if (!stepsByStage.has(sr.stage_id)) stepsByStage.set(sr.stage_id, []);
+        stepsByStage.get(sr.stage_id).push(sr);
+      }
+    }
+    for (const row of stageRows) {
+      const stepRows = stepsByStage.get(row.id) || [];
+      stages[row.stage] = {
+        status: row.status,
+        started_at: this._dumpIso(row.started_at) || undefined,
+        completed_at: this._dumpIso(row.completed_at) || undefined,
+        ...(row.revision ? { revision: row.revision } : {}),
+        steps: stepRows.map(sr => ({
+          name: sr.name,
+          status: sr.status,
+          ...(sr.output ? { output: sr.output } : {}),
+          ...(sr.completed_at ? { completed_at: this._dumpIso(sr.completed_at) } : {}),
+        })),
+      };
+    }
+
+    return {
+      project: projectName,
+      current_stage: currentStage || null,
+      current_change: changeName,
+      last_active: this._dumpIso(lastActive) || null,
+      stages,
+      user_inputs: this._readUserInputs(cwd),
+      artifacts: this._listArtifacts(cwd),
+    };
+  }
+
+  /** 只读 user-inputs.md 内容（不存在返回 null） */
+  _readUserInputs(cwd) {
+    const p = this._runtimePath(cwd, 'user-inputs.md');
+    if (!existsSync(p)) return null;
+    return readFileSync(p, 'utf8');
+  }
+
+  /** 列 artifacts 目录（不存在返回空数组） */
+  _listArtifacts(cwd) {
+    const dir = this._runtimePath(cwd, 'artifacts');
+    if (!existsSync(dir)) return [];
+    try {
+      return readdirSync(dir, { withFileTypes: true })
+        .filter(e => e.isFile())
+        .map(e => {
+          const fullPath = join(dir, e.name);
+          const st = statSync(fullPath);
+          return {
+            filename: e.name,
+            size_bytes: st.size,
+            last_modified: st.mtime.toISOString(),
+          };
+        });
+    } catch {
+      return [];
+    }
+  }
 }

package/src/quicklog.js

@@ -14,15 +14,22 @@ import { join, dirname, basename } from 'path'
 import { getRule } from './stage-contract-spec.js'
 import {
   openSync, closeSync, unlinkSync, statSync, mkdirSync, existsSync,
-  readFileSync, writeFileSync, readdirSync, renameSync, appendFileSync,
+  readFileSync, writeFileSync, writeSync, readdirSync, renameSync, appendFileSync,
 } from 'fs'
 import { randomBytes } from 'crypto'
 
 const sleep = (ms) => new Promise(r => setTimeout(r, ms))
 
 /**
- * O_EXCL 文件锁。`openSync(lockPath,'wx')` 独占创建；已存在则按 mtime 判 stale 偷锁，
- * 否则退避重试至超时。CLI 短进程、低频写入，stale 阈值 30s 足够。
+ * O_EXCL 文件锁。`openSync(lockPath,'wx')` 独占创建并写入持有者唯一 id；已存在则按
+ * mtime 判 stale 偷锁（rename 原子抢占 + 内容校验），否则退避重试至超时。
+ * CLI 短进程、低频写入，stale 阈值 30s 足够。
+ *
+ * 偷锁为何用 rename 而非 unlink（2026-08-20 体检 BUG-02）：两进程同偷一把 stale 锁时，
+ * 后到者的 unlink 会把先到者刚重建的新锁删掉（TOCTOU）→ 双进程同时进临界区。
+ * rename 到唯一名后比对内容：只有"观察时看到的那把锁"才允许删除；偷到并发者
+ * 新建的锁则原路放回。残余窗口仅剩"纳秒级三方精确竞争"（放回前 existsSync 检查
+ * 与 rename 之间），相比旧实现的必现双进已可忽略。
  * @param {string} lockPath 锁文件路径（建议与被保护文件同目录）
  * @param {() => (any|Promise<any>)} fn 临界区
  * @param {{staleMs?:number, timeoutMs?:number, retryMs?:number}} opts
@@ -31,11 +38,13 @@ export async function withFileLock(lockPath, fn, opts = {}) {
   const { staleMs = 30000, timeoutMs = 10000, retryMs = 50 } = opts
   mkdirSync(dirname(lockPath), { recursive: true })
   const start = Date.now()
+  const myId = `${process.pid}-${randomBytes(6).toString('hex')}`
   let fd = null
   // 抢锁循环
   while (true) {
     try {
       fd = openSync(lockPath, 'wx') // O_EXCL：已存在抛 EEXIST
+      writeSync(fd, myId)
       break
     } catch (e) {
       if (e.code !== 'EEXIST') throw e
@@ -43,7 +52,19 @@ export async function withFileLock(lockPath, fn, opts = {}) {
       try {
         const mtime = statSync(lockPath).mtimeMs
         if (Date.now() - mtime > staleMs) {
-          try { unlinkSync(lockPath) } catch {} // 偷 stale 锁后重试
+          try {
+            const observed = readFileSync(lockPath, 'utf8') // 观察到的持有者 id
+            const claim = `${lockPath}.steal-${randomBytes(6).toString('hex')}`
+            renameSync(lockPath, claim) // 原子抢占：并发者只可能有一个 rename 成功
+            if (readFileSync(claim, 'utf8') === observed) {
+              try { unlinkSync(claim) } catch {} // 确实是那把 stale 锁 → 回收
+            } else {
+              // 偷到并发者新建的锁：放回（原位已被占则放弃，先占者保留）
+              let restored = false
+              try { if (!existsSync(lockPath)) { renameSync(claim, lockPath); restored = true } } catch {}
+              if (!restored) { try { unlinkSync(claim) } catch {} }
+            }
+          } catch {}
           continue
         }
       } catch {}
@@ -339,7 +360,7 @@ function listQuicklogFiles(quicklogDir) {
 // reader 句柄是瞬时的，故对占用类错误做异步重试+退避；非占用错误立即抛。
 async function writeAtomic(filePath, content, opts = {}) {
   const { retries = 100, baseDelayMs = 5, maxDelayMs = 100 } = opts
-  const tmp = join(dirname(filePath), basename(filePath) + '.tmp-' + process.pid)
+  const tmp = join(dirname(filePath), basename(filePath) + '.tmp-' + process.pid + '-' + randomBytes(4).toString('hex')) // 随机段：Windows PID 重用激进，仅 pid 会撞名（对齐 fs-atomic.js 的同款修复）
   writeFileSync(tmp, content) // 同目录 = 同文件系统，rename 才原子（跨 fs 会退化 copy+delete）
   for (let attempt = 0; ; attempt++) {
     try {
@@ -417,24 +438,34 @@ function tasksPath(specBase, change) {
 // 关联变更目录不存在（笔误 / 未建 / 仅作标签关联）→ 不 fabricate stub 目录（历史坑 quick-change-phantom：
 // mkdirSync 硬造 changes/<名>/tasks.md，致 quick --done 边界审计自造自拦 BLOCK）。关联仍记入
 // QUICKLOG「关联变更」行（allocateQuicklogEntry 独立写入，不依赖本函数）。
-function appendTaskCheckbox(specBase, change, qlId, desc) {
+// 体检 BUG-17：tasks.md 是跨用户共享文件——QUICKLOG 按 <user> 分锁只串行化同用户会话，
+// 用户 A 勾选与用户 B 追加跨用户并发时须按目标文件加锁，否则读-改-写互相覆盖。
+function tasksLockPath(p) {
+  return p + '.tasklock'
+}
+
+async function appendTaskCheckbox(specBase, change, qlId, desc) {
   const dir = join(specBase, 'changes', change)
   if (!existsSync(dir)) return
   const p = tasksPath(specBase, change)
-  let content = existsSync(p) ? readFileSync(p, 'utf8') : ''
-  if (content.includes(qlId)) return
-  const prefix = content && !content.endsWith('\n') ? '\n' : ''
-  appendFileSync(p, `${prefix}- [ ] ${qlId} ${desc}\n`)
+  await withFileLock(tasksLockPath(p), () => {
+    let content = existsSync(p) ? readFileSync(p, 'utf8') : ''
+    if (content.includes(qlId)) return
+    const prefix = content && !content.endsWith('\n') ? '\n' : ''
+    appendFileSync(p, `${prefix}- [ ] ${qlId} ${desc}\n`)
+  })
 }
 
-// 勾选该 qlId 对应 task：- [ ] → - [x]
+// 勾选该 qlId 对应 task：- [ ] → - [x]（同 BUG-17：按 tasks.md 文件锁串行化跨用户读-改-写）
 async function checkTaskCheckbox(specBase, change, qlId) {
   const p = tasksPath(specBase, change)
   if (!existsSync(p)) return
-  let content = readFileSync(p, 'utf8')
-  const re = new RegExp(`- \\[ \\] (${escapeRe(qlId)})`)
-  content = content.replace(re, '- [x] $1')
-  await writeAtomic(p, content)
+  await withFileLock(tasksLockPath(p), async () => {
+    let content = readFileSync(p, 'utf8')
+    const re = new RegExp(`- \\[ \\] (${escapeRe(qlId)})`)
+    content = content.replace(re, '- [x] $1')
+    await writeAtomic(p, content)
+  })
 }
 
 // 就地翻某 qlId 条目：状态进行中→已完成，追加结果行
@@ -606,7 +637,7 @@ export async function allocateQuicklogEntry(specBase, gitUser, { description, li
     ].join('\n')
     appendFileSync(userFile, entry)
 
-    for (const c of linked) appendTaskCheckbox(specBase, c, qlId, desc)
+    for (const c of linked) await appendTaskCheckbox(specBase, c, qlId, desc)
 
     // 平台推送（task-06 / FR-02 / D-003）：锁外语义等同（推送不回写本地），但放锁内
     // 保证「分配即推送」顺序一致；best-effort 失败不影响返回。