@thincoder/core 0.9.2 → 0.9.3

package/session-index.mjs

@@ -0,0 +1,285 @@
+/**
+ * session-index.mjs — 会话派生索引库：打开 / DDL / schema / 行写入原语 / 测试缝（SESSION.md §6.19）。
+ *
+ * 机制契约全文 = `docs/core/design/SESSION.md` §6.19（D-SE43–D-SE47；D2 单一权威源）。
+ * 本档 = 「DB 打开 / DDL / schema / 测试缝」面；查询与 FTS 检索 = `session-index-query.mjs`；
+ * 写面（枚举 / 水位增量 / 会话重建 / 延迟拍 / 清行）= `session-index-build.mjs` +
+ * `session-index-pass.mjs`（>300 软线按设计「跨档线拆分预案」二分）；命令面 = `session-index-cmd.mjs`。
+ *
+ * **零权威**：主存（槽 JSON + `{槽}.d/` sidecar + manifest）= 真源；本库只读主存（整读 / 偏移
+ * `readSync`），**绝不写回** sessions 树；库丢 / 坏 = 重生成（D-SE46 打开即验 + 改名保留自愈）。
+ * **零第三方依赖**：仅 `node:` + 仓内相对 import（FTS5 同装配先例 = `memory/schema.mjs`）。
+ * 本档静态 import `node:sqlite` ⇒ **消费侧一律动态 import**（W8 契约②——`ledger-db.mjs` 同款：
+ * 静态 import 会把 node:sqlite 拉进 `read_history` 的装配期静态闭包）。
+ */
+import { DatabaseSync } from "node:sqlite"
+import { existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { configDir } from "./config-io.mjs"
+import { segmentCJK } from "./fts-text.mjs"
+
+/** 库名（单库——与 `memory.db` 同区 `~/.thincoder/`；D-SE43）。 */
+export const SESSION_INDEX_DB_NAME = "session-index.db"
+/** schema 版本（`index_meta.v` 不符 ⇒ 重建——不做迁移；D-SE46）。 */
+export const SESSION_INDEX_SCHEMA_VERSION = "1"
+/** 多进程（CLI + VSC 同启）竞争：WAL + busy_timeout（`memory/schema.mjs` 同值）。 */
+export const SESSION_INDEX_BUSY_TIMEOUT = 3000
+/** 水位 `tail_hash` 窗口 = 末段尾 4KB（D-SE45——等长改写检出）。 */
+export const TAIL_HASH_BYTES = 4096
+/** `tool_calls` 输出上限（= 存储面同值——`slimForDisplay` 截断面即精度上限；D-SE47）。 */
+export const ARG_MAX_CHARS = 300
+/** 延迟拍预算（D-SE45 触发点②：单趟 ≤ 2000ms 且 ≤ 40 会话）。 */
+export const INDEX_PASS_BUDGET_MS = 2000
+export const INDEX_PASS_MAX_SESSIONS = 40
+/** 查询窗口缺省 / 上限（与 read_history 参数面同值：缺省 50 / 上限 200）。 */
+export const DEFAULT_QUERY_LIMIT = 50
+export const MAX_QUERY_LIMIT = 200
+
+// ── 测试缝（`_setLedgerDirForTest` 同款：测试不碰真实用户目录）─────────────────
+let indexDirOverride = null
+export function _setSessionIndexDirForTest(dir) { indexDirOverride = dir }
+export function _resetSessionIndexDirForTest() { indexDirOverride = null }
+export function sessionIndexDir() { return indexDirOverride ?? configDir }
+export function sessionIndexDbPath() { return join(sessionIndexDir(), SESSION_INDEX_DB_NAME) }
+
+/** DDL（四表 + FTS + 元表；`UNIQUE(sid, idx)` 兼作查询主索引——同列序不重复建；D-SE44）。 */
+export const SESSION_INDEX_DDL = `
+CREATE TABLE IF NOT EXISTS sessions (
+  id INTEGER PRIMARY KEY,
+  cwd_key TEXT NOT NULL,
+  slot INTEGER NOT NULL,
+  file TEXT NOT NULL,
+  cwd TEXT,
+  title TEXT,
+  identity TEXT,
+  src TEXT NOT NULL,
+  updated_at INTEGER,
+  indexed_at INTEGER,
+  seg_n INTEGER NOT NULL DEFAULT 0,
+  seg_bytes INTEGER NOT NULL DEFAULT 0,
+  seg_mtime REAL NOT NULL DEFAULT 0,
+  tail_hash TEXT NOT NULL DEFAULT '',
+  UNIQUE(cwd_key, slot)
+);
+CREATE TABLE IF NOT EXISTS messages (
+  rowid INTEGER PRIMARY KEY,
+  sid INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  idx INTEGER NOT NULL,
+  seg INTEGER NOT NULL,
+  ts INTEGER,
+  role TEXT,
+  name TEXT,
+  tool_call_id TEXT,
+  content TEXT NOT NULL DEFAULT '',
+  UNIQUE(sid, idx)
+);
+CREATE INDEX IF NOT EXISTS messages_ts ON messages(ts);
+CREATE INDEX IF NOT EXISTS messages_name ON messages(name);
+CREATE TABLE IF NOT EXISTS tool_calls (
+  id INTEGER PRIMARY KEY,
+  sid INTEGER NOT NULL,
+  msg_idx INTEGER NOT NULL,
+  ord INTEGER NOT NULL,
+  call_id TEXT,
+  name TEXT,
+  args TEXT,
+  UNIQUE(sid, msg_idx, ord)
+);
+CREATE INDEX IF NOT EXISTS tool_calls_name ON tool_calls(name);
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(seg_content, seg_name, tokenize='unicode61');
+CREATE TABLE IF NOT EXISTS index_meta (k TEXT PRIMARY KEY, v TEXT);
+`
+
+function openRaw(path) {
+  const db = new DatabaseSync(path)
+  try {
+    db.exec(`PRAGMA journal_mode = WAL`)
+    db.exec(`PRAGMA busy_timeout = ${SESSION_INDEX_BUSY_TIMEOUT}`)
+    db.exec(`PRAGMA foreign_keys = ON`)
+    db.exec(SESSION_INDEX_DDL)
+    const v = readMeta(db, "v")
+    if (v !== null && v !== SESSION_INDEX_SCHEMA_VERSION) throw new Error(`session index schema ${v} ≠ ${SESSION_INDEX_SCHEMA_VERSION}`)
+    if (v === null) {
+      writeMeta(db, "v", SESSION_INDEX_SCHEMA_VERSION)
+      writeMeta(db, "built_at", Date.now())
+    }
+  } catch (e) {
+    // 失败句柄必须关闭：Windows 上未关闭的句柄会让改名失败（现场保留 + 新建两步都落空）
+    try { db.close() } catch { /* ignore */ }
+    throw e
+  }
+  return db
+}
+
+/** 打开即验 + 开箱自愈（D-SE46）：缺失 ⇒ 建；打开 / DDL / 版本失败 ⇒ 现场改名
+ *  `session-index.db.corrupt-<epochms>`（连同 `-wal` / `-shm`——否则残 WAL 会挂到新库上）+ 新建空库。
+ *  仍失败（磁盘满 / 目录不可写 / 无 node:sqlite）⇒ **null = 静默降级**（查询回落主存路径，主存零险）。 */
+export function openSessionIndex({ path = sessionIndexDbPath() } = {}) {
+  try { mkdirSync(dirname(path), { recursive: true }) } catch { /* 已存在 / 并发建目录竞争 */ }
+  try { return openRaw(path) } catch { /* 缺失 / 坏库 / 版本不符 ⇒ 走自愈 */ }
+  const stamp = `${path}.corrupt-${Date.now()}`
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try { if (existsSync(path + suffix)) renameSync(path + suffix, stamp + suffix) } catch { /* 现场保留尽力面 */ }
+  }
+  try { return openRaw(path) } catch { return null }
+}
+
+/** 元表读 / 写（`v` = schema 版本 · `built_at` = 首建 / 全量重建时刻 · `pass_at` = **最近一次
+ *  实际写入（变更）时刻**（无源变的 pass 零写、不推进）· 计数快照）。 */
+export function readMeta(db, k) {
+  try {
+    const row = db.prepare("SELECT v FROM index_meta WHERE k = ?").get(k)
+    return row ? row.v : null
+  } catch { return null }
+}
+
+export function writeMeta(db, k, v) {
+  db.prepare("INSERT INTO index_meta (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v").run(k, String(v))
+}
+
+// ── 行形态（写入面与读出面共用同一口径）──────────────────────────────────────
+
+/** 消息文本（多模态数组取 text 部件拼接）。**与 `agent-tools/read-history.mjs` 的 JSON 面
+ *  `messageText` 同规则**——两面各自持有（索引面不得静态引 read-history 的装配面，反之亦然），
+ *  等价性由过滤矩阵对拍用例覆盖。 */
+export function messageText(m) {
+  if (typeof m?.content === "string") return m.content
+  if (Array.isArray(m?.content)) {
+    return m.content
+      .map((p) => (p && typeof p === "object" && p.type === "text" ? p.text ?? "" : ""))
+      .filter((t) => t.length > 0)
+      .join(" ")
+  }
+  return ""
+}
+
+/** 一次工具声明 → `{ name, args, call_id }`（`{function:{…}}` 与扁平两形兼容；`args` 逐字取存储串）。 */
+export function toolCallParts(tc) {
+  return {
+    call_id: tc?.id ?? null,
+    name: tc?.function?.name ?? tc?.name ?? "",
+    args: typeof tc?.function?.arguments === "string" ? tc.function.arguments
+      : typeof tc?.arguments === "string" ? tc.arguments : null,
+  }
+}
+
+/** 输出上限（= 存储面同值：≤300 原样，超限截 300 + `…`）。 */
+export function capArguments(s) {
+  const t = String(s ?? "")
+  return t.length <= ARG_MAX_CHARS ? t : t.slice(0, ARG_MAX_CHARS) + "…"
+}
+
+// ── 删除面单点（FTS 同删义务——无触发器：四条删除路径全部经此函数，同事务内同步删；§6.19）──
+
+/** 删行单点：`fromIdx = null` ⇒ 整会话（消息 + FTS + 工具声明 + 会话行）；给定 `fromIdx` ⇒ 区间
+ *  （`idx >= fromIdx` 的消息 / FTS 与 `msg_idx >= fromIdx` 的声明——段重写 / 重扫面）。 */
+export function deleteSessionRows(db, sid, { fromIdx = null } = {}) {
+  const range = fromIdx === null ? "" : " AND idx >= ?"
+  const mArgs = fromIdx === null ? [sid] : [sid, fromIdx]
+  const tRange = fromIdx === null ? "" : " AND msg_idx >= ?"
+  db.prepare(`DELETE FROM messages_fts WHERE rowid IN (SELECT rowid FROM messages WHERE sid = ?${range})`).run(...mArgs)
+  db.prepare(`DELETE FROM tool_calls WHERE sid = ?${tRange}`).run(...mArgs)
+  db.prepare(`DELETE FROM messages WHERE sid = ?${range}`).run(...mArgs)
+  if (fromIdx === null) db.prepare(`DELETE FROM sessions WHERE id = ?`).run(sid)
+}
+
+/** 单会话清行（源消失面——单事务；幂等）：删四表该会话行 + 推进 `pass_at`
+ *  （查询侧据此走回落路径——既有 `session file not found` 文案逐字保留）。 */
+export function dropSessionRows(db, sid, now = Date.now()) {
+  db.exec("BEGIN IMMEDIATE")
+  try {
+    deleteSessionRows(db, sid, { fromIdx: null })
+    writeMeta(db, "pass_at", now)
+    db.exec("COMMIT")
+  } catch (e) {
+    try { db.exec("ROLLBACK") } catch { /* ignore */ }
+    throw e
+  }
+}
+
+/** `--rebuild` 面：清四表（单事务）+ 刷新 `built_at`。 */
+export function clearIndex(db) {
+  db.exec("BEGIN IMMEDIATE")
+  try {
+    db.exec("DELETE FROM messages_fts")
+    db.exec("DELETE FROM tool_calls")
+    db.exec("DELETE FROM messages")
+    db.exec("DELETE FROM sessions")
+    writeMeta(db, "built_at", Date.now())
+    db.exec("COMMIT")
+  } catch (e) {
+    try { db.exec("ROLLBACK") } catch { /* 回滚尽力面 */ }
+    throw e
+  }
+}
+
+// ── 会话行 / 消息行 / 声明行写入 ─────────────────────────────────────────────
+
+export function findSessionByFile(db, file) {
+  try { return db.prepare("SELECT * FROM sessions WHERE file = ?").get(file) ?? null } catch { return null }
+}
+
+export function findSessionByCwdSlot(db, cwdKey, slot) {
+  try { return db.prepare("SELECT * FROM sessions WHERE cwd_key = ? AND slot = ?").get(cwdKey, slot) ?? null } catch { return null }
+}
+
+/** 建会话行（返回 sid）；同 `(cwd_key, slot)` 已占 ⇒ 先摘旧行（槽号回收 / 轮转 / 本行重建面——
+ *  新旧行不混，`UNIQUE(cwd_key, slot)` 零冲突）。 */
+export function insertSession(db, row) {
+  const old = findSessionByCwdSlot(db, row.cwd_key, row.slot)
+  if (old) deleteSessionRows(db, old.id, { fromIdx: null })
+  const r = db.prepare(
+    `INSERT INTO sessions (cwd_key, slot, file, cwd, title, identity, src, updated_at, indexed_at, seg_n, seg_bytes, seg_mtime, tail_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(row.cwd_key, row.slot, row.file, row.cwd ?? null, row.title ?? null, row.identity ?? null, row.src,
+    row.updated_at ?? null, row.indexed_at ?? null, row.seg_n ?? 0, row.seg_bytes ?? 0, row.seg_mtime ?? 0, row.tail_hash ?? "")
+  return Number(r.lastInsertRowid)
+}
+
+/** 会话级元数据 / 水位推进（单语句——写面在同一事务内调用）。 */
+export function updateSession(db, sid, patch) {
+  const cols = ["cwd", "title", "identity", "src", "updated_at", "indexed_at", "seg_n", "seg_bytes", "seg_mtime", "tail_hash"]
+  const set = cols.filter((c) => patch[c] !== undefined)
+  if (set.length === 0) return
+  db.prepare(`UPDATE sessions SET ${set.map((c) => `${c} = ?`).join(", ")} WHERE id = ?`).run(...set.map((c) => patch[c]), sid)
+}
+
+/** 插消息行（连同 FTS 行——同事务）。`rows` = `{ idx, seg, ts, role, name, tool_call_id, content }`。 */
+export function insertMessages(db, sid, rows) {
+  const msg = db.prepare(`INSERT INTO messages (sid, idx, seg, ts, role, name, tool_call_id, content) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+  const fts = db.prepare(`INSERT INTO messages_fts (rowid, seg_content, seg_name) VALUES (?, ?, ?)`)
+  for (const r of rows) {
+    const info = msg.run(sid, r.idx, r.seg, r.ts ?? null, r.role ?? null, r.name ?? null, r.tool_call_id ?? null, r.content ?? "")
+    fts.run(Number(info.lastInsertRowid), segmentCJK(r.content ?? ""), segmentCJK(r.name ?? ""))
+  }
+}
+
+/** 插声明行（`ord` = 该消息内声明序；`args` = 存储串逐字）。 */
+export function insertToolCalls(db, sid, rows) {
+  const stmt = db.prepare(`INSERT INTO tool_calls (sid, msg_idx, ord, call_id, name, args) VALUES (?, ?, ?, ?, ?, ?)`)
+  for (const r of rows) stmt.run(sid, r.msg_idx, r.ord, r.call_id ?? null, r.name ?? "", r.args ?? null)
+}
+
+/** `--status` 读数（行数 / 取源分布 / 库字节 / 水位覆盖 / 上次变更时刻）。 */
+export function indexSummary(db, { path = sessionIndexDbPath() } = {}) {
+  const one = (sql) => { try { return Number(Object.values(db.prepare(sql).get())[0] ?? 0) } catch { return 0 } }
+  let bytes = 0
+  try { bytes = statSync(path).size } catch { /* 库不在 / 不可读 ⇒ 0 */ }
+  return {
+    sessions: one("SELECT COUNT(*) FROM sessions"),
+    sidecar: one("SELECT COUNT(*) FROM sessions WHERE src = 'sidecar'"),
+    json: one("SELECT COUNT(*) FROM sessions WHERE src = 'json'"),
+    messages: one("SELECT COUNT(*) FROM messages"),
+    toolCalls: one("SELECT COUNT(*) FROM tool_calls"),
+    bytes,
+    builtAt: Number(readMeta(db, "built_at") ?? 0),
+    passAt: Number(readMeta(db, "pass_at") ?? 0),
+  }
+}
+
+/** 库侧清理（测试收尾 / 现场重置）：删库文件三件套（含 WAL / SHM）。 */
+export function removeIndexFiles(path = sessionIndexDbPath()) {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try { rmSync(path + suffix, { force: true }) } catch { /* 尽力面 */ }
+  }
+}

package/session-slots-manifest.mjs

@@ -289,6 +289,25 @@ export function claimSlot(cwd, slot, m = loadManifest(cwd), deadParam = null) {
   saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true, release: [slot] })
 }
 
+/** 退出全释放（EXIT-CLAIM-RELEASE 批 · F-XR1 · SESSION.md §6.18 D-SE41）：优雅退出前释放
+ *  本进程**全部**槽认领（保留集空——`staleClaims` 释放谓词单源）；落盘判据 = `saveManifest`
+ *  `opts.release` 三条自动继承（fresh 同次快照取释放集 / 值条件删除——他人窗口内新认领不误删 /
+ *  内存认领表同步移除）。**零触碰 marker 面**（F-XR2 路标保留——下次启动经 `usableSlot`
+ *  无属主短路零探测直达恢复）；崩溃路径不经此（信号无 JS 钩子——F-XR3）。
+ *  早退面：磁盘无 manifest ⇒ `existsSync` 单条目早退**零写**（不造盘面）；本进程无认领 ⇒
+ *  零写返回 false。失败容忍（F-XR1「退出恒达」）：整体 try/catch **永不抛出**，返回 boolean
+ *  （true = 有释放且落盘成功；false = 早退 / 失败——断言面）；写失败盘面 = 认领残留 →
+ *  恢复走既有探测面（现状形态，数据零险）。 */
+export function releaseClaimsAll(cwd) {
+  try {
+    if (!existsSync(manifestPath(cwd))) return false // 无 manifest ⇒ 零写（不造盘面）
+    const m = loadManifest(cwd)
+    if (staleClaims(m, []).length === 0) return false // 无本进程认领 ⇒ 零写（免白刷共享 sessionId）
+    saveManifest(cwd, m, null, { release: [] }) // 保留集空 = 全释放；不 setActive（active 共享指针不动）
+    return true
+  } catch { return false } // F-XR1：退出恒达（写失败 = 认领残留 → 恢复走探测面）
+}
+
 /** Return the active slot number for this process, claiming one if necessary */
 export function activeSlot(cwd) {
   const m = loadManifest(cwd)

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