sillyspec 3.33.3 → 3.33.4

package/src/run/gates.js

@@ -28,6 +28,7 @@
  * 不搬：ensureDepsFreshness（execute 入口 deps 自检，调用方 runStage 非 completeStep，归属未来 execute-handler）
  */
 import { basename, join, relative, dirname } from 'node:path'
+import { timedAsync } from '../timing.js'
 import { runtimeStatePath } from '../runtime-paths.js'
 import { createHash } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
@@ -1227,6 +1228,29 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
       printVerifyTestCheck(testCheck)
       _obsJournal('green-cache', true, null)
     } else {
+      // ── 失败签名复用（2026-10-21-verify-reuse-large-repo FR-03）：真跑前先咨询上次失败──
+      // 同签名（代码指纹×豁免面×快照口径全等）+ 30min 窗口内 → 不重跑，合成 failed 照常阻断
+      // （dsh 0ff6f1c8 取证：文档门修复循环里每轮 --done 都整轮重测同签名失败 10~13.5 分钟）。
+      // fail-closed：任一判据不可得/失配/TTL 过期 → 照旧真跑。RERUN 逃生阀与 noAI 闸同阀对称。
+      let _failedReuse = null
+      try {
+        const { consultFailedScanReuse, synthesizeReusedFailedCheck } = await import('./verify-quality-scan.js')
+        const consult = consultFailedScanReuse({
+          specBase, cwd, changeName,
+          plannedSnapshot: Boolean(verifyGateSnap),
+          forceRerun: Boolean(process.env.SILLYSPEC_VERIFY_QUALITY_SCAN_RERUN),
+        })
+        if (consult.reuse) _failedReuse = synthesizeReusedFailedCheck(consult.record)
+        else if (consult.reason && consult.reason !== 'no-failed-record') {
+          _obsJournal('quality-scan-failed', false, consult.reason)
+        }
+      } catch { /* 咨询异常 → 真跑（复用是优化不是正确性依赖） */ }
+      if (_failedReuse) {
+        testCheck = _failedReuse
+        console.log(`\n♻️ Verify 测试对账：失败签名复用——上次实测 failed 且签名未变，免重跑（阻断照常，出路见下）`)
+        printVerifyTestCheck(testCheck)
+        _obsJournal('quality-scan-failed', true, null)
+      } else {
       // 测试实测是同步 execSync，长套件可跑 2~10min 且中途无输出——先预告避免 agent 误判卡死
       console.log(`\n⏳ Verify 测试对账：CLI 亲自执行 local.yaml 的 commands.test（同步，耗时可能较长，请等待…）`)
       // restrictFiles 接线（2026-09-26-verify-gate-restrictfiles，评审 P2 留痕缺口的清偿）：
@@ -1287,6 +1311,7 @@ export async function runStageCompletionGates({ stageName, cwd, changeName, plat
           }
         }
       } catch { /* auto-bind fail-soft */ }
+      } // 失败签名复用分支到此为止——下方记账层对 failed 复用结果是 no-op（passed 守卫）
       // P2 记账（fail-closed 层②：只有通过结果落账本——失败永不缓存，修复后重跑才能记）
       if (!traceHasActiveRows) {
       try {
@@ -1916,7 +1941,11 @@ function readDesignOwnFiles(specBase, changeName) {
  *          null = 全部通过，调用方继续自管收尾（如下一步提示）；
  *          非 null = gate/handler 失败已 rollback，调用方直接 return。
  */
-export async function completeStageGates({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText, ctx = null }) {
+export async function completeStageGates(args) {
+  return timedAsync('gates', () => completeStageGatesImpl(args))
+}
+
+async function completeStageGatesImpl({ stageName, cwd, changeName, platformOpts, specBase, progress, pm, stageData, steps, currentIdx, outputText, ctx = null }) {
   // 整体 try/catch（task-04 / review-2026-08-09 #2）：收尾段（execute 预检 + scan handler + validate* +
   // auxiliary 重置 + runStageCompletionGates）任一段抛非结构化异常 → rollbackCompletionAndReturn
   // （回滚 in-progress + 落盘 + 返回未完成对象），不冒顶 exit 1。正常的 _scanResult/_gateEarlyReturn

package/src/run/prompt.js

@@ -19,6 +19,7 @@
  *   - loadModuleContextIndex/buildModuleContextInjection 内 require('fs'/'path') 改顶部静态 import
  */
 import { basename, dirname, join } from 'node:path'
+import { timedAsync } from '../timing.js'
 import { runtimeStatePath } from '../runtime-paths.js'
 import { existsSync, readFileSync, mkdirSync, readdirSync, writeFileSync, rmSync } from 'node:fs'
 import { createHash } from 'node:crypto'
@@ -921,6 +922,10 @@ async function recordPromptInjectLedger({ runtimeRoot, changeName, stageName, fi
 }
 
 export async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts = {}, prevStepAnswer = null, waitHistory = null, autoMeta = null) {
+  return timedAsync('render', () => outputStepImpl(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts, prevStepAnswer, waitHistory, autoMeta))
+}
+
+async function outputStepImpl(stageName, stepIndex, steps, cwd, changeName, dbProjectName, platformOpts = {}, prevStepAnswer = null, waitHistory = null, autoMeta = null) {
   const step = steps[stepIndex]
   const total = steps.length
   // ── 越界防御 ──
@@ -941,7 +946,10 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
   // 网络阻塞；未连接平台静默 / quick 会话降级跳过 / 8s 熔断 / 失败只 warn，契约全在
   // triggerStepStartSync 内（shared.js docstring 即本接线点的说明），Node 事件循环保证在飞
   // POST 落地后进程才退出。
-  triggerStepStartSync(cwd, changeName, platformOpts)
+  // 例外（2026-10-21-protocol-tax task-06 / FR-06）：status 是只读查看阶段，不推——消费仓
+  // 实测该推送（进程退出等在飞 POST）占 status 命令耗时的大头（10-20s 量级，平台慢时更甚）；
+  // 查看态无步骤起点语义，平台停滞信号的新鲜度交给写命令。
+  if (stageName !== 'status') triggerStepStartSync(cwd, changeName, platformOpts)
 
   // ── 阶段产物模板落盘（R16 减负批次 2026-09-24）：模板出上下文——prompt 只留指针，模板
   //    幂等落盘 <specBase>/.runtime/templates/ 供 agent 写产物前 Read 一次。best-effort：

package/src/run/shared.js

@@ -11,6 +11,7 @@
  *     本模块仅 re-export，run/ 层现有调用方路径与行为不变。
  */
 import { basename, join, resolve, dirname, sep } from 'node:path'
+import { timedAsync } from '../timing.js'
 import { runtimeTempPath } from '../runtime-paths.js'
 import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, appendFileSync, realpathSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
@@ -981,6 +982,10 @@ function warnPlatformNotConnectedDaily(cwd, platformOpts = {}) {
 }
 
 export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {}) {
+  return timedAsync('sync', () => triggerSyncImpl(cwd, changeName, platformOpts, opts))
+}
+
+async function triggerSyncImpl(cwd, changeName, platformOpts = {}, opts = {}) {
   // ── 后台异步化（2026-09-20 用户反馈：--done 被网络尾巴拖住分钟级）──
   // 默认把同步整体挪进 detached 后台子进程：17 个调用点全部 fire-and-forget，但进程
   // 退出要等事件循环排空，在飞 fetch 拖住命令返回。回落 inline 的三条件：
@@ -1066,9 +1071,13 @@ export async function triggerSync(cwd, changeName, platformOpts = {}, opts = {})
  * @returns {{confirmed: boolean, delegated?: boolean, skipped?: string, result?: object}}
  */
 export async function triggerSyncTerminalStrict(cwd, changeName, platformOpts = {}, opts = {}) {
+  return timedAsync('sync', () => triggerSyncTerminalStrictImpl(cwd, changeName, platformOpts, opts))
+}
+
+async function triggerSyncTerminalStrictImpl(cwd, changeName, platformOpts = {}, opts = {}) {
   // quick 会话无实体变更目录（无归档/删除终态）——沿用既有 best-effort 语义
   if (changeName && QUICK_SID_RE.test(changeName)) {
-    await triggerSync(cwd, changeName, platformOpts, opts)
+    await triggerSyncImpl(cwd, changeName, platformOpts, opts)
     return { confirmed: false, delegated: true }
   }
   const syncMod = await import('../sync.js')
@@ -1139,6 +1148,10 @@ export async function triggerSyncTerminalStrict(cwd, changeName, platformOpts =
  * 每任务上报指引）覆盖。
  */
 export async function triggerStepStartSync(cwd, changeName, platformOpts = {}, opts = {}) {
+  return timedAsync('sync', () => triggerStepStartSyncImpl(cwd, changeName, platformOpts, opts))
+}
+
+async function triggerStepStartSyncImpl(cwd, changeName, platformOpts = {}, opts = {}) {
   try {
     // 无 changeName（渲染层个别路径/测试 fixture）直接静默——sync(null) 只会打 warn 噪音
     if (!changeName) return
@@ -1226,6 +1239,10 @@ export async function triggerPull(cwd, changeName, platformOpts = {}, opts = {})
  * 供 index.js 在 stage 命令（run/--done/archive）与 approve 决策点注入一行调用。
  */
 export async function triggerPullActiveChange(cwd, platformOpts = {}) {
+  return timedAsync('sync', () => triggerPullActiveChangeImpl(cwd, platformOpts))
+}
+
+async function triggerPullActiveChangeImpl(cwd, platformOpts = {}) {
   // 平台模式走自己的链路，跳过；自指回环（repo-native junction）按本地模式处理
   if (isPlatformMode(platformOpts, cwd)) return
   // 先检查是否连接平台：未连接直接 return，避免 _ensureDB 在无 local.yaml 的 cwd 创建空 DB 污染

package/src/run/stage.js

@@ -100,29 +100,32 @@ export async function runStage(pm, progress, stageName, cwd, changeName, skipApp
     const effectiveChange = changeName
     const { WorktreeManager } = await import('../worktree.js')
     const wm = new WorktreeManager({ cwd })
-    const existingMeta = wm.getMeta(effectiveChange)
-    if (existingMeta) {
-      console.log(`🔗 worktree 已存在: ${existingMeta.worktreePath} (${existingMeta.mode})`)
+    // ensure（2026-10-21-brainstorm-proto-worktree）：meta 已登记即复用——头脑风暴原型期
+    // 早建的 worktree / native 复用形态与 execute 首建走同一幂等入口，原 getMeta 短路语义收敛于此。
+    let wtResult
+    try {
+      wtResult = wm.ensure(effectiveChange, { adoptBranch: !!(quickOpts && quickOpts.adoptBranch) })
+    } catch (e) {
+      console.error(`❌ worktree 创建失败: ${e.message}`)
+      // 修复建议不再无条件推荐 git branch -D（坑 worktree-user-branch-conflict，2026-08-24：
+      // 同名分支可能是用户有意创建的——分支冲突时 create 报错已带三选一决策菜单，删不删
+      // 交由菜单/人工判断；doctor 的分支删除也有 review 锚点 + 无库保守双保护）。
+      console.error(`   修复建议：`)
+      console.error(`   1. 同名分支冲突/收编：按上方报错内三选一菜单处置（遗留分支确认作废后才删；用户指定分支用 --adopt-branch 收编）`)
+      console.error(`   2. worktree 状态异常：sillyspec worktree doctor --fix（分支删除有 review 锚点保护，不会误删在用分支）`)
+      console.error(`   3. 目录残留：确认无未提交改动后清理 .sillyspec/.runtime/worktrees/${effectiveChange}/ 再重试`)
+      process.exit(1)
+    }
+    if (wtResult.existing) {
+      console.log(`🔗 worktree 已存在: ${wtResult.worktreePath} (${wtResult.mode})`)
     } else {
-      try {
-        const result = wm.create(effectiveChange, { adoptBranch: !!(quickOpts && quickOpts.adoptBranch) })
-        console.log(`🔗 worktree 已创建: ${result.worktreePath} (分支: ${result.branch}, 模式: ${result.mode}${result.adoptedBranch ? ', 收编既有分支' : ''})`)
-      } catch (e) {
-        console.error(`❌ worktree 创建失败: ${e.message}`)
-        // 修复建议不再无条件推荐 git branch -D（坑 worktree-user-branch-conflict，2026-08-24：
-        // 同名分支可能是用户有意创建的——分支冲突时 create 报错已带三选一决策菜单，删不删
-        // 交由菜单/人工判断；doctor 的分支删除也有 review 锚点 + 无库保守双保护）。
-        console.error(`   修复建议：`)
-        console.error(`   1. 同名分支冲突/收编：按上方报错内三选一菜单处置（遗留分支确认作废后才删；用户指定分支用 --adopt-branch 收编）`)
-        console.error(`   2. worktree 状态异常：sillyspec worktree doctor --fix（分支删除有 review 锚点保护，不会误删在用分支）`)
-        console.error(`   3. 目录残留：确认无未提交改动后清理 .sillyspec/.runtime/worktrees/${effectiveChange}/ 再重试`)
-        process.exit(1)
-      }
+      console.log(`🔗 worktree 已创建: ${wtResult.worktreePath} (分支: ${wtResult.branch}, 模式: ${wtResult.mode}${wtResult.adoptedBranch ? ', 收编既有分支' : ''})`)
     }
     // 入口 deps 自检（D-002）：已存在 worktree（create short-circuit 不供给）时重供给
-    if (existingMeta) {
+    //（existing 标志置 undefined：JSON.stringify 丢弃，不随 deps 写回污染 meta.json）
+    if (wtResult.existing) {
       const execSpecBase = platformOpts?.specRoot || join(cwd, '.sillyspec')
-      await ensureDepsFreshness(cwd, effectiveChange, execSpecBase, existingMeta)
+      await ensureDepsFreshness(cwd, effectiveChange, execSpecBase, { ...wtResult, existing: undefined })
     }
 
     // ── 跨仓仓 worktree 隔离（坑 cross-repo-no-worktree-isolation，2026-08-27 用户实证）──

package/src/run/verify-quality-scan.js

@@ -317,6 +317,57 @@ export function shouldReuseLastPassedScan({ lastRecord, currentPassedKey, planne
   return { reuse: true, reason: null }
 }
 
+/**
+ * 收口门/gate verify 的失败签名复用咨询（2026-10-21-verify-reuse-large-repo FR-03）。
+ * 包装既有三件（loadLastQualityScanRecord + computeQualityScanDedupKey +
+ * shouldReuseLastFailedScan），供 gates.js 实测 else 分支与 machine-interface verify-test
+ * facet 在真跑前调用：上次 failed 且失败签名未变 → 不重跑，消费侧合成 failed 结果照常阻断
+ * （dsh 0ff6f1c8 取证：同签名失败在收口门前被完整重跑，每轮 10~13.5 分钟）。
+ *
+ * 与 noAI 步内 shouldReuseLastFailedScan 的两点刻意差异：
+ *   1. TTL（缺省 30min，对齐 green-cache 窗口）——dedupKey 不含测试面，agent 手动补测试
+ *      绑定后面漂移（记录面 X，本轮应跑面 X+Δ）在 noAI 步由「步骤不推进」自兜底，收口门
+ *      复用会把旧面失败压到新面收口上，窗口须有界；
+ *   2. RERUN 逃生阀由消费侧透传 forceRerun（与 noAI 失败签名闸同阀对称——环境确已修好等
+ *      场景不因复用层锁死）。
+ * fail-closed：任一判据不可得/失配 → { reuse: false, reason }，消费侧照旧真跑。
+ */
+export function consultFailedScanReuse({ specBase, cwd, changeName, plannedSnapshot, maxAgeMs = 30 * 60 * 1000, forceRerun = false, now = Date.now() }) {
+  const lastRecord = loadLastQualityScanRecord({ specBase, changeName })
+  const verdict = shouldReuseLastFailedScan({
+    lastRecord,
+    currentDedupKey: computeQualityScanDedupKey({ cwd, specBase }),
+    plannedSnapshot,
+    forceRerun,
+  })
+  if (!verdict.reuse) return { reuse: false, reason: verdict.reason, record: null }
+  if (maxAgeMs != null) {
+    const ranAtMs = Date.parse(lastRecord.ranAt || '')
+    if (!Number.isFinite(ranAtMs) || now - ranAtMs > maxAgeMs) {
+      return { reuse: false, reason: `ttl-expired（上次实测 ${lastRecord.ranAt || '未知时间'} 超 ${Math.round(maxAgeMs / 60000)}min 窗口——面漂移防护，照旧真跑）`, record: null }
+    }
+  }
+  return { reuse: true, reason: null, record: lastRecord }
+}
+
+/** consultFailedScanReuse 命中后的合成 testCheck（消费侧共用——披露统一、字段齐全） */
+export function synthesizeReusedFailedCheck(record) {
+  const t = (record && record.testResult) || {}
+  return {
+    status: 'failed',
+    reason: `♻️ 复用上次失败实测（失败签名未变：代码指纹/豁免面/快照口径全等${record && record.ranAt ? `，实测于 ${record.ranAt}` : ''}，免重跑）——${(t.reason || '测试失败').split('\n')[0]}。出路：① 修代码 ② 补 known_failures 豁免（均即失配自动重测）③ 强制重跑：SILLYSPEC_VERIFY_QUALITY_SCAN_RERUN=1（旁路本复用层直接重跑；=force 连 noAI 步失败签名闸一并旁路）`,
+    command: `${t.command || 'commands.test'} (failed-scan-reuse)`,
+    exitCode: typeof t.exitCode === 'number' ? t.exitCode : 1,
+    durationMs: 0,
+    outputTail: t.outputTail || null,
+    resultPath: t.resultPath || null,
+    strategy: t.strategy || null,
+    failureRemaining: t.failureRemaining || t.failure_remaining || null,
+    failureExempted: t.failureExempted || t.failure_exempted || null,
+    reusedFromRecord: true,
+  }
+}
+
 /**
  * 伪影分诊编排（ql-20260920-010 修复一 a）：测试失败 → classify 分类 → 命中且本次是
  * 快照口径 → 主树口径单点复跑对照。复跑过 = 伪影坐实：返回主树结果 + artifactTriage

package/src/runtime-paths.js

@@ -74,6 +74,9 @@ export const RUNTIME_STATE_SINGLETONS = [
   'spec-sync-last-success.json',
   'spec-sync-fail-streak.json',
   'spec-sync-follow-reported.json',
+  // 2026-10-21-cli-manifest-since-cache：spec-manifest 增量游标缓存（有读者、
+  // 不可再生前同步全量代价高——state/ 语义）
+  'spec-manifest-cache.json',
   'sync-noise-self-heal.json',
   'last-delta.json',
 ]

package/src/sillyhub-mcp/client.js

@@ -610,18 +610,21 @@ export class SillyHubMcpClient {
    * artifacts 原样透传不裁剪：平台实返形态（[{kind, content_ref, id}…] 或演进形态）整组
    * 透传——kind 匹配 / JSON 提取等语义解析归消费方（review-dispatch 的
    * extractReviewFromArtifacts），本封装保持传输层纯度（task-02 constraints）。
+   * answer 原文透传（2026-10-21-review-dispatch-answer-salvage / dsh 会话实证）：worker 可能把
+   * review JSON 放回答正文而非 artifacts——取 tool 返回的 answer 字段（缺省兜底 result 字段）
+   * 字符串原文一并透传，非字符串/双缺 → null；解析仍归消费方，传输层只搬运。
    * @param {object} p
    * @param {string} p.missionId
    * @param {string} p.workerId
-   * @returns {Promise<{workerId: string|null, status: string, artifacts: Array}>}
-   *   正常 → {workerId, status, artifacts} 原样解析（status 缺省 'unknown'，artifacts 缺省 []）；
-   *   未配置 / 调用失败(null) / tool isError → { workerId: null, status: 'unavailable', artifacts: [] }
+   * @returns {Promise<{workerId: string|null, status: string, artifacts: Array, answer: string|null}>}
+   *   正常 → {workerId, status, artifacts, answer} 原样解析（status 缺省 'unknown'，artifacts 缺省 []，answer 缺省 null）；
+   *   未配置 / 调用失败(null) / tool isError → { workerId: null, status: 'unavailable', artifacts: [], answer: null }
    *   （与 dispatchWorker/getDaemonStatus 同族 best-effort，绝不向上抛）
    */
   async getWorkerResult({ missionId, workerId } = {}) {
-    if (!this._configured) return { workerId: null, status: 'unavailable', artifacts: [] };
+    if (!this._configured) return { workerId: null, status: 'unavailable', artifacts: [], answer: null };
     const result = await this._callTool('get_worker_result', { mission_id: missionId, worker_id: workerId });
-    if (result === null || result.isError) return { workerId: null, status: 'unavailable', artifacts: [] };
+    if (result === null || result.isError) return { workerId: null, status: 'unavailable', artifacts: [], answer: null };
     const value = this._parseToolReturnValue(result);
     // workerId 兜底链与 dispatchWorker 同款（2026-09-10 平台实返 {id,…} 形态实证）
     const wid = value && typeof value === 'object'
@@ -631,7 +634,9 @@ export class SillyHubMcpClient {
       ? (value.status ?? 'unknown')
       : 'unknown';
     const artifacts = value && Array.isArray(value.artifacts) ? value.artifacts : [];
-    return { workerId: wid, status, artifacts };
+    const rawAnswer = value && typeof value === 'object' ? (value.answer ?? value.result) : null;
+    const answer = typeof rawAnswer === 'string' ? rawAnswer : null;
+    return { workerId: wid, status, artifacts, answer };
   }
 
   /**

package/src/spawn-settle.js

@@ -0,0 +1,47 @@
+/**
+ * spawn-settle —— detached 子进程孵化稳定化（2026-10-21-p0-p1-hardening FR-08）
+ *
+ * 背景（dsh z1/z2 各实证一次）：Windows 下父进程 spawn detached 子进程（watcher/bg-sync）后
+ * 立即退出，可触发 Node libuv 退出断言崩溃（`Assertion failed: !(handle->flags &
+ * UV_HANDLE_CLOSING) src\win\async.c`）——把本已成功的 CLI 调用污染成 exit 1。根因在 Node
+ * 运行时（父进程退出与子进程 async 句柄建立竞态），应用层无法根除；本 util 提供有界缓解：
+ * spawn 后等子进程 'spawn' 事件（孵化完成、句柄建立完毕）或 'error' 再放行，上限 timeoutMs
+ * 兜底——把「父进程在句柄建立中途退出」的竞态窗口压掉。best-effort：任何异常路径直接返回，
+ * 绝不影响命令功能。
+ */
+import { EventEmitter } from 'node:events';
+
+/**
+ * 等待 detached 子进程孵化稳定。
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {number} [timeoutMs=150] 兜底上限（'spawn'/'error' 均未发出时按此时长放行）
+ * @returns {Promise<void>} 事件到达 / 兜底超时 / child 已退出 / child 非法形态——均 resolve（永不 reject）
+ */
+export async function awaitSpawnSettled(child, timeoutMs = 150) {
+  if (!child || typeof child.once !== 'function') return;
+  // 已退出（同步失败形态：exitCode/signalCode 已定）——无句柄在途，立即返回
+  if (child.exitCode !== null && child.exitCode !== undefined) return;
+  if (child.signalCode) return;
+  await new Promise((resolve) => {
+    let settled = false;
+    const fin = () => {
+      if (settled) return;
+      settled = true;
+      try { child.off('spawn', fin); child.off('error', fin); } catch { /* 已解绑/非 EventEmitter——best-effort */ }
+      resolve();
+    };
+    child.once('spawn', fin);
+    child.once('error', fin);
+    // 上限兜底：两事件都不发（异常宿主/极端调度）也不让调用方久等
+    const t = setTimeout(fin, timeoutMs);
+    t.unref?.();
+  });
+}
+
+/** 测试辅助：构造最小 child 形态（EventEmitter + exitCode/signalCode 字段）。 */
+export function fakeChildForTest({ exitCode = null, signalCode = null } = {}) {
+  const c = new EventEmitter();
+  c.exitCode = exitCode;
+  c.signalCode = signalCode;
+  return c;
+}

package/src/spec-sync.js

@@ -16,6 +16,7 @@
  */
 
 import { createHash } from 'crypto';
+import { timedAsync } from './timing.js';
 import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join, relative, sep } from 'path';
 import { bindSyncNoiseRoot, syncConnectionWarn, isConnectionClassStatus, noteSyncSuccess } from './sync-noise.js';
@@ -433,6 +434,48 @@ function writeBaseSnapshot(specRoot, localFiles) {
   } catch { /* 快照失败只损失下次的内容级防回推，不影响本次同步结果 */ }
 }
 
+// ── spec-manifest 增量游标缓存（2026-10-21-cli-manifest-since-cache）──
+// 平台 spec-manifest 支持 ?since=<spec_version> 增量返回（multi-agent-platform
+// 2026-10-21-spec-manifest-incremental）。缓存 = 上次消费的整份清单 + 游标 +
+// 连续增量计数：稳态拉取只传变化行（生产实测全量 2.2MB/13145 行、5.5s@~400KBps
+// 链路——单请求吃掉 CLI 同步 8s 总预算七成；增量后 <10KB/亚秒）。
+// 形态 {spec_version:int, files:{path:{hash,version,exists}}, inc_count:int}；
+// .runtime 在上传排除面，缓存不进同步树。fail-soft：读写任何失败都退化为
+// 全量拉取（与无缓存同路径，行为不劣于现状）。
+const MANIFEST_CACHE = 'spec-manifest-cache.json';
+
+// 定期全量对账阈值：连续增量 N 轮后强制不带 since 全量（缓存与服务器脱钩的
+// 幻影行防线，design 风险节）。env SILLYSPEC_SPEC_SYNC_RECONCILE_EVERY 可调。
+function resolveReconcileEvery() {
+  const raw = Number(process.env.SILLYSPEC_SPEC_SYNC_RECONCILE_EVERY);
+  if (Number.isInteger(raw) && raw >= 1 && raw <= 10000) return raw;
+  return 50;
+}
+
+function readManifestCache(specRoot) {
+  try {
+    const c = JSON.parse(readFileSync(runtimeStatePath(join(specRoot, '.runtime'), MANIFEST_CACHE), 'utf8'));
+    if (
+      c && Number.isInteger(c.spec_version) && c.files && typeof c.files === 'object'
+      && Number.isInteger(c.inc_count)
+    ) return c;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function writeManifestCache(specRoot, cache) {
+  try {
+    mkdirSync(join(specRoot, '.runtime', 'state'), { recursive: true });
+    writeAtomicSync(runtimeStatePath(join(specRoot, '.runtime'), MANIFEST_CACHE), JSON.stringify(cache));
+  } catch { /* 缓存写失败只损失增量优化，下轮全量（fail-soft） */ }
+}
+
+function clearManifestCache(specRoot) {
+  try { unlinkSync(runtimeStatePath(join(specRoot, '.runtime'), MANIFEST_CACHE)); } catch { /* 不存在即无事 */ }
+}
+
 /**
  * 丢弃「跟随服务器」型 update op（坑 quicksync-conflict-granularity ①）。
  *
@@ -682,6 +725,10 @@ function attributeChangeLabel(paths) {
  * （syncSpecTreeOnly / resolve forcePush 等）不消费该字段，向后兼容。
  */
 export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
+  return timedAsync('sync', () => syncSpecTreeImpl(specRoot, platform, changeName, opts))
+}
+
+async function syncSpecTreeImpl(specRoot, platform, changeName, opts = {}) {
   if (!platform || !platform.url || !platform.token) {
     debugLog('[spec-sync] 未连接平台（本地合法状态）；跳过 spec 树增量同步');
     return { synced: 0, ok: true };
@@ -698,10 +745,15 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
   const manifestUrl = `${platform.url.replace(/\/$/, '')}/api/changes/-/spec-manifest`;
   const syncUrl = `${platform.url.replace(/\/$/, '')}/api/changes/-/spec-sync`;
 
-  // 1. GET 服务器清单
+  // 1. GET 服务器清单（2026-10-21-cli-manifest-since-cache：缓存感知——有可用
+  //    缓存带 ?since=<游标> 拉增量行合并；无缓存/对账轮/SILLYSPEC_SPEC_SYNC_FULL=1
+  //    走全量并落缓存；旧平台响应无 spec_version → 作废缓存回退现状行为；服务端
+  //    spec_version 倒退（重建）→ 一次性全量对账）
   let serverManifest = {};
+  const manifestCache = process.env.SILLYSPEC_SPEC_SYNC_FULL ? null : readManifestCache(specRoot);
+  const cacheUsable = manifestCache && manifestCache.inc_count < resolveReconcileEvery();
   try {
-    const res = await fetch(manifestUrl, {
+    const res = await fetch(cacheUsable ? `${manifestUrl}?since=${manifestCache.spec_version}` : manifestUrl, {
       headers: { Authorization: `Bearer ${platform.token}` },
       signal: withSignal(10000),
     });
@@ -724,7 +776,41 @@ export async function syncSpecTree(specRoot, platform, changeName, opts = {}) {
       return { synced: 0, ok: false };
     }
     const body = await res.json().catch(() => ({}));
-    serverManifest = body.files || {};
+    if (cacheUsable && typeof body.spec_version === 'number' && body.spec_version >= manifestCache.spec_version) {
+      // 增量合并：响应行（含 exists=false 墓碑行）逐行覆盖进缓存——与拉全量等价
+      const merged = { ...manifestCache.files, ...(body.files || {}) };
+      writeManifestCache(specRoot, { spec_version: body.spec_version, files: merged, inc_count: manifestCache.inc_count + 1 });
+      serverManifest = merged;
+    } else if (cacheUsable && typeof body.spec_version === 'number') {
+      // 服务端 spec_version 倒退（重建/回滚）——缓存脱离服务端纪元，一次性全量对账。
+      // 对账失败按拉取失败 fail-closed（ok:false）：空锚会触发全量 add 风暴，禁用。
+      debugLog(`[spec-sync] spec_version 倒退（${manifestCache.spec_version} → ${body.spec_version}，服务端重建？）——回退全量清单对账`);
+      const full = await fetch(manifestUrl, {
+        headers: { Authorization: `Bearer ${platform.token}` },
+        signal: withSignal(10000),
+      });
+      if (!full.ok) {
+        const failCount = bumpFailStreak(specRoot, logLabel, `倒退对账全量 HTTP ${full.status}`);
+        console.warn(`[spec-sync] 倒退对账全量拉取失败 HTTP ${full.status}（文件树本次未同步，下次自动重试）: ${logLabel}`);
+        if (failCount >= FAIL_STREAK_ESCALATE_AT) {
+          console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+        }
+        return { synced: 0, ok: false };
+      }
+      const fullBody = await full.json().catch(() => ({}));
+      serverManifest = fullBody.files || {};
+      if (typeof fullBody.spec_version === 'number') writeManifestCache(specRoot, { spec_version: fullBody.spec_version, files: serverManifest, inc_count: 0 });
+      else clearManifestCache(specRoot);
+    } else if (typeof body.spec_version === 'number') {
+      // 全量响应（首拉/对账轮/强制全量）：整份落缓存
+      writeManifestCache(specRoot, { spec_version: body.spec_version, files: body.files || {}, inc_count: 0 });
+      serverManifest = body.files || {};
+    } else {
+      // 旧平台（响应无 spec_version 字段）：忽略 since 参数恒回全量——作废缓存，
+      // 未部署窗口内行为与现状完全一致
+      serverManifest = body.files || {};
+      clearManifestCache(specRoot);
+    }
   } catch (err) {
     const failCount = bumpFailStreak(specRoot, logLabel, describeSyncError(err));
     const line = `[spec-sync] 拉取清单异常（文件树本次未同步，下次自动重试）: ${logLabel}: ${describeSyncError(err)}`;

package/src/stages/knowledge.js

@@ -118,8 +118,19 @@ export async function cmdSearch(dir, args, opts = {}) {
     vectorHint = vectorSwitchHint(dir)
   } catch { /* 提示 fail-open */ }
 
+  // 停车场过滤披露（FR-01，2026-10-21-knowledge-tier-denoise）：查询命中过 unmapped 停车场
+  // 文件但被检索核心滤除且最终零结果时，披露被滤文件——去噪不丢可见性，人工按需直查。
+  const parkingFiltered = !result.matched && Array.isArray(result.json && result.json.parkingFiltered)
+    ? result.json.parkingFiltered : []
+
   if (!result.matched) {
-    output(true, { query, matches: [], ...(vectorHint ? { hint: vectorHint } : {}) })
+    output(true, {
+      query, matches: [],
+      ...(vectorHint ? { hint: vectorHint } : {}),
+      ...(parkingFiltered.length > 0
+        ? { parkingFiltered, parkingNote: `停车场文件已过滤（${parkingFiltered.join('、')}）——按需直查文件` }
+        : {}),
+    })
     return
   }
 
@@ -620,11 +631,12 @@ export async function cmdKnowledge(args, dir, opts = {}) {
       '  refresh               重扫 scan 文档重写 generated/ 区（**写盘**——先 validate 再用）',
       '  propose / classify / inbox / graph / stats / renumber',
       '  renumber [--dry-run|--apply]  存量决策号迁移为全局号（dry-run 先行；apply 写盘幂等）',
+      '  redomain-unmapped [--face decisions|fr] [--apply]  unmapped 停车场存量批量清偿（文件锚/覆盖面投票目标域；dry-run 先行）',
       '',
       '写盘面子命令（refresh/propose/classify）先跑同名只读命令确认现状；探索用法先看本帮助。',
     ]
     for (const l of lines) console.log(l)
-    output(true, { help: true, subcommands: ['search', 'inspect', 'validate', 'digest', 'refresh', 'propose', 'classify', 'inbox', 'graph', 'stats'] })
+    output(true, { help: true, subcommands: ['search', 'inspect', 'validate', 'digest', 'refresh', 'propose', 'classify', 'inbox', 'graph', 'stats', 'redomain-unmapped'] })
     return
   }
   const subCommand = args[0] || ''
@@ -640,6 +652,16 @@ export async function cmdKnowledge(args, dir, opts = {}) {
       return cmdRefresh(dir, args.slice(1), opts)
     case 'propose':
       return cmdPropose(dir, args.slice(1), opts)
+    case 'redomain-unmapped': {
+      // unmapped 停车场存量批量清偿（FR-04，2026-10-21-knowledge-tier-denoise）：decisions 按文件锚
+      // / fr 按来源变更覆盖面投票目标域；缺省 dry-run 报告先行，--apply 幂等迁移（不裸删、冲突跳过）。
+      const mod = await tryImportSubcommandImpl('../redomain-unmapped.js', 'redomain-unmapped.js')
+      if (!mod || typeof mod.cmdRedomainUnmapped !== 'function') {
+        output(false, {}, { code: 'not_implemented', subcommand: 'redomain-unmapped' })
+        return
+      }
+      return mod.cmdRedomainUnmapped(dir, args.slice(1), opts)
+    }
     case 'graph': {
       // 知识图谱查询面（2026-10-08-knowledge-graph）：neighbors/path/impact/orphans/dangling，
       // --edges 边型筛选；全 JSON 出口（与 search/validate 同族）。
@@ -748,7 +770,7 @@ export async function cmdKnowledge(args, dir, opts = {}) {
       output(false, {}, {
         code: 'unknown_subcommand',
         subCommand: subCommand,
-        available: ['search', 'inspect', 'validate', 'refresh', 'propose', 'classify', 'inbox', 'stats', 'digest', 'graph', 'renumber'],  // dump 随 graph 路由面（2026-10-09-graph-dump-layout）
+        available: ['search', 'inspect', 'validate', 'refresh', 'propose', 'classify', 'inbox', 'stats', 'digest', 'graph', 'renumber', 'redomain-unmapped'],  // dump 随 graph 路由面（2026-10-09-graph-dump-layout）
       })
   }
 }

package/src/timing.js

@@ -0,0 +1,55 @@
+/**
+ * 分段计时记录器（2026-10-21-protocol-tax FR-01）。
+ *
+ * 背景：会话考古（2026-10-20-session-page-dsh-alignment z1/z2）发现 CLI 单命令耗时无从归因
+ * ——verify --done 挂 300s 靠会话死亡才暴露，status 6.3s 靠 CPU profile 考古才定位到平台同步。
+ * 本模块给命令提供四段计时（sync / gates / render / state-write），env DEBUG_SILLYSPEC_TIMING=1
+ * 时在进程退出前输出 `[timing] sync=…ms gates=…ms render=…ms state-write=…ms`。
+ *
+ * 契约（FR-01）：
+ * - 未设 env：timedSync/timedAsync 原样透传、退出钩子不输出——命令输出与现状逐字节等价。
+ * - 设 env：未触达段输出 `n/a` 不省略段名；同名段多次进入累加；走 stderr（不污染 --json
+ *   的 stdout envelope）。
+ * - 观测不改变行为：fn 抛错照抛，耗时只记到抛错前；模块注册的 exit 钩子只写一行 stderr。
+ * - 覆盖面：exit 钩子挂 process 'exit' 事件（含 process.exit 硬退出路径），无需各命令埋发射点。
+ */
+const SEGMENTS = ['sync', 'gates', 'render', 'state-write']
+const enabled = process.env.DEBUG_SILLYSPEC_TIMING === '1'
+const acc = new Map()
+
+function record(segment, ms) {
+  acc.set(segment, (acc.get(segment) || 0) + ms)
+}
+
+export function timedSync(segment, fn) {
+  if (!enabled) return fn()
+  const t0 = performance.now()
+  try {
+    return fn()
+  } finally {
+    record(segment, performance.now() - t0)
+  }
+}
+
+export async function timedAsync(segment, fn) {
+  if (!enabled) return fn()
+  const t0 = performance.now()
+  try {
+    return await fn()
+  } finally {
+    record(segment, performance.now() - t0)
+  }
+}
+
+function emitTimingIfEnabled(stream = process.stderr) {
+  if (!enabled) return
+  const parts = SEGMENTS.map((s) => {
+    const ms = acc.get(s)
+    return `${s}=${ms === undefined ? 'n/a' : `${Math.round(ms)}ms`}`
+  })
+  stream.write(`[timing] ${parts.join(' ')}\n`)
+}
+
+if (enabled) {
+  process.on('exit', () => emitTimingIfEnabled())
+}