sillyspec 3.33.2 → 3.33.4

package/src/review-dispatch.js

@@ -110,50 +110,65 @@ export function detectStall(record, nowMs, stallMs) {
 }
 
 /**
- * 从 artifacts 提取 review JSON（双通道容错，design 风险登记「平台 artifacts 形态演进」）：
+ * 首个平衡 JSON 对象扫描（通道②/③共用）：从文本首个 { 起括号配对扫描（字符串字面量内的
+ * } 不计数），命中即 JSON.parse 返回对象；无 {} / 首个平衡段解析失败 → null。
+ */
+function scanFirstBalancedJson(text) {
+  const t = String(text)
+  const start = t.indexOf('{')
+  if (start === -1) return null
+  let depth = 0, inStr = false, esc = false
+  for (let i = start; i < t.length; i++) {
+    const ch = t[i]
+    if (esc) { esc = false; continue }
+    if (ch === '\\') { esc = true; continue }
+    if (ch === '"') { inStr = !inStr; continue }
+    if (inStr) continue
+    if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) {
+        try {
+          const obj = JSON.parse(t.slice(start, i + 1))
+          if (obj && typeof obj === 'object') return obj
+        } catch { return null }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * 从 artifacts / answer 提取 review JSON（三通道容错，design 风险登记「平台 artifacts 形态演进」）：
  * ① kind 含 review/review_json 的 artifact，content/content_ref/text 字段 JSON.parse 优先；
- * ② 兜底任一 artifact 文本字段提取首个平衡 {} 对象。全失败 → null（调用方给人工 get_worker_result 指引）。
+ * ② 兜底任一 artifact 文本字段提取首个平衡 {} 对象；
+ * ③ answer 正文扫描（2026-10-21-review-dispatch-answer-salvage / dsh 会话实证：worker 把完整
+ *   review JSON 放回答正文而非 artifacts——任务书已明示该兜底形态）。
+ * 第二参可缺省——只传 artifacts 时行为与改前逐字一致（向后兼容）。全失败 → null（调用方给 --salvage 兜底指引）。
  */
-export function extractReviewFromArtifacts(artifacts) {
-  if (!Array.isArray(artifacts)) return null
+export function extractReviewFromArtifacts(artifacts, answer) {
   const texts = []
-  for (const a of artifacts) {
-    if (!a || typeof a !== 'object') continue
-    const kind = String(a.kind || '')
-    const text = typeof a.content === 'string' ? a.content
-      : typeof a.content_ref === 'string' ? a.content_ref
-      : typeof a.text === 'string' ? a.text : null
-    if (text === null) continue
-    if (/review/i.test(kind)) {
-      try {
-        const obj = JSON.parse(text)
-        if (obj && typeof obj === 'object') return obj
-      } catch { /* 该条不是合法 JSON，落兜底通道 */ }
+  if (Array.isArray(artifacts)) {
+    for (const a of artifacts) {
+      if (!a || typeof a !== 'object') continue
+      const kind = String(a.kind || '')
+      const text = typeof a.content === 'string' ? a.content
+        : typeof a.content_ref === 'string' ? a.content_ref
+        : typeof a.text === 'string' ? a.text : null
+      if (text === null) continue
+      if (/review/i.test(kind)) {
+        try {
+          const obj = JSON.parse(text)
+          if (obj && typeof obj === 'object') return obj
+        } catch { /* 该条不是合法 JSON，落兜底通道 */ }
+      }
+      texts.push(text)
     }
-    texts.push(text)
   }
+  if (typeof answer === 'string' && answer) texts.push(answer)
   for (const t of texts) {
-    const start = t.indexOf('{')
-    if (start === -1) continue
-    // 首个平衡对象：括号配对扫描（字符串字面量内的 } 不计数）
-    let depth = 0, inStr = false, esc = false
-    for (let i = start; i < t.length; i++) {
-      const ch = t[i]
-      if (esc) { esc = false; continue }
-      if (ch === '\\') { esc = true; continue }
-      if (ch === '"') { inStr = !inStr; continue }
-      if (inStr) continue
-      if (ch === '{') depth++
-      else if (ch === '}') {
-        depth--
-        if (depth === 0) {
-          try {
-            const obj = JSON.parse(t.slice(start, i + 1))
-            if (obj && typeof obj === 'object') return obj
-          } catch { break }
-        }
-      }
-    }
+    const obj = scanFirstBalancedJson(t)
+    if (obj) return obj
   }
   return null
 }
@@ -161,7 +176,8 @@ export function extractReviewFromArtifacts(artifacts) {
 /**
  * 组装 reviewer 任务书（FR-01 派发质量的核心）：四要素——①单源清单（前缀按 checklist
  * docblock 规则）②review.json 契约（与 gate 同源）③期望产出方式（read_only worker：
- * 结论经 artifacts 返回，**不写任何文件**——落盘归 CLI）④铁律段（禁改文件/禁 git commit）。
+ * 结论经 artifacts 返回，**不写任何文件**——落盘归 CLI；宿主不支持 artifacts 时放回答正文
+ * 首个 ```json 块，回收链第三通道兜底）④铁律段（禁改文件/禁 git commit）。
  */
 export function buildReviewerTaskBook({ stage, changeDir, reviewRunId, channelPriority, probeLines = null }) {
   const mainDoc = STAGE_MAIN_DOC[stage] || 'design.md'
@@ -183,6 +199,7 @@ export function buildReviewerTaskBook({ stage, changeDir, reviewRunId, channelPr
     '## 产出方式（read_only 约束）',
     '- **禁止修改任何文件、禁止 git commit、禁止写盘**——你只读文档与必要的源码佐证。',
     '- 把**完整 review.json 文本**（按上方契约 schema，含 reviewer: {"channel":"platform"}）作为产出返回（artifacts 里的 content 字段放纯 JSON 文本）。',
+    '- 宿主/平台不支持 artifacts 回传时，把**完整 review.json 文本**放进回答正文的**首个 ```json 代码块**（CLI 回收链会从回答正文扫描兜底）。',
     '- docHash 可占位（调度方 CLI 会按主文档机械重算），其余字段照实填写。',
   ].join('\n')
   return {
@@ -219,6 +236,32 @@ export function persistStageReview({ runtimeRoot, stage, changeName, reviewRunId
   return { ok: true, reviewPath }
 }
 
+/**
+ * worker 终态原文落盘（2026-10-21-review-dispatch-answer-salvage FR-04 证据链）：completed
+ * 回收路径统一调用——answer 原文优先，缺省序列化 artifacts 原文；两者皆空返回 null（无原文
+ * 可落，调用方走「确无结果」口径）。与 review.json 同 run 目录（结构化结论 + 原文证据并存，
+ * dsh 事故里人工只能靠平台 UI 贴回原文——原文必须本地在场）。best-effort：写失败 warn 不抛。
+ * @returns {string|null} 落盘绝对路径；无内容/写失败 null
+ */
+function writeWorkerAnswer({ runtimeRoot, stage, reviewRunId, gr }) {
+  try {
+    const answer = gr && typeof gr.answer === 'string' && gr.answer
+      ? gr.answer
+      : gr && Array.isArray(gr.artifacts) && gr.artifacts.length > 0
+        ? JSON.stringify(gr.artifacts, null, 2) + '\n'
+        : null
+    if (!answer) return null
+    const dir = join(runtimeRoot, 'stage-reviews', `${stage}-${reviewRunId}`)
+    mkdirSync(dir, { recursive: true })
+    const p = join(dir, 'worker-answer.md')
+    writeAtomicSync(p, answer.endsWith('\n') ? answer : answer + '\n')
+    return p
+  } catch (e) {
+    console.warn(`[sillyspec] worker-answer.md 落盘失败（不阻断回收）: ${e && e.message ? e.message : String(e)}`)
+    return null
+  }
+}
+
 /** 降级指引（channel_priority 去 platform 的剩余序渲染；probe 失败 / worker 失败共用）。 */
 export function renderFallbackGuidance(cwd) {
   const rest = readReviewChannelPriority(cwd).filter((c) => c !== 'platform')
@@ -235,13 +278,15 @@ export function renderFallbackGuidance(cwd) {
  * @param {object} opts
  *   mode: 'create'|'status'|'kill'；cwd/specBase/changeName 必填；stage（create 必填）；
  *   client: SillyHubMcpClient 实例（create/status 用）；probe: 可注入（默认真 probeSillyHub）；
- *   budgetUsd（默认 1.0）；stallMs（默认 900000）；reviewRunId（status 回收时缺省读 marker）。
+ *   budgetUsd（默认 1.0）；stallMs（默认 900000）；reviewRunId（status 回收时缺省读 marker）；
+ *   salvage（status 专用，默认 false——completed 提取失败时返回 salvagePath + --from 回收指引，
+ *   在途记录不清可重试；CLI 形态 `--status --salvage`）。
  * @returns {Promise<{ok: boolean, ...}>} 永不抛——所有异常转 {ok:false, reason}
  */
 export async function runReviewDispatch(opts = {}) {
   const {
     mode = 'create', cwd = process.cwd(), specBase, changeName,
-    stage, client, probe, budgetUsd = 1.0, stallMs = 900_000, reviewRunId,
+    stage, client, probe, budgetUsd = 1.0, stallMs = 900_000, reviewRunId, salvage = false,
   } = opts
   if (!specBase || !changeName) return { ok: false, reason: '缺少 specBase/changeName' }
 
@@ -340,21 +385,37 @@ export async function runReviewDispatch(opts = {}) {
       }
       if (st === 'completed') {
         const gr = await client.getWorkerResult({ missionId: rec.missionId, workerId: rec.workerId })
-        const review = extractReviewFromArtifacts(gr && gr.artifacts)
+        const runtimeRoot = join(specBase, '.runtime')
+        // 终态原文先落盘再提取（FR-04：无论提取成败，原文证据与 review.json 同 run 目录在场）
+        const answerPath = writeWorkerAnswer({ runtimeRoot, stage: rec.stage, reviewRunId: rec.reviewRunId, gr })
+        const review = extractReviewFromArtifacts(gr && gr.artifacts, gr && gr.answer)
         if (!review) {
-          return { ok: false, state: 'completed-no-artifact', statusLine, reason: 'worker completed 但 artifacts 提取不到 review JSON', guidance: `人工核对：平台 get_worker_result（mission ${rec.missionId} / worker ${rec.workerId}）；确认无法回收再 --kill 降级。` }
+          // 两步出口（dsh 事故复盘：旧文案「--kill 降级」混写处置与降级，误导 agent 跳过回收直接自审）：
+          // ① --salvage 兜底回收（落盘原文 + --from 指引）② 确认平台确无结果才降级
+          const reason = 'worker completed 但三通道（artifacts kind / artifacts 文本 / answer 正文）均提取不到 review JSON'
+          if (salvage) {
+            return {
+              ok: false, state: 'completed-no-artifact', statusLine, salvagePath: answerPath, reason,
+              guidance: answerPath
+                ? `① worker 终态原文已落盘 ${answerPath}——人工核对/修整出 review.json 后运行 sillyspec register-stage-review --change ${changeName} --stage ${rec.stage} --from <修整后的review.json> 回收\n② 确认平台确无结果（UI 核对 mission ${rec.missionId}）才按通道优先序降级：\n${renderFallbackGuidance(cwd)}`
+                : `① 平台未回传任何终态原文（answer 与 artifacts 均空）——在平台 UI 核对 mission ${rec.missionId} / worker ${rec.workerId}\n② 确认确无结果才按通道优先序降级：\n${renderFallbackGuidance(cwd)}`,
+            }
+          }
+          return {
+            ok: false, state: 'completed-no-artifact', statusLine, reason,
+            guidance: `① 回收兜底：sillyspec review-dispatch --status --salvage --change ${changeName}（自动落盘 worker-answer.md 并提示 register-stage-review --from 回收；平台 UI 可先核对 mission ${rec.missionId}）\n② 确认平台确无结果才按通道优先序降级：\n${renderFallbackGuidance(cwd)}`,
+          }
         }
-        const runtimeRoot = join(specBase, '.runtime')
         const mainDocPath = join(specBase, 'changes', changeName, STAGE_MAIN_DOC[rec.stage] || 'design.md')
         const p = persistStageReview({
           runtimeRoot, stage: rec.stage, changeName, reviewRunId: rec.reviewRunId,
           reviewObj: review, missionId: rec.missionId, mainDocPath,
         })
         if (!p.ok) {
-          return { ok: false, state: 'bad-review', statusLine, errors: p.errors, guidance: 'artifacts 里的 review 不符 schema——--kill 后降级，或人工按契约修 review.json（mission 证据保留）。' }
+          return { ok: false, state: 'bad-review', statusLine, errors: p.errors, guidance: `① 提取到的 review 不符 schema——按契约修整（终态原文参考：${answerPath || '同目录 worker-answer.md'}）后运行 sillyspec register-stage-review --change ${changeName} --stage ${rec.stage} --from <修整后的review.json> 回收\n② 确认平台确无结果才按通道优先序降级：\n${renderFallbackGuidance(cwd)}` }
         }
         clearDispatchRecord(specBase, changeName)
-        return { ok: true, state: 'completed', statusLine, reviewPath: p.reviewPath, verdict: `${review.specVerdict}/${review.qualityVerdict}` }
+        return { ok: true, state: 'completed', statusLine, reviewPath: p.reviewPath, verdict: `${review.specVerdict}/${review.qualityVerdict}`, nextStep: answerPath ? `终态原文已留存 ${answerPath}` : undefined }
       }
       if (st === 'failed' || st === 'killed') {
         clearDispatchRecord(specBase, changeName)
@@ -774,7 +835,8 @@ export async function dispatchShadowReview(opts = {}) {
       }
       if (st === 'completed') {
         const gr = await client.getWorkerResult({ missionId: rec.missionId, workerId: rec.workerId })
-        const review = extractReviewFromArtifacts(gr && gr.artifacts)
+        // 通道③同步受益（answer 正文——主线同款；影子 accounting-only 不加 salvage 交互面）
+        const review = extractReviewFromArtifacts(gr && gr.artifacts, gr && gr.answer)
         if (!review) {
           await mutateShadowLedger(runtimeRoot, (ledger) => {
             const e = ledger.entries.find((x) => x && x.shadowRunId === rec.shadowRunId)

package/src/run/bg-sync.js

@@ -182,6 +182,10 @@ export async function spawnBackgroundSync(cwd, changeName, platformOpts = {}, op
       env,
     });
     child.unref?.();
+    // 孵化稳定化（FR-08 / dsh 实证 libuv 退出断言）：等 spawn 事件落定（≤150ms 兜底）再放行，
+    // 压掉「父进程在子进程句柄建立中途退出」的崩溃竞态窗口。
+    const { awaitSpawnSettled } = await import('../spawn-settle.js');
+    await awaitSpawnSettled(child);
   } finally {
     if (logFd !== null) {
       try { closeSync(logFd); } catch { /* 父侧 fd 副本关闭；子进程持有继承副本 */ }

package/src/run/code-face-key.js

@@ -24,7 +24,10 @@ import { createHash } from 'node:crypto';
 
 function safeGit(cwd, args) {
   try {
-    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000, windowsHide: true });
+    // maxBuffer：execFileSync 默认 1MB，ls-tree -r -z 大仓输出必超（multi-agent-platform 1.95MB /
+    // 本仓 1.76MB，dsh 0ff6f1c8 取证）——ENOBUFS 被 catch 吞成 null 曾让指纹/dedupKey/passedKey
+    // 全链失效、verify 同码态全量实测 6×10~13.5min。256MB 对齐 git-helper GIT_MAX_BUFFER 口径。
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 60000, maxBuffer: 256 * 1024 * 1024, windowsHide: true });
   } catch {
     return null;
   }

package/src/run/command.js

@@ -54,6 +54,7 @@ const VALUE_FLAGS = new Set([
   '--session', // 显式会话标识（吃值；2026-09-14-change-ownership-guards task-02 所有权三级解析最高优先级层，启动 claim 消费）
   '--inherit-from', // wait 继承盖章锚点 <D-xxx@vN>（吃值；2026-09-18-preflight-slimming task-03 / D-003@v2：仅 --wait 场景合法，--wait 分发点校验消费）
   '--step', // --done --step <名|序号> 意图断言（吃值；:340 消费。漏登记死路同 --wait-interactive 前例：burst 说明书出示该形态却被未知参数 exit(2) 拦死，2026-09-23 执行会话实证）
+  '--answers', // --continue --answers k1=v1,k2=v2 批量回填多个 waiting 步骤（吃值；2026-10-21-protocol-tax task-04/FR-04：仅 --continue 场景合法，complete.js continueStep 消费）
 ])
 
 /**
@@ -272,8 +273,10 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   // W1-B: run <stage> 暂不支持 --json。之前 --json 进 knownFlags 白名单却从不读取（静默吞），
   // agent 按 gate/derive 契约期望 envelope 实则拿到混合人类文本。显式 fail-fast 杜绝歧义；
   // 完整 run envelope 待 outputStep 重构（W6）后支持（prompt + nextAction 结构化）。
-  if (opts.json) {
-    console.error('❌ run <stage> 暂不支持 --json（静默吞是 bug，故显式拒绝）。')
+  // 例外（2026-10-21-protocol-tax task-04 / FR-04）：--wait --json 放行——waitStep 输出唯一
+  // JSON 对象（问询+选项结构化，agent 直连 ask_user_question），是明确的局部契约而非静默吞。
+  if (opts.json && !args.includes('--wait')) {
+    console.error('❌ run <stage> 暂不支持 --json（静默吞是 bug，故显式拒绝；--wait 场景除外）。')
     console.error('   查事实用 gate/derive（支持 --json envelope）；run 输出人类可读 prompt 供 agent 直接执行。')
     process.exit(2) // 用法错 → exit 2
   }
@@ -420,6 +423,15 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     process.exit(2) // 用法错 → exit 2
   }
   const continueAnswer = getFlagValue('--answer')
+  // ── --answers 批量回填（2026-10-21-protocol-tax task-04 / FR-04）──
+  // 仅 --continue 场景合法（同 --inherit-from 模式：脱离 --continue 无消费点，静默吞会让
+  // agent 误以为已回填）；与 --answer 互斥校验在 complete.js 批路径入口（两值都解析完再判）。
+  const continueAnswers = getFlagValue('--answers')
+  if (continueAnswers !== null && !isContinue) {
+    console.error('❌ --answers 仅在 --continue 场景合法（一次回填多个 waiting 步骤：--answers k1=v1,k2=v2）')
+    console.error(`   用法: sillyspec run ${stageName} --continue --answers "1=答案A,3=答案B"`)
+    process.exit(2) // 用法错 → exit 2
+  }
   const resolvedSpecDir = specDir || getFlagValue('--spec-dir') || getFlagValue('--spec-root')
   const platformOpts = {
     specRoot: resolvedSpecDir ? resolve(resolvedSpecDir) : null,
@@ -747,6 +759,7 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
     '--skip-apply', // 归档收口跳过 apply 校验（task-02 只注册透传不改行为，消费归 task-03 archive 接线）
     '--inherit-from', // wait 继承盖章 <D-xxx@vN>（2026-09-18-preflight-slimming task-03：仅 --wait 场景合法，hasDecisionId 校验+盖章在 --wait 分发点/complete 层）
     '--step', // --done 意图断言 <名|序号>（吃值，VALUE_FLAGS 同步登记；:340 消费——漏登记则说明书出示的 --done --step 形态进命令即被未知参数拦死，2026-09-23 执行会话实证）
+    '--answers', // --continue 批量回填 k1=v1,k2=v2（吃值，VALUE_FLAGS 同步登记；2026-10-21-protocol-tax task-04：仅 --continue 场景合法，continueStep 消费）
     '--upgrade-thick', // 轻量→完整升档用户同意门（2026-09-25-thin-upgrade-consent：布尔 flag，混跑回退写侧 :1362 消费——无 flag 拒跑，带 flag 落 legacy_fallback+同意时点留痕）
     '--same-session', // R17 实验实证死路清偿（cli-protocol-trust）：STAGE_WALL 报错指引「加 --same-session 重跑」（stage.js 硬墙文案），消费在 runStage 逃生口——此前漏登记，照指引重跑即被本白名单 exit 2（指引指向死路的自我矛盾）
     '--force', // 同族第二实例（静态扫描新发现）：quick --cancel 强清消费点与报错指引（可用 --force）在场但未登记——同死路；一致性钉 test/flag-contract.test.mjs 守护整类
@@ -1726,7 +1739,9 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
   const changed = await ensureStageSteps(progress, stageName, cwd, specRoot)
   if (changed && effectiveChange) {
     pm._write(cwd, progress, effectiveChange)
-    triggerSync(cwd, effectiveChange, platformOpts)
+    // 只读查看（--status）不推平台（2026-10-21-protocol-tax task-06 / FR-06）：重播种是本地
+    // 自愈写（保留），平台同步面归写命令与 bg-sync——status 的同步语义对齐 progress show。
+    if (!isStatus) triggerSync(cwd, effectiveChange, platformOpts)
     progress = pm.read(cwd, effectiveChange) || progress
   }
   if (changed && _preReseedPending && (isDone || isSkip || isWait)
@@ -1795,12 +1810,12 @@ export async function runCommand(args, cwd, specDir = null, opts = {}) {
       }
       inheritFrom = waitInheritFrom
     }
-    return await waitStep(pm, progress, stageName, cwd, outputText, waitReason, waitOptions, { changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, inheritFrom })
+        return await waitStep(pm, progress, stageName, cwd, outputText, waitReason, waitOptions, { changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, inheritFrom, waitJson: Boolean(opts.json) })
   }
 
   // --continue: 从 waiting 恢复
   if (isContinue) {
-    return await continueStep(pm, progress, stageName, cwd, continueAnswer, { changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, fromStep: fromStepValue })
+    return await continueStep(pm, progress, stageName, cwd, continueAnswer, { changeName: effectiveChange, nonInteractive: isNonInteractive && !isInteractive, platformOpts, fromStep: fromStepValue, answersSpec: continueAnswers })
   }
 
   // --done

package/src/run/complete.js

@@ -161,7 +161,34 @@ export function synthesizeStepOutput({ stageName, stepName, cwd, platformOpts =
   return `【CLI 合成】步骤「${stepName}」完成${windowNote}；门禁以本次 CLI 校验输出为准（方案取舍等语义说明需 --output 手写）`
 }
 
+/**
+ * --done 心跳可观测 wrapper（FR-03 / dsh z2 实证：verify 纯文档步骤 --done 静默挂起 >5 分钟，
+ * agent 无从分辨在跑还是死锁）：收口链（单步 --done 与阶段完成门全链）超过 60s 时每 60s 打一行
+ * stderr 进度行——stdout 保持纯净（--json envelope 消费方 JSON.parse(stdout) 不被污染）；结束
+ * （任意 return/throw）finally 清理，interval unref（命令中断不残留定时器）。常规 <60s 路径
+ * 零输出零行为变化；intervalMs 可注入供测试。
+ */
+export async function withDoneHeartbeat(label, fn, { intervalMs = 60_000 } = {}) {
+  let beats = 0
+  const hb = setInterval(() => {
+    beats += 1
+    console.error(`⏳ ${label} 收口链仍在执行（已约 ${Math.round((beats * intervalMs) / 1000)}s）——实测门/探针/同步可能较慢；持续超 5 分钟可用 sillyspec flow status / progress show 旁路核对状态（非死锁判定）`)
+  }, intervalMs)
+  hb.unref?.()
+  try {
+    return await fn()
+  } finally {
+    clearInterval(hb)
+  }
+}
+
 export async function completeStep(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
+  return withDoneHeartbeat(`${stageName} --done`,
+    () => _completeStepInner(pm, progress, stageName, cwd, outputText, inputText, options),
+    { intervalMs: options.heartbeat?.intervalMs })
+}
+
+async function _completeStepInner(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   const { printNext = true, confirm = false, changeName, platformOpts = {}, nonInteractive = false, isForceBaseline = false, isAllowNew = false, isAllowDelete = false, isNoDocs = false, isSkipApply = false, sessionFlag = null, quickFiles = [], linkedChanges = [], linkedChangesAuto = [] } = options
   // specRoot(平台) > specDriftAnchor(worktree 漂移锚定主仓) > cwd/.sillyspec(本地)——
   // 与 prompt.js resolvePromptSpecBase 同序：--done 收尾的 user-inputs.md/超长 artifact 落盘
@@ -697,8 +724,16 @@ export async function completeStep(pm, progress, stageName, cwd, outputText, inp
     // 批量保持单步推进（亲测步照 noAI 硬门走）——「批量省的是上下文往返，不省任何门」承诺恢复成立。
     // 判定经 hasPendingVerifyScanStep：DB 步骤行只有 {name,status}（_cliAction 不持久化——评审
     // P1 修复：初版直接读 s._cliAction 恒 false 死代码），按 stageRegistry 定义索引对齐判。
+    // 资格先行（2026-10-21-verify-reuse-large-repo FR-02）：isVerifyBatchEligible 纯判定（只查
+    // 不改）先于亲测——批量不会触发时（报告未就绪/锚定步未过）中间步 --done 不再预跑整轮实测
+    // （dsh 0ff6f1c8 取证：step 3/4/5 各烧一轮 10~13.5 分钟全量实测只为随后单步推进）。资格成立
+    // 时行为不变：先亲测后批量；detectVerifyBatchFinish 内部全量复检不消费本判定，无 TOCTOU。
     let _skipBatch = false
-    if (hasPendingVerifyScanStep(stageName, steps)) {
+    const _batchEligible = isVerifyBatchEligible({ changeName, specBase, steps })
+    if (!_batchEligible.eligible && hasPendingVerifyScanStep(stageName, steps)) {
+      console.log(`   ℹ️ 批量对齐未就绪（${_batchEligible.reason}）——亲测归质量扫描步与收口门，本步不预跑`)
+    }
+    if (_batchEligible.eligible && hasPendingVerifyScanStep(stageName, steps)) {
       try {
         const { executeVerifyQualityScan } = await import('./verify-quality-scan.js')
         console.log('   🧪 批量对齐面含 noAI 亲测步——先亲测（幂等，有记录秒回）…')
@@ -1372,6 +1407,12 @@ function prefetchDiffFileSet(ctx) {
  * @returns {Promise<object|undefined>} 末轮 completeStep 返回值
  */
 export async function completeStepBurst(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
+  return withDoneHeartbeat(`${stageName} --done(burst)`,
+    () => _completeStepBurstInner(pm, progress, stageName, cwd, outputText, inputText, options),
+    { intervalMs: options.heartbeat?.intervalMs })
+}
+
+async function _completeStepBurstInner(pm, progress, stageName, cwd, outputText, inputText = null, options = {}) {
   if (outputText) console.log(`📦 burst 收口摘要：${outputText}`)
   let roundOptions = { ...options, printNext: false }
   // burst 单调时钟基准（坑 stage-burst ①）：null=首轮（用真实时刻），此后每轮保严格递增
@@ -1735,24 +1776,42 @@ export function hasPendingVerifyScanStep(stageName, steps) {
   }
 }
 
-export function detectVerifyBatchFinish({ changeName, specBase, steps }) {
-  if (!changeName) return { batched: false, aligned: 0 }
+/**
+ * 批量资格纯判定（2026-10-21-verify-reuse-large-repo FR-02，从 detectVerifyBatchFinish 抽出）：
+ * 只查不改（不 mutating 步骤状态）——verify --done 批量对齐块用它做「预跑亲测」的前置闸：
+ * 资格不成立时中间步 --done 不预跑 executeVerifyQualityScan（实测归亲测步自身与收口门；
+ * dsh 0ff6f1c8 取证：报告未就绪的每个中间步 --done 都整轮实测 10~13.5 分钟纯浪费）。
+ * 判据与 detectVerifyBatchFinish 逐字同源（那边消费本函数，理由串不变）。
+ */
+export function isVerifyBatchEligible({ changeName, specBase, steps }) {
+  if (!changeName) return { eligible: false, reason: '无 changeName' }
   try {
     const changeDir = join(specBase, 'changes', changeName)
     const reportPath = join(changeDir, 'verify-result.md')
-    if (!existsSync(reportPath)) return { batched: false, aligned: 0, reason: 'verify-result.md 缺席（报告未写不批量）' }
+    if (!existsSync(reportPath)) return { eligible: false, reason: 'verify-result.md 缺席（报告未写不批量）' }
     const report = readFileSync(reportPath, 'utf8')
     if (!/结论枚举[：:]\s*`?\s*(PASS WITH NOTES|PASS|FAIL)/.test(report)) {
-      return { batched: false, aligned: 0, reason: '结论枚举未填（待填占位不批量）' }
+      return { eligible: false, reason: '结论枚举未填（待填占位不批量）' }
     }
     if (!existsSync(join(changeDir, 'verify-facts.json'))) {
-      return { batched: false, aligned: 0, reason: 'verify-facts.json 缺席（探针未跑不批量）' }
+      return { eligible: false, reason: 'verify-facts.json 缺席（探针未跑不批量）' }
     }
-    const firstPendingIdx = steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress')
-    if (firstPendingIdx === -1) return { batched: false, aligned: 0, reason: '无剩余 step' }
+    const firstPendingIdx = (steps || []).findIndex(s => s.status === 'pending' || s.status === 'in-progress')
+    if (firstPendingIdx === -1) return { eligible: false, reason: '无剩余 step' }
     if (firstPendingIdx < 2) {
-      return { batched: false, aligned: 0, reason: '锚定步未过（step 1-2 须逐步完成，语义锚定不批量）' }
+      return { eligible: false, reason: '锚定步未过（step 1-2 须逐步完成，语义锚定不批量）' }
     }
+    return { eligible: true }
+  } catch (e) {
+    return { eligible: false, reason: `批量资格判定异常（fail-open 不批量）：${e && e.message ? e.message : e}` }
+  }
+}
+
+export function detectVerifyBatchFinish({ changeName, specBase, steps }) {
+  if (!changeName) return { batched: false, aligned: 0 }
+  const pre = isVerifyBatchEligible({ changeName, specBase, steps })
+  if (!pre.eligible) return { batched: false, aligned: 0, reason: pre.reason }
+  try {
     const now = new Date().toLocaleString('zh-CN', { hour12: false })
     let aligned = 0
     for (const step of steps) {
@@ -2041,6 +2100,31 @@ export async function waitStep(pm, progress, stageName, cwd, outputText, waitRea
     return
   }
 
+  // ── --wait --json（2026-10-21-protocol-tax task-04 / FR-04）──
+  // stdout 输出唯一一个可 JSON.parse 的对象（问询+选项结构化，agent 直连 ask_user_question，
+  // 免解析长文本）；退出码与文本模式一致（成功 0）。仅非盖章路径——--inherit-from 保持文本契约
+  //（盖章路径无问询语义，JSON 化无对象可给）。
+  if (options.waitJson && !inheritFrom) {
+    let waitOptionList = []
+    try {
+      const raw = stageData.steps[currentIdx].waitOptions
+      if (raw) waitOptionList = JSON.parse(raw)
+    } catch { /* 解析失败按无选项处理——JSON 面宁缺勿错 */ }
+    console.log(JSON.stringify({
+      ok: true,
+      command: 'wait',
+      change: changeName || null,
+      stage: stageName,
+      step: currentIdx + 1,
+      stepName: stageData.steps[currentIdx].name,
+      question: outputText || waitReason || null,
+      reason: waitReason || null,
+      options: (Array.isArray(waitOptionList) ? waitOptionList : []).map((o) => ({ label: String(o), description: '' })),
+      resumeCommand: `sillyspec run ${stageName} --continue --answer "你的选择"${changeName ? ` --change ${changeName}` : ''}`,
+    }))
+    return
+  }
+
   console.log(`⏸️  Step ${currentIdx + 1}/${stageData.steps.length} 已暂停等待：${stageData.steps[currentIdx].name}`)
   if (waitReason) console.log(`   原因：${waitReason}`)
   if (waitOptions) console.log(`   选项：${formatWaitOptions(waitOptions)}`)
@@ -2057,8 +2141,36 @@ export async function waitStep(pm, progress, stageName, cwd, outputText, waitRea
   }
 }
 
+/**
+ * --answers 批量回填键值解析（2026-10-21-protocol-tax task-04 / FR-04）。
+ * 形态：k1=v1,k2=v2；值含逗号用引号 k="v,含逗号"（引号包裹段内逗号不切分，引号字符本身不保留）。
+ * 纯函数：解析失败返回 null（调用方 exit 2）；空键/空值/无等号 token 均视为格式错。
+ */
+function parseAnswersSpec(spec) {
+  const parts = []
+  let cur = ''
+  let inQuote = false
+  for (const ch of String(spec)) {
+    if (ch === '"') { inQuote = !inQuote; continue }
+    if (ch === ',' && !inQuote) { parts.push(cur); cur = ''; continue }
+    cur += ch
+  }
+  parts.push(cur)
+  const pairs = []
+  for (const p of parts) {
+    const t = p.trim()
+    const eq = t.indexOf('=')
+    if (!t || eq <= 0) return null
+    const key = t.slice(0, eq).trim()
+    const value = t.slice(eq + 1).trim()
+    if (!key || !value) return null
+    pairs.push({ key, value })
+  }
+  return pairs.length > 0 ? pairs : null
+}
+
 export async function continueStep(pm, progress, stageName, cwd, answer, options = {}) {
-  const { changeName, platformOpts = {}, fromStep } = options
+  const { changeName, platformOpts = {}, fromStep, answersSpec = null } = options
   const specBase = platformOpts.specRoot || join(cwd, '.sillyspec')
   const stageData = progress.stages[stageName]
 
@@ -2067,16 +2179,75 @@ export async function continueStep(pm, progress, stageName, cwd, answer, options
     process.exit(1)
   }
 
-  if (!answer) {
-    console.error('❌ --continue 需要 --answer 参数')
+  // --answers 格式错 fail-fast（先于幂等分支：格式错是用法错误，与等待态无关——
+  // 幂等放行的是「合法调用但无等待对象」，不是「任何调用都吞」）
+  if (answersSpec != null && parseAnswersSpec(answersSpec) == null) {
+    console.error('❌ --answers 格式无法解析（期望 k1=v1,k2=v2 形态，值含逗号用引号 k="v,含逗号"）')
     process.exit(2) // 用法错 → exit 2
   }
 
   // 查找 waiting 的步骤
   const waitingSteps = stageData.steps.map((s, i) => ({ ...s, idx: i })).filter(s => s.status === 'waiting')
+  // ── 幂等 no-op（2026-10-21-protocol-tax task-05 / FR-05）──
+  // 无 waiting 步骤时 --continue 从 exit=1 报错改为 exit 0 + 指引行：会话考古（z1）实证
+  // 4 次「无等待步骤」失败全部来自 agent 在两次 --wait 之间干活后的链式防御写法误撞——
+  // 等待态不存在本身不是协议错误，失败化只迫使 agent 多一轮试错。答案不落盘（无对象可回填）。
   if (waitingSteps.length === 0) {
-    console.error(`没有处于等待状态的步骤（阶段 ${stageName} 当前无 waiting 步骤，--continue 无目标）。当前阶段状态：${stageData?.status ?? '未知'}。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
-    process.exit(1)
+    console.log(`ℹ️ 当前无等待中的步骤，--continue 幂等跳过（${answersSpec != null ? '--answers 未回填任何答案' : '--answer 未落盘'}）。用 \`sillyspec run ${stageName} --status\` 查看进度，或 \`sillyspec progress show\` 看全局下一步。`)
+    const firstActive = stageData.steps.findIndex(s => s.status === 'pending' || s.status === 'in-progress' || s.status === 'blocked')
+    const firstPending = stageData.steps.findIndex(s => s.status === 'pending')
+    return { stageCompleted: false, currentIdx: firstActive, nextPendingIdx: firstPending }
+  }
+
+  // 有 waiting 步骤时 answer 仍是必填（用法错 exit 2）——放在幂等分支之后：裸 --continue
+  // 无等待对象时幂等放行（FR-05），有等待对象时缺答案照旧硬拦（回填语义不容空答案）。
+  if (!answer && answersSpec == null) {
+    console.error('❌ --continue 需要 --answer 参数（批量回填用 --answers k1=v1,k2=v2）')
+    process.exit(2) // 用法错 → exit 2
+  }
+
+  // ── --answers 批量回填（2026-10-21-protocol-tax task-04 / FR-04）──
+  // 一次调用回填多个 waiting 步骤：k=步骤名或 1-based 序号，值含逗号用引号 k="v,含逗号"。
+  // 契约：全键命中才动状态——任一键未命中/重复命中同一 步骤，整单拒绝 exit 1 并列出可用键
+  //（禁止部分回填：半程状态比一次可重试的失败更难收拾）。
+  // 实现：校验通过后按序号升序逐个递归单答路径（--from-step <序号> + --answer），记录/回当前步
+  // 语义/收尾 gate/回放全部复用单答实现——批路径不复制状态机逻辑。
+  if (answersSpec != null) {
+    const pairs = parseAnswersSpec(answersSpec)
+    if (!pairs) {
+      console.error('❌ --answers 格式无法解析（期望 k1=v1,k2=v2 形态，值含逗号用引号 k="v,含逗号"）')
+      process.exit(2) // 用法错 → exit 2
+    }
+    if (answer) {
+      console.error('❌ --answers 与 --answer 互斥（批量回填与单步回答是两条路径，不要同时给）')
+      process.exit(2)
+    }
+    const targets = []
+    const unmatched = []
+    for (const { key, value } of pairs) {
+      const idx = /^\d+$/.test(key)
+        ? parseInt(key, 10) - 1
+        : stageData.steps.findIndex(s => s.name === key)
+      const step = idx >= 0 ? stageData.steps[idx] : null
+      if (!step || step.status !== 'waiting' || targets.some(t => t.idx === idx)) unmatched.push(key)
+      else targets.push({ idx, value })
+    }
+    if (unmatched.length > 0) {
+      console.error(`❌ --answers 键未命中等待中的步骤：${unmatched.join('、')}——整单拒绝，未回填任何步骤。`)
+      console.error(`   可用键（步骤名或 1-based 序号）：${waitingSteps.map(ws => `${ws.idx + 1}="${ws.name}"`).join('、')}`)
+      process.exit(1)
+    }
+    console.log(`📦 --answers 批量回填开始：${targets.length} 个等待步骤（升序逐个回填）`)
+    let lastResult = null
+    for (const t of [...targets].sort((a, b) => a.idx - b.idx)) {
+      lastResult = await continueStep(pm, progress, stageName, cwd, t.value, {
+        ...options,
+        answersSpec: null,
+        fromStep: String(t.idx + 1),
+      })
+    }
+    console.log(`📦 --answers 批量回填完成：${targets.length} 步`)
+    return lastResult
   }
 
   // --from-step 支持在多个 waiting 时指定恢复哪一个（避免被迫 --reset 破坏性重置）。