@thincoder/core 0.10.8 → 0.10.9

package/agent-tools/ssh-vault.mjs

@@ -0,0 +1,291 @@
+/**
+ * ssh-vault.mjs — SSH 保存凭据单点（保存件读写 ∥ 系统级加密后端 ∥ 清单 / 删除 ∥ 可用性判定 ∥ 凭据窗获取链）。
+ * 设计 = `docs/core/design/TOOLS.md` §6.22 ⑪（D-TO19 · 用户裁定 A+B）；台账 #1602。
+ *
+ * 档：`configDir/ssh-credentials.json`（**私档**——用户域，仓库零落点；与 ⑨ 非密档 `ssh-hosts.json`
+ * 分档）。形 = `{ version: 1, entries: { "<host[:port]>": { user, scheme, blob, savedAt, lastUsedAt? } } }`
+ * ——值只以**密文 blob** 落盘（明文零落盘，NS6）。
+ *
+ * 加密 = Windows DPAPI（经系统 PowerShell 宿主）：加密 `ConvertTo-SecureString -AsPlainText -Force`
+ * → `ConvertFrom-SecureString`（无 `-Key` ⇒ DPAPI；Microsoft 文档逐字）；解密反之，Marshal 取明文。
+ * 通道纪律（§6.22 ⑦）：脚本 = 常量字面（**值不入命令行**）；值以 base64 封包经子进程 **stdin**，
+ * 密文 ∥ 解出明文经 **stdout**（hex ∥ base64——交换面全 ASCII）；子进程 env 删 `TC_SSH_SECRET`；
+ * 超时有界（到点杀子进程 ⇒ 按解密失败走 fail-soft）。
+ *
+ * fail-soft（§6.22 ⑪，逐形分判）：档缺失 ⇒ 视同无（静默）；结构损坏（JSON 不可解析）⇒ 视同无 +
+ * **原档原位不动**（下次成功保存整体覆盖重建）；不可解密 / 后端抛 ⇒ 条目保留（可能是暂时态）。
+ * 删除面只涉本档（⑨ 非密记录不随删）。
+ *
+ * 观测缝（A 面四格判据落形——S1/S6/N6/B7）：模块级读次计数 = **读盘入口调用数**；
+ * `_vaultReadsForTest()` / `_resetVaultReadsForTest()`——缺省生产行为不变，用例 `finally` 复位
+ * （同族先例 = §6.14 测试态缝）。
+ * 模块图：→ ssh-transport.mjs（`sshConfigDir` 测试缝单点）· ../i18n.mjs（窗词面单源）·
+ * node:child_process / node:fs——叶子向、无环。
+ */
+import { spawn } from "node:child_process"
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { t } from "../i18n.mjs"
+import { sshConfigDir } from "./ssh-transport.mjs"
+
+/** 保存件档名（与 ⑨ `ssh-hosts.json` 分档）。 */
+export const VAULT_FILE = "ssh-credentials.json"
+/** 档形版本（结构损坏判据之一）。 */
+export const VAULT_VERSION = 1
+/** 后端子进程超时（到点杀子进程 ⇒ 按解密失败走 fail-soft）。 */
+export const VAULT_TIMEOUT_MS = 15_000
+
+/** 加密脚本（常量字面——值经 stdin；`ConvertFrom-SecureString` 无 `-Key` ⇒ DPAPI）。 */
+const PS_ENCRYPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "$b64 = [Console]::In.ReadToEnd().Trim()",
+  "$plain = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64))",
+  "$sec = ConvertTo-SecureString -String $plain -AsPlainText -Force",
+  "[Console]::Out.Write((ConvertFrom-SecureString -SecureString $sec))",
+].join("\n")
+/** 解密脚本（常量字面——hex 经 stdin；解出明文 base64 经 stdout）。 */
+const PS_DECRYPT = [
+  "$ErrorActionPreference = 'Stop'",
+  "$hex = [Console]::In.ReadToEnd().Trim()",
+  "$sec = ConvertTo-SecureString -String $hex",
+  "$bstr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec)",
+  "try { $plain = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($bstr) } finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr) }",
+  "[Console]::Out.Write([Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($plain)))",
+].join("\n")
+
+// ─── 观测缝（读次 = 读盘入口调用数）──────────────────────────────────────────
+
+let _reads = 0
+export function _vaultReadsForTest() { return _reads }
+export function _resetVaultReadsForTest() { _reads = 0 }
+
+// ─── 后端（DPAPI 经系统 PowerShell；测试缝只换命令，生产缺省不变）────────────
+
+let _backendCommand = null
+let _backendPrefix = []
+export function _setVaultBackendForTest(command, prefixArgs = []) {
+  _backendCommand = command
+  _backendPrefix = Array.isArray(prefixArgs) ? prefixArgs : []
+}
+export function _resetVaultBackendForTest() {
+  _backendCommand = null
+  _backendPrefix = []
+}
+
+const backendCommand = () => _backendCommand ?? "powershell.exe"
+/** 可用性单点（§6.22 裁决 ④：本批仅 Windows DPAPI；缺席 ⇒ 保存不可用，连接照常）。 */
+export const vaultAvailable = () => _backendCommand !== null || process.platform === "win32"
+
+/** 后端往返（脚本常量 + 输入 stdin → stdout；超时杀进程）。 */
+function runBackend(script, input) {
+  return new Promise((resolve, reject) => {
+    const env = { ...process.env }
+    delete env.TC_SSH_SECRET // 防残留（新增链路零 env；§6.22 ⑦）
+    const child = spawn(backendCommand(), [..._backendPrefix, "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", script], {
+      stdio: ["pipe", "pipe", "pipe"], windowsHide: true, env,
+    })
+    let out = ""
+    let err = ""
+    let done = false
+    const finish = (fn, value) => { if (done) return; done = true; clearTimeout(timer); fn(value) }
+    const timer = setTimeout(() => {
+      try { child.kill() } catch { /* 尽力面 */ }
+      finish(reject, new Error("vault backend timed out"))
+    }, VAULT_TIMEOUT_MS)
+    timer.unref?.()
+    child.stdout.on("data", (d) => { out += d })
+    child.stderr.on("data", (d) => { err += d })
+    child.on("error", (e) => finish(reject, new Error(`vault backend unavailable: ${e?.message ?? String(e)}`)))
+    child.on("exit", (code) => {
+      if (code !== 0) return finish(reject, new Error(`vault backend failed (${code}): ${err.trim().slice(0, 200)}`))
+      finish(resolve, out.trim())
+    })
+    child.stdin.on("error", () => { /* 退出竞态——判定面 = exit code */ })
+    child.stdin.end(input)
+  })
+}
+
+/** 加密：值 → hex 密文（值只经 stdin）。 */
+async function encryptValue(value) {
+  const b64 = Buffer.from(String(value), "utf8").toString("base64")
+  const hex = await runBackend(PS_ENCRYPT, b64)
+  if (!/^[0-9a-f]+$/i.test(hex)) throw new Error("vault backend returned an unexpected ciphertext")
+  return hex
+}
+
+/** 解密：hex 密文 → 明文（坏密文 / 后端抛 ⇒ reject——调用面走 fail-soft）。 */
+async function decryptBlob(blob) {
+  const b64 = await runBackend(PS_DECRYPT, String(blob ?? "").trim())
+  return Buffer.from(b64, "base64").toString("utf8")
+}
+
+// ─── 档（读 / 写 / 结构判定）────────────────────────────────────────────────
+
+const vaultFile = () => join(sshConfigDir(), VAULT_FILE)
+/** 读键单源（`host[:port]`，缺省 22；⑨ 记录面同引用）。 */
+export const hostKey = (host, port) => (port && Number(port) !== 22 ? `${host}:${port}` : String(host))
+
+/** 读盘入口（**唯一读次计数点**）。三态 = ok ∥ missing（静默视同无）∥ damaged（视同无，原档不动）。 */
+function readVaultFile() {
+  _reads += 1
+  let raw
+  try { raw = readFileSync(vaultFile(), "utf8") } catch (e) {
+    return e?.code === "ENOENT" ? { state: "missing" } : { state: "damaged", unreadable: true }
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    const entries = parsed?.entries
+    if (parsed?.version !== VAULT_VERSION || !entries || typeof entries !== "object" || Array.isArray(entries)) {
+      return { state: "damaged" }
+    }
+    return { state: "ok", entries }
+  } catch { return { state: "damaged" } }
+}
+
+/** 写盘单点（结构损坏的重建 = 调用面给空表整体覆盖——原档在此之前不动）。 */
+function writeVaultFile(entries) {
+  mkdirSync(sshConfigDir(), { recursive: true })
+  const body = JSON.stringify({ version: VAULT_VERSION, entries }, null, 2)
+  writeFileSync(vaultFile(), body, { encoding: "utf8", mode: 0o600 })
+  try { chmodSync(vaultFile(), 0o600) } catch { /* win32 无 POSIX mode——尽力面 */ }
+}
+
+/**
+ * 查条目（单次读盘）：条目 `user` 与「本次有效 `user`」不符 ⇒ 视同无（⑪）。
+ * @returns {{ state: "ok", key: string, entry: object } | { state: "missing"|"damaged"|"unreadable" }}
+ */
+export function getEntry(host, port, user) {
+  const read = readVaultFile()
+  if (read.state !== "ok") return { state: read.state }
+  const key = hostKey(host, port)
+  const entry = read.entries[key]
+  if (!entry || typeof entry !== "object") return { state: "missing" }
+  if (!user || entry.user !== user) return { state: "missing" }
+  return { state: "ok", key, entry }
+}
+
+/**
+ * 复用终段：读条目 → 解密。失败形分判（调用面各自回落窗 / 可读句）：
+ * `missing`（静默）· `damaged`（可读句）· `unavailable`（后端缺席）· `undecryptable`（条目保留）。
+ * @returns {Promise<{ state: "ok", key: string, value: string } | { state: string }>}
+ */
+export async function resolveSecret(host, port, user) {
+  const got = getEntry(host, port, user)
+  if (got.state !== "ok") return { state: got.state }
+  if (!vaultAvailable()) return { state: "unavailable" }
+  try {
+    const value = await decryptBlob(got.entry.blob)
+    if (!value.length) return { state: "undecryptable" } // 解出空值 = 不可用（不当空口令提交）
+    return { state: "ok", key: got.key, value }
+  } catch { return { state: "undecryptable" } }
+}
+
+/**
+ * 保存（窗内勾选且认证成功后调用）：加密 → 整体写档（结构损坏的旧档在此被覆盖重建）。
+ * @returns {Promise<{ ok: true, key: string } | { ok: false, reason: string }>}
+ */
+export async function saveEntry(host, port, { user, value } = {}) {
+  if (!vaultAvailable()) return { ok: false, reason: "unavailable" }
+  if (!String(value ?? "").length) return { ok: false, reason: "empty" }
+  let blob
+  try { blob = await encryptValue(value) } catch { return { ok: false, reason: "backend" } }
+  try {
+    const read = readVaultFile()
+    const entries = read.state === "ok" ? { ...read.entries } : {}
+    const key = hostKey(host, port)
+    entries[key] = { user: user ?? null, scheme: "dpapi", blob, savedAt: new Date().toISOString() }
+    writeVaultFile(entries)
+    return { ok: true, key }
+  } catch { return { ok: false, reason: "write" } }
+}
+
+/** 删除（`forget`）：条目不存在 ⇒ 幂等（existed:false）；结构损坏 ⇒ 原档不动（可读句）。 */
+export function deleteEntry(host, port) {
+  const key = hostKey(host, port)
+  const read = readVaultFile()
+  if (read.state === "missing") return { ok: true, existed: false }
+  if (read.state !== "ok") return { ok: false, reason: "damaged" }
+  if (!Object.hasOwn(read.entries, key)) return { ok: true, existed: false }
+  const entries = { ...read.entries }
+  delete entries[key]
+  try { writeVaultFile(entries) } catch { return { ok: false, reason: "write" } }
+  return { ok: true, existed: true }
+}
+
+/** `lastUsedAt` = 复用成功时更新；写失败 = 增益面静默（⑪）。 */
+export function touchEntry(host, port) {
+  const read = readVaultFile()
+  if (read.state !== "ok") return
+  const key = hostKey(host, port)
+  const entry = read.entries[key]
+  if (!entry || typeof entry !== "object") return
+  try { writeVaultFile({ ...read.entries, [key]: { ...entry, lastUsedAt: new Date().toISOString() } }) } catch { /* 增益面静默 */ }
+}
+
+// ─── 凭据获取链（§6.22 ⑧：`ctx.onSecretInput` 窗）────────────────────────────
+
+/** 凭据窗（§6.22 ⑧）：无 UI ⇒ 可读错（不挂起、不静默——`question.mjs` 无 UI 抛例同旨）；词面 = i18n 键。
+ *  端侧回调自身拒绝（CLI `refuseSecretInput()` 形：抛可读句）⇒ 同族直出（`noUi` 标记 = 失败句不另加前缀）。
+ *  `offerSave` ⇒ `fields` += `save`（`checkbox: true`——缺省不勾（opt-in）；提交值 = 布尔；核侧严格判 `=== true`）。
+ *  拆档由 = 会话面超 500 顾问线（拆前 ≈513 行；设计 490 再拆线 ⇒ 按落点表候选拆分「凭据获取链迁入 `ssh-vault.mjs`」）。 */
+export async function askCredential(ctx, { host, user, port, sessionId, offerSave = false }) {
+  if (typeof ctx?.onSecretInput !== "function") {
+    const err = new Error(t("ssh.no_ui"))
+    err.noUi = true // 可读句直出（catch 面不另加前缀——失败句单源 = 核字典）
+    throw err
+  }
+  const fields = [
+    { name: "user", masked: false, required: false, prefill: user ?? "" },
+    { name: "password", masked: true, required: true, prefill: "" },
+  ]
+  if (offerSave) fields.push({ name: "save", masked: false, required: false, prefill: false, checkbox: true })
+  let res
+  try {
+    res = await ctx.onSecretInput({
+      kind: "ssh-credential",
+      sessionId: sessionId != null ? `ssh#${sessionId}` : null,
+      host, user: user ?? null, port: port ?? null,
+      fields,
+      keys: { title: "ssh.credentialTitle", prompt: "ssh.credentialPrompt" },
+    })
+  } catch (e) {
+    // 端侧拒绝（无交互面 / 载荷成形外）⇒ 同族可读句直出（不裹「connect failed」前缀）。
+    const err = new Error(e?.message ?? String(e))
+    err.noUi = true
+    throw err
+  }
+  if (!res || typeof res !== "object") return null
+  return res
+}
+
+// ─── 保存凭据管理面（§6.22 ⑫：`credentials` 只读 ∥ `forget` 写——核单点，三端同源）────────────
+
+/** `credentials`（只读免审）：host / user / 保存时间 / 最近使用——**值零出现**（清单不含 blob）。 */
+export function credentialsSsh() {
+  const read = readVaultFile()
+  if (read.state === "missing") return { text: "(no saved ssh credentials)" }
+  if (read.state !== "ok") return { text: "saved ssh credentials: the store is damaged — the file was left untouched; delete it manually to reset the store" }
+  const rows = Object.entries(read.entries)
+    .map(([key, e]) => ({ key, user: e?.user ?? null, savedAt: e?.savedAt ?? null, lastUsedAt: e?.lastUsedAt ?? null }))
+    .sort((a, b) => a.key.localeCompare(b.key))
+  if (rows.length === 0) return { text: "(no saved ssh credentials)" }
+  const head = vaultAvailable()
+    ? "saved ssh credentials (encrypted with this Windows user account):"
+    : "saved ssh credentials (the credential store is not available on this platform):"
+  const lines = rows.map((r) => {
+    const saved = r.savedAt ? ` \u00b7 saved ${r.savedAt}` : ""
+    const used = r.lastUsedAt ? ` \u00b7 last used ${r.lastUsedAt}` : ""
+    return `[${r.key}]${r.user ? ` user ${r.user}` : ""}${saved}${used}`
+  })
+  return { text: `${head}\n${lines.join("\n")}` }
+}
+
+/** `forget`（写动作——过既有审批门）：按 `host` + 可选 `port` 删条目；幂等；值零出现。
+ *  删除 ⇒ 下次连接回落凭据窗（S8）；只涉保存档（⑨ 非密记录不随删）。 */
+export function forgetSsh({ host, port } = {}) {
+  const key = hostKey(host, port)
+  const res = deleteEntry(host, port)
+  if (!res.ok) return { error: `could not update the saved-credential store (${res.reason}) — the file was left untouched` }
+  if (!res.existed) return { text: `no saved credential for ${key} — nothing to forget (the call is idempotent)` }
+  return { text: `saved credential for ${key} deleted — the next connect asks in the credential window` }
+}

package/agent-tools/subagent-spawn.mjs

@@ -26,9 +26,9 @@ import { nextSubagentId } from "./subagent-scheduler.mjs"
 import {
   normalizeFileList, describeBlockers, assertNoDepCycle, depInfo,
 } from "./subagent-scheduler.mjs"
-// M5 F2（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.3）：任务书六强制字段校验本体落
+// M5 F2（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.3）：任务书 round 枚举 + 五项结构化参数校验/拼装本体落
 // spawn-gates.mjs（纯谓词零依赖）——本处只加 import 调用。
-import { validateTaskBookFields } from "./spawn-gates.mjs"
+import { validateRoundParam, validateTaskBookParams, composeTaskBookBrief } from "./spawn-gates.mjs"
 // 台账 #23（AGENT-LOOP-SUBAGENT.md §6.26 · D23-3）：审计块构造器外提（`summarizeEngTaskBook`
 // + `buildAuditBlock` 纯函数）——spawn 档只做「收集 + 绑定」；块文本逐字搬移（D23-4）。
 import { buildAuditBlock } from "./audit-block.mjs"
@@ -38,6 +38,14 @@ import { resolveBatchReadPath, batchDocBases } from "./batch-paths.mjs"
 // LOGGING（LOGGING.md）：#309 形三观测留痕走同一事件通道。
 import { logEvent } from "../log.mjs"
 
+/** 任务书播报文本：该角色名集拼装 + 可选 task 自由文本（拼装空 ⇒ 原 task 逐字——旧形零变）。 */
+function taskBriefOf(args, role) {
+  const composed = composeTaskBookBrief(args, role)
+  if (!composed) return args.task
+  const extra = typeof args.task === "string" ? args.task.trim() : ""
+  return extra ? `${composed}\n\n${extra}` : composed
+}
+
 /** #309 任务书 token 判据（`AGENT-LOOP-SUBAGENT.md` §6.29.3）：`.md` 结尾的连续路径型字面
  *  （含盘符形态——裸名 `AGENTS.md` 无分隔符且非绝对，见调用点过滤）。 */
 const MD_PATH_TOKEN = /[A-Za-z0-9_@.:\\/-]+\.md\b/g
@@ -211,7 +219,7 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     batchDocAbs = resolveBatchReadPath(parent.cwd ?? process.cwd(), given)
     if (!batchDocAbs) throw refusal(" (given path is not a readable file)")
     // #309 形三：任务书中的他批批次档引用观测留痕（不阻断——放行不受影响）。
-    logBatchDocRefs(parent, role, args.task, batchDocAbs)
+    logBatchDocRefs(parent, role, taskBriefOf(args, role), batchDocAbs)
   } else if (role === "coder") {
     const given = typeof args.batchDoc === "string" ? args.batchDoc.trim() : ""
     if (given) {
@@ -222,13 +230,12 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     }
   }
 
-  // M5 F2（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：任务书六强制字段门——
-  // 工程角色（eng-coder/eng-designer）必带 round（initial|fix）+ 五段任务书字段；
-  // 落点 = batchDoc 门之后、token 门之前（§2.2 数据流契约同序）。判据只到「字段在场」——
-  // 内容够不够由执行者拒收兜底（需求 §1.14 #9 行为面）。explore/plan/coder 豁免。
-  if (role === "eng-coder" || role === "eng-designer") {
-    validateTaskBookFields(args)
-  }
+  // M5 F2（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：任务书参数门——**所有 spawn 角色**。
+  // 工程角色：round 枚举（initial|fix）+ 四项核心 + `designPoints`；explore / plan / coder：
+  // 四项核心 + `scope`。判据三条零改（存在 ∧ string ∧ trim 非空）；落点 = batchDoc 门之后、
+  // token 门之前（门序 = AGENT-LOOP-SUBAGENT.md §6.22）。
+  if (role === "eng-coder" || role === "eng-designer") validateRoundParam(args)
+  validateTaskBookParams(args, role)
 
   // eng-coder token gate: the design review must have passed and the caller must
   // present the exact token advisor issued — otherwise the child is not authorized to code.
@@ -345,7 +352,7 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // 审计/探索（"status 里这个文件算不算超清单？"）。注入分支整体删除（B 方案
   // git 只读变体亦随裁定废弃——D-AG5）。顶层主 agent 注入保留（§3 prepareRun——
   // setup.mjs depth===0——D-AG7 范围边界）。
-  let input = args.context ? `Context:\n${args.context}\n\nTask:\n${args.task}` : args.task
+  let input = args.context ? `Context:\n${args.context}\n\nTask:\n${taskBriefOf(args, role)}` : taskBriefOf(args, role)
   // 台账 #23（AGENT-LOOP-SUBAGENT.md §6.26 · D23-1）：**spawn 级固定机制性指令改走 system 固块**——
   // 两处（批次档路径行 + 审计模板块）原随 user 首条下发，压缩把首条并入摘要即丢（长任务中后期
   // 既看不到批次档路径、也看不到审计模板 ⇒ 过度勘察的真病根）；固块值在 child 生命周期内恒定

package/agent-tools/subagent.mjs

@@ -5,7 +5,6 @@
  * 2026-10-07 批 ledger-tool（#927 并入）：+action: design-slots（只读清点面——
  * DESIGN-TOKEN-SETTLEMENT.md §9 F-SL1）+ consume-design 选择器扩展（designIds / expired /
  * olderThanDays）——实现在 `design-slots.mjs`（subagent-spawn.mjs re-export 保 import 面）。
- * 2026-10-14 批 design-token-recovery（#1384 并入）：design-slots 回收读口——`designId` 过滤 + `reveal:true` 单槽揭值（必携 designId；掩蔽 = 只揭活槽）——实现随动在 `design-slots.mjs`。
  *
  * 2026-09-03 拆分轮: subagent.mjs 超 500 硬顶——async 常量、共享 post-spawn 管线
  *（runChildPipeline）与队列/注入/并账机械迁至 ./subagent-async.mjs。execute
@@ -37,7 +36,7 @@ import { executeStatusAction, executeEscalateAction, executePanelAction, execute
 import { prepareScheduling, buildSpawnChild, executeConsumeDesignAction } from "./subagent-spawn.mjs"
 import { executeDesignSlotsAction } from "./design-slots.mjs"
 import { executeAsyncSpawn } from "./subagent-run.mjs"
-import { ROUND_VALUES } from "./spawn-gates.mjs"
+import { ROUND_VALUES, composeTaskBookBrief } from "./spawn-gates.mjs"
 // #15 描述外置：描述文本单点 = tool-docs/subagent.md（DESC 单解析面，缺档抛错语义不变）
 import { DESC } from "../tools/shared.mjs"
 
@@ -140,18 +139,23 @@ export const subagentTool = {
       action: { type: "string", enum: ["spawn", "status", "escalate", "cancel", "panel", "consume-design", "observe", "send", "design-slots"], description: "Which action — spawn (default) / status / observe / send / escalate / cancel / panel / consume-design / design-slots; semantics per action in the tool description." },
       view: { type: "boolean", description: "action:'panel' only: true (default) = the live panel blocks as the user sees them; false without freeze = error. Mutually exclusive with freeze (freeze wins)." },
       freeze: { type: "string", description: "action:'panel' only: block key of a digested-stuck block — reclaims it into the conversation; refused for running/done/unknown blocks or a still-pending report; works on the CLI TUI panel and on the desktop renderer panel (live readback of the blocks as the user sees them)." },
-      task: { type: "string", description: "Required for action:'spawn' (the self-contained task brief) and action:'escalate' (goal, constraints, entry files, acceptance criteria)." },
+      task: { type: "string", description: "For action:'spawn' (any role): OPTIONAL free-text supplement — the brief itself is the structured task-book parameters (four core: goal / knownFacts / acceptance / reportFormat, plus the role's fifth: designPoints for eng-coder/eng-designer, scope for explore/plan/coder); a task-only spawn is refused. For action:'escalate': the brief (goal, constraints, entry files, acceptance criteria)." },
       context: { type: "string", description: "Optional background the sub-agent needs (it cannot see this conversation); action:'spawn' only." },
       role: { type: "string", enum: ["explore", "plan", "coder", "eng-coder", "eng-designer"], description: "The sub-agent role — see the role matrix in the tool description. Exact spelling required. action:'spawn' only (escalate spawns its own expert internally)." },
       model: { type: "string", description: "action:'spawn': provider/model override ('provider:model', a provider, or a model name on the parent's provider) — defaults config.agent.subagentModels[role] → config.agent.subagentModel → the parent's provider; \"default\" inherits. action:'escalate': a consult candidate (default = the first)." },
       designToken: { type: "string", description: "Required when role='eng-coder': the token from advisor(type='design') after the review passed — without it, eng-coder cannot modify files." },
-      designId: { type: "string", description: "role='eng-coder': the designId echoed with the approved token — required to pick between concurrent designs (optional for one). action:'consume-design': the single-slot selector (required to pick between several; the gate refuses to guess); see designIds / expired / olderThanDays for batch consumption. action:'design-slots': filter the inventory to one slot (trimmed exact match; an empty string means no filter; an unknown id is refused with the held id list) — REQUIRED with reveal:true." },
+      designId: { type: "string", description: "role='eng-coder': the designId echoed with the approved token — required to pick between concurrent designs (optional for one). action:'consume-design': the single-slot selector (required to pick between several; the gate refuses to guess); see designIds / expired / olderThanDays for batch consumption. action:'design-slots': filter the inventory to one slot (trimmed exact match; an empty string means no filter; an unknown id is refused with the held id list)." },
       designIds: { type: "array", items: { type: "string" }, description: "action:'consume-design' (batch): an explicit non-empty list of design ids to close out — pass exactly ONE selector per call (designId / designIds / expired / olderThanDays)." },
       expired: { type: "boolean", description: "action:'consume-design' (batch): true = close out every expired slot (exactly ONE selector per call)." },
       olderThanDays: { type: "number", description: "action:'consume-design' (batch): close out every slot older than N days (age > N; exactly ONE selector per call)." },
-      reveal: { type: "boolean", description: "action:'design-slots' only: true = reveal the selected slot's full designToken — REQUIRES designId (one slot at a time, never a bulk dump); an expired or malformed slot is masked (designToken=—); a non-boolean value is refused. After a token drops from your context (compaction, restart), read it back this way and pass designId + designToken verbatim on the eng-coder spawn — the gate checks exact equality." },
       batchDoc: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer': the batch record path (e.g. <repo>/docs/batches/<batch>-<topic>.md; relative paths resolve against the session cwd first, then candidate project roots — or absolute) — the task book this spawn implements/writes. Refused when absent or when the path does not resolve to a readable file; the content is never validated. role='coder' (normal mode): optional — binds this spawn's §5 record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file." },
       round: { type: "string", enum: ROUND_VALUES, description: "REQUIRED for role='eng-coder'/'eng-designer': initial (first round for this design) or fix (a correction round reusing the same designId+designToken; docs FIRST). No default — missing = refused." },
+      goal: { type: "string", description: "REQUIRED for every spawn role: the task book's goal & why — the problem this solves and the cost chain (content only, no label — the runtime composes the labels)." },
+      knownFacts: { type: "string", description: "REQUIRED for every spawn role: the facts and file paths the parent already verified — the child must not re-explore them." },
+      designPoints: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer' (the fifth task-book parameter for engineering roles): design points & forbidden scope — what to land and what must not be touched. Non-engineering roles use `scope` instead — `scope` never substitutes for this one." },
+      scope: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder' (the fifth task-book parameter for non-engineering roles): scope & forbidden scope — what to read / search and what not to touch. Engineering roles use `designPoints` instead — `designPoints` never substitutes for this one." },
+      acceptance: { type: "string", description: "REQUIRED for every spawn role: acceptance criteria — machine-verifiable (commands / thresholds / assertion counts)." },
+      reportFormat: { type: "string", description: "REQUIRED for every spawn role: the delivery-report format the child must produce." },
       async: { type: "boolean", description: "action:'spawn'/'escalate': default at depth 0 = true (async; the report arrives automatically); depth>0 always sync. async:false forces the blocking flight." },
       files: { type: "array", items: { type: "string" }, description: "action:'spawn' only: the file write-domain this task declares — file-level paths only (cwd-relative or absolute; directories rejected — they bypass the conflict detector). Overlapping-file tasks serialize automatically. Omit = no conflict detection." },
       dependsOn: { type: "array", items: { type: "string" }, description: "action:'spawn' only: ids from prior async returns whose outcome this task needs — queues until every dependency settles, then starts. Consumed ids count as satisfied; a cancelled/failed dependency stays queued marked 'dependency cancelled' until you decide (AUTO sessions auto-start). Unknown ids error." },
@@ -218,8 +222,10 @@ export const subagentTool = {
     // Spawn requires a task brief — schema `required` is advisory (multi-action
     // schema), so the mechanical check lives here: an absent task would otherwise
     // flow downstream as `content: undefined` and surface as an obscure error.
-    if (typeof args.task !== "string" || !args.task.trim()) {
-      throw new Error("subagent action:'spawn' requires a task (the self-contained task brief).")
+    // 任务书载体：结构化参数（拼装后非空）——task 只作补充；两者皆缺 ⇒ 此处先拒。
+    // （五项必带门 = spawn-gates.validateTaskBookParams，覆盖所有 spawn 角色、落 buildSpawnChild——task-only 由该门点名拒。）
+    if (!composeTaskBookBrief(args, args.role) && (typeof args.task !== "string" || !args.task.trim())) {
+      throw new Error("subagent action:'spawn' requires the structured task-book parameters (four core + the role's fifth: designPoints for eng-coder/eng-designer, scope for explore/plan/coder) — a free-text task alone is not the brief.")
     }
     // §18 D-E1a depth-gated async default (2026-09-06 需求池 R12): depth-0 spawns
     // default to async for EVERY role (the old role-level default — eng-coder only —

package/agent-tools/timer.mjs

@@ -50,14 +50,14 @@ function kindText(t) {
   if (typeof everyMs === "number" && Number.isFinite(everyMs) && everyMs > 0) return `every ${everyMs / 1000}s`
   const daily = t?.daily
   if (typeof daily === "string" && DAILY_RE.test(daily)) return `daily ${daily}`
-  if (t?.at === true) return `at ${localText(t.expiresAt)}`
+  if (t?.at === true && Number.isFinite(t.expiresAt)) return `at ${localText(t.expiresAt)}`
   return "one-shot"
 }
 
 /** `list` 行第三槽：到期未投 ⇒ `due now`；否则 `next <dur>`（剩余现算）。 */
 function nextText(t, now) {
   const at = Number(t?.expiresAt)
-  return at > now ? `next ${durText(at - now)}` : "due now"
+  return Number.isFinite(at) && at > now ? `next ${durText(at - now)}` : "due now"
 }
 
 /** `message` 首行（`list` 行第四槽——逐字原样，不截断）。 */

package/config-defaults.mjs

@@ -0,0 +1,92 @@
+/**
+ * config-defaults.mjs — the configuration default table itself (pure data, one comment per
+ * non-obvious key). Split out of config.mjs so that changing a default value does not require
+ * reading the whole loader: defaults (data) ∥ load-time normalization rules (logic) ∥ request
+ * budget arithmetic were three unrelated things living in one file
+ * (CONTEXT-COMPACTION.md §6.16.9 — C1 split, judged by responsibility, not by line count).
+ *
+ * Re-exported unchanged by config.mjs (`export { DEFAULTS }`) — the 34 importer files keep
+ * their import path and this table keeps its name.
+ */
+
+import { join } from "node:path"
+import { configDir } from "./config-io.mjs"
+
+export const DEFAULTS = {
+  defaultModel: null, // top-level "provider:model" composite — new-session starting point (F-1)
+  agent: {
+    maxTurns: 200,
+    subagentTurns: 100,
+    subagentModel: null,  // default subagent model: "provider:model" | model name (parent provider); null = inherit parent provider
+    subagentModels: {},   // per-type override: { explore, plan, coder, "eng-coder" } — priority: subagent tool model arg > this[role] > subagentModel > parent provider
+    goalTurns: 200,
+    // compactThreshold: 键缺省 = auto（CONTEXT-COMPACTION.md §6.17 三档落值）——无默认值：留着默认值
+    // 会让每份配置看着都像显式。派生线只进 agent.compactThresholdResolved（内存面，不落盘）。
+    verifyGuard: false,  // push model back to verify when files were mutated but verify not run (opt-in)
+    // Multi-model consultation ("会诊") + escalate ("飞刀") — CLI parity with the VS Code plugin.
+    // consultModels: candidate pool for BOTH consult and escalate ({ provider, model, effort? }, up to 5).
+    consultModels: [],
+    consultTurns: 40,      // per-consultant tool-turn budget (diagnosis tasks)
+    consultTimeoutMs: 600000, // wall-clock ceiling per consultant (10min)
+    streamRules: [],      // time-traveling stream rules: [{ pattern: "regex", message: "reminder", action: "abort"|"warn", repeat: "always"|"once" }]
+    advisor: { guard: false },  // code review is always available; guard: true pushes completion back until reviewed (opt-in). Also accepts provider/model/thinking/reasoningEffort/timeoutMs overrides. Deprecated: enabled (2026-08-21)
+    autoThink: false,     // auto-classify task difficulty and set reasoning effort per-turn
+    engineering: false,   // initial default only — the runtime value is the session authority (MANIFEST.md §2.2 / ENGINEERING-MODE-V2.md §2.3 E5.1). Strict methodology enforcement — design-before-code (design review + user approval before code)
+    // Async pool limits (AGENT-LOOP-ASYNC-POOL.md §6.10 D-24a/R14 + R13 — POOL-CONFIG-
+    // UNIFIED 2026-09-09): { engCoder, other, advisor } — eng-coder pool / other-role
+    // pool / advisor-review pool, defaults 4/4/4 (user ruling "eng-coder 四路，其他
+    // 4 路" + advisor 评审池并入同一可配体系——三池统一默认 4)。engCoder/other
+    // runtime-validated at every subagent pool admission (subagent-async
+    // resolvePoolLimits); advisor runtime-validated at every advisor launch
+    // (advisor-async advisorPoolLimitFor——F-2——两域读取器独立不共享)——非法/缺省
+    // 回退 4——settings tool 与 /config 并发池菜单写此键——变更下个 spawn/launch 生效。
+    // ⚠ 与 subagent-async.mjs ASYNC_POOL_LIMITS（两键）/advisor-async.mjs
+    // ADVISOR_POOL_LIMIT 逐键同值（运行时回退常量）——耦合锚 T-24a4 断言锁住——
+    // 勿单侧改默认。
+    poolLimits: { engCoder: 4, other: 4, advisor: 4 },
+    // §6.30.3 门三件③（D-TW5）：timer 空闲自唤醒开关——默认开（工具描述面已承诺到点提醒）；
+    // false ⇒ 端侧不武装闩（回既有回合边界投递——零调度器面）。键面随 DEFAULTS 派生进 settings 类型表。
+    timerWake: true,
+    // 注入开关（PROMPT-SYSTEM.md §6.24 · 台账 #1420）：文档类 ∥ 记忆类自动注入——默认开；
+    // 判据 `!== false`（缺省 = 现行为零变）。消费点 = 核 `agent/setup.mjs` 判点（逐 run 现读）。
+    // 2026-10-15（§6.27 · 台账 #1465）：① 项目指令块独立成键——`injectDocs` 收窄为只管 ② 相关文档块；
+    // 两键完全正交（关任一方另一方照常）。`injectProjectRules` 判点 = 核 `agent/setup.mjs`（`prepareRun` 项目指令段）。
+    injectDocs: true,
+    injectProjectRules: true,
+    injectMemories: true,
+  },
+  memory: {
+    dbPath: join(configDir, "memory.db"),
+    projectDir: ".thincoder/memory",
+    team: null,
+    // 索引自维护（§6.14 面⑤ · 台账 #1096）：维护型备份保留枚数（轮转保最新 N——引擎钳 ≥ 1）
+    maintain: { backupKeep: 2 },
+  },
+  shell: null,            // bash tool shell executable (e.g. "C:\\Program Files\\Git\\bin\\bash.exe" or "pwsh"); null = system default (cmd on Windows, /bin/sh elsewhere)
+  embedding: {
+    baseURL: "https://api.siliconflow.cn/v1",
+    model: "BAAI/bge-m3",
+  },
+  mcp: {
+    servers: [],
+  },
+  websearch: {
+    // Structured search via Tavily when a key is set — empty apiKey → Bing RSS/HTML fallback (zero-config).
+    apiKey: "",          // Tavily key (tvly-...) — optional
+    // WEB-BACKEND-DEEPSEEK（CONFIG.md §6.5）：`auto` = a configured DeepSeek provider wins（TOOLS.md §6.23）；`local` = skip it.
+    backend: "auto",
+  },
+  // fetch 工具的后端选择（CONFIG.md §6.5）——语义同 `websearch.backend`（`local` = 本地直取）。
+  fetch: { backend: "auto" },
+  // 浏览器工具（BROWSER-TOOL.md §3.2）：非空 ⇒ navigate 目标 host ∥ click/evaluate/type 的当前页 host 须命中
+  //（全等（大小写不敏感）∥ `*.` 前缀 = 子域通配）——收束面非沙箱；缺省空 = 不设限。
+  browser: { allowDomains: [] },
+  traces: {
+    enabled: false,  // §18.6 D-TR6 修订（2026-09-05 用户裁定——发布隐私："不希望用户那边也采集"）：轨迹存档默认 OFF——新用户零采集；本地调试分析可显式开（~/.thincoder/config.json traces.enabled:true）
+    retentionHours: 24, // D-TR10：轨迹文件保留小时数——CLI 启动时删除超过该时长的文件（默认 24h）
+  },
+  // 诊断开关（用户面 ① 配置键——CONFIG.md §6.2 名录）：`heapWatch` 默认开（设 false 关闭）——自愈分支
+  // 遥测；`heapSnapshot` 默认关——采集 opt-in（堆转储敏感度 ≥ traces ⇒ 对齐发布隐私先例 D-TR6；
+  // 2026-09-30 采集收网批；桌面端运行期热读 ∥ CLI 本进程下次启动）
+  diagnostics: { heapWatch: true, heapSnapshot: false },
+}