thincoder 0.12.61 → 0.12.63

package/src/token-ttl.mjs

@@ -1,274 +0,0 @@
-/**
- * token-ttl.mjs — design-token TTL 语义 + 槽位清理 + 会话槽权威台账 I/O（R16——2026-09-06；
- * DESIGN-TOKEN-SETTLEMENT D1-D3——2026-09-08）。
- *
- * 共享目标（D-R16b）：过期判定语义在此定义一次，validateDesignToken
- * （agent-tools/design-token.mjs）、恢复过滤（session.mjs applySession）、开模式清理
- * （agent-tools/eng.mjs + tui/cmd-eng.mjs ON 路径）、spawn 门禁过期拒删槽
- * （subagent-spawn.mjs）共引。
- *
- * token 格式 = `uuid:expiresAt`（无签名流程凭证——HMAC 防伪层已删——见
- * ENGINEERING-MODE.md 2026-09-06 段）。过期判定只对**格式合法**的 token 判
- * 过期：格式/畸形串不在此清理（恢复时读回由门禁格式拒、门禁拒时也不删槽——
- * 防误删有效槽——F-R16b ①③）。
- *
- * DESIGN-TOKEN-SETTLEMENT（2026-09-08）：
- * - **D1**：persistEngTokens = settle 当场落盘的可复用函数（engTokenSlotFields 序列化 +
- *   session 安全写/轮转——guardForeignSlotFile 与 saveSession 共用同一份守卫）。
- * - **D2/D3**：readEngTokensFromSlot / reconcileEngTokensFromSlot = 门禁 miss 回读权威
- *   槽（spawn 门 D2 与 dispatch 写门 D3 同源 reconcile）。
- * - **D3**：**单值镜像 `_engDesignToken` 退役**——AC3 零写 + 仅一次性迁移读。本模块
- *   不再写镜像（engTokenSlotFields 只产多槽表）；restoreEngTokens 是唯一迁移读点（旧
- *   slot 残留 engDesignToken → 迁入 Map，此后不写不读镜像）。
- *
- * 依赖方向：本模块只 import 底层槽 I/O（session-slots.mjs 原语 + session-guard.mjs 轮转
- * 守卫）——session.mjs 同时 import 本模块（engTokenSlotFields/restoreEngTokens），形成
- * 静态环，与既有的 session ↔ session-slots 环同构（函数声明实例化期已初始化、只函数体
- * 内运行时使用——环安全）。
- */
-
-import { existsSync, readFileSync, statSync } from "node:fs"
-import {
-  slotPath, writeSessionFile, activeSlot, loadManifest, saveManifest, slotDigest,
-  writeEndMarker,
-} from "./session-slots.mjs"
-// F2 轮转守卫自 2026-09-08 迁至 session-guard.mjs（session-slots 再越 500 行硬限拆分）
-import { guardForeignSlotFile } from "./session-guard.mjs"
-
-const DESIGN_TOKEN_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
-
-/** 格式校验 + 数值过期时刻：格式合法 → expiresAt 数值；格式/畸形 → null
- *  （与 validateDesignToken 的 fail-closed 判定同源——单一权威）。 */
-export function tokenExpiryMs(token) {
-  if (!token || typeof token !== "string") return null
-  const parts = token.split(":")
-  if (parts.length !== 2) return null
-  const [uuid, expiresAt] = parts
-  if (!DESIGN_TOKEN_UUID_RE.test(uuid)) return null
-  if (!/^\d+$/.test(expiresAt)) return null
-  const expiry = parseInt(expiresAt, 10)
-  if (isNaN(expiry)) return null
-  return expiry
-}
-
-/** 过期判定——仅格式合法的 token 可判过期（畸形 → false，由门禁格式拒）。 */
-export function tokenExpired(token, now = Date.now()) {
-  const expiry = tokenExpiryMs(token)
-  return expiry !== null && now > expiry
-}
-
-/** 删一个 designId 槽（R16 D-R16c ③——spawn 门禁过期拒的清理面）。
- *  条件由调用方保证（槽在位且槽值 === token 且已过期）：Map 无该 id / 值不符 →
- *  不删（防误删有效槽）；designId 缺省（单槽省略 designId 路径）→ 按 token 扫删。
- *  DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像已退役——不再同步清镜像。
- *  返回是否删了槽。 */
-export function removeDesignTokenSlot(agent, designId, token) {
-  const map = agent?._engDesignTokens
-  let slotRemoved = false
-  if (map instanceof Map && token) {
-    if (designId) {
-      if (map.get(designId) === token) {
-        map.delete(designId)
-        slotRemoved = true
-      }
-    } else {
-      for (const [id, t] of map) {
-        if (t === token) {
-          map.delete(id)
-          slotRemoved = true
-          break
-        }
-      }
-    }
-  }
-  return slotRemoved
-}
-
-/** 遍历删过期槽（R16 F-R16b ②——eng enter / cmd-eng ON 真转换路径）：Map 只留
- *  有效 token。DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像已退役——无
- *  legacy 镜像分支。返回清理个数。 */
-export function purgeExpiredDesignTokens(agent) {
-  const map = agent?._engDesignTokens
-  let cleared = 0
-  if (map instanceof Map) {
-    for (const [id, t] of [...map]) {
-      if (typeof t === "string" && tokenExpired(t)) {
-        map.delete(id)
-        cleared++
-      }
-    }
-  }
-  return cleared
-}
-
-// ── 会话槽序列化/恢复面（session.mjs saveSession/applySession 的 token 字段——
-//    2026-09-06 R16：slot 持久化 = 跨重启/跨模式恢复的有意载体） ──
-
-/** saveSession 数据面：token 的序列化形态。多槽 Map → {designId: token}
- *  （JSON-safe）；空/缺 Map → undefined → JSON.stringify 丢 key——清过的会话写
- *  NO field，不从上次 save 复活槽。
- *  DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `engDesignToken` 退役——
- *  saveSession 不再写镜像字段（AC3 零写）；只产多槽表 engDesignTokens。 */
-export function engTokenSlotFields(agent) {
-  return {
-    engDesignTokens: agent._engDesignTokens instanceof Map && agent._engDesignTokens.size > 0
-      ? Object.fromEntries(agent._engDesignTokens)
-      : undefined,
-  }
-}
-
-/** applySession 恢复面（F-R16b ①——恢复 TTL 过滤）：EXPIRED token 不读回（丢弃——
- *  下次 save 自然清字段，清盘闭环）；格式/畸形串读回（门禁拒——不主动删——恢复不
- *  得销毁它无法判定的槽数据）。
- *  DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `_engDesignToken` 退役——
- *  本函数是**唯一镜像迁移读点**（AC3）：旧 slot 文件可能残留 engDesignToken 单值
- *  （D3 前 saveSession 写的 legacy 字段）。当多槽表缺失/为空（Map 空）且残留镜像为
- *  **格式合法且未过期** token 时 → 一次性迁入 Map（标 legacy——以 token 自身 uuid
- *  为 designId——确定性、可复现、不依赖曾回显的原 designId）。此后该字段随下次
- *  saveSession/persistEngTokens（不再写镜像）自然从槽文件消失，本函数不再读到
- *  残留——一次性语义。镜像若已过期/畸形 → 不迁移（drop——与 Map 过期项同处理，
- *  清盘闭环）。永不写 agent._engDesignToken。 */
-export function restoreEngTokens(agent, data) {
-  const map = new Map()
-  if (data.engDesignTokens && typeof data.engDesignTokens === "object" && !Array.isArray(data.engDesignTokens)) {
-    for (const [id, t] of Object.entries(data.engDesignTokens)) {
-      if (!(typeof t === "string" && tokenExpired(t))) map.set(id, t)
-    }
-  }
-  // legacy 单值镜像一次性迁移读（唯一镜像读点——AC3）：Map 空且残留为格式合法未过期 token
-  if (map.size === 0) {
-    const storedMirror = data.engDesignToken
-    if (typeof storedMirror === "string" && tokenExpiryMs(storedMirror) !== null && !tokenExpired(storedMirror)) {
-      map.set(storedMirror.split(":")[0], storedMirror)
-    }
-  }
-  if (map.size > 0) agent._engDesignTokens = map
-  else delete agent._engDesignTokens
-}
-
-// ── 会话槽权威台账 I/O（DESIGN-TOKEN-SETTLEMENT D1/D2/D3——槽文件 = 权威结算台账） ──
-
-/** 当前会话槽号（读侧——无认领副作用）：粘性 _slot 优先；未钉槽时读 manifest active
- *  （loadManifest 只读——不在门禁路径触发认领写）。无槽 → null。 */
-function currentSlotNoReadOnly(agent) {
-  const slot = agent?._slot
-  if (Number.isInteger(slot)) return slot
-  const active = loadManifest(agent?.cwd)?.active
-  return Number.isInteger(active) ? active : null
-}
-
-/** 读当前会话槽文件的权威台账（engDesignTokens 多槽表——不做 TTL 过滤，判定由调用方）。
- *  门禁侧轻读：JSON.parse 只读不改文件（.tmp 回退/改名等 loadSlotFile 副作用不引入）。
- *  单值镜像 engDesignToken 字段已退役——此处不读（AC3——运行时零镜像读；唯一镜像
- *  迁移读在 restoreEngTokens）。返回 {designId: token} 对象或 null（无槽/无文件/不可读）。 */
-export function readEngTokensFromSlot(agent) {
-  try {
-    const slot = currentSlotNoReadOnly(agent)
-    if (slot == null) return null
-    const p = slotPath(agent.cwd, slot)
-    if (!existsSync(p)) return null
-    const data = JSON.parse(readFileSync(p, "utf8"))
-    return (data && typeof data === "object" && !Array.isArray(data.engDesignTokens)
-      && data.engDesignTokens && typeof data.engDesignTokens === "object")
-      ? data.engDesignTokens
-      : null
-  } catch { return null }
-}
-
-/** 内存 miss 时从权威槽 reconcile（D2 spawn 门 + D3 dispatch 写门同源）：把槽文件中
- *  **未过期**项并进内存 Map（TTL 过滤保留——expired 不并入，fail-closed；格式/畸形串
- *  与 restoreEngTokens 同语义读回——门禁格式拒）；槽无活项 → 内存原样。返回判定用 Map。 */
-export function reconcileEngTokensFromSlot(agent) {
-  const slots = agent?._engDesignTokens
-  const obj = readEngTokensFromSlot(agent)
-  if (!obj) return slots instanceof Map ? slots : new Map()
-  const live = new Map()
-  for (const [id, t] of Object.entries(obj)) {
-    if (typeof t === "string" && !tokenExpired(t)) live.set(id, t)
-  }
-  if (live.size === 0) return slots instanceof Map ? slots : new Map()
-  const merged = slots instanceof Map ? slots : new Map()
-  for (const [id, t] of live) merged.set(id, t)
-  agent._engDesignTokens = merged
-  return merged
-}
-
-/** 是否存在任一活槽（DESIGN-TOKEN-SETTLEMENT D3——dispatch 写门判定"任一活槽存在"；
- *  AC4）。先问内存 Map（当前进程活缓存）；miss 回读权威槽文件 reconcile（与 spawn 门
- *  D2 同源）。判定 fail-closed：格式合法且未过期才算活槽（畸形/过期不构成活槽——不
- *  授权产品代码写）。 */
-export function anyLiveDesignSlot(agent) {
-  const live = (m) => {
-    for (const t of m.values()) {
-      if (typeof t === "string" && tokenExpiryMs(t) !== null && !tokenExpired(t)) return true
-    }
-    return false
-  }
-  const m = agent?._engDesignTokens
-  if (m instanceof Map && live(m)) return true
-  const rec = reconcileEngTokensFromSlot(agent)
-  return rec instanceof Map && live(rec)
-}
-
-/**
- * D1（DESIGN-TOKEN-SETTLEMENT，2026-09-08）：settle 当场同步落盘——把当前内存多槽
- * Map 写入会话槽文件的权威台账，消除 settle→回合尾 saveSession 间的重启丢 token 窗口。
- * 复用 engTokenSlotFields 序列化 + session 安全写/轮转（guardForeignSlotFile =
- * saveSession 同一份守卫——勿裸写文件）。槽文件缺失（本会话首次落盘）→ 写最小全新
- * 记录（字段形状同 saveSession——loadSlotFile 可读）；既有文件 → 读-改-写（只动 token
- * 字段，历史等其他字段原样保留）。写失败（writeSessionFile/parse 抛错）→ 抛出/返回
- * false——调用方（settle）失败即 settle 失败（token 不注册、可重评——评审 #1 语义）。
- */
-export function persistEngTokens(agent) {
-  const claimedNow = agent._slot == null
-  const slot = agent._slot ??= activeSlot(agent.cwd)
-  if (claimedNow) writeEndMarker(agent.cwd, slot)
-  const p = slotPath(agent.cwd, slot)
-  guardForeignSlotFile(agent, p, slot)
-  let data = null
-  if (existsSync(p)) {
-    data = JSON.parse(readFileSync(p, "utf8"))
-  } else {
-    // 全新槽（claim 先行、首保存落盘前）——最小记录（VSC newSlotData 同构——字段形状
-    // 同 saveSession 数据面，loadSlotFile 校验可读；历史留空——本会话首保存尚未发生，
-    // 此前历史本就未落盘，token 台账先行落盘不制造任何额外损失）。
-    data = {
-      version: 2,
-      cwd: agent.cwd,
-      title: agent.title ?? "",
-      activeProvider: agent.activeProvider ?? agent.provider?.name,
-      // MODEL-MERGE-SESSION 恒非空形态：随 saveSession 同款回落链（无渠道仍容忍 null）
-      activeModel: agent.activeModel ?? agent.provider?.model ?? null,
-      history: [],
-      contextHistory: [],
-      tasks: agent.tasks ?? [],
-      planMode: agent.planMode ?? false,
-      autoApprove: agent.autoApprove ?? false,
-      engineering: agent.config?.agent?.engineering ?? false,
-      goal: agent.goal ?? null,
-      advisor: agent.config?.advisor ?? null,
-      pendingReminders: agent._pendingReminders ?? [],
-      sessionStart: agent._sessionStart ?? null,
-    }
-  }
-  const fields = engTokenSlotFields(agent)
-  if (fields.engDesignTokens !== undefined) data.engDesignTokens = fields.engDesignTokens
-  else delete data.engDesignTokens
-  // 单值镜像字段永不复写（D3 零写）——残留 engDesignToken 随本次写一并清（更快退役，
-  // 杜绝 stale 镜像 + 空 Map 组合在下次 restore 二次迁移复活死 token 的边角）。
-  delete data.engDesignToken
-  data.updatedAt = Date.now()
-  writeSessionFile(p, data)
-  // 记录我们刚写的 mtime——下次保存/守卫跳过重复解析（saveSession 同款）
-  try { agent._slotMtime = statSync(p).mtimeMs } catch {}
-  // Update slot metadata in manifest（saveSession 同款尾——非致命：数据已安全，
-  // metadata 下次 listSlots 惰性恢复）
-  try {
-    const m = loadManifest(agent.cwd)
-    m.slots[slot] = slotDigest(data)
-    saveManifest(agent.cwd, m)
-  } catch (e) {
-    console.error(`[session] manifest metadata update failed for slot ${slot}: ${e.message}`)
-  }
-  return true
-}

package/src/tools/apply_patch.md

@@ -1,15 +0,0 @@
-Apply a unified diff to one or more files, atomically: if any hunk fails to apply, nothing is written.
-
-**Use it for whole-file and multi-file changes:** creating MULTIPLE new files at once (`--- /dev/null` header per file), whole-file replacement, and cross-file refactors — one unified-diff call covers the whole change. A batched call is one permission ask and one turn instead of N separate calls.
-
-Parameters:
-- patch (required): Unified diff text. One `--- a/path` / `+++ b/path` header pair per file, then `@@ -old,count +new,count @@` hunks. Use `--- /dev/null` to create a new file. The `+++ b/path` pair may be omitted for existing files — a lone `--- a/path` (or `--- b/path`) header followed directly by hunks applies to that path (new files still need `--- /dev/null` + `+++ b/path`).
-
-Notes:
-- Hunk header "@@" without coordinates is accepted. Coordinate-less hunks are located by their anchor lines: context lines plus the removed (-) lines, matched as a contiguous sequence — a unique match applies. The anchor-free forms require context: a hunk with no removed (-) lines (pure additions) needs at least 2 context lines for a unique match; a zero/one-context hunk with at least one removed (-) line is located by its anchor sequence (context + removed lines, in order) and applies on a unique match.
-- Returns the applied-file summary (`Applied patch to N file(s)` plus per-file change lines and syntax-check notes for changed .mjs files)
-- Use this for multi-file changes (e.g. rename an interface + update all callers) — one call, all-or-nothing
-- Hunks are located by their context/removed lines, not line numbers — but the context must match the file EXACTLY. Read the files first and generate the patch from actual content
-- If a hunk's context matches multiple locations it is rejected — add more surrounding context lines
-- Deleting files is not supported — use the delete tool
-- For single-file edits, edit is simpler; for full rewrites, write is simpler

package/src/tools/bash.md

@@ -1,37 +0,0 @@
-Execute a shell command and return stdout+stderr. Use for running commands, builds, tests.
-
-**Route to a dedicated tool instead of bash:**
-- `cat file` / `head` / `tail` → `read`
-- `ls` / `dir` → `ls`
-- `find` / glob search → `glob`
-- `grep` / `rg` → `grep`
-- `echo >` / `sed` / `printf >` / `cat << EOF` → `write` / `edit` / `hashline_edit` / `apply_patch` (preferred: write tools handle encoding/EOL correctly)
-- `git diff` / `git status` / `git log` → `git` tool
-
-Parameters:
-- command (required): Shell command to execute
-- timeout: Timeout in milliseconds (default 120000, max ~300000)
-- filter: Optional — a regex; only output lines matching it are returned (case-insensitive). Use instead of hand-writing a pipe into `findstr`/`grep`.
-
-Output format:
-```
-[stdout]:
-<standard output, or "(empty)">
-
-[stderr]:
-<standard error, only present if non-empty>
-
-(exit code N)
-```
-
-Notes:
-- There is NO TTY — editors, pagers (vim, less), and interactive prompts WILL hang. Always pass non-interactive flags: `git commit -m`, `git --no-pager`, `-y`/`--yes` where applicable
-- The environment sets GIT_PAGER=cat, PAGER=cat, EDITOR=true, TERM=dumb — but still always use non-interactive flags
-- Output is capped at ~200K chars; if you need more, redirect to a file and read it. Truncated output ends with a `[... truncated: N chars omitted]` marker — the missing tail may contain errors, so read the saved log file's tail before trusting success. Use `filter` to narrow instead of hand-piping.
-- Check `[stderr]` for error messages, warnings, and diagnostic output — it is separated from `[stdout]` so you can quickly identify problems.
-- On Windows the shell is **cmd.exe** (NOT Git Bash, NOT PowerShell): `&&`/`||` chaining works, use cmd built-ins (`del`, `dir`, `type`, `findstr`, `tasklist`) and `/dev/null`→`NUL`, `2>/dev/null`→`>nul 2>&1`. Bash-isms (`rm -rf`, `cp -r`, `head`, `$(...)`, `${VAR}`, single quotes, `;` separators) FAIL — the tool prepends a hint when it detects POSIX-only syntax, and still executes. For complex logic prefer the execute tool (node) over shell gymnastics.
-- Never use bash to read, copy, or transmit secret files (.env, keys, tokens)
-- Do NOT run destructive commands (rm -rf, force-push, drop table) without explicit user confirmation
-- After commands that change files (git checkout, npm install, etc.), repo_outline and code_search may be stale — re-run them to get current results.
-- Prefer read/glob/grep/ls for file operations inside the project — file tools and bash reach the same paths (no directory restriction).
-- NEVER use bash to write or modify files (echo/sed/printf > file, cat << EOF, etc.). Use write/edit/insert_after/apply_patch instead — they handle encoding, escaping, and EOL conventions correctly.

package/src/tools/bash.mjs

@@ -1,268 +0,0 @@
-import {
-  DESC,
-  sanitizeOutput,
-  truncate,
-  makeDecoder,
-  BASH_TIMEOUT_MS,
-} from "./shared.mjs";
-import { spawn, execFileSync } from "node:child_process";
-
-/** Maximum buffer size per stream (stdout / stderr) before truncation */
-const MAX_STREAM_BUF = 2_000_000
-
-/** Keep only output lines matching a regex (bash filter, case-insensitive). */
-function applyLineFilter(output, filter) {
-  let re
-  try { re = new RegExp(filter, "i") } catch (e) { return `Error: filter regex invalid: ${e.message}` }
-  const lines = output.split("\n").filter((l) => re.test(l))
-  if (lines.length === 0) return `(no output lines matched filter "${filter}")`
-  return truncate(lines.join("\n"))
-}
-
-/** POSIX-only constructs that cmd.exe reads literally (and thus breaks). Detected
- *  so the agent is told IMMEDIATELY instead of chasing a confusing failure — warning
- *  only, never a block (the approval layer is the real gate, same as destructive-command policy). */
-function posixSyntaxHint(command) {
-  const hits = []
-  if (/\$\([^)]*\)/.test(command)) hits.push("$(...)")
-  if (command.includes("`")) hits.push("backtick")
-  if (/;\s+/.test(command)) hits.push("';' separators (cmd.exe needs && or newline)")
-  if (/2>\s*\/dev\/null|>\s*\/dev\/null|&>\s*\/dev\/null/.test(command)) hits.push("/dev/null (use NUL)")
-  if (/'.*'/.test(command)) hits.push("single quotes (cmd.exe doesn't group)")
-  if (/\$\{[A-Za-z_]/.test(command)) hits.push("${VAR} (use %VAR%)")
-  if (!hits.length) return ""
-  return "[hint: POSIX-only construct(s) detected — " + hits.join(", ") + ". Current shell is cmd.exe; these will NOT work. Use && / NUL / %VAR%, or use the execute tool (node) for complex logic]"
-}
-
-
-// ====================================================================
-// bash — command execution with safety gates
-// ====================================================================
-
-/**
- * Build environment for child process.
- * Passes through all parent env vars, with non-interactive overrides (EDITOR/PAGER/TERM).
- * Sets PYTHONIOENCODING on Windows to override GBK default for Python scripts.
- */
-function buildBashEnv() {
-  const isWindows = process.platform === "win32"
-  return {
-    ...process.env,
-    GIT_EDITOR: "true",
-    EDITOR: "true",
-    VISUAL: "true",
-    GIT_PAGER: "cat",
-    PAGER: "cat",
-    TERM: "dumb",
-    ...(isWindows ? { PYTHONIOENCODING: "utf-8" } : {}),
-  }
-}
-
-/**
- * Platform-aware process tree kill.
- * POSIX: kill process group (spawned with detached=true).
- * Windows: taskkill /T to reach grandchildren (npm test's subprocesses, etc.).
- */
-function killProcessTree(child) {
-  if (process.platform === "win32") {
-    try { execFileSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" }) } catch {}
-  } else {
-    try { process.kill(-child.pid, "SIGKILL") } catch {}
-    try { child.kill("SIGKILL") } catch {} // fallback: kill directly if group kill fails
-  }
-}
-
-/**
- * Detect destructive git commands and auto-snapshot BEFORE execution.
- * The scenario: the model writes uncommitted code, then (after breaking things)
- * runs `git checkout -- .` / `git restore` / `git reset --hard` / `git clean -f` to
- * roll back — which silently DESTROYS all uncommitted work. The pre-task checkpoint
- * cannot help (it was taken before the code was written); only a snapshot taken
- * immediately before the destructive command can.
- *
- * This is the defense-in-depth guard: a WIDE match that snapshots before the command
- * runs — the command itself is NEVER blocked (a determined model bypasses text
- * matching anyway; the real gate is the approval layer). A snapshot alone is not
- * enough: the model may retry a variant that slips through the exact matcher
- * (e.g. `git checkout HEAD -- .`), or run git outside the bash tool. The snapshot
- * taken here survives all of those paths.
- *
- * Matching is intentionally WIDE (false positives are harmless — one extra snapshot;
- * a missed match is a data-loss disaster).
- */
-const GIT_DESTRUCTIVE_RE = /\bgit\s+(?:checkout\s+(?:[\w./-]+\s+)?--(?!\w)|checkout\s+\.|restore\s+(?!--help\b)(?!--staged\b(?!.*--worktree))|reset\s+--hard|clean\s+-(?=\S*f)(?!\S*n))/i
-
-/** Returns { id, notice } when a snapshot was taken, else null. Never throws. */
-async function gitGuardSnapshot(command, cwd) {
-  if (!GIT_DESTRUCTIVE_RE.test(command)) return null
-  try {
-    const { isGitRepo, createCheckpoint } = await import("../git/checkpoint.mjs")
-    if (!isGitRepo(cwd)) return null
-    const cp = await createCheckpoint(cwd)
-    if (!cp) return null
-    return {
-      id: cp.id,
-      notice: `[auto-protection] Destructive git command detected — snapshot ${cp.id} created BEFORE execution (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked). If this command destroyed uncommitted work, restore it: checkpoint action=checkpoint checkpointAction=rewind checkpointId=${cp.id}`,
-    }
-  } catch {
-    return null // protection is best-effort — never block the command
-  }
-}
-
-/**
- * Run a bash command: spawn, stream stdout/stderr with buffering and decoding,
- * enforce timeout and signal abort, return formatted result.
- *
- * Returns a promise that resolves to the formatted output string (stdout + stderr + status + truncation note).
- */
-function runBash(command, cwd, { timeout, signal, onOutput, shell }) {
-  return new Promise((resolve) => {
-    // Windows + default cmd: force UTF-8 code page for this child process (each spawn
-    // is an independent cmd, so chcp has no side effects on other shells) — otherwise
-    // cmd emits GBK bytes that the UTF-8 decoder turns into mojibake, and the model
-    // fights encoding errors instead of the actual command (reported UX on win11).
-    const effectiveCommand = process.platform === "win32" && !shell
-      ? `chcp 65001 >nul && ${command}`
-      : command
-    // args MUST be an explicit [] — the two-arg spawn(cmd, options) form is
-    // DEP0190-deprecated (Node 24): the options object would be misread as args.
-    const child = spawn(effectiveCommand, [], {
-      cwd,
-      shell: shell ?? true,
-      windowsHide: true,
-      detached: process.platform !== "win32",
-      stdio: ["ignore", "pipe", "pipe"],
-      env: buildBashEnv(),
-      // 双保险（2026-09-05——裸 spawn 无 signal 教训：abort 只靠 killTree 手动杀——taskkill
-      // best-effort 可能失败/竞态）——Node signal option = 第一道（abort 时自动杀**直接**子
-      // 进程——cmd——语义保证）；killTree 仍是必需兜底（孙进程握管道使 close 不触发——见
-      // L191 注释——spawn 级 kill 不达孙进程）
-      ...(signal ? { signal } : {}),
-    })
-
-    const killTree = () => killProcessTree(child)
-
-    // Separate decoders for stdout / stderr (same encoding in practice, but separate
-    // collection is cleaner and lets the model locate errors via stderr quickly)
-    const outDecoder = makeDecoder()
-    const errDecoder = makeDecoder()
-    let outBuf = ""
-    let errBuf = ""
-    let truncatedNote = ""
-
-    child.stdout.on("data", (d) => {
-      const s = sanitizeOutput(outDecoder(d))
-      if (s) onOutput?.(s)
-      if (outBuf.length < MAX_STREAM_BUF) outBuf += s
-      else if (!truncatedNote) truncatedNote =
-        "\n[... output exceeded 2MB, remainder discarded — redirect to a file if you need the full output]"
-    })
-
-    child.stderr.on("data", (d) => {
-      const s = sanitizeOutput(errDecoder(d))
-      if (s) onOutput?.(s)
-      if (errBuf.length < MAX_STREAM_BUF) errBuf += s
-    })
-
-    const timer = setTimeout(killTree, timeout)
-    if (signal) signal.addEventListener("abort", killTree, { once: true })
-
-    let settled = false
-    let graceTimer = null
-    const finish = (result) => {
-      if (settled) return
-      settled = true
-      clearTimeout(timer)
-      clearTimeout(graceTimer)
-      // 2026-09-05（advisor 🟡#2）：收尾移除 abort 监听器——ctx.signal 为长生命周期对象，
-      // 残留 once 监听器每次 bash 调用累积（闭包持有 child/输出缓冲直到 abort 才释放）
-      if (signal) signal.removeEventListener("abort", killTree)
-      resolve(result)
-    }
-
-    child.on("error", (error) => {
-      // signal 双保险（2026-09-05）：abort 时 Node signal option 杀直接子进程 → 本事件
-      // 以 AbortError 先触发——**跳过 finish**（不 settled）——exit 事件随后必到（实证
-      // 2ms 内）走 L195 分支带已收集输出收尾（user interrupted——不丢 partial）；
-      // 非 abort 的真 spawn 错误（command not found 等）保持原分支
-      if (error.name === "AbortError") return
-      finish(truncate(`Command failed: ${error.message}\n[stdout]:\n${outBuf || "(empty)"}`))
-    })
-
-    // Shell exited. Normally 'close' follows within milliseconds — but a BACKGROUND
-    // child (start /b, &, nohup …) inherits the stdio pipes, so the pipe stays open
-    // and 'close' never fires: the tool would hang until the timeout. Resolve after
-    // a short grace period instead, returning whatever output was collected.
-    child.on("exit", (code, exitSignal) => {
-      graceTimer = setTimeout(() => {
-        const outFlush = sanitizeOutput(outDecoder(Buffer.alloc(0), true))
-        const errFlush = sanitizeOutput(errDecoder(Buffer.alloc(0), true))
-        if (outFlush) onOutput?.(outFlush)
-        if (errFlush) onOutput?.(errFlush)
-        const status = exitSignal ? `killed: ${exitSignal}` : `exit code ${code}`
-        const parts = [`[stdout]:\n${(outBuf + outFlush).trim() || "(empty)"}`]
-        if ((errBuf + errFlush).trim()) parts.push(`[stderr]:\n${(errBuf + errFlush).trim()}`)
-        parts.push(`(${status})`)
-        parts.push("[background] the shell exited but a child process still holds the output pipe — output may be incomplete; the process may still be running")
-        finish(truncate(parts.join("\n\n") + truncatedNote))
-      }, 1500)
-    })
-
-    child.on("close", (code, exitSignal) => {
-      // Flush decoder tails — also push final bytes to panel
-      const outFlush = sanitizeOutput(outDecoder(Buffer.alloc(0), true))
-      const errFlush = sanitizeOutput(errDecoder(Buffer.alloc(0), true))
-      outBuf += outFlush
-      errBuf += errFlush
-      if (outFlush) onOutput?.(outFlush)
-      if (errFlush) onOutput?.(errFlush)
-
-      // Windows has no POSIX signals — check signal.aborted for user interrupts
-      const status = (exitSignal || signal?.aborted)
-        ? `killed: ${signal?.aborted ? "user interrupted" : "timeout"}`
-        : `exit code ${code}`
-
-      const parts = [`[stdout]:\n${outBuf.trim() || "(empty)"}`]
-      if (errBuf.trim()) parts.push(`[stderr]:\n${errBuf.trim()}`)
-      parts.push(`(${status})`)
-      finish(truncate(parts.join("\n\n") + truncatedNote))
-    })
-  })
-}
-
-// ====================================================================
-// tool definitions
-// ====================================================================
-
-export const bashTool = {
-  name: "bash",
-  description: DESC("bash"),
-  parameters: {
-    type: "object",
-    properties: {
-      command: { type: "string", description: "Shell command to execute" },
-      timeout: { type: "number", description: `Timeout in ms (default ${BASH_TIMEOUT_MS})` },
-      filter: { type: "string", description: "Optional: only return output lines matching this regex (case-insensitive)" },
-    },
-    required: ["command"],
-  },
-  readonly: false,
-  outputPanel: true, // stream stdout/stderr to panel during execution, collapse to summary on completion
-  async execute(args, ctx) {
-    // Git destructive commands are NEVER rejected — the model would bypass the
-    // guard anyway. Instead: snapshot every uncommitted file first, then ALLOW
-    // the command. The snapshot makes the rollback reversible (defense in depth:
-    // the wide matcher also covers variants like `git checkout HEAD -- .`).
-    const guard = await gitGuardSnapshot(args.command, ctx.cwd)
-    const result = await runBash(args.command, ctx.cwd, {
-      timeout: args.timeout ?? BASH_TIMEOUT_MS,
-      signal: ctx.signal,
-      onOutput: ctx.onOutput,
-      shell: ctx.agent?.config?.shell ?? null,
-    })
-    const filtered = args.filter ? applyLineFilter(result, args.filter) : result
-    const hint = posixSyntaxHint(args.command)
-    const body = guard ? `${guard.notice}\n\n${filtered}` : filtered
-    return hint ? `${hint}\n${body}` : body
-  },
-}