thincoder 0.12.59 → 0.12.61

package/src/agent-tools/read-history.mjs

@@ -1,9 +1,13 @@
 /**
- * agent-tools/read-history.mjs — read_history tool (SESSION.md §9).
+ * agent-tools/read-history.mjs — read_history tool (SESSION.md §9 + §13 R19 cross-session).
  *
- * Query THIS session's message history — the full human-readable record
- * (agent._fullHistory — NEVER compacted, audit-complete). Use to recall what
- * was said or done earlier: design decisions, tool-call timing, past rulings.
+ * Query message history — THIS session by default, any session on disk with `path`
+ * (SESSION.md §13 R19): an explicit session file path deep-queries that file's
+ * history line; "cwd:<dir>" discovers the sessions stored for that directory.
+ *
+ * Default (no path) — THIS session's full human-readable record (agent._fullHistory
+ * — NEVER compacted, audit-complete). Use to recall what was said or done earlier:
+ * design decisions, tool-call timing, past rulings.
  *
  * Filters AND together: role / keyword (message text) / tool (tool messages by
  * name + assistant messages that declared the call) / since-until (epoch ms
@@ -17,17 +21,44 @@
  * session file. assistant tool_calls are summarized to a name list (arguments
  * never expanded).
  *
+ * Cross-session (SESSION.md §13 D-R19a): path = a session file path (absolute, or
+ * relative to the project cwd) → read that file's history line and apply the SAME
+ * filter surface; path = "cwd:<dir>" → list every slot stored for that directory
+ * (slot number + full file path + title/message count/updatedAt — no dead-slot
+ * filtering, v1 decision). Single-file retrieval is guarded by a line-scan cap
+ * (READ_HISTORY_SCAN_MAX — an oversized file is refused before it is read whole)
+ * plus a message-count cap (READ_HISTORY_MAX_MESSAGES = 50,000 — L24 双保险第二道).
+ *
  * readonly: true — planMode pass / no permission ask. Registered depth-0 only:
  * subagents get their own throwaway history, so querying "the session" from a
- * child would be semantically confusing (SESSION.md §9.5 refinement 1).
- * Mirrored 1:1 in thincoder-vscode/src/agent-tools/read-history.mjs.
+ * child would be semantically confusing (SESSION.md §9.5 refinement 1 + §13 T-R19.4).
+ * §13 R19 extension mirrored per SESSION.md §13 — double-end isomorphic, no
+ * cross-end byte test (thincoder-vscode/src/agent-tools/read-history.mjs).
  */
 
+import { openSync, readSync, closeSync, readFileSync, existsSync, statSync } from "node:fs"
+import { isAbsolute, resolve } from "node:path"
+import { listSlots, slotPath } from "../session-slots.mjs"
+
 const DEFAULT_LIMIT = 50
 const MAX_LIMIT = 200
 const CONTENT_CAP = 500
 const VALID_ROLES = new Set(["user", "assistant", "tool"])
 
+/** 单槽检索行扫护栏（SESSION.md §13 D-R19a——评审 #3 定稿：超限不再读全文，返回定稿错误文案）。 */
+export const READ_HISTORY_SCAN_MAX = 200_000
+
+/** L24 消息数预算（评审 #2 钉死——双保险第二道）：行扫按物理 \n 行计——JSON 单行槽
+ *  行扫不设防——parse 后 history 数组长度超限即拒（同款定稿文案——双端同常量同文案）。 */
+export const READ_HISTORY_MAX_MESSAGES = 50_000
+
+/** 超限错误文案（SESSION.md §13——逐字定稿——T-R19.7 断言）。 */
+const TOO_LARGE_ERROR = JSON.stringify({ error: "session too large — refine keyword or since/until" })
+
+/** 检索/记忆族消歧总纲（SESSION.md §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) {
   if (typeof m?.content === "string") return m.content
@@ -80,17 +111,129 @@ function toEntry(m) {
   return entry
 }
 
+/** AND-filter one history message (role/keyword/tool/since-until) — shared by the in-memory
+ *  default and the cross-session file query (SESSION.md §13 D-R19a: 同 filter 面应用). */
+function matches(m, { role, kwRe, tool, since, until }) {
+  if (!m || typeof m !== "object") return false
+  if (role !== undefined && m.role !== role) return false
+  if (kwRe) {
+    const text = messageText(m)
+    if (!kwRe.test(text)) return false
+  }
+  if (tool) {
+    const byName = m.role === "tool" && m.name === tool
+    const byDeclaration = m.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.some((tc) => toolCallName(tc) === tool)
+    if (!byName && !byDeclaration) return false
+  }
+  const ts = m.ts
+  if (since !== null || until !== null) {
+    if (typeof ts !== "number") return false // no ts → no time-window match
+    if (since !== null && ts < since) return false
+    if (until !== null && ts > until) return false
+  }
+  return true
+}
+
+/** Direction picks the END of the matched set; output stays chronological either way. */
+function formatMatches(matched, direction, limit) {
+  const windowed = direction === "oldest" ? matched.slice(0, limit) : matched.slice(-limit)
+  return JSON.stringify(windowed.map(toEntry))
+}
+
+/** Line-scan guard: stream-count physical newlines, bailing the moment the cap is crossed —
+ *  an oversized file is refused BEFORE it is read whole ("不再读全文"——SESSION.md §13 D-R19a). */
+function exceedsScanMax(file) {
+  const CHUNK = 64 * 1024
+  let fd = null
+  try {
+    fd = openSync(file, "r")
+    const buf = Buffer.alloc(CHUNK)
+    let newlines = 0
+    for (;;) {
+      const n = readSync(fd, buf, 0, CHUNK, null)
+      if (n <= 0) break
+      for (let i = 0; i < n; i++) {
+        if (buf[i] === 0x0a) newlines++
+      }
+      if (newlines > READ_HISTORY_SCAN_MAX) return true
+    }
+    return false
+  } catch {
+    return false // 行扫失败 → 交由后续读取/解析路径给出真实错误
+  } finally {
+    if (fd !== null) {
+      try { closeSync(fd) } catch { /* ignore */ }
+    }
+  }
+}
+
+/** Cross-session deep query: one session file, same filter surface (§13 D-R19a). */
+function querySessionFile(pathArg, { role, kwRe, tool, since, until, direction, limit }, baseCwd) {
+  const file = isAbsolute(pathArg) ? pathArg : resolve(baseCwd ?? process.cwd(), pathArg)
+  if (!existsSync(file)) return `Error: session file not found: ${file}`
+  if (exceedsScanMax(file)) return TOO_LARGE_ERROR
+  let text
+  try {
+    text = readFileSync(file, "utf8")
+  } catch (e) {
+    return `Error: failed to read session file ${file}: ${e.message}`
+  }
+  let data
+  try {
+    data = JSON.parse(text)
+  } catch (e) {
+    return `Error: ${file} is not a valid session file (corrupt JSON: ${e.message})`
+  }
+  if (!data || typeof data !== "object" || !Array.isArray(data.history)) {
+    return `Error: ${file} is not a valid session file (no history array)`
+  }
+  if (data.history.length > READ_HISTORY_MAX_MESSAGES) {
+    // L24 消息数第二道（parse 后——行扫按物理行、单行 JSON 槽行扫不设防——超限同款拒绝）。
+    return TOO_LARGE_ERROR
+  }
+  const matched = data.history.filter((m) => matches(m, { role, kwRe, tool, since, until }))
+  return formatMatches(matched, direction, limit)
+}
+
+/** 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（§13 D-R19a
+ *  ——评审 #2：摘要必须含寻址字段——模型第二步深查 = 复制行内文件路径重调 path=）。 */
+function discoverCwd(raw, baseCwd) {
+  const dir = resolve(baseCwd ?? process.cwd(), raw)
+  let st = null
+  try {
+    st = statSync(dir)
+  } catch { /* fallthrough to the explicit error below */ }
+  if (st === null || !st.isDirectory()) {
+    return `Error: unknown cwd "${raw}" — no session directory for this cwd (directory not found: ${dir})`
+  }
+  const slots = listSlots(dir) // 时间序（updatedAt 降序）——含 manifest 记录的全部槽（v1 不做死槽过滤）
+  if (slots.length === 0) {
+    return `(no session slots found for cwd: ${dir} — no sessions started there yet)`
+  }
+  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 `Session slots for cwd: ${dir} (newest first):\n${lines.join("\n")}`
+}
+
 export const readHistoryTool = {
   name: "read_history",
   description:
-    "Query THIS session's message history (the full record — never compacted, audit-complete). " +
-    "Use when you need to recall what was said or done earlier: design decisions, tool-call timing, past rulings. " +
+    "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 (names only)}]. " +
     "Messages without ts return ts:null. Content is truncated — the full text is in the session file. " +
-    "For file-level changes this run (not messages), use recent_changes.",
+    "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); \"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. " +
+    "A session file over 50,000 messages or 200,000 lines is refused (\"session too large\") instead of being read whole.\n" +
+    SEARCH_FAMILY_GUIDE,
   parameters: {
     type: "object",
     properties: {
@@ -101,11 +244,15 @@ export const readHistoryTool = {
       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)." },
       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)." },
     },
   },
   readonly: true,
   execute(args, ctx) {
     const a = args ?? {}
+    if (a.path !== undefined && (typeof a.path !== "string" || a.path.trim().length === 0)) {
+      return `Error: invalid path "${a.path}" — must be a session file path or "cwd:<dir>"`
+    }
     const role = a.role
     if (role !== undefined && (typeof role !== "string" || !VALID_ROLES.has(role))) {
       return `Error: invalid role "${role}" — valid roles: user, assistant, tool`
@@ -131,30 +278,17 @@ export const readHistoryTool = {
     // keyword stays a literal substring).
     const kwRe = keyword ? new RegExp(keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "i") : null
     const tool = typeof a.tool === "string" && a.tool.length > 0 ? a.tool : null
+    const baseCwd = ctx.agent?.cwd ?? process.cwd()
+
+    const pathArg = typeof a.path === "string" && a.path.trim().length > 0 ? a.path.trim() : null
+    if (pathArg !== null) {
+      return pathArg.startsWith("cwd:")
+        ? discoverCwd(pathArg.slice("cwd:".length), baseCwd)
+        : querySessionFile(pathArg, { role, kwRe, tool, since, until, direction, limit }, baseCwd)
+    }
 
     const history = Array.isArray(ctx.agent?._fullHistory) ? ctx.agent._fullHistory : []
-    const matched = history.filter((m) => {
-      if (!m || typeof m !== "object") return false
-      if (role !== undefined && m.role !== role) return false
-      if (kwRe) {
-        const text = messageText(m)
-        if (!kwRe.test(text)) return false
-      }
-      if (tool) {
-        const byName = m.role === "tool" && m.name === tool
-        const byDeclaration = m.role === "assistant" && Array.isArray(m.tool_calls) && m.tool_calls.some((tc) => toolCallName(tc) === tool)
-        if (!byName && !byDeclaration) return false
-      }
-      const ts = m.ts
-      if (since !== null || until !== null) {
-        if (typeof ts !== "number") return false // no ts → no time-window match
-        if (since !== null && ts < since) return false
-        if (until !== null && ts > until) return false
-      }
-      return true
-    })
-    // Direction picks the END of the matched set; output stays chronological either way.
-    const windowed = direction === "oldest" ? matched.slice(0, limit) : matched.slice(-limit)
-    return JSON.stringify(windowed.map(toEntry))
+    const matched = history.filter((m) => matches(m, { role, kwRe, tool, since, until }))
+    return formatMatches(matched, direction, limit)
   },
 }

package/src/agent-tools/recent-changes.mjs

@@ -8,7 +8,8 @@ export const recentChangesTool = {
   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.",
+    "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.",
   parameters: {
     type: "object",
     properties: {},

package/src/agent-tools/review-streak.mjs

@@ -0,0 +1,93 @@
+/**
+ * review-streak.mjs — design-review failure streak guard（第 33 批——2026-09-11）。
+ *
+ * 同一 doc-set 的 design 评审**连续**未产出可用结算（宿主截断尾五 kind + 陈旧结算 +
+ * 凭证落盘失败 + 无报告结算）达 `MAX_DESIGN_REVIEW_STREAK` 次 ⇒ 后续发起被拒
+ * （工具层预检 + `runAdvisorReview` 内防线两级——零 LLM / 不耗轮次 / 不置「评审已覆盖」）。
+ * 设计权威 = `docs/design/ADVISOR-CONVERGENCE.md` §17（需求 = requirements 档 §12 F28/F29 + N20/N21）。
+ *
+ * 中立模块（**不 import 任何 src/ 模块**——打断潜在环，§17.5 模块图）：
+ *  - `normAbs` 自 advisor-settle.mjs 迁入（原处 re-export——既有 import 面零变）；
+ *  - `docSetKey` 自 advisor-async.mjs 迁入（原为私有——零 import 面）。
+ * 分类单源：`designReviewOutcome` 为异步结算 / 同步面两计数点共用（D-SK8——防两处分类漂移）。
+ * 载体 = 会话级内存 `agent._designReviewStreaks`（Map——不落盘、不进 session 文件；
+ * eng 模式切换不清护栏——与 `_advisorRuns` 刻意不同步，§17.9 #5 定案）。
+ */
+import { join } from "node:path"
+
+/** 连续未产出可用结算的阈值（三振——§17.2 表 1 选定 N=3；`MAX_ADVISOR_ROUNDS` 零改动）。 */
+export const MAX_DESIGN_REVIEW_STREAK = 3
+
+/** ABS 归一（cwd 相对 → cwd 拼接）——陈旧判定 / 冻结拦截 / doc-set 键同源（§14.14 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)
+}
+
+/** Canonical scope key for design reviews — the document multi-set
+ *  (order-insensitive, ABS-path normalized — launch 与 continuation 的写法差异
+ *  ("./docs/x.md" vs "docs/x.md"、反斜杠) 不误建新实例).
+ *  第 33 批自 advisor-async.mjs 逐字迁入（护栏与实例续跑同锚单源）。 */
+export function docSetKey(documents, cwd) {
+  const list = [...new Set((documents ?? [])
+    .filter((d) => typeof d === "string" && d.trim())
+    .map((d) => normAbs(d, cwd)))]
+  return JSON.stringify(list.sort())
+}
+
+/** 护栏适用的键判据：空清单（`[]` / `null` 的 `docSetKey` 产出 = "[]"）不适用——不计数、
+ *  不停止（§17.9 #3 登记；fail-open 于此面）。 */
+export function designReviewStreakApplies(key) {
+  return typeof key === "string" && key.length > 0 && key !== "[]"
+}
+
+/**
+ * 结算分类（纯函数单源——§17.3 优先级表，自上而下首个命中；输入 = 宿主可见事实，
+ * **零 LLM 输出解析**，N20）。neutral = 无信息事件（取消 / 中断 / 拒发）——不打断连续计数。
+ * @param {{launchRefused?: boolean, stale?: boolean, hasResult?: boolean,
+ *          incomplete?: string|null, persistFailed?: boolean}} input
+ * @returns {{reset: boolean, count: string|null}} reset=true 计数复位；count=需加一的类名；
+ *   两者皆空 = neutral（不动计数）。
+ */
+export function designReviewOutcome(input) {
+  const { launchRefused = false, stale = false, hasResult = true, incomplete = null, persistFailed = false } = input ?? {}
+  if (launchRefused) return { reset: false, count: null } // 1. 未发起请求（无尝试发生——§14.4 既有语义）
+  if (stale) return { reset: false, count: "stale" } // 2. 陈旧结算（未产出可用凭证）
+  if (!hasResult) return { reset: false, count: "no_report" } // 3. 无报告（fail-closed）
+  if (incomplete && incomplete !== "interrupted") return { reset: false, count: String(incomplete) } // 4. 宿主截断尾五 kind
+  if (incomplete === "interrupted") return { reset: false, count: null } // 5. 用户 / 系统中断类（与 cancelled 同族）
+  if (persistFailed) return { reset: false, count: "no_credential" } // 6. pass 但槽落盘失败（无可用凭证）
+  return { reset: true, count: null } // 7. 可用判决（pass 且落盘成功 / changes-required）——连续链断点
+}
+
+/** 记录只读视图（停止判定与结论表的数据源）；空清单键 / 无载体 ⇒ null。 */
+export function designReviewStreakRecord(agent, key) {
+  if (!designReviewStreakApplies(key)) return null
+  const streaks = agent?._designReviewStreaks
+  return streaks instanceof Map ? (streaks.get(key) ?? null) : null
+}
+
+/** 计数落账（§17.4）：reset ⇒ 删除该键记录；count ⇒ `{count: prev+1, log: […].slice(-N)}`；
+ *  neutral ⇒ 不动。载体懒初始化。 */
+export function noteDesignReviewOutcome(agent, key, outcome) {
+  if (!agent || !designReviewStreakApplies(key) || !outcome) return
+  if (outcome.reset) {
+    if (agent._designReviewStreaks instanceof Map) agent._designReviewStreaks.delete(key)
+    return
+  }
+  if (typeof outcome.count !== "string" || !outcome.count) return
+  const streaks = agent._designReviewStreaks instanceof Map
+    ? agent._designReviewStreaks
+    : (agent._designReviewStreaks = new Map())
+  const prev = streaks.get(key)
+  streaks.set(key, {
+    count: (prev?.count ?? 0) + 1,
+    log: [...(prev?.log ?? []), outcome.count].slice(-MAX_DESIGN_REVIEW_STREAK),
+  })
+}
+
+/** 停止判定：记录达阈值即停；空清单键恒 false。停止不可自解除（复位仅经可用判决——被拒后
+ *  无法发生；会话结束随载体清零）。 */
+export function designReviewStreakStopped(agent, key) {
+  return (designReviewStreakRecord(agent, key)?.count ?? 0) >= MAX_DESIGN_REVIEW_STREAK
+}

package/src/agent-tools/settings.mjs

@@ -4,12 +4,12 @@
  * 语义：set = 写盘（config.json——磁盘真相最小化：只写被设的键——默认值不固化）+
  * 热应用（ctx.agent.config 内存对象立即更新——回合边界键下回合生效）。
  * 护栏：敏感键（路径段含 apiKey/key/token/secret/password）回显/错误文本永不出现明文
- * （••••（masked）——防密钥泄漏进会话历史/trace）；已知键类型校验（类型表自动派生自
- * config.mjs DEFAULTS——不手写防漂移）；set 侧效走审批门（dispatch 动作级分类）。
+ * （••••（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 { mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { join } from "node:path"
-import { DEFAULTS, configPath } from "../config.mjs"
+import { DEFAULTS, configPath, writeConfigAtomic } from "../config.mjs"
 
 /** 敏感键段判定（完整点分路径的段级匹配——apiKey/api_key/api-key/token/secret/password 形态） */
 const SENSITIVE_SEGMENT = /(^|[._-])(api[_-]?key|key|token|secret|password)($|[._-])/i
@@ -19,19 +19,128 @@ function isSensitiveKey(path) {
   return SENSITIVE_SEGMENT.test(path)
 }
 
+/* ─── 形状层（第 8 批 2026-09-11——SETTINGS-TOOL.md §8.3；两表结构：相等面 / 存在性面） ─── */
+
 /**
- * 类型表：递归遍历 DEFAULTS——叶子（非对象/数组值）记 `路径 → typeof 默认值`。
- * 数组（providersList 等）不递归（下标元素无类型约束——全量域）；对象节递归到叶子。
+ * null 叶子形状表——唯一「逐键手写形状」面（完备性锁的**相等面**：键集 == _nullLeafPaths(DEFAULTS)）。
+ * 表值 = 形状规格：接受集 = 该键真实消费形态 ∪ `null`（显式清除——消费面均有「未设置」态）；
+ * 不可消费形态（应用侧读不出写入值）→ 拒绝（违例抛错，磁盘/内存零变化）。
  */
-function buildTypeMap(obj, prefix = "", out = {}) {
+const _NULL_LEAF_SHAPES = {
+  defaultModel: { kind: "nonEmptyString", providerModel: true, expects: 'non-empty string ("provider:model" composite)' },
+  "agent.subagentModel": { kind: "nonEmptyString", expects: "non-empty string" },
+  shell: { kind: "nonEmptyString", expects: "non-empty string" },
+  "memory.team": { kind: "team", expects: "object { repo: string, name?, dir? }" },
+}
+
+/** 同族/跨端形状表（**存在性断言面**——不参与完备性锁的集合相等）。W3 同族：`agent.subagentModels`
+ *  默认 `{}` ⇒ 派生表零条目 ⇒ 零约束（字符串被静默忽略——回落 subagentModel）。 */
+const _SIBLING_SHAPES = {
+  "agent.subagentModels": { kind: "roleMap", expects: "object of role→non-empty string" },
+}
+
+/** 派生：递归遍历默认值对象——叶子（非对象/数组值）记 `路径 → typeof 默认值`（旧语义逐字保留：
+ *  null 叶子记 "object"，其约束由形状表接管）；数组不递归（下标元素无类型约束——全量域）。 */
+function _deriveTypes(obj, prefix = "", out = {}) {
   for (const [k, v] of Object.entries(obj)) {
     const p = prefix ? `${prefix}.${k}` : k
-    if (v !== null && typeof v === "object" && !Array.isArray(v)) buildTypeMap(v, p, out)
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) _deriveTypes(v, p, out)
     else out[p] = Array.isArray(v) ? "array" : typeof v
   }
   return out
 }
-const TYPE_MAP = buildTypeMap(DEFAULTS)
+
+/** 类型表 = 派生 + 可选 `patch` 覆盖（测试缝——非 null 叶子逐键与派生结果相等；T-S2.15）。 */
+function _buildShapeTable(obj, patch = null) {
+  const out = _deriveTypes(obj)
+  return patch ? Object.assign(out, patch) : out
+}
+const TYPE_MAP = _buildShapeTable(DEFAULTS)
+
+/** null 叶子路径枚举（数组不递归——与派生表同域）。 */
+function _nullLeafPaths(obj, prefix = "", out = []) {
+  for (const [k, v] of Object.entries(obj)) {
+    const p = prefix ? `${prefix}.${k}` : k
+    if (v === null) out.push(p)
+    else if (typeof v === "object" && !Array.isArray(v)) _nullLeafPaths(v, p, out)
+  }
+  return out
+}
+
+/** 完备性锁（N-S1.5）：未声明的 null 叶子 = 形状表漂移——返回键名 + 一次性警告列出键名。 */
+let _shapeWarned = false
+function _checkShapeCompleteness(defaults, warn = console.warn) {
+  const declared = new Set(Object.keys(_NULL_LEAF_SHAPES))
+  const missing = _nullLeafPaths(defaults).filter((p) => !declared.has(p))
+  if (missing.length && !_shapeWarned) {
+    _shapeWarned = true
+    warn(`[settings] null-default keys missing from _NULL_LEAF_SHAPES: ${missing.join(", ")} — declare their real consumption shape (SETTINGS-TOOL.md §8.3; N-S1.5 completeness lock)`)
+  }
+  return missing
+}
+_checkShapeCompleteness(DEFAULTS) // 装载自检——形状表必须覆盖全部 null 叶子（漂移即警告）
+
+/** 值位渲染（错误文本——敏感键命中时遮罩：N-S1.2 / D-S2.4——明文零进错误句）。 */
+function _shownValue(path, value) {
+  return isSensitiveKey(path) ? MASKED : JSON.stringify(value)
+}
+
+function _kindOf(value) {
+  return value === null ? "null" : Array.isArray(value) ? "array" : typeof value
+}
+
+function _expectsError(path, expects, value) {
+  return new Error(`settings set: "${path}" expects ${expects} — got ${_kindOf(value)} (${_shownValue(path, value)})`)
+}
+
+/** 形状校验（形状表命中键——`null` 在 _checkKnownKeyValue 已放行）。 */
+function _checkShape(path, spec, value) {
+  if (spec.kind === "team") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw _expectsError(path, spec.expects, value)
+    if (typeof value.repo !== "string" || !value.repo.trim()) {
+      throw new Error(`settings set: "${path}" requires a non-empty "repo" (team layer stays off without it) — got ${_shownValue(path, value)}`)
+    }
+    for (const k of ["name", "dir"]) {
+      if (value[k] !== undefined && (typeof value[k] !== "string" || !value[k].trim())) throw _expectsError(path, spec.expects, value)
+    }
+    return
+  }
+  if (spec.kind === "roleMap") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw _expectsError(path, spec.expects, value)
+    for (const v of Object.values(value)) {
+      if (typeof v !== "string" || !v.trim()) throw _expectsError(path, spec.expects, value)
+    }
+    return
+  }
+  // nonEmptyString —— defaultModel 另加 provider:model 形态面（与 model-ref.mjs:25-36 同判据；
+  // 存在性面不查——D-S2.5）
+  if (typeof value !== "string" || !value.trim()) throw _expectsError(path, spec.expects, value)
+  if (spec.providerModel) {
+    const sep = value.indexOf(":")
+    if (sep <= 0 || !value.slice(sep + 1)) throw _expectsError(path, spec.expects, value)
+  }
+}
+
+/**
+ * 已知键值校验（set 写盘前；违例抛错——磁盘/内存零变化）：
+ * ① 形状表命中键（`_NULL_LEAF_SHAPES` / `_SIBLING_SHAPES` **两表都查**——表值 = 形状规格）→ 形状校验
+ *    （`null` = 显式清除，放行）；② 非 null 叶子（派生表值 = `typeof` 串）→ 既有语义逐字保留
+ *    （`want === "array"` 跳过 / `null` + `want === "object"` 放行）；③ 未知键 → 原样通过（全量域）。
+ */
+function _checkKnownKeyValue(path, value) {
+  const spec = _NULL_LEAF_SHAPES[path] ?? _SIBLING_SHAPES[path]
+  if (spec) {
+    if (value === null) return // 显式清除 = 有效动作（消费面均有「未设置」态——D-S2.3）
+    return _checkShape(path, spec, 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)
+  }
+}
+
+/* ─── 既有工具面 helpers（第 8 批零改动） ─── */
 
 /** 点分路径解析（含数组数字段）——逐段下钻；返回 { ok, value } 或缺失段信息 */
 function resolvePath(obj, path) {
@@ -82,7 +191,9 @@ function parseValue(raw) {
     const v = JSON.parse(s)
     // JSON 顶层标量都接受；解析失败（裸字符串）→ 字符串字面
     if (typeof v === "number" || typeof v === "boolean" || v === null || Array.isArray(v) || typeof v === "object") return v
-    return s // "abc"（带引号传的字符串）——JSON.parse 成功但返回字符串——保持解析结果
+    // "abc"（带引号传的字符串）——JSON.parse 成功但返回字符串：返回**解析值**（去引号）
+    // ——两端统一 ①（2026-09-11 用户裁定；SETTINGS-TOOL.md §9.3）。
+    return v
   } catch {
     return s // 裸 abc → 字符串字面
   }
@@ -91,23 +202,13 @@ function parseValue(raw) {
 export function settingsTool(opts = {}) {
   const cfgPath = opts.configPath ?? configPath // 测试注入 tmp 文件；默认全局 configPath
 
-  async function readDisk() {
-    let text
-    try { text = readFileSync(cfgPath, "utf8") } catch { return {} } // 不存在 → 空对象（写盘最小化——默认不固化）
-    try { return JSON.parse(text) } catch { throw new Error(`settings: config file not parseable — refusing to overwrite: ${cfgPath}`) }
-  }
-  async function writeDisk(disk) {
-    mkdirSync(join(cfgPath, ".."), { recursive: true })
-    writeFileSync(cfgPath, JSON.stringify(disk, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
-  }
-
   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 against the built-in defaults (agent.maxTurns must be a number, traces.enabled a boolean); unknown keys under a known section are stored as given. Values parse as JSON first (true/false/numbers/objects/arrays), else stay strings.\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 contains apiKey/key/token/secret/password) 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.",
     parameters: {
@@ -142,21 +243,23 @@ export function settingsTool(opts = {}) {
       // set
       if (!args.key || args.value === undefined) throw new Error("settings set: key and value are required")
       const value = parseValue(args.value)
-      // 已知键类型校验（类型表派生自 DEFAULTS——未知键 JSON 原样）
-      const want = TYPE_MAP[String(args.key)]
-      if (want && want !== "array") {
-        const got = value === null ? "null" : typeof value
-        if (got !== want && !(value === null && want === "object")) {
-          throw new Error(`settings set: "${args.key}" expects ${want} — got ${got} (${JSON.stringify(args.value)})`)
-        }
-      }
-      // 写盘（磁盘真相最小化：只改被设键——默认不固化）+ 热应用（内存对象）
-      const disk = await readDisk()
-      setKeyPath(disk, args.key, value)
-      await writeDisk(disk)
+      // 已知键校验（形状表两表都查 + 派生类型表——SETTINGS-TOOL.md §8.3；未知键 JSON 原样）
+      _checkKnownKeyValue(String(args.key), value)
+      // 写盘（D-F5b：磁盘真相最小化——writeConfigAtomic 磁盘新鲜读 + 只改被设键 + mtime
+      // 门控——默认不固化；冲突/畸形抛错，内存不热应用（零虚假成功））+ 热应用（内存对象）
+      const r = await writeConfigAtomic(cfgPath, (disk) => {
+        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（运行中已生效）"}`
     },
   }
 }
+
+/**
+ * 测试缝导出（`_` 前缀——config.mjs `_setConfigPathForTest` 先例；SETTINGS-TOOL.md §8.3 第 6 条）：
+ * `_checkShapeCompleteness` = 完备性锁的运行时面（T-S2.14「一次性警告列出键名」的机械断言缝）。
+ */
+export { _buildShapeTable, _nullLeafPaths, _NULL_LEAF_SHAPES, _SIBLING_SHAPES, _checkKnownKeyValue, _checkShapeCompleteness }