sillyspec 3.26.11 → 3.26.14

package/src/doctor-diagnostics.js

@@ -21,7 +21,7 @@
  * writer 落盘到 <authoritySpecDir>/.runtime/。
  */
 import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
-import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
 import { join } from 'path';
 import { CHECK_SEVERITY } from './constants.js';
 import { checkPlatformManaged } from './run/shared.js';
@@ -101,6 +101,14 @@ function probeDb(dbPath) {
       schema_version: pick('SELECT schema_version FROM project LIMIT 1'),
       change_count: pick('SELECT count(*) FROM changes', 0),
       active_changes: pickCol("SELECT name FROM changes WHERE status='active'"),
+      // SS-2b（2026-08-20）：active 行 name → last_active 映射，供 D4 空壳判定做时间门槛
+      //（刚创建的合法变更目录本来就是空的，见 GHOST_EMPTY_DIR_STALE_MS 注释）。
+      active_last_active: (() => {
+        try {
+          const rows = db.prepare("SELECT name, last_active FROM changes WHERE status='active'").all();
+          return Object.fromEntries(rows.map((r) => [r.name, r.last_active]));
+        } catch { return {}; }
+      })(),
       last_active: pick('SELECT MAX(last_active) FROM changes'),
       execute_status_by_change: pickExecuteStatusByChange(),
     };
@@ -211,6 +219,10 @@ function detectMultiDb(cwd, pointer) {
       change_count: d.change_count,
       last_active: d.last_active,
       active: d.readable ? summarizeActive(d.active_changes) : null,
+      // SS-2：全量名单随摘要透传，供 D4 精确集合对账（ghost/orphan）消费。
+      active_changes: d.readable ? (d.active_changes || []) : [],
+      // SS-2b：name → last_active 映射随摘要透传，供 D4 空壳判定（时间门槛）消费。
+      active_last_active: d.readable ? (d.active_last_active || {}) : {},
     })),
   };
 }
@@ -359,6 +371,35 @@ function detectChangesSplit(cwd, pointer) {
 
 // ── D4 change↔db 一致性（针对权威 db + 权威 changes 目录）──────────────
 
+// SS-2b（2026-08-20）：空壳目录判定的 last_active 时间门槛（7 天）。
+// 背景：brainstorm 刚注册的合法变更目录本来就是 0 文件（首份产物 proposal.md
+// 落盘前有空窗，2026-08-20 task-truth-unify 即空目录数小时）。「active 行 + 目录
+// 0 文件」不能直接判幽灵，必须叠加 last_active 陈旧度；门槛取 7 天（quick 会话
+// 生命周期通常当天结束，正规变更 brainstorm 首产物也远早于 7 天）。
+const GHOST_EMPTY_DIR_STALE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** 目录内是否 0 个常规文件（递归；空目录/仅空子目录都算 0 文件）。读失败按非空处理（宁漏勿杀）。 */
+function dirHasNoFiles(dirPath) {
+  const stack = [dirPath];
+  while (stack.length > 0) {
+    const cur = stack.pop();
+    let entries;
+    try { entries = readdirSync(cur, { withFileTypes: true }); } catch { return false; }
+    for (const e of entries) {
+      if (e.isFile()) return false;
+      if (e.isDirectory()) stack.push(join(cur, e.name));
+    }
+  }
+  return true;
+}
+
+/** last_active 是否陈旧超过 GHOST_EMPTY_DIR_STALE_MS。无值/不可解析按非陈旧处理（宁漏勿杀）。 */
+function isStaleLastActive(lastActive, now = Date.now()) {
+  if (!lastActive) return false;
+  const ts = Date.parse(lastActive);
+  return Number.isFinite(ts) && (now - ts) > GHOST_EMPTY_DIR_STALE_MS;
+}
+
 function detectChangeDbConsistency(cwd, pointer, multiDb) {
   const auth = (multiDb.dbs || []).find((d) => d.role === DB_ROLE.AUTHORITY);
   if (!auth) {
@@ -373,25 +414,52 @@ function detectChangeDbConsistency(cwd, pointer, multiDb) {
   }
   const authoritySpecRoot = pointer.present && pointer.specRoot ? pointer.specRoot : join(cwd, '.sillyspec');
   const dirChanges = listChanges(authoritySpecRoot);
-  const dbActive = auth.active || { count: 0, sample: [] };
-  // active.count 是权威 db 的 active change 数；但 listChanges 给的是目录数，两者口径要对齐
-  // 这里用 active_changes 全量需从 probe 取——summary 只给了 count/sample，
-  // 所以用 count 与目录数做粗对齐，细对齐留给后续 dump。
-  const dirCount = dirChanges.length;
-  const dbCount = dbActive.count;
+  // SS-2（2026-08-20）：从 count 粗对齐升级为精确集合对账——ghost_rows（db active
+  // 无目录）与 orphan_dirs（目录无 db active 行）逐名列出，供 doctor --cleanup-ghosts
+  // 消费，不再让 52 条残留只停留在「需 dump 后细对齐」。
+  const activeNames = (auth.active_changes && Array.isArray(auth.active_changes))
+    ? auth.active_changes
+    : [];
+  const dirSet = new Set(dirChanges);
+  const activeSet = new Set(activeNames);
+  const ghostRows = activeNames.filter((n) => !dirSet.has(n));
+  const orphanDirs = dirChanges.filter((n) => !activeSet.has(n));
+  // SS-2b：空壳——db active + 目录存在但 0 文件 + last_active 超过 7 天。有目录所以
+  // 逃过 ghostRows 的「无目录」判定（2026-08-15 清理时 6 个空壳即此漏网形态）。
+  const activeLastActive = (auth.active_last_active && typeof auth.active_last_active === 'object')
+    ? auth.active_last_active
+    : {};
+  const emptyShells = activeNames.filter((n) =>
+    dirSet.has(n) && isStaleLastActive(activeLastActive[n]) && dirHasNoFiles(join(authoritySpecRoot, 'changes', n)));
   const findings = [];
   let pass = true;
   let severity = null;
-  // 仅当差异显著才告警（口径不完全可比，避免误报）
-  if (Math.abs(dirCount - dbCount) > Math.max(2, dirCount * 0.2)) {
+  if (ghostRows.length > 0) {
     pass = false;
     severity = CHECK_SEVERITY.WARNING;
     findings.push(
-      `权威 db active changes (${dbCount}) 与 changes/ 目录数 (${dirCount}) 差异显著——` +
-      `可能存在孤儿目录（有目录无 db 记录）或幽灵记录（db 有记录无目录），需 dump 后细对齐`
+      `幽灵记录 ${ghostRows.length} 条（db active 但无目录）：${ghostRows.slice(0, 10).join(', ')}${ghostRows.length > 10 ? ' …' : ''}——` +
+      `可用 sillyspec doctor --cleanup-ghosts --confirm 归档清理`
+    );
+  }
+  if (emptyShells.length > 0) {
+    pass = false;
+    severity = severity || CHECK_SEVERITY.WARNING;
+    findings.push(
+      `空壳目录 ${emptyShells.length} 个（db active + 目录 0 文件 + last_active 超 7 天）：${emptyShells.slice(0, 10).join(', ')}${emptyShells.length > 10 ? ' …' : ''}——` +
+      `可用 sillyspec doctor --cleanup-ghosts --confirm 归档行并移除空目录`
+    );
+  }
+  if (orphanDirs.length > 0) {
+    pass = false;
+    severity = severity || CHECK_SEVERITY.WARNING;
+    findings.push(
+      `孤儿目录 ${orphanDirs.length} 个（目录存在但无 db active 行）：${orphanDirs.slice(0, 10).join(', ')}${orphanDirs.length > 10 ? ' …' : ''}——` +
+      `先 dump 确认再手工归位，doctor 不自动删目录`
     );
-  } else {
-    findings.push(`权威 db active changes (${dbCount}) 与 changes/ 目录数 (${dirCount}) 基本一致`);
+  }
+  if (pass) {
+    findings.push(`权威 db active changes (${activeNames.length}) 与 changes/ 目录数 (${dirChanges.length}) 完全一致`);
   }
   return {
     name: 'change_db_consistency',
@@ -399,10 +467,15 @@ function detectChangeDbConsistency(cwd, pointer, multiDb) {
     pass,
     severity,
     findings,
-    safe_actions: [],
+    safe_actions: ghostRows.length > 0 || emptyShells.length > 0
+      ? ['sillyspec doctor --cleanup-ghosts（dry-run）→ 加 --confirm 归档幽灵行/空壳目录']
+      : [],
     authority_spec_root: authoritySpecRoot,
-    dir_count: dirCount,
-    db_active_count: dbCount,
+    dir_count: dirChanges.length,
+    db_active_count: activeNames.length,
+    ghost_rows: ghostRows,
+    orphan_dirs: orphanDirs,
+    empty_shells: emptyShells,
   };
 }
 
@@ -416,15 +489,17 @@ function detectChangeDbConsistency(cwd, pointer, multiDb) {
  * @returns {{total:number, checked:number} | null} null = plan/tasks.md 都不存在或无 task 行
  */
 function readPlanCheckboxStatus(changeDir) {
-  const planPath = join(changeDir, 'plan.md');
+  // 2026-08-20-task-truth-unify：tasks.md（任务注册表）优先；plan.md 纯 ID 引用行无 checkbox，
+  // 旧「plan 优先」顺序对新契约变更恒 null（D5 诊断静默致盲）。tasks.md 缺失回退 plan.md（旧变更兼容）。
   const tasksPath = join(changeDir, 'tasks.md');
+  const planPath = join(changeDir, 'plan.md');
   let content = null;
-  if (existsSync(planPath)) {
-    try { content = readFileSync(planPath, 'utf8'); } catch { content = null; }
-  }
-  if (content == null && existsSync(tasksPath)) {
+  if (existsSync(tasksPath)) {
     try { content = readFileSync(tasksPath, 'utf8'); } catch { content = null; }
   }
+  if (content == null && existsSync(planPath)) {
+    try { content = readFileSync(planPath, 'utf8'); } catch { content = null; }
+  }
   if (content == null) return null;
   // match both "- [ ] task-01: title" and "- [x] task-01: title"
   const taskLine = /(?:^- \[[ x]\] )task-\d+[^:]*:?\s*.+$/gm;
@@ -709,3 +784,115 @@ function writeDump(result, authoritySpecDir) {
     return { ...result, dump_write_error: e.message };
   }
 }
+
+
+/**
+ * SS-2（2026-08-20）：归档幽灵行——db active 但 changes/ 无同名目录的记录。
+ * SS-2b（2026-08-20）：扩空壳目录——db active + 目录存在但 0 文件 + last_active 超
+ * 7 天（GHOST_EMPTY_DIR_STALE_MS）。两者都是 quick 收尾注销缺陷（工具侧已修）在
+ * 历史会话中累积的僵尸 active 行，污染 listChanges/progress show 的「活跃变更」
+ * 列表；旧 doctor 只 WARNING 不给动作（stage-machine 提示「可用 doctor 清理」却清不掉）。
+ *
+ * 安全设计：
+ * - 仅把 changes.status 从 active 改为 archived（对齐 change-registry 归档语义，
+ *   状态可逆：手工改回 status='active' 即恢复，不删任何行）。
+ * - 默认 dry-run 只列名单；加 confirm 才写。
+ * - 空壳目录归档时同时移除空目录（删前复查仍为 0 文件，复查非空整条放过）；
+ *   有内容的目录一律不动。孤儿目录（有目录无行）不自动删，留给人工归位。
+ */
+export async function cleanupGhostChanges({ cwd, specDir = null, confirm = false }) {
+  const pointer = resolvePointer(cwd);
+  const localSpec = join(cwd, '.sillyspec');
+  const candidates = [
+    join(localSpec, '.runtime', 'sillyspec.db'),
+    join(localSpec, 'sillyspec.db'),
+  ];
+  if (pointer.specRoot) {
+    candidates.unshift(
+      join(pointer.specRoot, '.runtime', 'sillyspec.db'),
+      join(pointer.specRoot, 'sillyspec.db'),
+    );
+  }
+  let dbPath = null;
+  for (const p of candidates) {
+    try {
+      if (existsSync(p) && statSync(p).size > 0) { dbPath = p; break; }
+    } catch { /* stat 失败跳过 */ }
+  }
+  if (!dbPath) {
+    return { action: 'skipped', reason: '未找到非空 sillyspec.db', ghosts: [], archived: [], errors: [], count: 0 };
+  }
+  const authoritySpecRoot = (pointer.present && pointer.specRoot && existsSync(pointer.specRoot))
+    ? pointer.specRoot
+    : localSpec;
+  const changesDir = join(authoritySpecRoot, 'changes');
+  let dirNames = [];
+  try {
+    dirNames = readdirSync(changesDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== 'archive')
+      .map((e) => e.name);
+  } catch { /* 目录缺失 → 全部 active 都是幽灵 */ }
+  const dirSet = new Set(dirNames);
+
+  let db = null;
+  const archived = [];
+  const errors = [];
+  const skippedNonEmpty = [];
+  const removedDirs = [];
+  try {
+    db = openDatabase(dbPath, { readOnly: !confirm });
+    // last_active 与 name 一起取：空壳判定需要时间门槛（见 isStaleLastActive）。
+    const activeRows = db.prepare("SELECT name, last_active FROM changes WHERE status='active'").all();
+    const ghosts = activeRows.filter((r) => !dirSet.has(r.name)).map((r) => r.name);
+    const emptyShells = activeRows
+      .filter((r) => dirSet.has(r.name) && isStaleLastActive(r.last_active) && dirHasNoFiles(join(changesDir, r.name)))
+      .map((r) => r.name);
+    if (confirm) {
+      const now = new Date().toISOString();
+      const stmt = db.prepare("UPDATE changes SET status = 'archived', last_active = ? WHERE name = ? AND status = 'active'");
+      for (const n of ghosts) {
+        try {
+          stmt.run(now, n);
+          archived.push(n);
+        } catch (e) {
+          errors.push({ name: n, error: e.message });
+        }
+      }
+      for (const n of emptyShells) {
+        // 删目录前复查非空：dry-run 与 --confirm 之间并发会话可能已往空目录写入首份产物
+        //（如 brainstorm 落 proposal.md）。复查非空 → 整条放过（行也不归档），宁漏勿杀。
+        const dirPath = join(changesDir, n);
+        if (!dirHasNoFiles(dirPath)) {
+          skippedNonEmpty.push(n);
+          continue;
+        }
+        try {
+          stmt.run(now, n);
+          rmSync(dirPath, { recursive: true, force: true });
+          removedDirs.push(n);
+          archived.push(n);
+        } catch (e) {
+          errors.push({ name: n, error: e.message });
+        }
+      }
+    }
+    const activeAfter = confirm ? pluckAll(db, "SELECT name FROM changes WHERE status='active'") : null;
+    return {
+      action: confirm ? 'archived' : 'dry_run',
+      db_path: dbPath,
+      changes_dir: changesDir,
+      ghosts: confirm ? archived : ghosts,
+      empty_shells: confirm ? removedDirs : emptyShells,
+      skipped_nonempty: skippedNonEmpty,
+      removed_dirs: removedDirs,
+      archived,
+      errors,
+      count: ghosts.length + emptyShells.length,
+      active_after: activeAfter,
+    };
+  } catch (e) {
+    return { action: 'error', reason: e.message, ghosts: [], archived: [], errors: [{ error: e.message }], count: 0 };
+  } finally {
+    if (db) { try { db.close(); } catch { /* 忽略关闭失败 */ } }
+  }
+}

package/src/fs-atomic.js

@@ -58,7 +58,9 @@ export function renameSyncRetry(from, to, retries = 5) {
  */
 export function writeAtomicSync(filePath, content) {
   const dir = dirname(filePath);
-  const tmpPath = join(dir, `.${basename(filePath)}.${process.pid}.tmp`);
+  // pid + 随机段双因子：Windows PID 重用激进，两进程可能撞同 pid，tmp 名碰撞 rename 互相覆盖
+  const rnd = Math.random().toString(36).slice(2, 10);
+  const tmpPath = join(dir, `.${basename(filePath)}.${process.pid}.${rnd}.tmp`);
   writeFileSync(tmpPath, content);
   try {
     renameSyncRetry(tmpPath, filePath);

package/src/git-helper.js

@@ -53,13 +53,16 @@ export function safeGit(cwd, args, opts = {}) {
  * 调用方自行 catch；不经 shell，参数以数组元素传递。
  * @param {string} cwd
  * @param {string[]} args
- * @param {{ trim?: boolean, timeout?: number }} [opts]
- * @returns {string}
+ * @param {{ trim?: boolean, timeout?: number, encoding?: string }} [opts]
+ *   - encoding:'buffer' 返回原始 Buffer（git diff --binary 等**二进制输出**专用——
+ *     utf8 解码会破坏 NUL 字节使补丁不可应用；Buffer 输出跳过 trim）
+ * @returns {string|Buffer}
  */
 export function git(cwd, args, opts = {}) {
-  const { trim = true, timeout = 5000 } = opts
+  const { trim = true, timeout = 5000, encoding = 'utf8' } = opts
   const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
-  const value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'] })
+  const value = execFileSync('git', fullArgs, { encoding, timeout, stdio: ['ignore', 'pipe', 'pipe'] })
+  if (Buffer.isBuffer(value)) return value
   return trim ? value.trim() : value
 }
 

package/src/hooks/worktree-guard.js

@@ -121,8 +121,14 @@ function readWorktreeMeta(cwd, changeName) {
 
 function isPathInside(child, parent) {
   if (!child || !parent) return false
-  const absChild = path.resolve(child)
-  const absParent = path.resolve(parent)
+  let absChild = path.resolve(child)
+  let absParent = path.resolve(parent)
+  // Windows 文件系统大小写不敏感：git worktree list / 编辑器给出的路径大小写可能与
+  // 注册的 meta.worktreePath 不一致，敏感比较会把 worktree 内合法写入误判为越权（体检 BUG-09）
+  if (process.platform === 'win32') {
+    absChild = absChild.toLowerCase()
+    absParent = absParent.toLowerCase()
+  }
   return absChild === absParent || absChild.startsWith(absParent + path.sep)
 }