@cfitsec/dsh-ast-guard 0.0.0-stage → 2.0.0

package/lib/daemon.js

@@ -0,0 +1,185 @@
+// 常驻 PowerShell 解析器的客户端：启动、握手、请求、超时、崩溃后重启。
+//
+// 为什么常驻：实测每命令起一个解释器要 1,130 ms，常驻后每命令 0.8 ms。
+// 进程活着就用，死了就按需重启；重启失败达到上限就进入降温，避免刷屏式重启。
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const DEFAULT_SCRIPT = path.join(HERE, 'ast-daemon.ps1')
+
+export class AstDaemon {
+  constructor(options = {}) {
+    this.script = options.script ?? DEFAULT_SCRIPT
+    this.powershell = options.powershell ?? 'powershell.exe'
+    this.timeoutMs = options.timeoutMs ?? 5000
+    this.maxRestarts = options.maxRestarts ?? 3
+    this.restartCooldownMs = options.restartCooldownMs ?? 30000
+    this.logger = options.logger ?? null
+
+    this.child = null
+    this.readyPromise = null
+    this.pending = new Map()
+    this.buffer = ''
+    this.seq = 0
+    this.restarts = 0
+    this.stopped = false
+    this.lastFailure = null
+  }
+
+  get running() {
+    return this.child !== null && this.child.exitCode === null && !this.child.killed
+  }
+
+  start() {
+    if (this.running) return this.readyPromise
+    if (this.stopped) return Promise.reject(new Error('daemon 已关闭'))
+
+    this.buffer = ''
+    const child = spawn(this.powershell, [
+      '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', this.script,
+    ], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
+    this.child = child
+
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk) => this.#onData(chunk))
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk) => {
+      const text = String(chunk).trim()
+      if (text !== '') this.logger?.warn?.(`ast-guard: 解析器 stderr：${text.slice(0, 400)}`)
+    })
+    child.on('error', (error) => this.#onExit(child, error))
+    child.on('exit', (code) => this.#onExit(child, new Error(`解析器进程退出（code ${code}）`)))
+
+    // 三道保险，任何一条路径退出都不能把这孩子留成孤儿 ——
+    // 它一旦继承着宿主的管道句柄活下来，调用方会一直等那个句柄关闭。
+    if (this.exitHook === undefined) {
+      this.exitHook = () => { try { this.child?.kill() } catch { /* 已经没了 */ } }
+      process.once('exit', this.exitHook)
+    }
+
+    this.readyPromise = new Promise((resolve, reject) => {
+      this.readyResolve = resolve
+      this.readyReject = reject
+      setTimeout(() => reject(new Error('解析器启动超时')), Math.max(this.timeoutMs, 10000)).unref?.()
+    })
+    return this.readyPromise
+  }
+
+  #onData(chunk) {
+    this.buffer += chunk
+    let index
+    while ((index = this.buffer.indexOf('\n')) >= 0) {
+      const line = this.buffer.slice(0, index).trim()
+      this.buffer = this.buffer.slice(index + 1)
+      if (line === '') continue
+
+      let message
+      try { message = JSON.parse(line) } catch {
+        // 解析不了的行 = 响应被换行截断了，或解析器吐了别的东西。丢掉会变成静默超时，所以必须喊。
+        this.logger?.warn?.(`ast-guard: 解析器输出无法解析（前 200 字符）：${line.slice(0, 200)}`)
+        continue
+      }
+
+      if (message.ready === true) {
+        this.restarts = 0
+        this.readyResolve?.()
+        continue
+      }
+      const entry = this.pending.get(message.id)
+      if (entry === undefined) continue
+      this.pending.delete(message.id)
+      clearTimeout(entry.timer)
+      entry.resolve(message)
+    }
+  }
+
+  #onExit(child, error) {
+    // 迟到的通知：老进程退出时新进程可能已经起来了。不认这一条，
+    // 否则会把新进程的引用清成 null 并误拒它的就绪承诺（实测就栽在这）。
+    if (child !== undefined && child !== this.child) return
+    this.lastFailure = error
+    this.logger?.warn?.(`ast-guard: ${error.message}`)
+    for (const [, entry] of this.pending) {
+      clearTimeout(entry.timer)
+      entry.reject(error)
+    }
+    this.pending.clear()
+    this.readyReject?.(error)
+    this.readyResolve = undefined
+    this.readyReject = undefined
+    this.readyPromise = null
+    this.child = null
+  }
+
+  async parse(command) {
+    return this.#send({ command })
+  }
+
+  /**
+   * 别名对账：问 PowerShell 自己"这名字是什么、别名指向谁"。
+   * 规则文件里的别名表必须和这个结果一致 —— 2026-09-22 凭记忆写漏过 ri / rm，
+   * 所以把它变成可以自动核对的东西，而不是靠谁记得。
+   */
+  async recon(names, aliasesOf = []) {
+    return this.#send({ recon: { names, aliasesOf } })
+  }
+
+  async #send(payload) {
+    if (this.stopped) throw new Error('daemon 已关闭')
+    if (!this.running) {
+      if (this.restarts >= this.maxRestarts) {
+        throw new Error(`解析器重启次数超过上限（${this.maxRestarts}），暂停使用`)
+      }
+      this.restarts += 1
+      await this.start()
+    } else if (this.readyPromise !== null) {
+      await this.readyPromise
+    }
+
+    const id = ++this.seq
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        // 一条请求卡住 = 后面全部排队，守卫会因此把所有 pwsh 都拒掉。
+        // 所以直接把这个进程判死：exit 会拒掉其余在途请求，下次调用重新拉起。
+        try { this.child?.kill() } catch { /* 已经没了 */ }
+        reject(new Error(`解析请求超时（${this.timeoutMs} ms）；该进程已判死，下次调用会重启`))
+      }, this.timeoutMs)
+      timer.unref?.()
+      this.pending.set(id, { resolve, reject, timer })
+      this.child.stdin.write(JSON.stringify({ id, ...payload }) + '\n')
+    })
+  }
+
+  stop() {
+    this.stopped = true
+    if (this.child !== null) {
+      try { this.child.stdin.end() } catch { /* 进程可能已经没了 */ }
+      try { this.child.kill() } catch { /* 同上 */ }
+    }
+    this.child = null
+  }
+}
+
+// 进程级单例。解析器是**无状态**的（一问一答，按 id 配对），所以跨插件实例共享完全安全。
+//
+// 为什么必须共享（2026-09-23 实测）：宿主会**反复调用 apply()**，每次新建一个 AstDaemon
+// —— 结果是同一个宿主底下挂着两个 powershell 进程（一个漏着不释放，另一个每次重建），
+// 而且每次重建都要付一次约 700 ms 的进程启动。做成单例之后不管上层怎么反复 apply，
+// 都是一个进程。
+//
+// ⚠️ 共享的东西**不能由某个实例的 dispose 关掉** —— 那会把别人的解析器一起弄没。
+// 所以这里只在进程退出时收尾，不提供 stop()。
+let shared = null
+
+export function sharedDaemon(options = {}) {
+  if (shared === null) {
+    shared = new AstDaemon(options)
+    process.once('exit', () => {
+      try { shared?.stop() } catch { /* 可能已经在关了 */ }
+    })
+  }
+  return shared
+}

package/lib/deliberate.js

@@ -0,0 +1,275 @@
+// 三思层：在「有正当用途、但代价高」的动作前插一道冷却期。
+//
+// 语义（用户 2026-09-22 定，逐条照做）：
+//   - 拦截时给出完整的语法树摘要
+//   - 冷却期 x 秒（可配，**不低于 10**）：这段时间内**任何回答 —— 是或否 —— 都无效**
+//   - 窗口内的回答会被拒，并告诉还剩几秒，同时提醒反复回看"这是不是我的本意"
+//   - 只有 ≥ x 秒之后的回答才有效
+//   - 确认是**一次性**的，绑定到那一条具体命令（规范化后的哈希），过期作废
+//
+// 时钟是注入的：测试可以把时间直接推快，不用真等 10 秒。
+import { createHash, randomBytes } from 'node:crypto'
+
+export const MIN_COOLDOWN_SECONDS = 10
+
+/** 待确认项的编号：短、随机、每次拦截都换一个。 */
+export function newPendingId() {
+  return randomBytes(3).toString('hex')
+}
+
+export function canonicalCommand(text) {
+  return String(text ?? '').replace(/\r\n/g, '\n').trim()
+}
+
+export function commandHash(text) {
+  return createHash('sha256').update(canonicalCommand(text), 'utf8').digest('hex').slice(0, 16)
+}
+
+// PowerShell 允许无歧义前缀（`-Rec` 就是 `-Recurse`），所以按"参数是规范标志的前缀"判，
+// 与 PowerShell 自己的规则一致。歧义由规则作者承担：只列它真在意的标志。
+export function flagMatches(arg, flag) {
+  const bare = String(arg).toLowerCase().replace(/:.*$/, '')
+  if (bare.length < 2 || !bare.startsWith('-')) return false
+  // ⚠️ 裸 `--` 是"选项结束"标记，不是标志。不排掉它，`--` 会成为**所有** `--xxx` 的前缀
+  // （`--hard` / `--force` / `--delete` 全中）—— 2026-10-10 实测：`git checkout -- <单个文件>`
+  // 因此被误判成"范围收缩"，而对照组要求它必须放行。
+  if (bare === '--') return false
+  return flag.startsWith(bare)
+}
+
+/** 取值型全局选项：它们的**下一个参数是值**，不是位置参数。
+ *  `git -C <仓库> checkout -- .` 的第一个位置参数是**仓库路径**，不是 `checkout` ——
+ *  而带上 `-C` 正是 2026-10-10 那次事故的写法（`git -C $proj checkout -- .`），
+ *  不跳过就整条规则失效。 */
+const GLOBAL_OPTIONS_WITH_VALUE = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env'])
+
+function firstPositional(args) {
+  // ⚠️ 从 **1** 开始：daemon 给的形状是 `["git","reset","--hard"]` —— **args[0] 是命令名本身**。
+  // 2026-10-10 实测踩到：不跳它会取到 `git` 而不是 `reset`，于是整个 `subcommands` 维度
+  // 是哑的（10-03 加的注册表规则只靠 paths 那一半在工作，而当时没给语法树层写过用例）。
+  // 规则里列的子命令都不会等于命令名，所以无条件跳第一个是安全的。
+  for (let index = 1; index < args.length; index++) {
+    const arg = String(args[index])
+    if (GLOBAL_OPTIONS_WITH_VALUE.has(arg)) { index++; continue }
+    if (arg.startsWith('-')) continue
+    return arg
+  }
+  return undefined
+}
+
+/**
+ * 一条 when 条件：**组内各维是 OR**（命中任一维，这条条件就算成立），返回命中的理由。
+ * 这是"与"的零件 —— 2026-10-10 加。起因：`git checkout -b x`（建分支，无害）与
+ * `git checkout -- .`（丢整棵树）**只差一个参数**，一组条件分不开，必须两组相与。
+ */
+export function matchCondition(condition, args) {
+  const reasons = []
+  const subcommands = Array.isArray(condition.subcommands) ? condition.subcommands : []
+  const argsExact = Array.isArray(condition.argsExact) ? condition.argsExact : []
+  const flags = Array.isArray(condition.flags) ? condition.flags : []
+  const paths = Array.isArray(condition.paths) ? condition.paths : []
+  const argsContain = Array.isArray(condition.argsContain) ? condition.argsContain : []
+
+  // 子命令：第一个位置参数（跳过取值型全局选项，见上）。
+  // `reg add`、`git checkout` 这类外部命令的参数形态解析器认不出来，位置参数就是它的子命令。
+  // 取法是防御式的：规则对象可能是别处手写的（离线工具），缺某一维按空处理。
+  if (subcommands.length > 0) {
+    const first = firstPositional(args)
+    if (first !== undefined && subcommands.includes(String(first).toLowerCase())) reasons.push(`子命令 ${String(first)}`)
+  }
+
+  for (const arg of args) {
+    const text = String(arg)
+    if (argsExact.length > 0 && argsExact.includes(text)) reasons.push(`参数 ${text}`)
+    for (const flag of flags) if (flagMatches(text, flag)) reasons.push(`带标志 ${text}`)
+    if (condition.wildcard === true && /[*?]/.test(text)) reasons.push(`通配 ${text}`)
+    for (const needle of paths) if (text.includes(needle)) reasons.push(`落在受保护位置 ${text}`)
+    for (const needle of argsContain) if (text.toLowerCase().includes(needle.toLowerCase())) reasons.push(`参数含 ${needle}`)
+  }
+  return reasons
+}
+
+/**
+ * 按效应判：命中命令名之后，还要看参数里有没有真的踩到"贵"的那一面。
+ * 规则没写 when 就是按命令名，一律三思。
+ * when.all（2026-10-10 加）= **合取**：列表里每组条件都必须成立；没写 all 就是单组，行为同以前。
+ */
+export function evaluateDeliberate(rule, facts) {
+  const hits = []
+  for (const command of facts.commands ?? []) {
+    const name = String(command.name ?? '')
+    // 同 rules.js：命令词可能是**全路径**，裸名匹配会漏 ⇒ 连 basename 一起比。
+    const named = name.toLowerCase()
+    const base = named.split(/[\\/]/).pop()
+    if (!rule.commands.has(named) && !rule.commands.has(base)) continue
+    const args = Array.isArray(command.args) ? command.args : []
+    const shown = args.join(' ') || name
+
+    if (rule.when === null) {
+      hits.push({ command: shown, reasons: ['规则没有限定效应条件，按命令名触发'] })
+      continue
+    }
+
+    const conditions = Array.isArray(rule.when.all) ? rule.when.all : [rule.when]
+    const reasons = []
+    let allMatched = true
+    for (const condition of conditions) {
+      const part = matchCondition(condition, args)
+      if (part.length === 0) { allMatched = false; break }
+      reasons.push(...part)
+    }
+    if (allMatched && reasons.length > 0) hits.push({ command: shown, reasons })
+  }
+  return hits
+}
+
+export class DeliberateDesk {
+  /**
+   * pendingTtlMs 是刻意的短：忘了的待确认项必须自己烂掉。
+   * 否则"很久之后顺手 confirm 一下"就会批准一条早就忘了的危险命令。
+   */
+  constructor({ now = () => Date.now(), confirmWindowMs = 60000, pendingTtlMs = 120000 } = {}) {
+    this.now = now
+    this.confirmWindowMs = confirmWindowMs
+    this.pendingTtlMs = pendingTtlMs
+    this.pendings = new Map()
+    this.grants = new Map()
+  }
+
+  static key(sessionId, hash) {
+    return `${sessionId}\u0000${hash}`
+  }
+
+  /**
+   * 三态：allow-once（有效的一次性放行被消费）/ deliberate（拦截，进冷却）/ null（本层无意见）
+   */
+  check({ sessionId, command, facts, rules }) {
+    const hash = commandHash(command)
+    const grantKey = DeliberateDesk.key(sessionId, hash)
+    const grant = this.grants.get(grantKey)
+    const now = this.now()
+
+    if (grant !== undefined) {
+      if (grant.used || grant.expiresAt <= now) this.grants.delete(grantKey)
+      else {
+        grant.used = true
+        this.grants.delete(grantKey)
+        return { action: 'allow-once', ruleId: grant.ruleId }
+      }
+    }
+
+    for (const rule of rules.deliberate) {
+      const hits = evaluateDeliberate(rule, facts)
+      if (hits.length === 0) continue
+      const pending = {
+        id: newPendingId(),
+        sessionId,
+        hash,
+        rule,
+        hits,
+        command: canonicalCommand(command),
+        requestedAt: now,
+        readyAt: now + rule.cooldownSeconds * 1000,
+      }
+      this.pendings.set(sessionId, pending)
+      return { action: 'deliberate', pending }
+    }
+    return null
+  }
+
+  /** none / live / expired —— 区分开才能给出"该重发命令了"这种有用的拒绝理由。 */
+  stateFor(sessionId) {
+    const pending = this.pendings.get(sessionId)
+    if (pending === undefined) return { status: 'none' }
+    const ageMs = this.now() - pending.requestedAt
+    if (ageMs > this.pendingTtlMs) {
+      this.pendings.delete(sessionId)
+      return { status: 'expired', ageMs, command: pending.command }
+    }
+    return { status: 'live', pending }
+  }
+
+  /**
+   * 智能体来回答。三道门，缺一不可：
+   *   ① 待确认项还活着（过期即作废，防"忘了之后顺手确认"）
+   *   ② 编号对得上（**不接受不带编号的"是"** —— 那是意外确认的唯一入口）
+   *   ③ 冷却期已满（窗口内是或否都无效）
+   */
+  confirm({ sessionId, id, decision, command }) {
+    const state = this.stateFor(sessionId)
+
+    if (state.status === 'none') {
+      return { ok: false, reason: 'no-pending', message: '这个会话当前没有等待确认的三思命令。' }
+    }
+
+    if (state.status === 'expired') {
+      return {
+        ok: false,
+        reason: 'expired',
+        message: [
+          `这次确认被拒：那条命令是 ${Math.round(state.ageMs / 1000)} 秒前拦下的，`,
+          `已经超过等待上限（${Math.round(this.pendingTtlMs / 1000)} 秒），自动作废了。`,
+          '作废是故意的 —— 免得你在很久之后顺手确认一条自己已经忘了的危险命令。',
+          '',
+          '真要执行它，把那条命令重新发一次：会重新拦截、重新走一遍冷却期。',
+        ].join('\n'),
+      }
+    }
+
+    const pending = state.pending
+    if (typeof id !== 'string' || id !== pending.id) {
+      return {
+        ok: false,
+        reason: 'wrong-id',
+        message: [
+          '这次确认被拒：编号对不上。',
+          `当前待确认的编号是 ${pending.id}；你给的是 ${id === undefined ? '（没给）' : JSON.stringify(id)}。`,
+          '不带编号的"是"一律无效 —— 这是为了挡住"顺手确认一条自己已经忘了的命令"。',
+          '',
+          '待确认的命令：',
+          ...pending.command.split('\n').map((line) => `  ${line}`),
+        ].join('\n'),
+      }
+    }
+
+    if (command !== undefined && commandHash(command) !== pending.hash) {
+      return {
+        ok: false,
+        reason: 'mismatch',
+        message: '你附带的命令原文和待确认的那条对不上。待确认的是：\n  ' + pending.command,
+      }
+    }
+
+    const now = this.now()
+    const remainingMs = pending.readyAt - now
+    if (remainingMs > 0) {
+      return {
+        ok: false,
+        reason: 'too-early',
+        remainingSeconds: Math.ceil(remainingMs / 1000),
+        pending,
+      }
+    }
+
+    this.pendings.delete(sessionId)
+    if (decision !== 'yes') {
+      return { ok: true, decision: 'no', message: '已放弃，这条命令不会被放行。' }
+    }
+
+    const expiresAt = now + this.confirmWindowMs
+    this.grants.set(DeliberateDesk.key(sessionId, pending.hash), {
+      ruleId: pending.rule.id,
+      approvedAt: now,
+      expiresAt,
+      used: false,
+    })
+    return {
+      ok: true,
+      decision: 'yes',
+      expiresAt,
+      ruleId: pending.rule.id,
+      id: pending.id,
+      command: pending.command,
+    }
+  }
+}

package/lib/evidence.js

@@ -0,0 +1,121 @@
+// 三思窗口的「要丢什么」—— 规则里声明的只读探针，由守卫自己跑，结果打进窗口。
+//
+// 为什么必须有这一层（2026-10-10 事故征候「回退范围扩张」）：
+//   `git checkout -- .` 这行字**看起来完全无害**，它甚至不含路径。
+//   决定"要不要停"的信息不在命令里，在**工作区状态**里 ——
+//   那次是 `?? src/lab/`：两个文件、644 行、**从未提交**，而 reflog 只记 HEAD 移动过的东西，
+//   对"从未提交的文件"没有任何记录，丢了就没有第二处。
+//   报告 §5.3/§6.2 的结论：**加多少条规则都拦不住那次，除非窗口里带上这个清单。**
+//
+// 三条硬约束：
+//   ① **只跑规则文件里写死的命令**，不是模型给的 —— 探针的命令文本不经过任何外部输入；
+//   ② 只读、带超时、失败就如实说（不许让探针把守卫拖死，也不许假装拿到数据）；
+//   ③ 数字**由命令算出来**，守卫自己不估（报告原话："不许守卫自己估"）。
+import { spawn } from 'node:child_process'
+
+const MAX_LINES_PER_PROBE = 14
+const DEFAULT_TIMEOUT_MS = 2500
+
+function runOnce(command, cwd, timeoutMs) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(command, { cwd, shell: true, windowsHide: true })
+    } catch (error) {
+      resolve({ ok: false, text: `没能启动：${error.message}` })
+      return
+    }
+    let out = ''
+    let err = ''
+    let settled = false
+    const finish = (result) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(result)
+    }
+    const timer = setTimeout(() => {
+      try { child.kill() } catch { /* 已经结束了 */ }
+      finish({ ok: false, text: `超过 ${timeoutMs} ms 没返回，已终止` })
+    }, timeoutMs)
+    child.stdout?.on('data', (chunk) => { out += chunk })
+    child.stderr?.on('data', (chunk) => { err += chunk })
+    child.on('error', (error) => finish({ ok: false, text: `没能启动：${error.message}` }))
+    child.on('close', (code) => {
+      const text = (out.trim() !== '' ? out : err).trim()
+      finish({ ok: code === 0, text: text === '' ? '（无输出）' : text })
+    })
+  })
+}
+
+/** 把探针输出算成一句账 —— 数字全部来自命令本身，守卫不加不减。 */
+function accountFor(byProbe) {
+  // ⚠️ 只有**真跑成功**的输出才算数：报错文本和"（无输出）"这种占位符不许混进账里 ——
+  // 否则它们会被当成文件名数进去（2026-10-10 实测：账上写着"1 个未跟踪文件：（无输出）"）。
+  const raw = (probe) => {
+    const result = byProbe[probe]
+    return result !== undefined && result.ok === true ? result.text : ''
+  }
+  const porcelain = raw('git status --porcelain')
+  const others = raw('git ls-files --others --exclude-standard')
+  const shortstat = raw('git diff --shortstat HEAD').trim()
+  if (porcelain === '' && others === '' && shortstat === '') return []
+
+  const untracked = others.split('\n').map((line) => line.trim()).filter((line) => line !== '')
+  const tracked = porcelain
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !line.startsWith('??'))
+  const account = []
+  if (tracked.length > 0) {
+    account.push(`将丢弃 ${tracked.length} 个已跟踪文件的改动（${shortstat === '' ? '行数见上' : shortstat}）—— **可从 HEAD 恢复**`)
+  }
+  if (untracked.length > 0) {
+    const head = untracked.slice(0, 6).join(' / ')
+    account.push(`${untracked.length} 个未跟踪文件 —— **从未提交，reflog 救不回**：${head}${untracked.length > 6 ? ` …共 ${untracked.length} 个` : ''}`)
+  }
+  if (account.length === 0) account.push('工作区看起来是干净的：没有未提交内容会因这一下丢掉')
+  return ['', '▶ 按上面探针算出来的账：', ...account.map((line) => `   ${line}`)]
+}
+
+/**
+ * 跑规则里声明的探针，返回可直接塞进窗口的文本行。
+ * probes：规则里的 `evidence:` 列表；cwds：会话 cwd + 命令里 `-C <路径>` 指向的仓库。
+ */
+export async function collectEvidence({ probes, cwds, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const lines = []
+  const list = Array.isArray(probes) ? probes.filter((item) => typeof item === 'string' && item.trim() !== '') : []
+  const dirs = [...new Set((cwds ?? []).filter((dir) => typeof dir === 'string' && dir.trim() !== ''))]
+  if (list.length === 0 || dirs.length === 0) return lines
+
+  for (const cwd of dirs) {
+    lines.push(`── 只读探针（守卫自己跑的，工作目录 ${cwd}）`)
+    const byProbe = {}
+    for (const probe of list) {
+      const result = await runOnce(probe, cwd, timeoutMs)
+      byProbe[probe] = result
+      const all = result.text.split('\n')
+      for (const line of all.slice(0, MAX_LINES_PER_PROBE)) lines.push(`   ${line}`)
+      // 硬截断：`git diff` 在非仓库目录里会打**整篇 usage**（几百行），不截会把窗口灌满。
+      if (all.length > MAX_LINES_PER_PROBE) lines.push(`   …（这条输出还有 ${all.length - MAX_LINES_PER_PROBE} 行，为免灌满窗口已省略）`)
+      if (result.ok !== true) lines.push('   （这条没跑成，下面只按拿到的算）')
+    }
+    lines.push(...accountFor(byProbe))
+  }
+  return lines
+}
+
+/**
+ * 探针在哪儿跑：命令里 `-C <路径>` 指向的仓库；没有才用会话 cwd。
+ * ⚠️ 有 `-C` 时**只跑那个仓库** —— 会话 cwd 多半不是 git 仓库，在那儿跑探针只会拿到
+ * git 的 usage 长文（2026-10-10 实测：那一坨把窗口灌满，而真正有用的三行在另一个目录里）。
+ */
+export function evidenceCwds(cwd, facts) {
+  const fromDashC = []
+  for (const command of facts?.commands ?? []) {
+    const args = Array.isArray(command.args) ? command.args.map((item) => String(item)) : []
+    const at = args.indexOf('-C')
+    if (at >= 0 && args[at + 1] !== undefined) fromDashC.push(args[at + 1].replace(/^["']|["']$/g, ''))
+  }
+  return fromDashC.length > 0 ? [...new Set(fromDashC)] : [cwd]
+}