sillyspec 3.26.14 → 3.27.1

package/src/taskcard.js

@@ -14,7 +14,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { git } from './git-helper.js'
 import { assertSafeChangeName, resolveSpecDir } from './run/shared.js'
-import { parseTaskNames } from './stages/plan.js'
+import { parseTaskNames, readTaskRegistryContent } from './stages/plan.js'
+import { parseTaskRegistry } from './stages/execute.js'
 
 /**
  * 任务号归一：接受 task-01 / task-1 / 01 / 1，统一为 task-NN（两位补零，与任务卡文件名一致）。
@@ -52,21 +53,44 @@ function yamlScalar(v) {
  * 字符串只含 \n：writeFileSync 直写不经任何行尾转换，Windows 下天然 LF 安全。
  * title/title_zh/author 经 yamlScalar 转义（自由文本防 YAML 指示符炸解析）。
  *
- * @param {{ taskId: string, title: string, titleZh: string, author: string, now: string }} p
+ * @param {{ taskId: string, title: string, titleZh: string, author: string, now: string,
+ *           dependsOn?: string[], sets?: Record<string,string> }} p
+ *   dependsOn：tasks.md 行内注解反填（坑 taskcard-design-field-conflicts，2026-08-21 实证）——
+ *     "(depends_on: task-01,02)" 注解由 CLI 解析进 frontmatter，省主代理逐卡裁决
+ *   sets：--set key=value 覆盖（yamlScalar 转义；仅覆盖已存在的标量键，防注入任意结构）
  * @returns {string}
  */
-export function buildTaskcardSkeleton({ taskId, title, titleZh, author, now }) {
+export function buildTaskcardSkeleton({ taskId, title, titleZh, author, now, dependsOn = [], sets = {} }) {
+  const fm = {
+    id: taskId,
+    title: yamlScalar(title),
+    title_zh: yamlScalar(titleZh),
+    author: yamlScalar(author),
+    created_at: now,
+    priority: 'P0',
+    depends_on: (Array.isArray(dependsOn) && dependsOn.length > 0)
+      ? `[${dependsOn.map(d => `'${d}'`).join(', ')}]`
+      : '[]',
+    blocks: '[]',
+    requirement_ids: '[FR-XX]',
+    decision_ids: '[D-XXX@vN]',
+  }
+  // --set 覆盖（白名单键 + yamlScalar 转义值；depends_on 数组形态单独拼不进标量 map，跳过）
+  const SETTABLE_KEYS = new Set(['id', 'title', 'title_zh', 'author', 'priority', 'created_at', 'requirement_ids', 'decision_ids', 'blocks', 'goal'])
+  for (const [k, v] of Object.entries(sets || {})) {
+    if (SETTABLE_KEYS.has(k)) fm[k] = yamlScalar(v)
+  }
   return `---
-id: ${taskId}
-title: ${yamlScalar(title)}
-title_zh: ${yamlScalar(titleZh)}
-author: ${yamlScalar(author)}
-created_at: ${now}
-priority: P0
-depends_on: []
-blocks: []
-requirement_ids: [FR-XX]
-decision_ids: [D-XXX@vN]
+id: ${fm.id}
+title: ${fm.title}
+title_zh: ${fm.title_zh}
+author: ${fm.author}
+created_at: ${fm.created_at}
+priority: ${fm.priority}
+depends_on: ${fm.depends_on}
+blocks: ${fm.blocks}
+requirement_ids: ${fm.requirement_ids}
+decision_ids: ${fm.decision_ids}
 allowed_paths:
   - src/example/file.ts
 goal: >
@@ -105,7 +129,7 @@ constraints:
  * @returns {{ created: string[], skipped: string[], tasksDir: string }}
  */
 export function cmdTaskcard(changeName, opts = {}) {
-  const { cwd, specDir = null, taskIds, title = null, titleZh = null, force = false } = opts
+  const { cwd, specDir = null, taskIds, title = null, titleZh = null, force = false, sets = {} } = opts
   assertSafeChangeName(changeName, '变更名')
 
   const changeDir = join(resolveSpecDir(cwd, { specDir }), 'changes', changeName)
@@ -114,25 +138,27 @@ export function cmdTaskcard(changeName, opts = {}) {
   }
 
   // 任务注册表 tasks.md（2026-08-20-task-truth-unify 唯一真相；CRLF 归一后解析，
-  // --all 时强依赖）。tasks.md 缺失回退 plan.md（旧归档变更兼容读侧）
-  let planTasks = []
+  // --all 时强依赖）。tasks.md 缺失回退 plan.md（旧归档变更兼容读侧）。
+  // parseTaskRegistry（坑 taskcard-design-field-conflicts，2026-08-21）：除编号/标题外还带出
+  // 行内注解（[model:xxx] / (depends_on: task-01,02)）——depends_on 直接反填进骨架 frontmatter。
+  let registry = []
   const tasksMdPath = join(changeDir, 'tasks.md')
   const planPath = join(changeDir, 'plan.md')
   const registryPath = existsSync(tasksMdPath) ? tasksMdPath : planPath
   if (existsSync(registryPath)) {
     const registryContent = readFileSync(registryPath, 'utf8').replace(/\r\n/g, '\n')
-    planTasks = parseTaskNames(registryContent)
+    registry = parseTaskRegistry(registryContent)
   }
 
   let ids
   if (taskIds === 'all') {
-    if (planTasks.length === 0) {
+    if (registry.length === 0) {
       throw new Error(
         `--all 需要 tasks.md 中存在 checkbox 任务行（格式 "- [ ] task-XX: 任务名"）` +
         (existsSync(registryPath) ? '，当前任务清单未解析到任何任务行' : '，且变更目录下未找到 tasks.md/plan.md')
       )
     }
-    ids = planTasks.map(t => `task-${t.num}`)
+    ids = registry.map(t => t.id)
   } else if (Array.isArray(taskIds) && taskIds.length > 0) {
     ids = taskIds
   } else {
@@ -161,9 +187,9 @@ export function cmdTaskcard(changeName, opts = {}) {
   const created = []
   const skipped = []
   for (const id of ids) {
-    const planMatch = planTasks.find(t => `task-${t.num}` === id)
-    const finalTitle = title || (planMatch ? planMatch.name : null) || `${id} fill-english-title`
-    const finalTitleZh = titleZh || (planMatch ? planMatch.name : null) || finalTitle
+    const reg = registry.find(t => t.id === id)
+    const finalTitle = title || (reg ? reg.name : null) || `${id} fill-english-title`
+    const finalTitleZh = titleZh || (reg ? reg.name : null) || finalTitle
     const filePath = join(tasksDir, `${id}.md`)
     if (existsSync(filePath) && !force) {
       skipped.push(filePath)
@@ -171,6 +197,10 @@ export function cmdTaskcard(changeName, opts = {}) {
     }
     writeFileSync(filePath, buildTaskcardSkeleton({
       taskId: id, title: finalTitle, titleZh: finalTitleZh, author, now,
+      // depends_on 从 tasks.md 行内注解反填（坑 taskcard-design-field-conflicts）：注册表
+      // 注解与 plan/design 的依赖声明同源，骨架直接带上省主代理逐卡转录
+      dependsOn: reg ? reg.dependsOn : [],
+      sets,
     }), 'utf8')
     created.push(filePath)
   }

package/src/verify-postcheck.js

@@ -60,6 +60,104 @@ export function extractTestCommand(yamlText) {
   return null
 }
 
+/**
+ * 从 local.yaml 文本提取 commands.lint（2026-08-21 审查 CLI-1：lint 对账）。
+ * 与 extractTestCommand 同风格同容错（带引号/不带引号/unavailable）。
+ * 模块内私有（runVerifyLintCheck 消费；extractTestCommand 系 export 供 test）。
+ */
+function extractLintCommand(yamlText) {
+  if (!yamlText) return null
+  const doubleQuoted = yamlText.match(/^\s*lint:\s*"([^"]+)"\s*(?:#.*)?$/m)
+  const singleQuoted = yamlText.match(/^\s*lint:\s*'([^']+)'\s*(?:#.*)?$/m)
+  const quoted = doubleQuoted || singleQuoted
+  if (quoted && quoted[1]) {
+    return quoted[1].toLowerCase() === 'unavailable' ? null : quoted[1].trim()
+  }
+  const bare = yamlText.match(/^\s*lint:\s*([^\n#"']+?)\s*(?:#.*)?$/m)
+  if (bare && bare[1]) {
+    const cmd = bare[1].trim()
+    return cmd.toLowerCase() === 'unavailable' ? null : cmd
+  }
+  return null
+}
+
+/**
+ * verify --done 实测跑 local.yaml commands.lint（2026-08-21 审查 CLI-1）。
+ * 此前 lint 全靠 agent 自跑自报（"我跑过 lint 了"纯口头），与 test 侧的对账不对称——
+ * agent 偷懒漏跑时格式债被推迟到用户 commit 才被 pre-commit hook 炸出。
+ * advisory 起步：失败只打印不阻断（test 门已 fail-closed，lint 门观察期后再升级）。
+ * 信任边界与 runVerifyTestCheck 一致：命令只来源于主仓 .sillyspec/local.yaml。
+ */
+export function runVerifyLintCheck({ cwd, specBase }) {
+  const localYamlPath = join(specBase, 'local.yaml')
+  const yamlText = existsSync(localYamlPath) ? readFileSync(localYamlPath, 'utf8') : null
+  const command = extractLintCommand(yamlText)
+
+  if (!command) {
+    return {
+      status: 'skipped',
+      command: null,
+      exitCode: null,
+      durationMs: null,
+      outputTail: null,
+      reason: yamlText
+        ? 'local.yaml 未配置 commands.lint（或标记 unavailable）'
+        : `local.yaml 不存在（${localYamlPath}）`,
+    }
+  }
+
+  const LINT_TIMEOUT_MS = Number(process.env.SILLYSPEC_LINT_TIMEOUT_MS) || 3 * 60 * 1000
+  const startedAt = Date.now()
+  let exitCode = 0
+  let output = ''
+  let reason = null
+  try {
+    output = execSync(command, {
+      cwd,
+      encoding: 'utf8',
+      timeout: LINT_TIMEOUT_MS,
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+  } catch (e) {
+    exitCode = typeof e.status === 'number' ? e.status : 1
+    output = [e.stdout, e.stderr].filter(Boolean).join('\n') || e.message
+    reason = e.signal === 'SIGTERM' && Date.now() - startedAt >= LINT_TIMEOUT_MS
+      ? `lint 命令超时（>${LINT_TIMEOUT_MS / 1000}s）`
+      : `lint 命令退出码 ${exitCode}`
+  }
+  const durationMs = Date.now() - startedAt
+  const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
+
+  return {
+    status: exitCode === 0 ? 'passed' : 'failed',
+    command,
+    exitCode,
+    durationMs,
+    outputTail,
+    reason: exitCode === 0 ? null : reason,
+  }
+}
+
+/** 打印 lint 实测结果（advisory：失败不阻断，只把口头汇报对上账） */
+export function printVerifyLintCheck(result) {
+  if (result.status === 'skipped') {
+    console.warn(`\n⚠️  Verify lint 实测跳过：${result.reason}`)
+    return
+  }
+  if (result.status === 'passed') {
+    console.log(`\n✅ Verify lint 实测通过：\`${result.command}\` 退出码 0（${(result.durationMs / 1000).toFixed(1)}s）`)
+    return
+  }
+  console.error(`\n⚠️  Verify lint 实测失败（advisory，不阻断本次完成）：\`${result.command}\` — ${result.reason}`)
+  console.error('   agent 的 lint 自报告与实测不符时以实测为准；请修复后重跑，避免格式债推迟到 commit 被 pre-commit hook 拦截。')
+  if (result.outputTail) {
+    const tail = result.outputTail.split('\n').slice(-15).join('\n')
+    console.error('   输出（末尾）：')
+    for (const line of tail.split('\n')) console.error(`   | ${line}`)
+  }
+}
+
 /**
  * 从 local.yaml 文本提取顶层 test_strategy。
  * 轻量正则（与 extractTestCommand 同风格，不引 yaml 依赖）。
@@ -207,15 +305,30 @@ export function pickHitModules(changedFiles, modules) {
 
   const files = changedFiles.map(f => String(f).replace(/\\/g, '/'))
   const hits = []
+  const looseHits = []
   for (const [name, mod] of Object.entries(modules)) {
     if (!mod || !mod.path) continue
     const modPath = String(mod.path).replace(/\\/g, '/')
     const prefix = modPath.endsWith('/') ? modPath : modPath + '/'
     // path 本身被改 或 path/ 下任意文件被改
     const hit = files.some(f => f === modPath || f.startsWith(prefix))
-    if (hit) hits.push({ name, path: modPath, test: mod.test })
+    if (hit) { hits.push({ name, path: modPath, test: mod.test }); continue }
+    // 宽松段匹配 fallback（坑 module-path-layout-mismatch，2026-08-22 实证：pnpm monorepo
+    // 常见 packages/frontend 布局 vs modules 配 frontend/ 前缀——严格前缀 0 命中时按
+    // 「路径段等于模块首段」兜底（packages/frontend/src/x → 命中 frontend），多测不漏测。
+    // 首段去斜杠后比对，防 frontend-guide 之类前缀误蹭）
+    const firstSeg = prefix.split('/')[0]
+    if (firstSeg && files.some(f => ('/' + f + '/').includes('/' + firstSeg + '/'))) {
+      looseHits.push({ name, path: modPath, test: mod.test, looseMatch: true })
+    }
   }
-  return hits
+  // 严格命中优先；全部严格 0 命中才用宽松兜底（并 warn 可见——宽松规则可能多命中）
+  if (hits.length > 0) return hits
+  if (looseHits.length > 0) {
+    console.warn(`⚠️ 模块命中用宽松段匹配（modules path 前缀与 diff 布局不一致，如 packages/<name> vs <name>/）：命中 ${looseHits.map(h => h.name).join(', ')}——建议 local.yaml modules 的 path 对齐实际目录布局`)
+    return looseHits
+  }
+  return []
 }
 
 /**
@@ -360,6 +473,7 @@ function runOneModule(name, testCommand, cwd, knownFailures = []) {
   let exitCode = 0
   let output = ''
   let reason = null
+  warnPortRaceBeforeRun(testCommand)
   try {
     output = execSync(testCommand, {
       cwd,
@@ -374,6 +488,10 @@ function runOneModule(name, testCommand, cwd, knownFailures = []) {
     reason = e.signal === 'SIGTERM' && Date.now() - startedAt >= TEST_TIMEOUT_MS
       ? `模块 ${name} 测试超时（>${TEST_TIMEOUT_MS / 1000}s）`
       : `模块 ${name} 测试退出码 ${exitCode}`
+    // 资源竞争鉴别提示（坑 verify-devserver-port-race，同 runFullCommand）
+    if (/EADDRINUSE|address already in use|端口.*被占用|port.*already/i.test(output)) {
+      reason += '。⚠️ 输出含端口占用信号（EADDRINUSE）——极可能是与你自留 dev server 的资源竞争而非代码问题：停掉占用服务后重跑 verify 再定论'
+    }
   }
   const durationMs = Date.now() - startedAt
   const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
@@ -475,9 +593,35 @@ function gitChangedFiles(cwd) {
  * @param {object|null} [ctx] - MultiRepoContext 实例（可选，缺省/null 走单仓原逻辑）
  * @returns {string[]|null} 变更文件列表；git 不可用返回 null（调用方按 hitCount=-1 处理）
  */
-export function resolveVerifyChangedFiles(cwd, changeName, ctx = null) {
+export function resolveVerifyChangedFiles(cwd, changeName, ctx = null, opts = {}) {
+  const { includeWorkingTree = false } = opts
   // 主仓 diff（原逻辑不动，单仓零回归）
-  const mainFiles = resolveMainChangedFiles(cwd, changeName)
+  let mainFiles = resolveMainChangedFiles(cwd, changeName)
+
+  // 并入 worktree 未提交改动（坑 module-subset-zero-hit-uncommitted，2026-08-21 实证：
+  // 子代理默认不 commit，真实改动全在 worktree working-tree——只看 base..HEAD commit diff
+  // 时 module 映射 0 命中直接跳过（frontend/** 变更未命中 frontend 模块）。与
+  // generateTaskReviewDrafts 的并入口径同源：meta.worktreePath 下 status --porcelain 文件
+  // （排除 .sillyspec/ 运行时产物）。opt-in（默认关）：d drafts 有自己的并入点，避免双并。
+  if (includeWorkingTree && mainFiles !== null) {
+    try {
+      const metaPath = join(cwd, '.sillyspec', '.runtime', 'worktrees', changeName, 'meta.json')
+      if (changeName && existsSync(metaPath)) {
+        const meta = JSON.parse(readFileSync(metaPath, 'utf8'))
+        const wtGitDir = (meta.worktreePath && meta.mode !== 'in-place-fallback' && existsSync(meta.worktreePath))
+          ? meta.worktreePath
+          : cwd
+        const wtStatus = gitQuiet(wtGitDir, ['status', '--porcelain'], { timeout: 30000, trim: false })
+        const wtFiles = String(wtStatus || '').split('\n')
+          .map(l => l.slice(3).trim().split(' -> ').pop() || '')
+          .map(p => p.replace(/^"|"$/g, '').replace(/\\/g, '/'))
+          .filter(p => p && p !== '.sillyspec' && !p.startsWith('.sillyspec/'))
+        if (wtFiles.length > 0) {
+          mainFiles = [...new Set([...(mainFiles || []), ...wtFiles])]
+        }
+      }
+    } catch { /* working-tree 并入失败退回 commit diff 口径（fail-open） */ }
+  }
 
   // 无 ctx / ctx 无跨仓 entry → 主仓 diff 即结果（零回归）
   if (!ctx || typeof ctx.repos !== 'object' || ctx.repos === null) return mainFiles
@@ -581,11 +725,15 @@ export function runVerifyTestCheck({ cwd, specBase, changeName = null, ctx = nul
   let modulesPresent = false
   let hitCount = 0
   let hits = []
+  let lastChangedFiles = [] // 0 命中诊断用（diff 文件样例可见性，坑 module-path-layout-mismatch）
   if (strategy === 'module') {
     const modules = extractModules(yamlText)
     if (modules) {
       modulesPresent = true
-      const changedFiles = resolveVerifyChangedFiles(cwd, changeName)
+      // includeWorkingTree（坑 module-subset-zero-hit-uncommitted）：子代理不 commit 的改动
+      // 也参与 module 命中判定，0 命中跳过不再误伤 worktree 未提交的真实变更
+      const changedFiles = resolveVerifyChangedFiles(cwd, changeName, null, { includeWorkingTree: true })
+      lastChangedFiles = Array.isArray(changedFiles) ? changedFiles : []
       if (changedFiles === null) {
         hitCount = -1 // git 不可用 / 非仓库
       } else {
@@ -602,13 +750,24 @@ export function runVerifyTestCheck({ cwd, specBase, changeName = null, ctx = nul
   } else if (action === 'module-zero-hit-skip') {
     // module 模式 0 命中：不静默回退注定超时/含预存失败的全量（坑 verify-worktree-... 修复方向 3）。
     // 据 verify-result.md 自报告判定；想跑全量请显式设 test_strategy: full。
+    // 诊断可见性（坑 module-path-layout-mismatch，2026-08-22 实证：0 命中「靠第一次跑过的
+    // 记录兜底」——为何没命中完全黑箱）：落 modules 配置 path vs diff 文件样例，配置前缀
+    // 对不上（如 packages/frontend vs frontend/）一眼可见
+    const modules_ = extractModules(yamlText) || {}
+    const diagLines = [
+      `已配置 modules（${Object.keys(modules_).length} 个）: ${Object.entries(modules_).map(([k, m]) => `${k}→${m.path}`).join('、') || '（无）'}`,
+      `本次 diff（${lastChangedFiles.length} 个文件，前 5）: ${lastChangedFiles.slice(0, 5).join(', ') || '（空）'}`,
+    ]
+    console.warn(`⚠️ 模块 0 命中诊断（对照 path 前缀与 diff 布局是否一致，如 packages/<name> vs <name>/）：`)
+    for (const l of diagLines) console.warn(`   ${l}`)
     mainResult = {
       status: 'skipped',
       command: null,
       exitCode: null,
       durationMs: null,
       outputTail: null,
-      reason: 'test_strategy: module 但本次变更未命中任何已配置 modules（0 命中）。为避免回退到注定超时/含预存失败的全量 commands.test，CLI 未自动跑全量——据 verify-result.md 自报告判定测试。若需全量覆盖，显式设 test_strategy: full。',
+      reason: 'test_strategy: module 但本次变更未命中任何已配置 modules（0 命中）。为避免回退到注定超时/含预存失败的全量 commands.test，CLI 未自动跑全量——据 verify-result.md 自报告判定测试。若需全量覆盖，显式设 test_strategy: full。' +
+        ` 诊断：${diagLines.join('；')}`,
       resultPath: null,
       mode: 'module-zero-hit',
       fallbackReason: null,
@@ -794,6 +953,53 @@ function mergeResultInfo(mainResult, crossResults) {
 /**
  * 全量跑 commands.test（现有逻辑，brownfield 行为不变）。
  */
+/**
+ * 从测试命令文本提取疑似服务端口（坑 verify-devserver-port-race，2026-08-22 实证：CLI 全量
+ * 对账与用户自留 dev server 资源竞争——端口被占导致测试失败，差点误报 FAIL 成代码问题）。
+ * 认 --port=N / --port N / PORT=N。
+ * @param {string} cmd
+ * @returns {number[]}
+ */
+function extractPortsFromCommand(cmd) {
+  const s = String(cmd || '')
+  const ports = new Set()
+  for (const m of s.matchAll(/--port[=\s]+(\d{2,5})/gi)) ports.add(Number(m[1]))
+  for (const m of s.matchAll(/\bPORT=(\d{2,5})/gi)) ports.add(Number(m[1]))
+  return [...ports]
+}
+
+/**
+ * 端口占用探测（同步 spawnSync node 试连——verify 实测是同步 execSync 流，无法 await）。
+ * @param {number} port
+ * @returns {boolean} true=已被占用（疑似自留 dev server/长驻服务在跑）
+ */
+function isPortOccupiedSync(port) {
+  try {
+    const { spawnSync } = require('node:child_process')
+    const r = spawnSync(process.execPath, ['-e',
+      `const n=require('node:net');const s=n.connect(${port},'127.0.0.1',()=>{console.log('Y');s.end()});s.on('error',()=>console.log('N'));setTimeout(()=>{console.log('N');process.exit(0)},1500)`],
+      { encoding: 'utf8', timeout: 4000 })
+    return (r.stdout || '').trim().endsWith('Y')
+  } catch { return false }
+}
+
+/**
+ * 实测前资源竞争预警（坑 verify-devserver-port-race）：测试命令涉及的端口已被占用 →
+ * 显著 warn「疑似自留 dev server」+ 建议停服务重跑——防把资源竞争误判成代码问题报 FAIL。
+ * best-effort：探测失败静默。
+ */
+function warnPortRaceBeforeRun(command) {
+  try {
+    const ports = extractPortsFromCommand(command)
+    for (const p of ports) {
+      if (isPortOccupiedSync(p)) {
+        console.warn(`⚠️ 端口 ${p} 已被占用（测试命令 ${command.slice(0, 50)}… 引用）——疑似你自留的 dev server/长驻服务。`)
+        console.warn(`   测试若因此失败（端口冲突/EADDRINUSE），是资源竞争而非代码问题——停掉占用服务（或换端口）后重跑 verify 再定论，勿直接报 FAIL。`)
+      }
+    }
+  } catch { /* 探测失败不阻断实测 */ }
+}
+
 function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName, fallbackReason = null, knownFailures = [] }) {
   const command = extractTestCommand(yamlText)
 
@@ -817,6 +1023,7 @@ function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName, fa
   let exitCode = 0
   let output = ''
   let reason = null
+  warnPortRaceBeforeRun(command)
   try {
     output = execSync(command, {
       cwd,
@@ -831,6 +1038,11 @@ function runFullCommand({ yamlText, localYamlPath, cwd, specBase, changeName, fa
     reason = e.signal === 'SIGTERM' && Date.now() - startedAt >= TEST_TIMEOUT_MS
       ? `测试命令超时（>${TEST_TIMEOUT_MS / 1000}s）`
       : `测试命令退出码 ${exitCode}`
+    // 资源竞争鉴别提示（坑 verify-devserver-port-race）：EADDRINUSE/端口占用类失败极可能是
+    // 自留 dev server 竞争而非代码问题——输出里明示鉴别路径，防误报 FAIL
+    if (/EADDRINUSE|address already in use|端口.*被占用|port.*already/i.test(output)) {
+      reason += '。⚠️ 输出含端口占用信号（EADDRINUSE）——极可能是与你自留 dev server 的资源竞争而非代码问题：停掉占用服务后重跑 verify 再定论'
+    }
   }
   const durationMs = Date.now() - startedAt
   const outputTail = output.length > OUTPUT_TAIL_CHARS ? '…' + output.slice(-OUTPUT_TAIL_CHARS) : output
@@ -873,6 +1085,11 @@ function runModuleSubset({ cwd, specBase, changeName, hits, knownFailures = [] }
   const reason = status === 'passed'
     ? null
     : `模块子集测试失败：${perModule.filter(r => r.status === 'failed').map(r => r.name).join(', ')}`
+      // 失败模块的 reason 明细透传（坑 verify-devserver-port-race：EADDRINUSE 资源竞争鉴别
+      // 提示在 runOneModule 的 reason 里，不透传会被顶层 reason 吞掉）
+      + (perModule.filter(r => r.status === 'failed' && r.reason).some(r => /EADDRINUSE|资源竞争/.test(r.reason))
+        ? '。' + perModule.filter(r => r.status === 'failed' && r.reason && /EADDRINUSE|资源竞争/.test(r.reason)).map(r => r.reason).join('；')
+        : '')
 
   const result = {
     status,