sillyspec 3.26.11 → 3.26.13

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,145 @@ 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. 活跃变更（取第一个，或空）
+    const changeRows = sqlDb.prepare("SELECT id, name, current_stage, last_active FROM changes WHERE status = 'active' ORDER BY name").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 失败不影响返回。

package/src/run/command.js

@@ -23,7 +23,7 @@ import { basename, join, resolve, dirname } from 'node:path'
 import { existsSync, readdirSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
 import { randomBytes, randomUUID } from 'node:crypto'
 import { writeAtomicSync } from '../fs-atomic.js'
-import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './shared.js'
+import { resolveSpecDir, countAncestorSpecDirs, resolveChangeDir, triggerSync, getStageSteps, formatWaitOptions, checkApproval, warnApprovalUnknown, didYouMean, assertSafeChangeName, detectQuickSessionDrift, detectWorktreeSpecDrift, resolveRuntimeRoot, writePlatformPointer, checkPlatformManaged, PLATFORM_MANAGED_FILENAME } from './shared.js'
 import { resolveQuickLinkedChanges } from './quick-audit.js'
 import { outputStep } from './prompt.js'
 import { completeStep, skipStep, waitStep, continueStep } from './complete.js'
@@ -108,6 +108,11 @@ export async function ensureStageSteps(progress, stageName, cwd, specDir = null)
   // 检查步骤数量是否匹配（execute 动态步骤可能变化）
   if (progress.stages[stageName].steps.length !== steps.length) {
     const oldSteps = progress.stages[stageName].steps
+    // 漂移显式化（坑 execute-step-table-drift，2026-08-20 实证）：plan.md Wave 数在 execute
+    // 中途被改后 DB 步骤表与重算定义错位（17/12 交替），重播种本身按名保留完成态是对的，
+    // 但此前完全静默——agent 只见各处计数打架的报错，不知道发生了什么、该不该继续
+    console.warn(`⚠️ ${stageName} 步骤表与当前定义漂移（DB ${oldSteps.length} 步 → 定义 ${steps.length} 步，常见原因：execute 中途修改了 plan.md 的 Wave 结构）`)
+    console.warn(`   已按步骤名保留完成态重播种（新增步骤置 pending；Wave 重编号时同名步骤继承旧状态，勾选真相以 tasks.md/review.json 为准）`)
     progress.stages[stageName].steps = steps.map(s => {
       const old = oldSteps.find(step => step.name === s.name)
       if (old) return old  // 精确名命中 → 保留旧状态
@@ -195,10 +200,13 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // ── cwd 纠正：向上查找真实项目根 ──
   // 防止多 project 工作区中 cwd 停在子目录（如 backend/）时
   // 状态写入子目录下误建的 .sillyspec，导致状态分裂
-  if (!specDir && !existsSync(join(cwd, '.sillyspec-platform.json'))) {
-    // 平台模式（cwd 有 .sillyspec-platform.json 指针）不做 cwd 纠正：指针已明确 specDir，
-    // 向上找 .sillyspec 反而会撞到无关项目（如用户 home 的 .sillyspec），导致 --done 恢复
-    // 读写 ~/.sillyspec-platform.json 出错的 specRoot。
+  // HUB-12c：守卫须同时查平台接管声明——指针被 cleanup、声明还在、祖先有别的 .sillyspec
+  //（monorepo 嵌套）时，cwd 被上移后 checkPlatformManaged 在新 cwd 扑空 → 静默落本地库，
+  // 双入口 fail-closed 被绕过（状态分裂正是它要防的）
+  if (!specDir && !existsSync(join(cwd, '.sillyspec-platform.json')) && !checkPlatformManaged(cwd)) {
+    // 平台模式（cwd 有 .sillyspec-platform.json 指针或接管声明）不做 cwd 纠正：指针已明确
+    // specDir，向上找 .sillyspec 反而会撞到无关项目（如用户 home 的 .sillyspec），导致
+    // --done 恢复读写 ~/.sillyspec-platform.json 出错的 specRoot。
     const resolvedRoot = resolveSpecDir(cwd)
     if (resolvedRoot && resolvedRoot !== join(cwd, '.sillyspec')) {
       const realRoot = dirname(resolvedRoot)
@@ -1271,8 +1279,9 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
           console.log(`⏳ 变更 ${changeName} 的执行审批待处理中...`)
           console.log('  提示：使用 --skip-approval 跳过审批检查')
         }
+        // HUB-07：unknown 醒目警告 + 留痕（原单行 warn 不显眼且无记录）
         if (approval.status === 'unknown') {
-          console.warn(`⚠️ 变更 ${changeName} 的审批状态未知（${approval.reason || '请求失败'}），按本地模式放行（非审批中，无需等待）`)
+          warnApprovalUnknown(cwd, changeName, approval.reason)
         }
       }
     }
@@ -1288,6 +1297,12 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
   const result = await completeStep(pm, progress, currentStage, cwd, outputText, inputText, { printNext: false, changeName, platformOpts })
   if (!result) return
   progress = pm.read(cwd, changeName)
+  // change 行被并发归档/删除时 read 返回 null（体检 BUG-05）：引导排查而非 TypeError 崩溃
+  if (!progress) {
+    console.error(`❌ 完成步骤后进度数据消失（变更 ${changeName} 可能被并发归档/删除），请用 sillyspec progress show 核对当前状态`)
+    process.exitCode = 1
+    return
+  }
 
   const nextPendingIdx = progress.stages[currentStage]?.steps?.findIndex(step => step.status === 'pending' || step.status === 'in-progress') ?? -1
   if (nextPendingIdx !== -1) {
@@ -1304,8 +1319,9 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
           console.log(`⏳ 变更 ${changeName} 的执行审批待处理中...`)
           console.log('  提示：使用 --skip-approval 跳过审批检查')
         }
+        // HUB-07：unknown 醒目警告 + 留痕（原单行 warn 不显眼且无记录）
         if (approval.status === 'unknown') {
-          console.warn(`⚠️ 变更 ${changeName} 的审批状态未知（${approval.reason || '请求失败'}），按本地模式放行（非审批中，无需等待）`)
+          warnApprovalUnknown(cwd, changeName, approval.reason)
         }
       }
     }
@@ -1357,6 +1373,12 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
   pm._write(cwd, progress, changeName)
   triggerSync(cwd, changeName, platformOpts)
   progress = pm.read(cwd, changeName)
+  // 同 BUG-05：写入后被并发删除的窗口，null 直接解引用会 TypeError
+  if (!progress) {
+    console.error(`❌ 阶段推进后进度数据消失（变更 ${changeName} 可能被并发归档/删除），请用 sillyspec progress show 核对当前状态`)
+    process.exitCode = 1
+    return
+  }
 
   console.log(`\n${currentStage} complete. Auto advanced to ${next}.`)
   const nextSteps = await getAutoSteps(next)
@@ -1374,8 +1396,9 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
           console.log(`⏳ 变更 ${changeName} 的执行审批待处理中...`)
           console.log('  提示：使用 --skip-approval 跳过审批检查')
         }
+        // HUB-07：unknown 醒目警告 + 留痕（原单行 warn 不显眼且无记录）
         if (approval.status === 'unknown') {
-          console.warn(`⚠️ 变更 ${changeName} 的审批状态未知（${approval.reason || '请求失败'}），按本地模式放行（非审批中，无需等待）`)
+          warnApprovalUnknown(cwd, changeName, approval.reason)
         }
       }
     }

package/src/run/complete-handlers.js

@@ -98,10 +98,9 @@ export function validateParsedProjects(projects, sourceRoot) {
 /**
  * 在 changes/archive/ 下查找变更 <changeName> 是否已被归档（archive 脱钩自愈用）。
  *
- * 归档目录名 = archiveDestDirName(date, changeName) = `<归档日期>-<剥前导日期的描述>`；
- * 但手动 / 部分流程归档可能保留原 changeName（含前导日期）或用别的日期前缀。
- * 按「描述部分」（剥前导 YYYY-MM-DD-）匹配，并要求目录含 plan.md（归档必备产物，
- * 防止同名巧合误判）。issue: archive-stage-physical-tracking-desync。
+ * 归档目录名 = 原变更名（直接移入 archive/，不重命名）。
+ * 精确匹配 + 要求目录含 plan.md（归档必备产物，防止同名巧合误判）。
+ * issue: archive-stage-physical-tracking-desync。
  *
  * @param {string} archiveDir - changes/archive 绝对路径
  * @param {string} changeName - 变更名（currentChange）
@@ -115,15 +114,9 @@ export function findAlreadyArchivedDir(archiveDir, changeName) {
   } catch {
     return null
   }
-  const descOf = (n) => String(n).replace(/^\d{4}-\d{2}-\d{2}-/, '')
-  const targetDesc = descOf(changeName)
-  if (!targetDesc) return null
-  // 1. 精确原名命中（手动 mv 保留原 changeName）
+  // 精确原名命中
   const exact = entries.find((e) => e === changeName && existsSync(join(archiveDir, e, 'plan.md')))
   if (exact) return join(archiveDir, exact)
-  // 2. 描述部分命中（archiveDestDirName 产出的 <date>-<desc>，或手动剥前导日期的目录）
-  const descMatch = entries.find((e) => descOf(e) === targetDesc && existsSync(join(archiveDir, e, 'plan.md')))
-  if (descMatch) return join(archiveDir, descMatch)
   return null
 }
 
@@ -506,9 +499,12 @@ export async function handleScanProjectListStep({ stageName, steps, currentIdx,
         const yamlContent = readFileSync(join(projectsDir, yf), 'utf8')
         const pathMatch = yamlContent.match(/^path:\s*(.+)/m)
         const pPath = pathMatch ? pathMatch[1].trim() : pName
-        // 校验 path 是否存在且在 source_root 内
+        // 校验 path 是否存在且在 source_root 内。
+        // 用 relative 判越界（与 validateParsedProjects 同口径）：startsWith 前缀比较
+        // 无分隔符，C:\repo 会放行兄弟目录 C:\repository2（体检 BUG-13）
         const absPath = resolve(cwd, pPath)
-        if (pPath.includes('..') || (!absPath.startsWith(resolve(cwd)) && absPath !== resolve(cwd))) {
+        const rel = relative(resolve(cwd), absPath)
+        if (rel.startsWith('..') || isAbsolute(rel)) {
           fallbackSkipped.push(`${pName} (path 越界: ${pPath})`)
           continue
         }
@@ -1162,7 +1158,9 @@ export async function handleExecuteWaveArtifact({ stageName, steps, currentIdx,
 export async function collectExecuteChangedFiles({ runtimeRoot, changeName }) {
   if (!runtimeRoot || !changeName) return []
   const { resolveLatestExecuteRunIdWithTasks, readReview, normalizeRepoKey } = await import('../task-review.js')
-  const runId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot })
+  // changeName 透传：run 解析按 change 戳优先归属（坑 worktree-cleanup-marker-chain），
+  // 避免 marker 断裂后聚合到其他变更 run 的 changedFiles 误报 missing
+  const runId = resolveLatestExecuteRunIdWithTasks({ runtimeRoot, changeName })
   if (!runId) return []
   const tasksDir = join(runtimeRoot, 'execute-runs', runId, 'tasks')
   if (!existsSync(tasksDir)) return []
@@ -1300,6 +1298,15 @@ export async function handleExecuteWorktreeCleanup({ stageName, changeName, cwd
 export async function handleScanStageCompleted({ stageName, currentIdx, cwd, progress, pm, stageData, changeName, outputText, platformOpts }) {
   // 平台模式：scan 完成后生成 manifest.json + post-check
   if (stageName === 'scan' && (platformOpts.specRoot || platformOpts.runtimeRoot)) {
+    if (!platformOpts.specRoot) {
+      // 只传 runtimeRoot 无 specRoot（command.js 允许的组合）：manifest 无处落盘。
+      // 显式 fail-closed 报错——此前 mkdirSync(null) 抛 TypeError 被外层 catch 吞掉，
+      // postcheck/指针升级/阻断全部静默跳过，scan 失败也"干净成功"（体检 BUG-12）
+      console.error(`❌ 平台模式缺少 --spec-root，无法写 manifest.json（scan postcheck 中止）`)
+      stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = false
+      stageData.scanMeta.manifestError = 'missing specRoot'
+      return
+    }
     try {
       stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = false; // 默认失败
       const manifestDir = platformOpts.specRoot