@thincoder/core 0.9.1

package/skills.mjs

@@ -0,0 +1,234 @@
+/**
+ * skills.mjs — skill system
+ * Discovers .md skill files AND subdirectory SKILL.md from .thincoder/skills/ directory,
+ * injects into system prompt for agent to load on demand.
+ * Use the skill tool to activate a specific skill; content is written into conversation history wrapped in <skill-loaded>.
+ *
+ * Supported formats:
+ *   .thincoder/skills/my-skill.md           (flat, name = "my-skill")
+ *   .thincoder/skills/my-skill/SKILL.md     (subdirectory, name = "my-skill")
+ */
+
+import { readFile, readdir, stat } from "node:fs/promises"
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { join } from "node:path"
+import { homedir } from "node:os"
+
+/** Valid skill name pattern (alphanumeric + hyphens/underscores) */
+const NAME_RE = /^[a-zA-Z0-9_-]+$/
+
+/**
+ * Try to read a skill from a path, return { name, path, description } or null.
+ */
+async function tryReadSkill(dir, name, filePath) {
+  try {
+    const s = await stat(filePath)
+    if (!s.isFile()) return null
+    const head = await readFile(filePath, "utf8")
+    const body = head.slice(0, 400).split("\n")
+    let desc = ""
+    let inFrontmatter = false
+    for (const line of body) {
+      const t = line.trim()
+      if (t === "---") { inFrontmatter = !inFrontmatter; continue }
+      if (inFrontmatter) continue
+      if (t && !t.startsWith("#")) {
+        desc = t.slice(0, 120)
+        break
+      }
+    }
+    return { name, path: filePath, description: desc || "(no description)" }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Scan a single skills directory, return skill list.
+ * Supports flat .md files and subdirectories with SKILL.md inside.
+ * Each skill: { name, path, description } — name derived from filename or directory.
+ * Returns empty array if directory is missing or empty.
+ */
+async function loadSkillsFromDir(dir) {
+  let entries
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+    // Deterministic order: readdir order is filesystem-dependent; an unsorted scan would
+    // reshuffle the skills listing → system prompt byte change with zero content change
+    // (2026-08-16 cache audit — that silently misses the provider prefix cache).
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+  } catch {
+    return []
+  }
+  const skills = []
+  const added = new Set()
+
+  // Pass 1: subdirectories (higher priority — standard convention)
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    if (!NAME_RE.test(entry.name)) continue
+    const skill = await tryReadSkill(dir, entry.name, join(dir, entry.name, "SKILL.md"))
+    if (skill) { skills.push(skill); added.add(entry.name) }
+  }
+
+  // Pass 2: flat .md files (backward compat; skipped if subdirectory with same name exists)
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const m = entry.name.match(/^([a-zA-Z0-9_-]+)\.md$/)
+    if (!m) continue
+    const name = m[1]
+    if (added.has(name)) continue
+    const skill = await tryReadSkill(dir, name, join(dir, entry.name))
+    if (skill) { skills.push(skill); added.add(name) }
+  }
+  return skills
+}
+
+/**
+ * Scan both project-level and user-level skills directories.
+ * Project-level skills (cwd/.thincoder/skills/) take priority over user-level (~/.thincoder/skills/).
+ * Returns merged skill list with project-level skills first.
+ */
+export async function loadSkills(cwd) {
+  const projectDir = join(cwd, ".thincoder", "skills")
+  const userDir = join(homedir(), ".thincoder", "skills")
+  
+  // Load project-level skills first (higher priority)
+  const projectSkills = await loadSkillsFromDir(projectDir)
+  const added = new Set(projectSkills.map(s => s.name))
+  
+  // Load user-level skills, skipping duplicates
+  const userSkills = await loadSkillsFromDir(userDir)
+  for (const skill of userSkills) {
+    if (!added.has(skill.name)) {
+      projectSkills.push(skill)
+      added.add(skill.name)
+    }
+  }
+  
+  return projectSkills
+}
+
+/**
+ * Generate skill listing text for system prompt injection.
+ * At most 3 (small footprint); overflow marked "... and N more".
+ * Prefixed with DISREGARD: when listing refreshes (skills added/removed), old listings are auto-invalidated without needing to delete history (inspired by kimi-code).
+ */
+export function formatSkillListing(skills) {
+  if (skills.length === 0) return ""
+  const listed = skills.slice(0, 3)
+  const lines = listed.map((s) => `- **${s.name}**: ${s.description}`)
+  if (skills.length > 3) lines.push(`  ... and ${skills.length - 3} more`)
+  return "DISREGARD any earlier skill listings. Current available skills (use the skill tool to load one):\n" + lines.join("\n")
+}
+
+/**
+ * Read the full content of a specific skill file.
+ * Tries project-level directory first, then user-level directory.
+ * For each directory, tries subdirectory format (name/SKILL.md) first, then flat format (name.md).
+ * Returns text, or null if not found.
+ */
+export async function readSkill(cwd, name) {
+  if (!NAME_RE.test(name)) return null
+
+  const dirs = [
+    join(cwd, ".thincoder", "skills"),
+    join(homedir(), ".thincoder", "skills")
+  ]
+
+  for (const baseDir of dirs) {
+    // Try subdirectory format: name/SKILL.md
+    try {
+      const p = join(baseDir, name, "SKILL.md")
+      return await readFile(p, "utf8")
+    } catch { /* not found, try flat */ }
+
+    // Fallback to flat format: name.md
+    try {
+      const p = join(baseDir, `${name}.md`)
+      return await readFile(p, "utf8")
+    } catch { /* not found, try next directory */ }
+  }
+  
+  return null
+}
+
+// ─── 同步 loader 面（#88——「同步 loader 面按核内结构归一」）────────────────────────────
+// 语义与上方异步面**逐条同源**：同发现规则（扁平 `.md` + 子目录 `SKILL.md`）· 同排序
+// （localeCompare——前缀缓存要求确定性）· 同层级优先（项目层 → 用户层，按名去重）。
+// 端侧接核后若仍需同步面，直接用本面（不再自持副本——单一结构）。
+
+/** 同步版读取单个 skill 条目（描述提取规则同异步 tryReadSkill）。 */
+function tryReadSkillSync(name, filePath) {
+  try {
+    const s = statSync(filePath)
+    if (!s.isFile()) return null
+    const head = readFileSync(filePath, "utf8")
+    const body = head.slice(0, 400).split("\n")
+    let desc = ""
+    let inFrontmatter = false
+    for (const line of body) {
+      const t = line.trim()
+      if (t === "---") { inFrontmatter = !inFrontmatter; continue }
+      if (inFrontmatter) continue
+      if (t && !t.startsWith("#")) { desc = t.slice(0, 120); break }
+    }
+    return { name, path: filePath, description: desc || "(no description)" }
+  } catch {
+    return null
+  }
+}
+
+/** 同步版扫描单目录（Pass1 子目录 → Pass2 扁平；排序 / 去重规则同异步 loadSkillsFromDir）。 */
+function loadSkillsFromDirSync(dir) {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+  } catch {
+    return []
+  }
+  const skills = []
+  const added = new Set()
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    if (!NAME_RE.test(entry.name)) continue
+    const skill = tryReadSkillSync(entry.name, join(dir, entry.name, "SKILL.md"))
+    if (skill) { skills.push(skill); added.add(entry.name) }
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const m = entry.name.match(/^([a-zA-Z0-9_-]+)\.md$/)
+    if (!m) continue
+    const name = m[1]
+    if (added.has(name)) continue
+    const skill = tryReadSkillSync(name, join(dir, entry.name))
+    if (skill) { skills.push(skill); added.add(name) }
+  }
+  return skills
+}
+
+/** 同步 loader（项目层优先 → 用户层；返回形态与异步 loadSkills 等价）。 */
+export function loadSkillsSync(cwd) {
+  const skills = loadSkillsFromDirSync(join(cwd, ".thincoder", "skills"))
+  const added = new Set(skills.map((s) => s.name))
+  for (const skill of loadSkillsFromDirSync(join(homedir(), ".thincoder", "skills"))) {
+    if (!added.has(skill.name)) { skills.push(skill); added.add(skill.name) }
+  }
+  return skills
+}
+
+/** 同步 readSkill（name 校验 + `name/SKILL.md` → `name.md`，项目层 → 用户层——同异步）。 */
+export function readSkillSync(cwd, name) {
+  if (!NAME_RE.test(name)) return null
+  for (const baseDir of [join(cwd, ".thincoder", "skills"), join(homedir(), ".thincoder", "skills")]) {
+    for (const filePath of [join(baseDir, name, "SKILL.md"), join(baseDir, `${name}.md`)]) {
+      try {
+        if (statSync(filePath).isFile()) return readFileSync(filePath, "utf8")
+      } catch { /* try the next candidate */ }
+    }
+  }
+  return null
+}

package/text-budget.mjs

@@ -0,0 +1,79 @@
+/**
+ * text-budget.mjs — 文本额度纯函数（零依赖——TUI-OOM-ROOTCAUSE 批，AGENT-LOOP.md §23.3.1 / TUI.md §15.3.2）。
+ *
+ * 单一来源（D2）：agent 侧捕获截断（spawn-child.mjs——子代理 `_capturedOutput`）与 TUI 面
+ * 载体额度（tui/display-budget.mjs）共用本体的 `capText` / `appendCappedText`——两处各自
+ * 复制截断逻辑的漂移面被消除。本模块零 import（可被任意层直接引用）。
+ *
+ * 计量口径 = **UTF-16 码元**（`String.length`——与 JS 字符串内存近似、确定、O(1) 计长；
+ * TUI.md §15.2 表 1）。截断形态 = 头保 + 中段标记 + 尾保（标记含真实省略数 N）。
+ *
+ * 标记串约定：`marker` 模板中以字面 `N` 为省略数占位（逐字进测试断言——如
+ * `… [captured output truncated: N chars omitted] …`）。
+ */
+
+/** 省略数占位符替换（首个 `N`——模板约定；TUI 面 capLines 等复用）。 */
+export function fillMarker(marker, omitted) {
+  if (typeof marker === "function") return String(marker(omitted))
+  const tpl = String(marker ?? "")
+  const i = tpl.indexOf("N")
+  return i === -1 ? `${tpl} (${omitted} omitted)` : `${tpl.slice(0, i)}${omitted}${tpl.slice(i + 1)}`
+}
+
+/**
+ * 头尾保真截断：`text` ≤ `max` 时零拷贝原样返回；超限 → 头 `keepHead` + 标记 + 尾 `keepTail`。
+ * keepHead/keepTail 各自夹紧到文本长度（互不重叠——头 + 尾 ≤ 文本长）。
+ * @returns {string} 原串或截断串（含 `marker` 替换后的省略数）
+ */
+export function capText(text, { max, keepHead = 0, keepTail = 0, marker = "" } = {}) {
+  const t = String(text ?? "")
+  if (!(max > 0) || t.length <= max) return t
+  const head = Math.max(0, Math.min(keepHead, t.length))
+  const tail = Math.max(0, Math.min(keepTail, t.length - head))
+  const omitted = t.length - head - tail
+  return t.slice(0, head) + fillMarker(marker, omitted) + (tail > 0 ? t.slice(t.length - tail) : "")
+}
+
+/**
+ * 流式累积（滞后水位——摊还 O(1)）：`prev + add`；超 `hard` 时立即裁至
+ * 头 `head` + 标记 + 尾 `tail`（下一轮从截断值继续累积——稳态长度 ≤ hard）。
+ * @returns {string} 合并（可能已截断）的累积串
+ */
+export function appendCappedText(prev, add, { hard, head = 0, tail = 0, marker = "" } = {}) {
+  const merged = String(prev ?? "") + String(add ?? "")
+  if (!(hard > 0) || merged.length <= hard) return merged
+  return capText(merged, { max: hard, keepHead: head, keepTail: tail, marker })
+}
+
+/**
+ * UTF-16 safe HEAD slice（§2.5 #76 / #164 并入——VSC 侧实现归位；VSC 与 CLI 两处独立实现
+ * 的安全规则一致）：plain `slice(0, N)` cuts BY UTF-16 CODE UNIT —— a surrogate pair
+ * straddling the boundary leaves a LONE high surrogate (U+D800-DBFF) that strict UTF-16
+ * decoders reject. When the cut point lands on a high surrogate, step back one code unit
+ * (the pair is dropped whole).
+ */
+export function safeSliceUTF16(text, max) {
+  const t = String(text ?? "")
+  if (t.length <= max) return t
+  const cp = t.charCodeAt(max - 1)
+  if (cp >= 0xd800 && cp <= 0xdbff) return t.slice(0, max - 1)
+  return t.slice(0, max)
+}
+
+/**
+ * UTF-16 safe TAIL slice（safeSliceUTF16 的对称面——§2.5 #164 并入）。两个切点都要安全：
+ *  - START：孤立低代理（U+DC00-DFFF）= 代理对被切开 ⇒ 前进一码元（整对丢弃）；
+ *  - END（原文末尾）：末尾孤立高代理（U+D800-DBFF）也去掉——尾切片不得新增头切片规则
+ *    同样要避开的孤立代理（VSC 侧强化形态，随融合并入）。
+ */
+export function safeSliceUTF16Tail(text, max) {
+  const t = String(text ?? "")
+  if (t.length <= max) return t
+  let start = t.length - max
+  const first = t.charCodeAt(start)
+  if (first >= 0xdc00 && first <= 0xdfff) start += 1 // 起点落低代理 → 丢弃代理对整体（向前一码元）
+  let tail = t.slice(start)
+  const last = tail.charCodeAt(tail.length - 1)
+  if (last >= 0xd800 && last <= 0xdbff) tail = tail.slice(0, -1) // 终点孤立高代理 → 去掉（截断边界安全）
+  return tail
+}

package/token-ttl.mjs

@@ -0,0 +1,285 @@
+/**
+ * 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。
+ *  #154（VSC 侧并入——`reconcileEngDesignTokens` 的**清理方向**）：内存中的过期项先清（过期项在
+ *  任何门禁都过不了 tokenExpired——清掉不改变授权结果，仅防槽计数/落盘被死 token 撑大）。
+ *  **与 VSC 版的两处有意差异（如实登记，非偏差）**：① 同 id 冲突以**槽为准**（本函数下段
+ *  `merged.set`——D2「槽 = 权威」；VSC 版为内存优先）；② VSC 的 `droppedExpired` 有当场权威
+ *  台账回写一步（`setSlotEngDesignTokens`），本形态回写为**惰性**（下一次 `persistEngTokens` /
+ *  `saveSession` 携带清理后的 Map）。 */
+export function reconcileEngTokensFromSlot(agent) {
+  const slots = agent?._engDesignTokens
+  if (slots instanceof Map) {
+    for (const [id, t] of [...slots]) {
+      if (typeof t === "string" && tokenExpired(t)) slots.delete(id)
+    }
+  }
+  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/tool-docs/apply_patch.md

@@ -0,0 +1,15 @@
+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/tool-docs/bash.md

@@ -0,0 +1,38 @@
+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`.
+{{inject:bash-terminal-face}}
+
+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/tool-docs/delete.md

@@ -0,0 +1,13 @@
+Delete a file. Use when the agent created a temporary or junk file that should be cleaned up, or when the user explicitly asks to delete something. Refuses to delete git-tracked files as a safety measure — tracked files should be edited or removed via bash with explicit user confirmation.
+
+**Route to delete instead of bash:** `del file` / `rm file` → delete (single files). Use bash `rm -rf` only for directories (delete is single-file).
+
+Parameters:
+- path (required): File path, relative to cwd or absolute
+- force: Allow deleting git-tracked files (default false)
+
+Notes:
+- Untracked or non-git files are deleted immediately
+- Tracked files require force=true (user must confirm separately)
+- Directories must be removed with bash (rm -rf)
+- Returns `Deleted <path>` (or `Error: ...` on failure/tracked refusal).