@thincoder/core 0.9.5 → 0.10.1

package/agent-tools/read-history.mjs

@@ -44,6 +44,8 @@
 import { openSync, readSync, closeSync, readFileSync, existsSync, statSync } from "node:fs"
 import { isAbsolute, resolve } from "node:path"
 import { listSlots, slotPath } from "../session-slots.mjs"
+// #15 描述外置：描述文本单点 = tool-docs/read_history.md（DESC 单解析面，缺档抛错语义不变）
+import { DESC } from "../tools/shared.mjs"
 
 const DEFAULT_LIMIT = 50
 const MAX_LIMIT = 200
@@ -63,9 +65,6 @@ export const READ_HISTORY_MAX_MESSAGES = 50_000
 /** 超限错误文案（SESSION.md §6.13——逐字定稿——T-R19.7 断言）。 */
 const TOO_LARGE_ERROR = JSON.stringify({ error: "session too large — refine keyword or since/until" })
 
-/** 检索/记忆族消歧总纲（SESSION.md §6.13 D-R19b——逐字定稿——read_history 描述尾段——T-R19.5 锚）。 */
-const SEARCH_FAMILY_GUIDE =
-  "检索/记忆族选哪个：查**本会话**说过/裁定过 → read_history（默认）；查**别的会话/项目**旧对话 → read_history 带 path/cwd 参数；查**本 run 改过哪些文件** → recent_changes；查**跨会话已存知识/约定**（memory）→ memory search；查**项目设计文档** → doc_search；查**代码实现** → code_search；查 git 历史快照 → checkpoint cat/versions。read_history 只查会话消息——文件级改动用 recent_changes——知识与约定用 memory——互相不替代。"
 
 /** Message text for keyword matching + output: strings pass through; multimodal content arrays → text parts joined (never crashes, empty parts skipped, images ignored). */
 function messageText(m) {
@@ -219,7 +218,8 @@ function querySessionFile(pathArg, { role, kwRe, tool, since, until, direction,
 
 /** Discovery surface (path = "cwd:<dir>"): list every slot stored for that directory, one line
  *  per slot — slot number + FULL session file path + title/message count/updatedAt（§6.13 D-R19a
- *  ——评审 #2：摘要必须含寻址字段——模型第二步深查 = 复制行内文件路径重调 path=）。 */
+ *  ——评审 #2：摘要必须含寻址字段——模型第二步深查 = 复制行内文件路径重调 path=）。
+ *  计数不可得 = `null` ⇒ `messages: —`（§6.25 判据句 4——禁显示数值 0：真 0 与未知可分）。 */
 function discoverCwd(raw, baseCwd) {
   const dir = resolve(baseCwd ?? process.cwd(), raw)
   let st = null
@@ -235,7 +235,7 @@ function discoverCwd(raw, baseCwd) {
   }
   const lines = slots.map((s) => {
     const title = s.title ? `"${s.title}"` : "(untitled)"
-    return `slot ${s.slot}: ${slotPath(dir, s.slot)} — title: ${title}, messages: ${s.messageCount}, updatedAt: ${s.updatedAt}`
+    return `slot ${s.slot}: ${slotPath(dir, s.slot)} — title: ${title}, messages: ${s.messageCount ?? "—"}, updatedAt: ${s.updatedAt}`
   })
   return `Session slots for cwd: ${dir} (newest first):\n${lines.join("\n")}`
 }
@@ -310,34 +310,18 @@ async function queryAllSessions(filters, current = null) {
 
 export const readHistoryTool = {
   name: "read_history",
-  description:
-    "Query message history — THIS session by default, any session on disk with `path`. " +
-    "Default (no path): THIS session's full record (never compacted, audit-complete) — recall what " +
-    "was said or done earlier: design decisions, tool-call timing, past rulings. " +
-    "Filters combine with AND: role / keyword (case-insensitive substring of message text) / " +
-    "tool (tool result messages by name AND the assistant messages that declared the call — pair with tool_call_id / ts for timing) / " +
-    "since-until (epoch ms time window; only messages with ts can match) / limit (default 50, clamped to 200) / direction (which end of the matches to take). " +
-    "Returns a JSON array in chronological order: [{ts, role, name?, tool_call_id?, content (≈500 chars, truncated marker), tool_calls ([{name, arguments}] — arguments capped at 300 chars)}]. " +
-    "Messages without ts return ts:null. Content is truncated — the full text is in the session file. " +
-    "Cross-session (path, optional): a session file path deep-queries THAT session's history with the same filters " +
-    "(relative paths resolve against the project cwd) — answered from the derived session index when it covers that session, " +
-    "otherwise from the session file itself (a file over 50,000 messages or 200,000 lines is refused as \"session too large\"). " +
-    "\"cwd:<dir>\" lists every session slot stored for that directory — one line per slot: slot number + full session file path + " +
-    "title + message count + updatedAt; copy a listed file path into path= to deep-query it. " +
-    "\"all\" searches EVERY INDEXED session at once (cross-project; keyword = FTS words / phrases; each row carries session.file for the follow-up deep query) — " +
-    "`all` covers the derived index only: sessions never indexed yet are invisible there (query them with path=<file>, or index everything first with the CLI `thincoder session index --rebuild`).\n" +
-    SEARCH_FAMILY_GUIDE,
+  description: DESC("read_history"),
   parameters: {
     type: "object",
     properties: {
       role: { type: "string", enum: ["user", "assistant", "tool"], description: "Only messages with this role." },
-      keyword: { type: "string", description: "Case-insensitive substring of the message text (multimodal messages match on their text parts); with path=\"all\" it is matched as FTS words / phrases over the indexed text." },
-      tool: { type: "string", description: "Only messages for this tool: role=tool messages with name=tool, plus assistant messages that declared a call to it." },
-      since: { type: "integer", description: "Earliest ts to match, epoch ms, INCLUSIVE. Messages without ts never match a time window." },
-      until: { type: "integer", description: "Latest ts to match, epoch ms, INCLUSIVE. since > until yields an empty result." },
-      limit: { type: "integer", description: "Maximum messages to return (default 50; larger values are clamped to 200)." },
+      keyword: { type: "string", description: "Case-insensitive substring of the message text (multimodal matches on text parts); with path=\"all\" matched as FTS words / phrases." },
+      tool: { type: "string", description: "Only messages for this tool: role=tool messages with name=tool, plus assistant messages that declared a call to it (pair with tool_call_id / ts for timing)." },
+      since: { type: "integer", description: "Earliest ts to match, epoch ms, INCLUSIVE; messages without ts never match." },
+      until: { type: "integer", description: "Latest ts to match, epoch ms, INCLUSIVE; since > until yields empty." },
+      limit: { type: "integer", description: "Maximum messages to return (default 50; clamped to 200)." },
       direction: { type: "string", enum: ["oldest", "newest"], description: "Take the limit window from the oldest or newest end of the matched set (default newest)." },
-      path: { type: "string", description: "Optional — query another session instead of this one: a session file path (as listed by a \"cwd:<dir>\" call) deep-queries that session; \"cwd:<dir>\" lists that directory's session slots (slot number + full file path + title + message count + updatedAt); \"all\" searches every indexed session across projects (FTS words / phrases; rows carry session.file)." },
+      path: { type: "string", description: "Optional — another session instead of this one: a session file path deep-queries that session; \"cwd:<dir>\" lists that directory's session slots (slot + file path + title + count + updatedAt); \"all\" searches every indexed session across projects (FTS words / phrases; rows carry session.file)." },
     },
   },
   readonly: true,

package/agent-tools/recent-changes.mjs

@@ -3,13 +3,12 @@
  * More precise than git status — only looks at this session's changes, independent of git tracking.
  * Helps the model recall what it already modified during long tasks.
  */
+// 描述面 = `tool-docs/recent_changes.md`（#15 描述外置统一——DESC 单一解析面，与内置工具族同径）
+import { DESC } from "../tools/shared.mjs"
+
 export const recentChangesTool = {
   name: "recent_changes",
-  description:
-    "Show files modified in this agent run (write/edit/insert_after/delete). " +
-    "Use when you need to remember which files you've already touched — during long multi-file tasks, " +
-    "it's easy to lose track. This is scoped to the current run, unlike git status which shows all uncommitted changes. " +
-    "For session-level history (what was said in a session), use read_history.",
+  description: DESC("recent_changes"),
   parameters: {
     type: "object",
     properties: {},

package/agent-tools/review-facts.mjs

@@ -13,7 +13,7 @@
  */
 import { join } from "node:path"
 
-/** ABS 归一（cwd 相对 → cwd 拼接）——陈旧判定 / 冻结拦截 / 评审范围键同源（§14.14 E-4）。 */
+/** ABS 归一（cwd 相对 → cwd 拼接）——陈旧判定 / 冻结拦截 / 评审范围键同源（ADVISOR-GUARDS.md §5 E-4）。 */
 export function normAbs(p, cwd) {
   const s = String(p)
   return /^[a-zA-Z]:[\\/]/.test(s) || s.startsWith("/") || s.startsWith("\\\\") ? s : join(cwd, s)

package/agent-tools/settings.mjs

@@ -3,20 +3,27 @@
  * 用户裁定：全量 config.json 任意键（点分路径）+ 单工具多动作 list/get/set + 双端同批。
  * 语义：set = 写盘（config.json——磁盘真相最小化：只写被设的键——默认值不固化）+
  * 热应用（ctx.agent.config 内存对象立即更新——回合边界键下回合生效）。
- * 护栏：敏感键（路径段命中词表 apiKey/key/token/secret/password/authorization/auth/cookie/credential，
- * 或段名 headers/env 整族）回显/错误文本永不出现明文
+ * `null` = **显式清除 ⇒ 删键**（盘删键 + 内存回填 `DEFAULTS` 默认值——全端同形；SETTINGS-TOOL.md §2.3）。
+ * 护栏：敏感键（路径段命中词表 apiKey/key/token/secret/password/authorization/auth/cookie/credential
+ * （含**段内复合名**——`refreshToken` ∕ `clientSecret` ∕ `privateKey` 类 camelCase ∕ 前缀复合；
+ * #677 · I13），或段名 headers/env 整族）回显/错误文本永不出现明文
  * （••••（masked）——防密钥泄漏进会话历史/trace）；已知键类型校验——非 null 叶子类型表
  * 自动派生自 config.mjs DEFAULTS（不手写防漂移——F-S1.5/N-S1.5）；null 默认值键与同族键
  * 走显式形状表（_NULL_LEAF_SHAPES 相等面 / _SIBLING_SHAPES 存在性面——按各自真实消费形态
  * 校验，完备性机械锁 + 一次性警告；SETTINGS-TOOL.md §8）；set 侧效走审批门（dispatch 动作级分类）。
  */
 import { DEFAULTS, configPath, writeConfigAtomic } from "../config.mjs"
+import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/settings.md
 
-/** 敏感键段判定（完整点分路径的段级匹配——两句取或：词表段 ∨ 开口键族段；SETTINGS-TOOL.md §2.4） */
-const SENSITIVE_SEGMENT = /(^|[._-])(api[_-]?key|key|token|secret|password|authorization|auth|cookie|credential)($|[._-])/i
+/** 敏感键段判定（完整点分路径的段级匹配——两句取或：词表段 ∨ 开口键族段；SETTINGS-TOOL.md §2.4）。
+ *  #677 · I13（C2 裁定 · D-ST17）：段内复合敏感名入遮——词表句左界扩 `[a-z0-9]`（camelCase 复合，
+ *  `refreshToken` ∕ `clientSecret` ∕ `privateKey` 类）；右界仍须段界 ⇒ `maxTokens`（复数）∕
+ *  `tokenCount`（敏感词非末位）不误遮；假阳方向安全（只丢值、键名可见）。 */
+const SENSITIVE_SEGMENT = /(^|[._-]|[a-z0-9])(api[_-]?key|key|token|secret|password|authorization|auth|cookie|credential)($|[._-])/i
 /** 开口键族段判定（headers / env——段名命中 ⇒ 其下全部子键整族遮罩：头名 / 变量名不可枚举） */
 const SENSITIVE_FAMILY = /(^|[._-])(headers|env)($|[._-])/i
-const MASKED = "••••（masked）"
+/** 敏感键遮罩字面（**导出单源**——工具回显 ∕ 桌面 `settings-values.mjs` ∕ VSC `settings.mjs` 三端同源；B10 S13 转 export） */
+export const MASKED = "••••（masked）"
 
 /** #58（hygiene-sweep 批）：谓词/标记导出——CLI `/mcp` 表单现值脱敏同源（`cmd-mcp-form.mjs`）。 */
 export function isSensitiveKey(path) {
@@ -61,6 +68,10 @@ function _buildShapeTable(obj, patch = null) {
 }
 const TYPE_MAP = _buildShapeTable(DEFAULTS)
 
+/** #645 放行面扩族：`null`（显式清除——删键回退默认）可接受者 = `object`（既有）∪ `number` ∕
+ *  `boolean`（本批扩）；`string` 类维持拒（消费面无「未设置」态——如 `memory.dbPath`）。 */
+const _NULL_CLEARABLE = new Set(["object", "number", "boolean"])
+
 /** null 叶子路径枚举（数组不递归——与派生表同域）。 */
 function _nullLeafPaths(obj, prefix = "", out = []) {
   for (const [k, v] of Object.entries(obj)) {
@@ -129,7 +140,8 @@ function _checkShape(path, spec, value) {
  * 已知键值校验（set 写盘前；违例抛错——磁盘/内存零变化）：
  * ① 形状表命中键（`_NULL_LEAF_SHAPES` / `_SIBLING_SHAPES` **两表都查**——表值 = 形状规格）→ 形状校验
  *    （`null` = 显式清除，放行）；② 非 null 叶子（派生表值 = `typeof` 串）→ 既有语义逐字保留
- *    （`want === "array"` 跳过 / `null` + `want === "object"` 放行）；③ 未知键 → 原样通过（全量域）。
+ *    （`want === "array"` 跳过 / `null` + `want ∈ _NULL_CLEARABLE` 放行——#645 扩 number/boolean）；
+ *  ③ 未知键 → 原样通过（全量域）。
  */
 function _checkKnownKeyValue(path, value) {
   const spec = _NULL_LEAF_SHAPES[path] ?? _SIBLING_SHAPES[path]
@@ -140,7 +152,7 @@ function _checkKnownKeyValue(path, value) {
   const want = TYPE_MAP[path]
   if (want && want !== "array") {
     const got = value === null ? "null" : typeof value
-    if (got !== want && !(value === null && want === "object")) throw _expectsError(path, want, value)
+    if (got !== want && !(value === null && _NULL_CLEARABLE.has(want))) throw _expectsError(path, want, value)
   }
 }
 
@@ -173,6 +185,17 @@ function setKeyPath(obj, path, value) {
   return old
 }
 
+/** 点分路径删键（#645：`null` = 显式清除 ⇒ 删键——沿桌面 `settings-values.mjs` 同形；缺段 ⇒ 无操作）。 */
+function deleteKeyPath(obj, path) {
+  const segs = String(path).split(".")
+  let cur = obj
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (cur === null || typeof cur !== "object") return
+    cur = cur[segs[i]]
+  }
+  if (cur !== null && typeof cur === "object") delete cur[segs[segs.length - 1]]
+}
+
 /** 递归展平 config 对象（数组下标段形态）→ 排序的 { path, value } 列表 */
 function flatten(obj, prefix = "", out = []) {
   for (const [k, v] of Object.entries(obj)) {
@@ -209,13 +232,7 @@ export function settingsTool(opts = {}) {
 
   return {
     name: "settings",
-    description:
-      "Adjust ThinCoder runtime configuration — persisted to config.json AND hot-applied to the live agent config.\n" +
-      "Actions: list (all keys + values, flattened) | get <key> | set <key> <value> — dot paths into config.json (agent.maxTurns, traces.enabled, providers.0.model, any nesting).\n" +
-      "set persists to disk (only the set key is written — defaults are never baked in) and takes effect in the running session immediately (turn-boundary keys apply next turn); the value survives restarts.\n" +
-      "Known keys are type-checked: scalar keys against the built-in defaults (agent.maxTurns a number, traces.enabled a boolean); keys whose default is null against their real consumption shape — defaultModel \"provider:model\", agent.subagentModel / shell non-empty string, memory.team object with a repo — so a value the app would silently drop is refused (null clears the key). Unknown keys under a known section are stored as given. Values parse as JSON first (true/false/numbers/objects/arrays), else stay strings.\n" +
-      "SENSITIVE keys (path segment matching apiKey/key/token/secret/password/authorization/auth/cookie/credential, or any key under a headers/env segment) are NEVER echoed in plaintext — list/get/set replies show ••••（masked）; setting a sensitive key is allowed and stored, but never echoed back.\n" +
-      "list/get are read-only (planMode ok, no approval); set is a side effect (approval gate). The /config TUI command is the human equivalent.",
+    description: DESC("settings"), // #15 外置：文本单点 = tool-docs/settings.md
     parameters: {
       type: "object",
       properties: {
@@ -250,15 +267,25 @@ export function settingsTool(opts = {}) {
       const value = parseValue(args.value)
       // 已知键校验（形状表两表都查 + 派生类型表——SETTINGS-TOOL.md §8.3；未知键 JSON 原样）
       _checkKnownKeyValue(String(args.key), value)
-      // 写盘（D-F5b：磁盘真相最小化——writeConfigAtomic 磁盘新鲜读 + 只改被设键 + mtime
-      // 门控——默认不固化；冲突/畸形抛错，内存不热应用（零虚假成功））+ 热应用（内存对象）
+      // 写盘（D-F5b：磁盘真相最小化——默认不固化；冲突/畸形抛错，内存不热应用（零虚假成功））+
+      // 热应用（内存对象）。#645 写形归一（全端同形）：`null` = 显式清除 ⇒ **盘删键**（回退
+      // DEFAULTS）+ 内存删键后回填该键 DEFAULTS 默认值（等价 loadConfig 重载；未登记键 ⇒ 零回填）。
       const r = await writeConfigAtomic(cfgPath, (disk) => {
-        setKeyPath(disk, args.key, value)
+        if (value === null) deleteKeyPath(disk, args.key)
+        else setKeyPath(disk, args.key, value)
       })
       if (!r.ok) throw new Error("config changed on disk concurrently — retry (settings set not applied)")
-      setKeyPath(config, args.key, value)
-      const shown = isSensitiveKey(String(args.key)) ? MASKED : value
-      return `settings set: ${args.key} = ${shown} (${Array.isArray(value) ? "array" : typeof value})${isSensitiveKey(String(args.key)) ? " — stored（值不回显）" : " — persisted + hot-applied（运行中已生效）"}`
+      if (value === null) {
+        deleteKeyPath(config, args.key)
+        const d = resolvePath(DEFAULTS, String(args.key))
+        if (d.ok) setKeyPath(config, args.key, d.value) // 回填默认（形状表键默认 null ⇒ 与今日同形）
+      } else setKeyPath(config, args.key, value)
+      const sensitive = isSensitiveKey(String(args.key))
+      const shown = sensitive ? MASKED : value
+      const suffix = value === null
+        ? " — key removed（键已删除——回退默认）"
+        : sensitive ? " — stored（值不回显）" : " — persisted + hot-applied（运行中已生效）"
+      return `settings set: ${args.key} = ${shown} (${_kindOf(value)})${suffix}`
     },
   }
 }

package/agent-tools/skill.mjs

@@ -1,5 +1,6 @@
 import { loadSkills, readSkill } from "../skills.mjs"
 import { escapeXml } from "../agent.mjs"
+import { DESC } from "../tools/shared.mjs"
 
 // ─── skill loader 注入缝（#88——「同步 loader 面按核内结构归一」的端侧覆盖面）──────────
 /**
@@ -17,14 +18,11 @@ export function resetSkillLoader() { injectedLoader = null }
 
 /**
  * skill tool: load project skill files on demand (.thincoder/skills/*.md).
- * After loading, skill content is injected into the conversation wrapped in <skill-loaded> for subsequent reference.
- * Use action="list" to see all available skills.
+ * 描述面 = `tool-docs/skill.md`（DESC() 加载）；加载内容经 <skill-loaded> 注入会话。
  */
 export const skillTool = {
   name: "skill",
-  description:
-    "Load a project skill from .thincoder/skills/. Skills contain reusable instructions, workflows, or reference material. Use this when the user references a skill by name, or when a task matches a known skill's description. Call with action='list' to see available skills; call with action='load' and name=<skill> to activate one. " +
-    "Returns the skill list ('list'), the load confirmation ('load' — instructions arrive in the next message), or Error: ... with the available skills.",
+  description: DESC("skill"),
   parameters: {
     type: "object",
     properties: {

package/agent-tools/spawn-gates.mjs

@@ -68,7 +68,7 @@ export function validateTaskBookFields(args) {
 }
 
 /**
- * F6 过程档 basename 族（父侧维护文件——AGENT-LOOP.md §28 R26 F-R26b 同族扩展）：
+ * F6 过程档 basename 族（父侧维护文件——AGENT-LOOP-SUBAGENT.md §6.9 R26 同族扩展）：
  * CHANGELOG.md。（台账 = 用户数据目录键控库——项目内无文件，不再入族；老台账族 todo.md /
  * todo-archive.md / checklist 族随 M2 SQLite 化 + M7 checklist 废除退役。）
  * 大小写不敏感全名匹配（路径任意层——归一化在调用点 normalizeFileList 已做）。
@@ -76,7 +76,7 @@ export function validateTaskBookFields(args) {
 const PROCESS_BASENAMES = new Set(["changelog.md"])
 
 /**
- * 工程模式写入面 basename（#33 二道防线——设计 docs/core/design/MANIFEST.md §2.5 / KD-M1-14）：
+ * 写域 basename（**模式无关**——#33 二道防线；`PROJECT-MANIFEST.json` 是项目级状态档，其写门对任何会话生效；设计 docs/core/design/MANIFEST.md §2.5 / KD-M1-14）：
  * PROJECT-MANIFEST.json = M1 项目状态档——写门唯主 agent（`manifest.mjs` `writeManifest` 的
  * `writer` 闸，fail-closed）；本常量 = `files` 声明面**第二道防线**（子代理无法把该路径声明为
  * 写域）。字面量（匹配前已大小写归一；**不** import `MANIFEST_REL`——保本模块「叶子·零 import」
@@ -98,7 +98,7 @@ export function rejectEngineeringFilePaths(files) {
     const segs = String(f).replace(/\\/g, "/").split("/").filter((s) => s)
     const base = (segs[segs.length - 1] ?? "").toLowerCase()
     if (segs.some((s) => s.toLowerCase() === "scripts")) {
-      violations.push(`engineering tool path ${f} must not be listed in files — scripts/** is the engineering-tool face, not a content product (files carries source/test/design-doc paths only)`)
+      violations.push(`engineering-tools face path ${f} must not be listed in files — scripts/** is the engineering-tools face, not a content product (applies to every session, not engineering-mode-scoped; files carries source/test/design-doc paths only)`)
     } else if (PROCESS_BASENAMES.has(base)) {
       violations.push(`Parent-side maintained file ${f} must not be listed in files — reconciliation is the parent's duty; use the design-doc path if you need to edit a design doc`)
     } else if (base === MANIFEST_BASENAME) {

package/agent-tools/subagent-actions-query.mjs

@@ -0,0 +1,270 @@
+/**
+ * subagent-actions-query.mjs — subagent 查询面执行器 + 摘要助手族（2026-09-28 拆分批 · R3——
+ * 自 `subagent-actions.mjs`（498/499 贴 500 硬限）外提查询面：status ∕ observe 两执行器 +
+ * 留痕文本构造（`touchedSummary` / `shortTouchedPath`）；各函数**逐字迁移**、零行为改）。
+ * 原档 re-export `executeStatusAction` / `executeObserveAction` 保 `subagent.mjs` 与各消费档
+ * 的既有 import 面（路径与名面不动——subagent-panel 尾部 re-export 先例）。
+ * 依赖 = `subagent-scheduler.mjs`（describeBlockers / detectStall / STALL_NOTE）·
+ * `async-settle.mjs`（getAsyncPool accessor）· `checkpoint.mjs`（turnCapTrace）——三者均
+ * 不回引本档（无环）。
+ */
+import { isAbsolute, relative } from "node:path"
+import { describeBlockers, detectStall, STALL_NOTE } from "./subagent-scheduler.mjs"
+// ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
+import { getAsyncPool } from "./async-settle.mjs"
+import { turnCapTrace } from "./checkpoint.mjs"
+
+/**
+ * subagent action:"status" (AGENT-LOOP-SUBAGENT.md §6.7 D-M2, new): NON-BLOCKING async-pool query —
+ * returns immediately and never consumes a result (results belong to the auto
+ * channel — AGENT-LOOP-SUBAGENT.md §6.7.5: no check action any more). Source of truth = the pool
+ * (_asyncSubagents): entries moved to _pendingAsyncResults during a suspension
+ * (AGENT-LOOP-ASYNC-POOL.md §6.8 D-S3 ② — injected at the next run start) are no longer in the pool and
+ * are NOT counted as done-waiting.
+ * - id given → { id, role, status, model?, elapsedSec?, turn?, maxTurns?,
+ *   touchedFiles?/touchedMore?/touched? ... } for that entry; unknown id → error
+ *   (T12 semantics — unknown async-subagent id error, same wording as the pool).
+ * - id omitted → { overview: { running: [{id, role, model, elapsedSec, turn,
+ *   maxTurns, touchedFiles?/touched?}], queued: [{id, role, position, touched?}],
+ *   done: [{id, role}] } } — live queue positions (index in _asyncQueue + 1).
+ * AGENT-LOOP-SUBAGENT.md §6.7.2: running 条目带 touched files 摘要（touchedFiles 前 5 + touchedMore 超出
+ * 计数——相对查询方 cwd；0 改动 → touched 占位）；queued 条目带 touched 占位
+ * "—（未启动）"；done/error/取消条目无 touched 字段（round3 #9）。
+ * A settled-but-unconsumed entry (settled during a NORMAL turn) reports done
+ * with a "not yet consumed" note — the auto channel (turn-end collection / the
+ * suspension digest) still delivers it afterwards (AGENT-LOOP-SUBAGENT.md §6.7.5: sole consumption path).
+ */
+/** AGENT-LOOP-SUBAGENT.md §6.7.2 D-M5 decision-field assembly (F9): running entries report
+ *  {id, role, model, elapsedSec, turn, maxTurns} — the data needed to decide
+ *  WHO to cancel. Model is recorded at spawn (childProvider), startedAt at
+ *  ACTUAL start (queued waits don't count), turn/maxTurns mirrored from the
+ *  child's ⟦ev⟧turn events at the callbacks-wrap layer (subagent.mjs tracker).
+ *  elapsedSec computed at call time from startedAt. */
+/** AGENT-LOOP-SUBAGENT.md §6.7.2 D-SF2/N-SF1 摘要形态：status 调用时实时读 entry.childAgent._touchedFiles
+ *  （绝对路径——per-run 记账）→ 相对查询方 cwd；cwd 之外保留绝对形态 +
+ *  "../" 前缀；>80 字符截尾（不超行）；前 5 个 + 独立截断字段 touchedMore（超出
+ *  计数——不混入数组——消费方按类型区分）。占位：running 0 改动 → "—（尚无改动）"
+ *  （T-SF2a）；queued 未启动 → "—（未启动）"（T-SF2b）；done/error/取消条目不含
+ *  本摘要（round3 #9 明示——本批只做 running/queued）。 */
+function touchedSummary(entry, cwd) {
+  if (entry.status !== "running") return { touched: "—（未启动）" }
+  const files = entry.childAgent?._touchedFiles ?? []
+  if (files.length === 0) return { touched: "—（尚无改动）" }
+  const shown = files.slice(0, 5).map((f) => shortTouchedPath(f, cwd))
+  const out = { touchedFiles: shown }
+  if (files.length > 5) out.touchedMore = files.length - 5
+  return out
+}
+
+/** N-SF1 单路径显示形态：cwd 内 → 相对路径；cwd 外 → "../" + 绝对路径；>80 截尾。 */
+function shortTouchedPath(f, cwd) {
+  let p = f
+  if (cwd) {
+    const rel = relative(cwd, f)
+    p = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : `../${f}`
+  }
+  return p.length > 80 ? `${p.slice(0, 79)}…` : p
+}
+
+function statusFields(entry, cwd) {
+  // AGENT-LOOP-ASYNC-POOL.md §6.11 #1（第 10 批——双池并表）：评审池条目专属字段面——role 区分两池；子代理条目
+  // 字段面零变化（NFR-B2）。reviewType(design|code) / round / elapsedSec——与子代理
+  // 的 turn/maxTurns 而非（评审无子回合预算语义）。
+  if (entry.role === "advisor") {
+    const base = { id: String(entry.id), role: entry.role, reviewType: entry.reviewType ?? null, round: entry.round ?? entry.run?.round ?? null }
+    if (entry.model != null) base.model = entry.model
+    if (entry.startedAt) base.elapsedSec = Math.max(0, Math.round((Date.now() - entry.startedAt) / 1000))
+    return base
+  }
+  const base = { id: String(entry.id), role: entry.role }
+  if (entry.status === "running") {
+    base.model = entry.model ?? null
+    base.elapsedSec = entry.startedAt ? Math.max(0, Math.floor((Date.now() - entry.startedAt) / 1000)) : 0
+    base.turn = entry.turn ?? 0
+    base.maxTurns = entry.maxTurns ?? 0
+    // AGENT-LOOP-SUBAGENT.md §6.7.2：touched files 摘要（T-SF1..4——新字段追加——既有字段零破坏）
+    Object.assign(base, touchedSummary(entry, cwd), { turnCap: turnCapTrace(entry) })
+  } else if (entry.status === "queued") {
+    // AGENT-LOOP-SUBAGENT.md §6.7.2 T-SF2b：未启动——确定性占位（不崩；无对象可读）
+    base.touched = "—（未启动）"
+  }
+  return base
+}
+
+export function executeStatusAction(args, ctx) {
+  // #46（批 TOOLFACE-FIXES ①——设计 AGENT-LOOP-SUBAGENT.md §6.25 ①）：七动作族 depth 门收口——
+  // status 与 observe/send/escalate/cancel/panel freeze 同为 depth-0 专有（子代无自有异步池）；
+  // 缺门时子代静默空 overview（把「不可用」读成「无在飞」）。族锚取现行可解析节号（§6.7.2）。
+  if ((ctx.depth ?? 0) > 0) {
+    return JSON.stringify({ status: "error", error: "status is only available at depth 0 — a child agent has no async pool of its own" })
+  }
+  const agent = ctx.agent
+  const map = getAsyncPool(agent, "subagent") ?? new Map()
+  const advisors = getAsyncPool(agent, "advisor") ?? new Map()
+  const queue = agent._asyncQueue ?? []
+  const queuedPosition = (id) => {
+    const i = queue.findIndex((e) => String(e.id) === id)
+    return i >= 0 ? i + 1 : undefined
+  }
+  const { id } = args ?? {}
+  if (id !== undefined && id !== null && String(id) !== "") {
+    const key = String(id)
+    // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b: by-id queries fall through to the advisor pool (shared counter —
+    // ids are unique across both pools; role identifies the kind).
+    const entry = map.get(key) ?? advisors.get(key)
+    if (!entry) {
+      // Wording kept exact — locked by subagent-async/tool tests (unknown-id error
+      // semantics); an unknown id simply names neither pool (the pools share the
+      // id counter, so the message stays unambiguous).
+      return JSON.stringify({ id: key, status: "error", error: `unknown async subagent id: ${key}` })
+    }
+    const target = statusFields(entry, agent.cwd)
+    if (entry.status === "running") return JSON.stringify({ ...target, status: "running" })
+    if (entry.status === "queued") {
+      // AGENT-LOOP-SUBAGENT.md §6.9 F-SD4/D-SD3b：waiting 语义对模型可见——排队原因（冲突对象/依赖对象）随
+      // status 返回；纯槽满等位（kind slot）无 waiting 字段（position 已足够）。
+      const blk = describeBlockers(agent, entry)
+      const out = { ...target, status: "queued", position: queuedPosition(key) ?? entry.position }
+      if (blk.kind !== "slot") {
+        out.waiting = blk.kind === "depc" ? "dependency-cancelled" : "waiting-deps"
+        out.reason = blk.detail
+      }
+      // §6.9 P-SL2（D-SL2）：停滞机械标记——池停滞时本任务所在闭环阻塞链随 status
+      // 返回（F-SL2——status 视图可显示停滞——模型可见——零正常路径字段变化）。
+      const stall = detectStall(agent)
+      if (stall) {
+        const chain = stall.chains.find((c) => c.task === entry)?.text
+        if (chain) out.stall = { chain, note: STALL_NOTE }
+      }
+      return JSON.stringify(out)
+    }
+    // done = settled during this turn and not yet consumed — the auto channel still
+    // delivers it (AGENT-LOOP-SUBAGENT.md §6.7.5: turn-end collection / the suspension digest — no fetch action).
+    target.status = "done"
+    target.done = true
+    if (entry.error) target.error = entry.error
+    target.note = "settled, not yet consumed — delivered by the auto channel (turn-end collection or the suspension digest injects it)"
+    return JSON.stringify(target)
+  }
+  const overview = { running: [], queued: [], done: [] }
+  const mapEntries = [...map.values(), ...advisors.values()]
+  for (const entry of mapEntries) {
+    if (entry.status === "running") overview.running.push(statusFields(entry, agent.cwd))
+    else if (entry.status === "queued") {
+      // §6.9：queued 条目补 waiting/reason（F-SD4——依赖/冲突原因模型可见）；
+      // AGENT-LOOP-SUBAGENT.md §6.7.2 T-SF2b：未启动占位（确定性——不崩）。
+      const blk = describeBlockers(agent, entry)
+      const row = statusFields(entry, agent.cwd)
+      row.position = queuedPosition(String(entry.id)) ?? entry.position
+      if (blk.kind !== "slot") {
+        row.waiting = blk.kind === "depc" ? "dependency-cancelled" : "waiting-deps"
+        row.reason = blk.detail
+      }
+      overview.queued.push(row)
+    }
+    else if (entry.done) overview.done.push({ id: String(entry.id), role: entry.role })
+  }
+  // §6.9 P-SL2（D-SL2）：停滞机械标记——overview 级标注（可显示停滞——F-SL2）——
+  // 链文本随视图返回（逐条——每 queued 条目一行——闭环可破环引导同挂）。
+  const stall = detectStall(agent)
+  if (stall) {
+    overview.stall = {
+      chains: stall.chains.map((c) => c.text),
+      note: STALL_NOTE,
+    }
+  }
+  return JSON.stringify({ overview })
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// SUBAGENT-OBSERVE-SEND（SUBAGENT-OBSERVE-SEND.md——CLI 端）
+// observe（D1——readonly 查询）+ send（D2——控制类豁免注入引导）——动作执行器。
+// 目标 = 父自身 spawn 的异步子代理池条目（_asyncSubagents——非 advisor/escalate——
+// 后者共享 id 计数但非"读写子代理"，错误路径明示）。
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** D1/N2 摘要形态：从子代理 _fullHistory（real 消息——pushReal 累积）倒序收最近 N 个
+ *  assistant 回合的一行描述（newest-first；assistant 消息 = 一回合——带 tool_calls =
+ *  工具轮、独立 content = 回复首行）。返回纯摘要非全量（N2 隔离——不把子代理噪音灌父）。 */
+function recentTurnLines(child, limit) {
+  const hist = child?._fullHistory
+  if (!Array.isArray(hist)) return []
+  const out = []
+  for (let i = hist.length - 1; i >= 0 && out.length < limit; i--) {
+    const m = hist[i]
+    if (m?.role !== "assistant") continue
+    const tcs = Array.isArray(m.tool_calls)
+      ? m.tool_calls.filter((t) => typeof t?.function?.name === "string")
+      : []
+    if (tcs.length) out.push(`tools: ${tcs.map((t) => t.function.name).join(", ")}`)
+    else if (typeof m.content === "string" && m.content.trim()) {
+      const first = m.content.trim().split(/\r?\n/).find((l) => l.trim())
+      out.push((first ?? m.content.trim()).slice(0, 120))
+    } else out.push("(assistant — no content)")
+  }
+  return out
+}
+
+function queuedPositionOf(agent, key) {
+  const i = (agent?._asyncQueue ?? []).findIndex((e) => String(e.id) === key)
+  return i >= 0 ? i + 1 : undefined
+}
+
+/** recent 参数钳制（默认 ~5 条摘要——可参数；钳到 1..20 防超长 N2 失控）。 */
+function clampRecent(n) {
+  const v = Number.parseInt(n, 10)
+  if (!Number.isFinite(v)) return 5
+  return Math.max(1, Math.min(20, v))
+}
+
+/**
+ * subagent action:"observe"（D1——READONLY 查询，父回合内）：按 id 拉运行中异步子代理的
+ * 最近活动快照——从 entry.childAgent（subagent-run.mjs start() 绑定）读**已落回合**摘要
+ * （_fullHistory 最近 N 条）+ _touchedFiles + turn/maxTurns + status + **in-flight 当前
+ * 工具**（评审 #1——从 dispatch runOne 维护的 child._inflightTools 读——非只读已落
+ * history：卡在长工具调用时 history 无新回合、恰是 observe 要检测的卡死态）。返摘要非
+ * 全量（N2）。observe = readonly——running/queued/done 均可查（done 终报 / queued 占位）。
+ */
+export function executeObserveAction(args, ctx) {
+  if ((ctx.depth ?? 0) > 0) {
+    return JSON.stringify({ status: "error", error: "observe is only available at depth 0 — a child agent has no async pool of its own" })
+  }
+  const agent = ctx.agent
+  const id = args?.id
+  if (id === undefined || id === null || String(id) === "") {
+    return JSON.stringify({ status: "error", error: "observe requires the id of the async subagent to inspect (from the async spawn return) — pass the id; omitting it observes nothing" })
+  }
+  const key = String(id)
+  const entry = getAsyncPool(agent, "subagent")?.get(key)
+  if (!entry) {
+    if (getAsyncPool(agent, "advisor")?.has(key)) {
+      return JSON.stringify({ status: "error", error: `id ${key} is an async ADVISOR review — observe is for async subagents (read/edit children); track an advisor with action:'status' or wait for its auto-delivered report` })
+    }
+    return JSON.stringify({ status: "error", error: `unknown async subagent id: ${key}` })
+  }
+  const child = entry.childAgent
+  const out = { id: key, role: entry.role, status: entry.status }
+  if (entry.status === "running") {
+    out.turn = entry.turn ?? 0
+    out.maxTurns = entry.maxTurns ?? 0
+    Object.assign(out, touchedSummary(entry, agent.cwd), { turnCap: turnCapTrace(entry) })
+    // in-flight 当前工具（评审 #1）：child._inflightTools Set——dispatch runOne 在工具
+    // 执行前后维护——LLM 生成/工具间空隙为空；子代理 await 长工具调用时父回合可见它。
+    const inflight = child?._inflightTools
+    if (inflight instanceof Set && inflight.size > 0) out.currentTool = [...inflight]
+    const n = clampRecent(args?.recent)
+    out.recentTurns = recentTurnLines(child, n)
+    out.note = `observing running ${entry.role}#${key} — recentTurns newest-first (cap ${n}); currentTool shown only while a tool is executing (stuck detection); sent directions consume at the next turn boundary`
+  } else if (entry.status === "queued") {
+    out.position = queuedPositionOf(agent, key) ?? entry.position ?? null
+    out.note = "queued — not started yet; no activity to observe (starts when the slot frees / dependencies clear; action:'send' targets running only)"
+  } else {
+    // done = settled this turn, not yet consumed — final report rides the auto channel.
+    out.done = true
+    out.turn = entry.turn ?? 0
+    out.maxTurns = entry.maxTurns ?? 0
+    out.recentTurns = child ? recentTurnLines(child, clampRecent(args?.recent)) : []
+    out.note = "settled — the final report is delivered by the auto channel (turn-end collection or the suspension digest); observe returns the activity summary, not the full report (N2)"
+  }
+  return JSON.stringify(out)
+}