@thincoder/core 0.9.1 → 0.9.3

package/session-stale.mjs

@@ -0,0 +1,247 @@
+/**
+ * session-stale.mjs — sessions 存量治理（SESSION.md §6.17 · STARTUP-LATENCY 批，2026-09-21）。
+ *
+ * 职责 = 分组 / 三合取判据 / 回收（rename 进回收批）/ 清运（超期批）/ 有界逐扫。
+ * 全链异步（D-SE34）：本档零同步扫描——目录与逐文件面一律 `node:fs/promises`
+ * （同步 fs 面只留单条目 `existsSync`——本档不使用；bounded 单文件面归既有档）。
+ *
+ * 可清组 ⟺ 三合取（D-SE35；组 = sessions 根下同一 40 位 cwd 哈希前缀的全文件集合）：
+ *   ③ 安全窗：组内最新 mtime < now − STALE_SAFETY_WINDOW_MS（7 天——异常现场窗口）；
+ *   ① 无活属主：manifest `slotSessions` 全量经入口一次探测束 + `ownerState` 三态——
+ *      活 / 未知（探测失败 / 缺行）⇒ 保留；无 manifest ⇒ 无认领面 ⇒ 该条自动满足；
+ *   ② 内容面不可达或无内容：**T1** = 组内可读数据文件 `cwd` 全部不存在于磁盘（至少读到一份）；
+ *      **T2** = 组内无任何数据文件。数据文件不可读 / 无 `cwd` 字段 ⇒ T1 不成立 ⇒ 保留（fail-safe）。
+ * 求值序 = ③ → ① → ②（任一步不通过 ⇒ 保留并短路）；选取顺序 = 组最新 mtime 升序（最旧优先）。
+ * 预算（D-SE40）= **过 ③ 进 ① 即耗 1**（含 ① 面 manifest 读）——每 pass 总评估 ≤ `STALE_SWEEP_LIMIT`，
+ * 达上限即停、余量下一 pass 继续；③ 短路组零预算（未读盘），① / ② 短路组已耗 1（不退）；
+ * 显式面 limit = Infinity（全量）。
+ * 90 天冷 cwd 判据**不在本档**（cwd 存活组唯一出口——保持显式命令面；实现住 session-gc.mjs）。
+ *
+ * 回收（D-SE36）：判据窗 7 天 + 回收保留 7 天 ⇒ 不可逆删除最早 = 最后写入 + 14 天；
+ * 回收根 = 当次 sessions 根 `dir` 派生的同级 `sessions-trash/<批次时间戳>/`（sessions 根外——
+ * 不参与扫描 / 不入发现面；`dir` 注入缝因此覆盖回收批）；逐文件 rename（同卷元数据操作）——
+ * 单文件失败 / 回收根不可写 = 跳过并计数，**不 unlink 兜底**（零误删；部分移动态安全）。
+ */
+import { readdir, readFile, stat, rename, mkdir, rm } from "node:fs/promises"
+import { join, dirname } from "node:path"
+import { ownerPid } from "./session-slots-manifest.mjs"
+import { probeOwnersAsync, ownerState } from "./process-probe.mjs"
+
+export const STALE_SAFETY_WINDOW_MS = 7 * 24 * 3600 * 1000
+export const STALE_SWEEP_LIMIT = 500
+export const TRASH_RETENTION_MS = 7 * 24 * 3600 * 1000
+export const TRASH_DIR_NAME = "sessions-trash"
+
+/** 测试注入缝（`_traceHooks` 同惯例）：rename / mkdir / rm / stat / readdir 计数与失败注入。
+ *  生产永远走真实实现（本对象只在测试内 `Object.assign` + 还原）。 */
+export const _staleHooks = {
+  readdir: (dir) => readdir(dir),
+  readFile: (p) => readFile(p, "utf8"),
+  stat: (p) => stat(p),
+  rename: (from, to) => rename(from, to),
+  mkdir: (dir) => mkdir(dir, { recursive: true }),
+  rm: (dir) => rm(dir, { recursive: true, force: true }),
+}
+
+const GROUP_RE = /^([0-9a-f]{40})\.json(?:\.|$)/
+const DATA_SUFFIX_RE = /^(?:\.\d+)?$/
+const STAT_CHUNK = 128
+
+/** 回收根（D-SE36）= 当次 sessions 根的同级 `sessions-trash`。 */
+export function trashRootFor(dir) { return join(dirname(dir), TRASH_DIR_NAME) }
+
+/** 分组（纯函数）：entries（名串或 {name, mtimeMs}）→ Map<hash, {hash, prefix, files,
+ *  dataFiles, newestMtimeMs}>。只认 40 位哈希前缀族（非本族名一律不碰）；数据文件 =
+ *  裸 `{hash}.json` 与 `{hash}.json.N`（记录存储 sidecar `.N.d` 与残留随组处理，不计入）。 */
+export function groupSessionEntries(entries) {
+  const groups = new Map()
+  for (const e of entries) {
+    const name = typeof e === "string" ? e : e?.name
+    if (typeof name !== "string") continue
+    const m = GROUP_RE.exec(name)
+    if (!m) continue
+    const hash = m[1]
+    const prefix = `${hash}.json`
+    let g = groups.get(hash)
+    if (!g) { g = { hash, prefix, files: [], dataFiles: [], newestMtimeMs: 0 }; groups.set(hash, g) }
+    g.files.push(name)
+    if (DATA_SUFFIX_RE.test(name.slice(prefix.length))) g.dataFiles.push(name)
+    if (typeof e !== "string") g.newestMtimeMs = Math.max(g.newestMtimeMs, Number(e?.mtimeMs) || 0)
+  }
+  return groups
+}
+
+/** 三合取判定（**纯函数**——零 IO；入参 = 已取证事实）：
+ *  facts = { now, newestMtimeMs, ownerStates, dataFiles: [{readable, cwdExists}] }
+ *  → { cleanable, reason }（reason 面：window / live-owner / unknown-owner / no-content /
+ *  cwd-gone / cwd-exists / unreadable）。 */
+export function judgeStaleGroup(facts) {
+  const { now, newestMtimeMs = 0, ownerStates = [], dataFiles = [] } = facts
+  if (!(newestMtimeMs < now - STALE_SAFETY_WINDOW_MS)) return { cleanable: false, reason: "window" }
+  if (ownerStates.includes("alive")) return { cleanable: false, reason: "live-owner" }
+  if (ownerStates.includes("unknown")) return { cleanable: false, reason: "unknown-owner" }
+  if (!dataFiles.length) return { cleanable: true, reason: "no-content" } // T2
+  for (const f of dataFiles) { // T1：可读数据文件 cwd 全不在盘（至少一份；不可读 ⇒ fail-safe 保留）
+    if (!f.readable || f.cwdExists == null) return { cleanable: false, reason: "unreadable" }
+    if (f.cwdExists) return { cleanable: false, reason: "cwd-exists" }
+  }
+  return { cleanable: true, reason: "cwd-gone" }
+}
+
+/** 目录快照 → 组集合：本族名逐条目 `stat` 异步（分块——非阻塞、不进启动关键路径）。
+ *  names 缺省 = 自行 readdir（dir 注入缝；pass 编排可传共享快照——readdir 恰一次）。
+ *  `hashes` 在场 ⇒ **按前缀预筛后再 stat**（单组重校验面：逐组调用不随存量放大——
+ *  `--confirm <hash>` / 端侧命令面的逐组重校验成本 = O(该组文件数)）。 */
+async function snapshotGroups(dir, names, hashes = null) {
+  if (!names) {
+    try { names = await _staleHooks.readdir(dir) } catch { return new Map() }
+  }
+  const want = hashes ? hashes.map((h) => `${h}.json`) : null
+  const hit = names.map((n) => (typeof n === "string" ? n : n?.name))
+    .filter((n) => typeof n === "string" && GROUP_RE.test(n) && (!want || want.some((p) => n === p || n.startsWith(p + "."))))
+  const facts = []
+  for (let i = 0; i < hit.length; i += STAT_CHUNK) {
+    const chunk = await Promise.all(hit.slice(i, i + STAT_CHUNK).map(async (name) => {
+      try { return { name, mtimeMs: (await _staleHooks.stat(join(dir, name))).mtimeMs } } catch { return null }
+    }))
+    for (const f of chunk) if (f) facts.push(f)
+  }
+  return groupSessionEntries(facts)
+}
+
+/** ① 面入参：manifest `slotSessions` 属主 pid（manifest 缺失 / 损坏 ⇒ 空 ⇒ 该条自动满足）。 */
+async function manifestOwners(dir, prefix) {
+  let m
+  try { m = JSON.parse(await _staleHooks.readFile(join(dir, `${prefix}.manifest`))) } catch { return [] }
+  const pids = []
+  for (const owner of Object.values(m?.slotSessions ?? {})) {
+    const pid = typeof owner === "string" && owner ? ownerPid(owner) : 0
+    if (pid) pids.push(pid)
+  }
+  return pids
+}
+
+/** cwd 是否在盘（异步单条目）；非 ENOENT（权限 / 网络错）⇒ 不可判 ⇒ 视为存在（保守向）。 */
+async function pathExists(p) {
+  try { await _staleHooks.stat(p); return true } catch (e) { return e?.code !== "ENOENT" }
+}
+
+/** ② 面取证：逐数据文件（可读 ∧ cwd 字段在盘）。不可读 / 无 `cwd` ⇒ readable:false（fail-safe）。 */
+async function dataFileFacts(dir, group) {
+  const out = []
+  for (const name of group.dataFiles) {
+    let data = null
+    try { data = JSON.parse(await _staleHooks.readFile(join(dir, name))) } catch { data = null }
+    const cwd = typeof data?.cwd === "string" && data.cwd ? data.cwd : null
+    out.push(cwd ? { readable: true, cwdExists: await pathExists(cwd) } : { readable: false, cwdExists: null })
+  }
+  return out
+}
+
+/**
+ * 候选列举（显式面 / 自动面共用）：③（廉价——短路组零预算）→ ①（**过 ③ 进 ① 即耗 1 预算**——
+ * 该组 manifest 读与（若过 ① 的）② 内容读均在此预算内）→ ②（内容判据）。
+ * 预算闸 = 过 ③ 进 ① 的组数 ≤ `limit`（达上限即停——升序余量下一 pass 继续；显式面传 Infinity）。
+ * 返回 { candidates, evaluated, groups }——`evaluated` = 过 ③ 进 ① 的组数（= 预算消耗组数，
+ * 含 ① 面 manifest 读——D-SE40）。
+ * `hashes` 在场 ⇒ 只判这些 hash（单组重校验面——`deleteStaleCwd` 用）。
+ */
+export async function listStaleCwds({ dir, entries = null, now = Date.now(), probeFn = probeOwnersAsync, limit = STALE_SWEEP_LIMIT, hashes = null } = {}) {
+  const groups = await snapshotGroups(dir, entries, hashes)
+  const all = [...groups.values()]
+  const wanted = hashes ? all.filter((g) => hashes.includes(g.hash)) : all
+  const ordered = wanted.sort((a, b) => a.newestMtimeMs - b.newestMtimeMs || (a.hash < b.hash ? -1 : 1))
+  const ownersByHash = new Map()
+  const allPids = new Set()
+  let evaluated = 0
+  for (const g of ordered) {
+    if (!(g.newestMtimeMs < now - STALE_SAFETY_WINDOW_MS)) continue // ③ 短路（零预算——未读盘）
+    if (evaluated >= limit) break // 预算闸（过 ③ 进 ① 即耗——达上限即停；余量下一 pass 继续）
+    evaluated++ // 该组 ① manifest 读 +（若过 ① 的）② 内容读均在此预算内（D-SE40）
+    const pids = await manifestOwners(dir, g.prefix)
+    ownersByHash.set(g.hash, pids)
+    for (const pid of pids) allPids.add(pid)
+  }
+  const bundle = allPids.size ? await probeFn([...allPids]) : { aliveSet: null, cmds: null }
+  const candidates = []
+  for (const g of ordered) {
+    const pids = ownersByHash.get(g.hash)
+    if (!pids) continue // ③ 短路 / 预算外（未进 ①）
+    const states = pids.map((pid) => ownerState(pid, bundle))
+    if (states.some((s) => s !== "dead")) continue // ① 短路（活 / 未知 ⇒ 保留——预算已耗，不退）
+    const verdict = judgeStaleGroup({ now, newestMtimeMs: g.newestMtimeMs, ownerStates: states, dataFiles: await dataFileFacts(dir, g) })
+    if (verdict.cleanable) {
+      candidates.push({ hash: g.hash, prefix: g.prefix, reason: verdict.reason, dataFiles: g.dataFiles.length, newestMtime: g.newestMtimeMs, files: g.files })
+    }
+  }
+  return { candidates, evaluated, groups: ordered.length }
+}
+
+/** 回收序（§6.17 落地顺序）：残留 / 端标记 → manifest → 数据文件。 */
+function recycleRank(name, prefix) {
+  const rest = name.slice(prefix.length)
+  if (rest === ".manifest") return 1
+  if (rest === "" || /^\.\d+$/.test(rest) || /^\.\d+\.d$/.test(rest)) return 2
+  return 0
+}
+
+/** 逐组回收（组粒度——非事务）：逐文件 rename 进回收批。单文件失败 / 回收根不可写 = 跳过并计数，
+ *  不 unlink 兜底（原文件零删除）；返回 { moved, skipped, batch }（零移动 ⇒ batch:null）。 */
+export async function recycleGroup(group, { dir, now = Date.now() } = {}) {
+  const batch = join(trashRootFor(dir), String(now))
+  const out = { moved: [], skipped: [], batch: null }
+  const ordered = [...group.files].sort((a, b) => recycleRank(a, group.prefix) - recycleRank(b, group.prefix))
+  for (const name of ordered) {
+    try {
+      if (!out.batch) { await _staleHooks.mkdir(batch); out.batch = batch }
+      await _staleHooks.rename(join(dir, name), join(batch, name))
+      out.moved.push(name)
+    } catch { out.skipped.push(name) }
+  }
+  if (!out.moved.length) out.batch = null
+  return out
+}
+
+/** 单组回收（显式命令面 / 端侧命令面）：重校验（TOCTOU——单组重判三合取）→ 回收。
+ *  `entries` = 目录名快照（可选——命令面循环可传同一快照免逐组全目录 readdir；
+ *  mtime 事实同自动面 pass 模型，**① 面 manifest 读与探测束仍逐组新鲜**——变活组由 ① 拦截）。 */
+export async function deleteStaleCwd(hash, { dir, now = Date.now(), probeFn = probeOwnersAsync, entries = null } = {}) {
+  const { candidates } = await listStaleCwds({ dir, now, probeFn, limit: Infinity, hashes: [hash], entries })
+  const target = candidates.find((c) => c.hash === hash)
+  if (!target) return { ok: false, reason: "not-cold", deleted: [] } // 期间变活 / 出窗 ⇒ 拒绝（零删除）
+  const r = await recycleGroup(target, { dir, now })
+  if (!r.moved.length) return { ok: false, reason: "recycle-failed", deleted: [], skipped: r.skipped }
+  return { ok: true, reason: target.reason, deleted: r.moved, skipped: r.skipped, batch: r.batch }
+}
+
+/** 清运（D-SE36）：超期回收批整删（批名 = 批次时间戳，13 位 epoch ms ⇒ 到期可比）。失败静默跳过
+ *  （不误删在期批）；后续 pass 重试。非批次名（外来目录）一律不碰。 */
+export async function purgeTrash({ dir, now = Date.now(), retentionMs = TRASH_RETENTION_MS } = {}) {
+  const root = trashRootFor(dir)
+  const out = { purged: [], failed: [] }
+  let batches
+  try { batches = await _staleHooks.readdir(root) } catch { return out } // 无回收根 ⇒ 无事可做
+  for (const batch of batches) {
+    if (!/^\d{13}$/.test(batch)) continue // 批名形态锁（本档写入口 = String(Date.now())）——外来目录不碰
+    const ts = Number(batch)
+    if (!(ts + retentionMs <= now)) continue
+    try { await _staleHooks.rm(join(root, batch)); out.purged.push(batch) } catch { out.failed.push(batch) }
+  }
+  return out
+}
+
+/** 有界清立面 pass（**自动面**——绑启动**窗外延迟拍**（`scheduleSessionGC`），每进程一次）：
+ *  候选（**过 ③ 进 ① ≤ `limit`**——含 ① 面 manifest 读）→ 逐组回收 → 超期批清运。
+ *  全链异步；失败由调用面静默（本函数不抛——逐文件失败已计数）。 */
+export async function sweepStale({ dir, entries = null, now = Date.now(), probeFn = probeOwnersAsync, limit = STALE_SWEEP_LIMIT } = {}) {
+  const { candidates, evaluated, groups } = await listStaleCwds({ dir, entries, now, probeFn, limit })
+  let moved = 0
+  let skipped = 0
+  for (const c of candidates) {
+    const r = await recycleGroup(c, { dir, now })
+    moved += r.moved.length
+    skipped += r.skipped.length
+  }
+  const purged = await purgeTrash({ dir, now })
+  return { groups, evaluated, candidates: candidates.length, moved, skipped, purged: purged.purged.length, purgeFailed: purged.failed.length }
+}

package/token-window.mjs

@@ -0,0 +1,188 @@
+/**
+ * token-window.mjs — token 计量 / 窗口 / 切割族（自 `context.mjs` **逐字迁出**）+ 上下文用量单源
+ * （CONTEXT-COMPACTION.md §6.16.3 / §6.16.4 / §6.16.8 · context-tool 批 2026-09-21）。
+ * 迁出三族（语义零改——原档越限在即，本批按 §6.16.8 拆出）：① 计量面（IMAGE_TOKEN_ESTIMATE + `estimateTokens`）；
+ * ② 尾族（KEEP_HEAD 头注 + TAIL_BUDGET_FRACTION / SUMMARY_TOKEN_ESTIMATE / TAIL_FLOOR_MESSAGES + `keepTailSize` + `tailBudgetTokens`）；
+ * ③ 切分与配对修复族（`splitHistory` + `repairedTailStart` + `tightenTailByBudget`）。
+ * 新增族：`contextUsage`（与 `compressIfNeeded` 的 token 判定**同一函数**）· `historyPercent`（与两端状态行**同式**）·
+ * `collectStaleToolOutputs`（陈旧工具输出合格集）+ 门槛常量 `PRUNE_MIN_TOKENS`（**与合格集同住本档** ⇒ 消费方单向取用、零回指）。
+ * 依赖面 = `provider/rate.mjs`（`estimateText`）+ `config.mjs`（`providerSpec` / `resolveCompactThreshold`）——**零 import 环**。
+ */
+import { estimateText } from "./provider/rate.mjs"
+import { providerSpec, resolveCompactThreshold } from "./config.mjs"
+
+const IMAGE_TOKEN_ESTIMATE = 2000 // rough estimate for image content tokens (CLI legacy 256 underestimated real image costs, delaying compaction)
+
+/** Rough token count for a list of messages (body + reasoning + tool_calls params) */
+export function estimateTokens(messages) {
+  let tokens = 0
+  for (const m of messages) {
+    if (typeof m.content === "string") tokens += estimateText(m.content)
+    else if (Array.isArray(m.content)) {
+      for (const part of m.content) {
+        if (part.type === "text") tokens += estimateText(part.text)
+        else if (part.type === "image_url") tokens += IMAGE_TOKEN_ESTIMATE
+      }
+    }
+    if (typeof m.reasoning_content === "string") tokens += estimateText(m.reasoning_content)
+    for (const tc of m.tool_calls ?? []) {
+      tokens += estimateText(tc.function?.name ?? "") + estimateText(tc.function?.arguments ?? "")
+    }
+  }
+  return tokens
+}
+
+const KEEP_HEAD = 0 // No dedicated head: earliest messages may be a COMPLETED earlier task in multi-task
+// sessions — keeping them verbatim anchored attention on stale work. Everything before the tail is
+// summarized (the summary itself distinguishes completed vs in-progress work; see SUMMARIZE_PROMPT).
+// Tail count formula (D4): window-adaptive (~30 msgs per 100K — old fixed 10 too thin on 1M), capped
+// at 40% of history; §6.4④ D-T1/D-T2 make the count only a CANDIDATE — a token budget (TAIL_BUDGET_FRACTION
+// × window − SUMMARY_TOKEN_ESTIMATE ≈1K, §6.9) tightens it over pair-safe boundaries when compaction runs,
+// never below TAIL_FLOOR_MESSAGES; ordinary sessions never reach it (D-T4: trigger 0.6 untouched).
+const TAIL_BUDGET_FRACTION = 0.15
+const SUMMARY_TOKEN_ESTIMATE = 1000 // §6.9: summary output target ~1K tokens — reserved from the 15%
+const TAIL_FLOOR_MESSAGES = 10 // §6.4④ D-T2: the tail keeps ≥10 verbatim messages — floor beats budget
+export function keepTailSize(provider, historyLen) {
+  // provider is guaranteed at every call site (runAgent always builds one); providerSpec
+  // degrades to DEFAULT_SPEC (128K) only if provider is somehow absent — acceptable
+  // because the 40% history cap still bounds the tail. providers[].context override
+  // (K units) is honored here (PROVIDER.md §6.15 T-C2: tail formula follows the window).
+  const ctxWindow = providerSpec(provider).context
+  return Math.min(Math.max(10, Math.floor((ctxWindow / 100_000) * 30)), Math.floor(historyLen * 0.4))
+}
+// §6.4④ D-T1 tail token budget: window×15% − summary ~1K — the compressed history segment (summary + placeholder + tail) lands ≈ 15% (B 口径 §6.4④).
+export function tailBudgetTokens(provider) {
+  return Math.max(0, Math.floor(providerSpec(provider).context * TAIL_BUDGET_FRACTION) - SUMMARY_TOKEN_ESTIMATE)
+}
+
+/**
+ * Split history into head / middle (to be summarized) / tail; return null if no middle to compress.
+ * head is normally empty (KEEP_HEAD = 0 — earliest messages go into the summary); the tool_calls-extension logic below is defensive for future KEEP_HEAD > 0.
+ * The tail boundary must include any assistant whose tool results are in the tail — if the assistant is in the middle, the summary swallows it, leaving orphan tool results → protocol 400.
+ * `budgetTokens` (optional, §6.4④ D-T1): when the candidate's estimate exceeds it, the boundary moves
+ * forward until the tail fits — never below the D-T2 floor (10 msgs, or the candidate itself when
+ * the 40% cap made it < 10 — short history).
+ */
+export function splitHistory(history, keepTail, budgetTokens = null) {
+  if (history.length <= KEEP_HEAD + keepTail + 1) return null
+  let headEnd = KEEP_HEAD
+  // head must not end with dangling tool_calls: when assistant declares tool_calls, all its tool results must stay in head.
+  // Parallel calls: one assistant followed by multiple tool messages — accepting only one still causes 400, must collect all
+  if (history[headEnd - 1]?.role === "assistant" && history[headEnd - 1].tool_calls?.length) {
+    while (headEnd < history.length && history[headEnd].role === "tool") headEnd++
+  }
+  const candidate = repairedTailStart(history, headEnd, history.length - keepTail)
+  if (candidate <= headEnd) return null
+  let tailStart = candidate
+  // §6.4④ D-T1: tighten only above the floor — a candidate ≤ 10 IS the floor (short history under the 40% cap must not tighten further, review #5); the floor is D5-repaired too.
+  if (budgetTokens > 0 && keepTail > TAIL_FLOOR_MESSAGES) {
+    const floor = repairedTailStart(history, headEnd, history.length - TAIL_FLOOR_MESSAGES)
+    if (floor > candidate) tailStart = tightenTailByBudget(history, candidate, floor, budgetTokens)
+  }
+  return { headEnd, tailStart }
+}
+
+/**
+ * D5 tail-side pairing repair for a raw cut at history.length − tailCount: pull into the tail any
+ * assistant whose tool results are in the tail (the summary swallowing the owner leaves orphan tool
+ * results → protocol 400), then skip orphan tool messages at the new boundary. Single-assistant
+ * assumption (nearest owner only — a tail spans at most one assistant→tools cycle); bounds-guarded.
+ */
+function repairedTailStart(history, headEnd, tailStart) {
+  const tailToolIds = new Set()
+  for (let i = tailStart; i < history.length; i++) {
+    if (history[i].role === "tool") tailToolIds.add(history[i].tool_call_id)
+  }
+  for (let i = tailStart - 1; i > headEnd; i--) {
+    const m = history[i]
+    if (m.role === "assistant" && m.tool_calls?.some((tc) => tailToolIds.has(tc.id))) {
+      tailStart = i
+      break
+    }
+  }
+  while (tailStart < history.length && tailStart > headEnd && history[tailStart].role === "tool") {
+    tailStart++
+  }
+  return tailStart
+}
+
+/**
+ * §6.4④ D-T1 budget tightening (pair-safe, review #2): walk the boundary FORWARD (fewer tail messages —
+ * the rest joins the summary) while the tail's estimated tokens exceed the budget. Only pair-safe
+ * positions may stop the walk: a boundary ON a tool message would orphan its owner assistant into the
+ * middle (D5); pairing is contiguous in the machine line (§6.4③) — every non-tool boundary is safe.
+ * No fit before the floor → keep the floor, accept the overrun.
+ */
+function tightenTailByBudget(history, start, floorStart, budgetTokens) {
+  const suffixTokens = new Array(history.length + 1)
+  suffixTokens[history.length] = 0
+  for (let i = history.length - 1; i >= 0; i--) suffixTokens[i] = suffixTokens[i + 1] + estimateTokens([history[i]])
+  if (suffixTokens[start] <= budgetTokens) return start // already fits — ordinary sessions stay untouched (D-T2)
+  for (let p = start + 1; p <= floorStart; p++) { // first fit keeps the most recent verbatim context
+    if (history[p].role !== "tool" && suffixTokens[p] <= budgetTokens) return p
+  }
+  return floorStart
+}
+
+/**
+ * 上下文用量单源（§6.16.4「取自哪里」）——与 `compressIfNeeded` 的 token 判定**同一函数**：实测优先 =
+ * `_lastPromptTokens + 增量(history.slice(_usageAtLen))`；无实测 = `estimateTokens(history) + system + tools`（固定开销面经 extras 随带）。
+ * `threshold` = 该回合检查所用值（`agent._ctxBasis.threshold`——核 `agent.mjs` / VSC `checkAndCompact` 各一处暂存）；缺省回退 `resolveCompactThreshold`（退化面①）。
+ * `window` = `providerSpec(agent.provider).context`。
+ * @returns {{basis:"measured"|"estimated", total, history, system, tools, overhead, threshold, window}}
+ */
+export function contextUsage(agent, extras = {}) {
+  const history = Array.isArray(agent?.history) ? agent.history : []
+  const system = extras.systemPrompt ? estimateText(extras.systemPrompt) : 0
+  const tools = extras.tools ? estimateText(JSON.stringify(extras.tools)) : 0
+  const overhead = system + tools
+  const historyTokens = estimateTokens(history)
+  const measured = agent?._lastPromptTokens != null
+  return {
+    basis: measured ? "measured" : "estimated",
+    total: measured
+      ? agent._lastPromptTokens + estimateTokens(history.slice(agent._usageAtLen ?? history.length))
+      : historyTokens + overhead,
+    history: historyTokens,
+    system,
+    tools,
+    overhead,
+    threshold: agent?._ctxBasis?.threshold
+      ?? resolveCompactThreshold(agent?.config?.agent?.compactThreshold, agent?.provider).value,
+    window: providerSpec(agent?.provider).context,
+  }
+}
+
+/**
+ * 状态行百分比（§6.16.4「与状态行 ctx% 的单源关系」）——与 CLI 状态行（`render-frame.mjs` 式）与 VSC `ctxPercentForHistory` **同式**；
+ * stats 报出的就是用户看到的那个百分比（不新增第三口径）；空历史 ⇒ 0（状态行的 `ctxPct > 0` 显示门在端侧）。
+ */
+export function historyPercent(history, provider) {
+  return Math.round((estimateTokens(history ?? []) / providerSpec(provider).context) * 100)
+}
+
+/** 陈旧工具输出门槛（§6.16.3 判据③）：低于门槛的替换是净增 token（stub 本身有长度）——常量与合格集同住本档。 */
+export const PRUNE_MIN_TOKENS = 200
+
+/**
+ * 陈旧工具输出合格集（§6.16.3——三条件合取，单源实现）：① `role === "tool"`；② **保护尾之外**（复用 `splitHistory` 的同一 `tailStart`——不新增第二处切割判据）；③ 估算 ≥ `PRUNE_MIN_TOKENS`。
+ * 返回逐条计数面（prune 回执 + stats 两处消费）：`indexes` 合格索引（升序）· `tokens` 合格集估算和 · `candidates` 全史 tool 结果数 · `tailKept` 保护尾内保留数 · `belowMin` 门槛下跳过数 · `tailCount` 保护尾消息数。
+ * **短历史（无中段）⇒ 合格集为空**（no-op——§6.16.3 边界）。
+ */
+export function collectStaleToolOutputs(history, provider) {
+  const h = Array.isArray(history) ? history : []
+  const split = splitHistory(h, keepTailSize(provider, h.length), tailBudgetTokens(provider))
+  // 无中段（短历史）⇒ 可摘要面为空 ⇒ **全史即保护尾**（tailStart = 0——合格集必为空，同压缩面 no-op）
+  const tailStart = split ? split.tailStart : 0
+  const r = { indexes: [], tokens: 0, candidates: 0, tailKept: 0, belowMin: 0, tailCount: h.length - tailStart }
+  for (let i = 0; i < h.length; i++) {
+    if (h[i]?.role !== "tool") continue
+    r.candidates++
+    if (i >= tailStart) { r.tailKept++; continue }
+    const est = estimateTokens([h[i]])
+    if (est < PRUNE_MIN_TOKENS) { r.belowMin++; continue }
+    r.indexes.push(i)
+    r.tokens += est
+  }
+  return r
+}

package/tools/bash.mjs

@@ -5,7 +5,10 @@ import {
   makeDecoder,
   BASH_TIMEOUT_MS,
 } from "./shared.mjs";
-import { spawn, execFileSync } from "node:child_process";
+import { spawn } from "node:child_process";
+// 树杀单源（台账 #208② · TOOLS.md §6.14 落位表行 2）：本地副本删除——改用 `./process-tree.mjs`
+// （行为逐字同：win32 `taskkill /T /F` · POSIX 组杀 + 直杀兜底）。
+import { killProcessTree } from "./process-tree.mjs";
 
 /** Maximum buffer size per stream (stdout / stderr) before truncation */
 const MAX_STREAM_BUF = 2_000_000
@@ -58,20 +61,6 @@ function buildBashEnv() {
   }
 }
 
-/**
- * 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)

package/tools/execute.mjs

@@ -24,9 +24,10 @@
  *   filter     — return only output lines matching this regex (case-insensitive)
  *   timeoutMs  — timeout (default 30s, max 600000ms)
  */
-import { spawn, execFileSync } from "node:child_process"
+import { spawn } from "node:child_process"
 import { resolve } from "node:path"
 import { DESC } from "./shared.mjs"
+import { killProcessTree } from "./process-tree.mjs"
 
 const MAX_SCRIPT = 50_000
 const MAX_OUTPUT = 50_000
@@ -58,18 +59,9 @@ function applyFilter(output, filter) {
   }
 }
 
-/** Platform-aware process tree kill — mirror of system.mjs/verify.mjs killProcessTree.
- *  Timeout/abort must reach grandchildren: a script that spawned children keeps the
- *  pipes open otherwise — "close" never fires and the tool stalls until the 3s kick
- *  while the orphan keeps running (2026-09-05 advisor 🟡#4). */
-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 {}
-  }
-}
+/** 树杀单源 = `tools/process-tree.mjs`（TOOLS.md §6.14 落位表行 2：自本档抽出以断
+ *  `shared → git-run → execute → shared` 环）；**再导出面保留**（`test/tool-seams.test.mjs:26` 消费，
+ *  `configureProcessTreeKill` 缺省径零改）。 */
 export { killProcessTree }
 
 // ─── 树杀注入缝（#57——「树杀实现按端注入」，形态参 §2.13.5 注入缝）───────────────

package/tools/git-checkpoint.mjs

@@ -25,7 +25,7 @@ export async function lazyClearIfCommitted(cwd) {
   try {
     const cps = await listCheckpoints(cwd)
     if (cps.length === 0) return
-    const headSec = runGit(cwd, ["log", "-1", "--format=%ct"])
+    const headSec = await runGit(cwd, ["log", "-1", "--format=%ct"])
     const headMs = Number.parseInt(headSec, 10) * 1000
     if (!Number.isFinite(headMs) || headMs <= 0) return
     const newest = cps[0] // listCheckpoints returns newest → oldest

package/tools/git-ext.mjs

@@ -4,7 +4,7 @@
  * 供 git.mjs 核心 action 复用——500 行硬限拆分）。CLI 与 VS Code 两端同构（镜像，修改须两端同批）。
  */
 import { runGit, truncate } from "./shared.mjs"
-import { execFileSync } from "node:child_process"
+import { spawnGit, gitTimeoutNote } from "./git-run.mjs"
 
 /** Keep only output lines matching a regex (git filter, case-insensitive). */
 export function filterLines(output, filter) {
@@ -19,12 +19,15 @@ export function filterLines(output, filter) {
 }
 
 /** Run git and report failure (stderr + exit code) instead of swallowing it.
- *  Used by write ops (commit/push/rm) where a silent "" would masquerade as success. */
-export function runGitStrict(cwd, cmdArgs, config = []) {
+ *  Used by write ops (commit/push/rm) where a silent "" would masquerade as success.
+ *  §6.14：体改**异步薄壳**（`spawnGit` 单点——加固 env + 两档超时 + 树杀）；`{ok, out, err}` 形逐字保留
+ *  + 超时分支（`err` = 单源超时注——可辨性不靠 stderr 文本猜）。 */
+export async function runGitStrict(cwd, cmdArgs, config = []) {
   try {
-    const out = execFileSync("git", [...config, ...cmdArgs], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim().replace(/\r/g, "")
+    const out = (await spawnGit(cwd, [...config, ...cmdArgs])).trim().replace(/\r/g, "")
     return { ok: true, out }
   } catch (e) {
+    if (e.timedOut) return { ok: false, out: String(e.stdout || "").trim(), err: gitTimeoutNote(e.timeoutMs) }
     return { ok: false, out: String(e.stdout || "").trim(), err: String(e.stderr || e.message || "").trim() }
   }
 }
@@ -36,7 +39,7 @@ export function validateRef(ref, what = "git ref") {
 }
 
 /** Normalize args.config into `-c key=value` pairs (git -c overrides, e.g. a proxy).
- *  Values are execFileSync array args (no shell injection) — still reject newlines/empty. */
+ *  Values are spawn array args (no shell injection) — still reject newlines/empty. */
 export function gitConfigArgs(config) {
   if (config == null) return []
   if (!Array.isArray(config)) throw new Error("config must be an array of \"key=value\" strings")
@@ -70,11 +73,11 @@ export async function executeExtAction(args, ctx) {
       if (!args.remote) return "Error: clone requires remote (URL or local path)"
       const cmdArgs = ["clone", args.remote]
       if (args.path) cmdArgs.push(args.path)
-      const r = runGitStrict(ctx.cwd, cmdArgs, gitConfigArgs(args.config))
+      const r = await runGitStrict(ctx.cwd, cmdArgs, gitConfigArgs(args.config))
       return r.ok ? truncate(r.out || `Cloned ${args.remote}`) : truncate(`git clone failed: ${r.err || r.out}`)
     }
     case "init": {
-      const r = runGitStrict(ctx.cwd, ["init"])
+      const r = await runGitStrict(ctx.cwd, ["init"])
       return r.ok ? truncate(r.out || "Initialized empty git repository") : truncate(`git init failed: ${r.err || r.out}`)
     }
     case "rebase": {
@@ -89,21 +92,21 @@ export async function executeExtAction(args, ctx) {
       if (sub === "abort") cmdArgs.push("--abort")
       else if (sub === "continue") cmdArgs.push("--continue")
       else { if (!args.ref) return "Error: rebase requires ref (branch/commit to rebase onto)"; cmdArgs.push(validateRef(args.ref)) }
-      const r = runGitStrict(ctx.cwd, cmdArgs)
+      const r = await runGitStrict(ctx.cwd, cmdArgs)
       return r.ok ? truncate(snap + (r.out || `Rebase ${sub} complete`)) : truncate(snap + `git rebase failed: ${r.err || r.out} — use rebaseAction=abort to abort`)
     }
     case "remote": {
       const sub = args.remoteAction ?? "list"
-      if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["remote", "-v"]) || "(no remotes)", args.filter))
+      if (sub === "list") return truncate(filterLines(await runGit(ctx.cwd, ["remote", "-v"]) || "(no remotes)", args.filter))
       if (!args.remote) return `Error: remote ${sub} requires remote (name)`
       validateRef(args.remote, "remote name")
       if (sub === "add" || sub === "set-url") {
         if (!args.remoteUrl) return `Error: remote ${sub} requires remoteUrl`
-        const r = runGitStrict(ctx.cwd, ["remote", sub === "add" ? "add" : "set-url", args.remote, args.remoteUrl])
+        const r = await runGitStrict(ctx.cwd, ["remote", sub === "add" ? "add" : "set-url", args.remote, args.remoteUrl])
         return r.ok ? `Remote ${args.remote} ${sub === "add" ? "added" : "URL set"}` : truncate(`git remote ${sub} failed: ${r.err || r.out}`)
       }
       if (sub === "remove") {
-        const r = runGitStrict(ctx.cwd, ["remote", "remove", args.remote])
+        const r = await runGitStrict(ctx.cwd, ["remote", "remove", args.remote])
         return r.ok ? `Remote ${args.remote} removed` : truncate(`git remote remove failed: ${r.err || r.out}`)
       }
       return "Error: remote requires remoteAction — use: list | add | remove | set-url"
@@ -113,7 +116,7 @@ export async function executeExtAction(args, ctx) {
       // dryRun (-n) is a preview: no deletion, no snapshot.
       const snap = args.dryRun ? "" : await snapshotBefore(ctx, "clean")
       const cmdArgs = ["clean", args.dryRun ? "-n" : "-f", "-d"]
-      const r = runGitStrict(ctx.cwd, cmdArgs)
+      const r = await runGitStrict(ctx.cwd, cmdArgs)
       return r.ok ? truncate(snap + (r.out || (args.dryRun ? "Nothing to clean (dry run)" : "Clean complete"))) : truncate(snap + `git clean failed: ${r.err || r.out}`)
     }
     case "switch": {
@@ -122,28 +125,28 @@ export async function executeExtAction(args, ctx) {
       const cmdArgs = ["switch"]
       if (args.create) cmdArgs.push("-c")
       cmdArgs.push(args.name)
-      const r = runGitStrict(ctx.cwd, cmdArgs)
+      const r = await runGitStrict(ctx.cwd, cmdArgs)
       return r.ok ? truncate(r.out || `Switched to branch ${args.name}`) : truncate(`git switch failed: ${r.err || r.out}`)
     }
     case "apply": {
       // Apply a patch — non-destructive (fails cleanly on conflict, applies nothing).
       if (!args.path) return "Error: apply requires path (patch file)"
-      const r = runGitStrict(ctx.cwd, ["apply", "--", args.path])
+      const r = await runGitStrict(ctx.cwd, ["apply", "--", args.path])
       return r.ok ? truncate(r.out || `Applied ${args.path}`) : truncate(`git apply failed: ${r.err || r.out}`)
     }
     case "worktree": {
       const sub = args.worktreeAction ?? "list"
-      if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["worktree", "list"]) || "(no worktrees)", args.filter))
+      if (sub === "list") return truncate(filterLines(await runGit(ctx.cwd, ["worktree", "list"]) || "(no worktrees)", args.filter))
       if (sub === "add") {
         if (!args.path) return "Error: worktree add requires path (new worktree directory)"
         const cmdArgs = ["worktree", "add", args.path]
         if (args.ref) cmdArgs.push(validateRef(args.ref))
-        const r = runGitStrict(ctx.cwd, cmdArgs)
+        const r = await runGitStrict(ctx.cwd, cmdArgs)
         return r.ok ? truncate(r.out || `Worktree added at ${args.path}`) : truncate(`git worktree add failed: ${r.err || r.out}`)
       }
       if (sub === "remove") {
         if (!args.path) return "Error: worktree remove requires path"
-        const r = runGitStrict(ctx.cwd, ["worktree", "remove", args.path])
+        const r = await runGitStrict(ctx.cwd, ["worktree", "remove", args.path])
         return r.ok ? truncate(r.out || `Worktree removed: ${args.path}`) : truncate(`git worktree remove failed: ${r.err || r.out}`)
       }
       return "Error: worktree requires worktreeAction — use: list | add | remove"
@@ -154,17 +157,17 @@ export async function executeExtAction(args, ctx) {
       const cmdArgs = ["archive", "--format=tar", "-o", args.path]
       if (args.ref) cmdArgs.push(validateRef(args.ref))
       else cmdArgs.push("HEAD")
-      const r = runGitStrict(ctx.cwd, cmdArgs)
+      const r = await runGitStrict(ctx.cwd, cmdArgs)
       return r.ok ? truncate(r.out || `Archived ${args.ref ?? "HEAD"} to ${args.path}`) : truncate(`git archive failed: ${r.err || r.out}`)
     }
     case "blame": {
       if (!args.path) return "Error: blame requires path (file)"
-      const out = runGit(ctx.cwd, ["blame", "--", args.path])
+      const out = await runGit(ctx.cwd, ["blame", "--", args.path])
       return truncate(out || `(no blame output for ${args.path})`)
     }
     case "mv": {
       if (!args.path || !args.dest) return "Error: mv requires path (source) and dest (destination)"
-      const r = runGitStrict(ctx.cwd, ["mv", "--", args.path, args.dest])
+      const r = await runGitStrict(ctx.cwd, ["mv", "--", args.path, args.dest])
       return r.ok ? truncate(r.out || `Moved ${args.path} → ${args.dest}`) : truncate(`git mv failed: ${r.err || r.out}`)
     }
     default: