@thincoder/core 0.10.3 → 0.10.5

package/agent-tools/design-slots.mjs

@@ -0,0 +1,232 @@
+/**
+ * design-slots.mjs — design-token 槽位清点 + 消费核（2026-10-07 批 ledger-tool · 台账 #927 并入）。
+ * 设计单源 = `docs/core/design/DESIGN-TOKEN-SETTLEMENT.md` §10（F-SL1 清点面 / F-SL2 批量消费）。
+ *
+ * 面一 `executeDesignSlotsAction`（`subagent` action `design-slots`——只读）：
+ *   数据源 = 槽文件权威表（`readEngTokensFromSlot`——无 TTL 过滤原样）∪ 内存 Map（并集去重，
+ *   冲突以槽为准——D-S3 同源）；**零写**（不 reconcile 回写、不落盘）。列表面 = 逐槽一行
+ *   （designId ∥ live/expired ∥ ageDays ∥ expiresAt ∥ 批；龄序 = 最老在前）+ 计数尾行；
+ *   「批」= `_advisorRuns` 按 designId 命中 run 的 `docSetKey` 中 `batches/` 段档取 basename
+ *   （KD-SL2——零新存储；不可得 ⇒ `—`）。
+ * 面二 `executeConsumeDesignAction`（`subagent` action `consume-design` 消费核——自
+ *   `subagent-spawn.mjs` 迁入）：选择器恰一（`designId` ∥ `designIds` ∥ `expired` ∥
+ *   `olderThanDays`——KD-SL3 fail-closed 不猜）；目标集 = 并集视图按选择器解析 → 逐枚移出
+ *   （`removeDesignTokenSlot` 同款 token 值守护）→ **单次** `persistEngTokens` 落盘（D-S6 单点）；
+ *   落盘失败 ⇒ 内存快照整体回滚 + 抛（KD-SL4——不留半消费态）。单枚形态（designId / 无选择器
+ *   单槽）：语义 / 拒文 / 回执**现行逐字不变**。
+ *
+ * 签发链行为零改（mint / settle / TTL / persist 存储形——#868 面另论）；工程模式父侧（depth-0）限定
+ * （门 = 本档两执行器；depth 面由装配与受限变体门承载）。
+ */
+import { persistEngTokens, readEngTokensFromSlot, reconcileEngTokensFromSlot, removeDesignTokenSlot, tokenExpired, tokenExpiryMs } from "../token-ttl.mjs"
+import { effectiveTokenTtlMs } from "./design-token.mjs"
+import { advisorRuns } from "./advisor-async.mjs"
+
+const DAY_MS = 86400000
+
+/** 槽并集视图（F-SL1 数据源 / F-SL2 目标集解析）：内存 Map 先行、槽文件权威表覆盖（同 id 冲突以槽
+ *  为准——D-S3 同源）；纯读——零回写、零落盘。 */
+function unionSlots(agent) {
+  const merged = new Map()
+  const mem = agent?._engDesignTokens
+  if (mem instanceof Map) for (const [id, t] of mem) merged.set(id, t)
+  const file = readEngTokensFromSlot(agent)
+  if (file) for (const [id, t] of Object.entries(file)) merged.set(id, t)
+  return merged
+}
+
+/** 「批」列派生（KD-SL2——零新存储）：会话内评审实例注册表 `_advisorRuns` 按 designId 命中的**最新**
+ *  run ⇒ `docSetKey`（被审文档绝对路径集 JSON）中 `batches/` 段档取 basename；不可得（跨重启 /
+ *  模式重进 / 注册表回收）⇒ `—`（如实降级）。 */
+function batchOf(agent, designId) {
+  const runs = advisorRuns(agent)
+  if (!(runs instanceof Map)) return "—"
+  for (const run of [...runs.values()].reverse()) {
+    if (run?.designId !== designId || typeof run.docSetKey !== "string") continue
+    const name = batchBasename(run.docSetKey)
+    if (name) return name
+  }
+  return "—"
+}
+
+/** docSetKey（JSON 串）→ `batches/` 段档 basename（首命中）；不可解析 / 无命中 ⇒ null。 */
+function batchBasename(docSetKey) {
+  let list = null
+  try { list = JSON.parse(docSetKey) } catch { return null }
+  if (!Array.isArray(list)) return null
+  for (const p of list) {
+    if (typeof p !== "string") continue
+    const parts = p.split(/[\\/]/)
+    const i = parts.lastIndexOf("batches")
+    if (i >= 0 && i < parts.length - 1 && parts[i + 1]) return parts[i + 1]
+  }
+  return null
+}
+
+/** 槽事实（清点列与选择器共用）：状态 = `tokenExpired` 单源；`ageDays` = now − (expiresAt −
+ *  `effectiveTokenTtlMs`) 派生（TTL 配置曾改时为近似——如实注）；`expiresAt` 精确；畸形 / 格式外
+ *  token ⇒ 两项 `—`（不可判龄）。 */
+function slotFacts(agent, designId, token, now, ttlMs) {
+  const expiry = typeof token === "string" ? tokenExpiryMs(token) : null
+  return {
+    designId, token,
+    expired: typeof token === "string" && tokenExpired(token, now),
+    ageDays: expiry === null ? null : (now - (expiry - ttlMs)) / DAY_MS,
+    expiresAt: expiry,
+    batch: batchOf(agent, designId),
+  }
+}
+
+/** 龄序比较（最老在前——剩余有效期升序；不可判龄（畸形串）排尾——不冒充最老）。 */
+const byOldest = (a, b) => (b.ageDays ?? -Infinity) - (a.ageDays ?? -Infinity)
+
+/**
+ * `subagent` action `design-slots`（F-SL1——只读清点面）：工程模式父侧限定（与 consume-design
+ * 同门）。输出 = 行文本（逐槽行 + 计数尾行）；字段 / 序 / 降级标记 = 契约，行内措辞 = 实现面。
+ * 分类 = 只读（planMode 放行 / 免审批 / digest 放行——谓词在 `agent/dispatch-gates.mjs`）。
+ */
+export function executeDesignSlotsAction(args, ctx) {
+  const parent = ctx?.agent
+  if (!parent?.config?.agent?.engineering) {
+    throw new Error("Engineering mode is not active — design-slots applies only to engineering-mode design tokens (spawn 同门).")
+  }
+  const now = Date.now()
+  const ttlMs = effectiveTokenTtlMs(parent)
+  const entries = [...unionSlots(parent)].map(([id, t]) => slotFacts(parent, id, t, now, ttlMs))
+  entries.sort(byOldest)
+  const lines = entries.map((e) =>
+    `- designId=${e.designId} status=${e.expired ? "expired" : "live"} ageDays=${e.ageDays === null ? "—" : e.ageDays.toFixed(1)} expiresAt=${e.expiresAt === null ? "—" : new Date(e.expiresAt).toISOString()} batch=${e.batch}`)
+  const live = entries.filter((e) => !e.expired).length
+  lines.push(`design-slots: ${entries.length} slot(s) — ${live} live / ${entries.length - live} expired`)
+  return lines.join("\n")
+}
+
+/**
+ * `subagent` action `consume-design` 消费核（F-SL2；自 `subagent-spawn.mjs` 迁入——2026-10-07）：
+ * 选择器恰一——`designId`（现行 · 单枚）∥ `designIds`（显式非空清单）∥ `expired:true`（全部过期项）
+ * ∥ `olderThanDays:N`（ageDays > N）；多选择器同给 / 选择器缺失且多槽 ⇒ 拒（fail-closed——不猜）。
+ * 单枚形态走 `consumeSingle`（拒文 / 回执逐字不变）；批量走 `consumeBatch`（逐枚行 + `consumed N` 计数行）。
+ */
+export function executeConsumeDesignAction(args, ctx) {
+  const parent = ctx?.agent
+  if (!parent?.config?.agent?.engineering) {
+    throw new Error("Engineering mode is not active — consume-design applies only to engineering-mode design tokens (spawn 同门).")
+  }
+  const slots = parent?._engDesignTokens
+  const hasSlots = slots instanceof Map && slots.size > 0
+  const designId = args?.designId ? String(args.designId) : undefined
+  const selectors = []
+  if (designId !== undefined) selectors.push("designId")
+  if (args?.designIds !== undefined && args?.designIds !== null) selectors.push("designIds")
+  if (args?.expired !== undefined && args?.expired !== null) selectors.push("expired")
+  if (args?.olderThanDays !== undefined && args?.olderThanDays !== null) selectors.push("olderThanDays")
+  if (selectors.length > 1) {
+    throw new Error(`consume-design: pass exactly ONE selector — designId / designIds / expired / olderThanDays (got: ${selectors.join(" + ")}); a batch consume never guesses its target set.`)
+  }
+  if (selectors.length === 0) {
+    // 无选择器 = 单枚兼容形态（现行语义零变）：缺 designId 且多槽 ⇒ 拒（不误消费任一槽）
+    if (hasSlots && slots.size > 1) {
+      throw new Error(`consume-design: Multiple approved designs in this session (${slots.size}) — pass the designId parameter (echoed with each token) to choose which design to close out.`)
+    }
+    return consumeSingle(parent, undefined)
+  }
+  if (selectors[0] === "designId") return consumeSingle(parent, designId)
+  return consumeBatch(parent, selectors[0], args)
+}
+
+/** 单枚消费（现行形态逐字保留——读内存槽；未知 / 已消费 ⇒ 幂等 no-op；落盘失败 ⇒ 槽回滚 + 抛）。 */
+function consumeSingle(parent, designId) {
+  const slots = parent?._engDesignTokens
+  const hasSlots = slots instanceof Map && slots.size > 0
+  // 读槽值：给定 designId → 精确槽（未知/已消费 → undefined）；缺省 → 唯一槽
+  let token = null
+  if (designId && hasSlots) token = slots.get(designId) ?? null
+  else if (!designId && hasSlots) token = [...slots.values()][0]
+  // 未知 designId / 已消费 / 无任何槽 → 幂等 no-op 提示（不报错——评审 #3 定死）
+  if (!token) {
+    return `consume-design: no live slot${designId ? ` for designId ${designId}` : ""} (already consumed or never issued) — idempotent no-op, nothing changed.`
+  }
+  const slotId = designId ?? [...slots.keys()][0]
+  removeDesignTokenSlot(parent, designId, token)
+  try {
+    persistEngTokens(parent)
+  } catch (e) {
+    if (slotId) parent._engDesignTokens.set(slotId, token)
+    throw new Error(`consume-design: the slot was removed in memory but could NOT be durably deleted from the slot file (${e.message}) — the slot is restored in memory; retry consume-design.`)
+  }
+  return `design slot consumed — designId ${designId ?? "(single-design session)"} is closed out; a further eng-coder spawn for this design is mechanically rejected, and any new work (including deviation fixes) requires a fresh advisor(type='design') review and token.`
+}
+
+/** 批量消费（F-SL2 / KD-SL3 / KD-SL4）：目标集 = 并集视图按选择器解析；逐枚移出（token 值守护）→
+ *  单次 persist；落盘失败 ⇒ 内存快照整体回滚 + 抛。回执 = 逐枚行 + 计数行（`consumed N`）。
+ *  落盘前先经 D2 权威表 reconcile（槽 = 权威；未选中的**活**槽因此并入内存、随 persist 保住——
+ *  过期项则随本次落盘一并出清，即「落盘携带（如实）」注）。 */
+function consumeBatch(parent, selector, args) {
+  const now = Date.now()
+  const ttlMs = effectiveTokenTtlMs(parent)
+  const snapshot = parent._engDesignTokens instanceof Map ? new Map(parent._engDesignTokens) : null
+  reconcileEngTokensFromSlot(parent)
+  const union = unionSlots(parent)
+  const targets = []
+  const seen = new Set()
+  if (selector === "designIds") {
+    if (!Array.isArray(args.designIds) || args.designIds.length === 0) {
+      throw new Error("consume-design: designIds must be a non-empty array of design ids — pass an explicit list, or use expired / olderThanDays.")
+    }
+    for (const raw of args.designIds) {
+      const id = typeof raw === "string" ? raw.trim() : ""
+      if (!id) throw new Error(`consume-design: designIds entries must be non-empty strings (got ${JSON.stringify(raw)}).`)
+      if (seen.has(id)) continue // 重复条目去重（同一 id 只计一次——回执计数不虚增）
+      seen.add(id)
+      const token = union.get(id) ?? null
+      targets.push({ designId: id, token, consumed: token !== null }) // 未知 / 已消费 ⇒ 逐枚 no-op（幂等）
+    }
+  } else if (selector === "expired") {
+    if (args.expired !== true) {
+      throw new Error("consume-design: expired must be true — it selects every expired slot; pass designIds / olderThanDays for other shapes.")
+    }
+    for (const [id, t] of union) {
+      if (typeof t === "string" && tokenExpired(t, now)) {
+        const expiry = tokenExpiryMs(t)
+        targets.push({ designId: id, token: t, consumed: true, ageDays: expiry === null ? null : (now - (expiry - ttlMs)) / DAY_MS })
+      }
+    }
+    targets.sort(byOldest)
+  } else {
+    const n = args.olderThanDays
+    if (typeof n !== "number" || !Number.isFinite(n) || n < 0) {
+      throw new Error("consume-design: olderThanDays must be a non-negative number — pass the day threshold (e.g. olderThanDays: 30).")
+    }
+    for (const [id, t] of union) {
+      const expiry = typeof t === "string" ? tokenExpiryMs(t) : null
+      if (expiry === null) continue // 畸形串不可判龄——不被龄选择器选中（清点面照列）
+      const ageDays = (now - (expiry - ttlMs)) / DAY_MS
+      if (ageDays > n) targets.push({ designId: id, token: t, consumed: true, ageDays })
+    }
+    targets.sort(byOldest)
+  }
+  const removals = targets.filter((t) => t.consumed)
+  for (const t of removals) removeDesignTokenSlot(parent, t.designId, t.token)
+  if (removals.length > 0) {
+    try {
+      persistEngTokens(parent)
+    } catch (e) {
+      // KD-SL4：内存快照整体回滚 + 抛（不留半消费态——可重试）
+      if (snapshot) {
+        const map = parent._engDesignTokens instanceof Map ? parent._engDesignTokens : (parent._engDesignTokens = new Map())
+        map.clear()
+        for (const [id, v] of snapshot) map.set(id, v)
+      } else {
+        delete parent._engDesignTokens
+      }
+      throw new Error(`consume-design: ${removals.length} slot(s) were removed in memory but could NOT be durably deleted from the slot file (${e.message}) — the slots are restored in memory; retry consume-design.`)
+    }
+  }
+  const lines = targets.map((t) => (t.consumed
+    ? `- designId ${t.designId} — consumed`
+    : `- designId ${t.designId} — no live slot (already consumed or never issued) — idempotent no-op, nothing changed.`))
+  lines.push(removals.length > 0
+    ? `consumed ${removals.length} design slot(s) — a further eng-coder spawn for these designs is mechanically rejected; any new work (including deviation fixes) requires a fresh advisor(type='design') review and token.`
+    : "consumed 0 design slot(s) — nothing changed (idempotent no-op).")
+  return lines.join("\n")
+}

package/agent-tools/design-token.mjs

@@ -95,6 +95,19 @@ export function stripDesignTokenEcho(text, designToken) {
 const NO_VALID_ECHO_MARK = "未回显有效 token——未签发 (no valid token echo — no design token was issued)"
 const TRUNCATED_ECHO_MARK = "注：回显被截断（uuid 之后缺失或不符）——已按批准结算；全串 token 已签发 (note: truncated echo — the part after the uuid was missing or inexact; settled as approved; the full token was issued)"
 
+/** §5.2 verdict gate (#940): the echo alone is NOT the verdict — the receipt must
+ *  carry a `VERDICT: pass` line and no `VERDICT: changes-required` line (fail-closed). */
+const VERDICT_PASS_LINE    = /^[ \t]*[*_`]*[ \t]*VERDICT:[ \t]*pass[ \t]*[*_`]*[ \t]*$/m
+const VERDICT_CHANGES_LINE = /^[ \t]*[*_`]*[ \t]*VERDICT:[ \t]*changes-required[ \t]*[*_`]*[ \t]*$/m
+export function verdictGateFailure(rawResult) {
+  if (typeof rawResult !== "string") return "no-pass-line"
+  if (VERDICT_CHANGES_LINE.test(rawResult)) return "changes-required"
+  return VERDICT_PASS_LINE.test(rawResult) ? null : "no-pass-line"
+}
+
+/** §5.2 rejection mark (verbatim — machine-greppable; reason = no-pass-line | changes-required). */
+const VERDICT_GATE_MARK = (reason) => `裁定非通过——token 未签发 (review verdict is not pass — no design token was issued; reason: ${reason}; the echoed token was stripped)`
+
 /**
  * Shared design-review settlement (sync wrapper + async settle): the token echo
  * IS the verdict — the advisor echoes it only on approval. On echo (full string
@@ -134,6 +147,13 @@ export function settleDesignReview(agent, run, designToken, rawResult, opts = {}
     const stripped = stripDesignTokenEcho(rawResult, designToken).trim()
     return { passed: false, output: [stripped, NO_VALID_ECHO_MARK].filter(Boolean).join("\n\n") }
   }
+  // §5.2 裁定闸（#940）：签发 = 回显 ∧ 裁定行——缺 `VERDICT: pass` 行或含 `VERDICT: changes-required` 行
+  // ⇒ 拒签（与 M1 径同形：剥净回显 + 恒定标记；槽零写 ∥ 实例保持——修后重评）。
+  const gateFailure = verdictGateFailure(rawResult)
+  if (gateFailure !== null) {
+    const stripped = stripDesignTokenEcho(rawResult, designToken).trim()
+    return { passed: false, output: [stripped, VERDICT_GATE_MARK(gateFailure)].filter(Boolean).join("\n\n") }
+  }
   // Echoed the token → review passed. Issue it to the parent for eng-coder.
   agent._engDesignTokens ??= new Map()
   agent._engDesignTokens.set(run.designId, designToken)

package/agent-tools/digest-budget.mjs

@@ -55,7 +55,7 @@ export function digestBudgetOver(agent, size) {
   return over
 }
 
-/** Test seam: 落盘目录重定向（单测沙箱——生产从不调用）。 */
+/** Test seam: 落盘目录重定向（单元测试沙箱——生产从不调用）。 */
 let _digestOffloadDirOverride = null
 export function _setDigestOffloadDirForTest(dir) { _digestOffloadDirOverride = dir }
 

package/agent-tools/escalate-async.mjs

@@ -107,8 +107,10 @@ function touchedFilesNote(child, cwd) {
 export function classifyEscalateSettle(parent, entry) {
   if (entry.cancelled) return { cancelled: true }
   // AGENT-LOOP.md §6.15（TUI-OOM-ROOTCAUSE）——childAgent 语义面：settle 分类（touched 摘要/partial
-  // merge）与 status/observe 摘要的读取源；**消化注入完成后由 `releaseSettledEntry`
-  // （async-settle.mjs）置 null**（池内未消化窗口不释放——表 2 候选 2 否决）。
+  // merge）与 status/observe 摘要的读取源；**消化注入完成后释放**（池内未消化窗口不释放——表 2 候选 2 否决）；
+  // fallback 面（无 `_daSession`）由 `releaseSettledEntry`（async-settle.mjs）置 null（逐字沿用）；会话态
+  // （`_daSession`）注入后改调 `releaseChildHold`（仅释放 `childAgent`——`report` 保留至销账 / 升级；
+  // §6.31.4 ∥ KD-DA7）。
   const child = entry.childAgent
   const touched = child?._touchedFiles ?? []
   const overlap = overlapPaths(parent, entry.launchSeq, touched)

package/agent-tools/manifest.mjs

@@ -0,0 +1,193 @@
+/**
+ * agent-tools/manifest.mjs — `manifest` 工具：M1 项目状态档（`PROJECT-MANIFEST.json`）的
+ * agent 侧读写出口（2026-10-08 · 台账 #1098；权威设计 = `docs/core/design/MANIFEST.md` §2.10）。
+ *
+ * 三动作（KD-M1-38）：
+ *  - `read`  ⇒ `projectView(target)` 五态报明（稳定锚 `state=ok|missing|invalid|ambiguous|no-project`）；
+ *              `ok` 态再 `readManifest(view.root)` 取细节面（`projectView` 面不含 `missingKeys` /
+ *              `unknownKeys`）——**不抛**（缺档报明，非拒）。
+ *  - `init`  ⇒ 缺档建默认档（`initManifest`——内容 = `DEFAULT_MANIFEST`）；**已带档 ⇒ 拒**
+ *              （不覆盖——`initManifest` 本体无覆盖保护，工具面补此闸）。
+ *  - `write` ⇒ **点改**：读现档 → 设节点 → 落盘（`writeManifest` 内先 `validateManifest`——
+ *              编辑结果非法 ⇒ 拒 + 盘零变）；**缺档 ⇒ 拒** + 引导 `init`（写不建档）。
+ *
+ * 写面白名单（判据单源 = `MANIFEST_SCHEMA`——钉死谓词）：`keys` 中**非** `nestedKeys` 父键者
+ * （`version` / `phase` / `promptsLanding` / `codePaths` 整键）+ `nestedKeys` 子键
+ * （`docRoot.*` / `checkConfig.*` / `index.*`（含 `publicRepos`）/ `advisor.*`）；**四族整键写
+ * （传整个对象）⇒ 拒**；白名单外 ⇒ 拒（拼写保护——未知键写盘 = 静默死键，KD-M1-36 问题本体）。
+ * `value` 解析 = 同款口径 `settings.mjs:216-228`（先 `JSON.parse`，失败取字面串；`"null"` ⇒ `null`
+ * ——`docRoot.*` 的「本面无」，KD-M1-37）。
+ *
+ * 目标面（KD-M1-39——判据复用零新解析器）：`read` = `projectView`；`init` / `write` =
+ * `projectRootView`（歧义 ⇒ 拒 + 候选全列——不猜）；`resolveProjectRoot` 对歧义塌缩 `null` 再回落 cwd
+ * ⇒ 写 / 建两动作**不得**直用。
+ *
+ * 写路径复用（零新写路径）：落盘恒经 `writeManifest` / `initManifest`——`writer` 恒显式 `'main'`
+ * （缺省 `'subagent'` = 写门 fail-closed 缺省，KD-M1-3 / AC-M1-5 零改）。
+ *
+ * 报告面随动（KD-M1-40）：本工具**不写** `agent.manifest`（第二值源否——工具目标可为非锚项目）——
+ * 写盘 = 盘面变化，情境行经既有 ③b mtime 门控于下回合采纳（`agent/setup-reminders.mjs`）。
+ */
+import { existsSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { MANIFEST_REL, MANIFEST_SCHEMA, initManifest, projectRootView, projectView, readManifest, writeManifest } from "../manifest.mjs"
+import { DESC } from "../tools/shared.mjs"
+
+/** 拒面统一前缀（设计 §2.10：`manifest <action>: refused — …`）——盘零变类拒绝一律经此抛错。 */
+function refuse(action, reason) {
+  return new Error(`manifest ${action}: refused — ${reason}`)
+}
+
+/** `target` 解析（先例 `eng.mjs:81` 缺省会话锚 ∥ `git.mjs:32-35` 相对形归一）：缺省 = 会话锚
+ *  （`ctx.agent.cwd ?? ctx.cwd ?? process.cwd()`）；显式相对形按会话锚归一（绝对形原样）。 */
+function resolveTarget(args, ctx) {
+  const base = ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
+  return args?.target ? resolve(base, String(args.target)) : resolve(base)
+}
+
+/** 写面白名单谓词（**钉死**——设计 §2.10）：点分路径恰两形——
+ *  ① 单段：`keys` ∩ ∉ `nestedKeys`（= `version` / `phase` / `promptsLanding` / `codePaths` 整键）；
+ *  ② 双段：`nestedKeys[父]` 含子键（四族子键）；其余（四族整键写 / 未知键 / 更深路径）⇒ 拒。
+ *  `Array.isArray` 守卫：原型链名（`__proto__` / `constructor` / `toString` 类）取到非数组 ⇒ 落拒面
+ *  （不得 TypeError 直出——白名单外一律 `refused` 统一前缀）。 */
+function isWritableKey(key) {
+  const segs = String(key).split(".")
+  if (segs.length === 1) return MANIFEST_SCHEMA.keys.includes(segs[0]) && !Object.hasOwn(MANIFEST_SCHEMA.nestedKeys, segs[0])
+  if (segs.length === 2) {
+    const subs = MANIFEST_SCHEMA.nestedKeys[segs[0]]
+    return Array.isArray(subs) && subs.includes(segs[1])
+  }
+  return false
+}
+
+/** `value` 解析（同款口径 = `settings.mjs:216-228`）：先 `JSON.parse`（`"null"` ⇒ `null`；数值 /
+ *  布尔 / 数组皆 JSON 形），失败取字面串（裸串如 `docs/design`）。 */
+function parseValue(raw) {
+  const s = String(raw)
+  try { return JSON.parse(s) } catch { return s }
+}
+
+/** 点分路径设值（自动建中间对象——settings `setKeyPath` 同款；白名单谓词已保父段为已知族）。 */
+function setKeyPath(obj, path, value) {
+  const segs = String(path).split(".")
+  let cur = obj
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (cur[segs[i]] === null || typeof cur[segs[i]] !== "object") cur[segs[i]] = {}
+    cur = cur[segs[i]]
+  }
+  cur[segs[segs.length - 1]] = value
+}
+
+/** 歧义拒文案（候选全列——不猜；init / write 共用）：多候选 = 显式指定 target，机制不代选。 */
+function ambiguousReason(target, candidates) {
+  return `ambiguous target ${target} — ${candidates.length} candidate projects (the mechanism never picks one); pass target explicitly:\n` +
+    candidates.map((c) => `- ${c}`).join("\n")
+}
+
+/** read 动作（五态报明——**不抛**）：`state=` 稳定锚 + 各态附行（ok 细节面 / missing 引导 /
+ *  ambiguous 候选全列 / invalid 错误行）。 */
+function readAction(target) {
+  const view = projectView(target)
+  const lines = [`state=${view.state}`]
+  if (view.path) lines.push(`path=${view.path}`)
+  if (view.state === "ok") {
+    const m = readManifest(view.root) // 细节面：missingKeys / unknownKeys / errors（非空才出）
+    lines.push(`manifest=${JSON.stringify(m.manifest)}`)
+    if (m.missingKeys?.length) lines.push(`missingKeys=${m.missingKeys.join(", ")}`)
+    if (m.unknownKeys?.length) lines.push(`unknownKeys=${m.unknownKeys.join(", ")}`)
+    if (m.errors?.length) lines.push(`errors=${m.errors.join("；")}`)
+  } else if (view.state === "missing") {
+    lines.push(`hint: run manifest action=init to create the default manifest here`)
+  } else if (view.state === "no-project") {
+    lines.push(`hint: no project on the ancestor chain and none below — manifest action=init can create one at the target`)
+  } else if (view.state === "ambiguous") {
+    lines.push(`candidates (${(view.candidates ?? []).length}):`)
+    for (const c of view.candidates ?? []) lines.push(`- ${c}`)
+    lines.push(`hint: pass target explicitly — the mechanism never picks one`)
+  } else if (view.state === "invalid") {
+    if (view.errors?.length) lines.push(`errors=${view.errors.join("；")}`)
+  }
+  return lines.join("\n")
+}
+
+export const manifestTool = {
+  name: "manifest",
+  description: DESC("manifest"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["read", "init", "write"], description: "read — current manifest + validation state (five-state anchor, never throws); init — create the default manifest when missing (refused when one already exists); write — point-edit one node (key + value) of an existing manifest" },
+      target: { type: "string", description: "Explicit target directory — defaults to the session anchor; relative paths resolve against it. Ambiguous targets are refused with the full candidate list (never picks one)." },
+      key: { type: "string", description: "(write) Dot path of the node to set — version / phase / promptsLanding / codePaths, or a sub-key of docRoot / checkConfig / index / advisor (e.g. docRoot.design / index.publicRepos / advisor.docMap); whole-object writes of those four families are refused", },
+      value: { type: "string", description: "(write) New value — parsed as JSON first (null / true / 5 / [\"a\"]), otherwise kept as a literal string; \"null\" is the explicit no-such-face for docRoot.<key>" },
+    },
+    required: ["action"],
+  },
+  readonly: false, // 动作级分类（dispatch-gates `isSubagentReadonlyAction`）：read = 只读类；init / write 保持侧效门
+  async execute(args, ctx) {
+    const action = args?.action
+    if (!["read", "init", "write"].includes(action)) {
+      throw new Error(`manifest: action must be one of read/init/write — got ${JSON.stringify(action)}`)
+    }
+    const target = resolveTarget(args, ctx)
+
+    if (action === "read") return readAction(target)
+
+    // init / write：目标面 = `projectRootView`（歧义直读形——不猜；KD-M1-39）
+    const rootView = projectRootView(target)
+    if (rootView.state === "ambiguous") {
+      throw refuse(action, ambiguousReason(target, rootView.candidates))
+    }
+
+    if (action === "init") {
+      const root = rootView.state === "ok" ? rootView.root : target // 梯⑤（无项目）⇒ 落点 = target 自身
+      const file = join(root, MANIFEST_REL)
+      if (existsSync(file)) {
+        throw refuse("init", `${file} already carries a manifest — init never overwrites (use action=write to edit it)`)
+      }
+      try {
+        initManifest(root, { writer: "main" }) // 落盘恒经写门（writer 闸 + 校验前闸——零新写路径）
+      } catch (e) {
+        throw refuse("init", `could not write the default manifest at ${file} — ${e?.message ?? String(e)}`)
+      }
+      return `manifest init: created default manifest (DEFAULT_MANIFEST)\npath=${file}`
+    }
+
+    // write：缺档 ⇒ 拒 + 引导 init（写不建档——多写权面唯一的建档动作 = init）
+    if (rootView.state === "none") {
+      throw refuse("write", `no project at ${target} — write requires an existing ${MANIFEST_REL}; run manifest action=init first (write never creates one)`)
+    }
+    const root = rootView.root
+    const file = join(root, MANIFEST_REL)
+    const key = args?.key
+    if (!key) throw new Error("manifest write: key is required (dot path, e.g. docRoot.design)")
+    if (args?.value === undefined) throw new Error("manifest write: value is required (JSON-parsed first, otherwise a literal string)")
+    if (!isWritableKey(key)) {
+      throw refuse("write", `key "${key}" is not writable — writable nodes: version / phase / promptsLanding / codePaths + sub-keys of docRoot / checkConfig / index / advisor (whole-object writes of the four families are refused)`)
+    }
+    let current
+    try {
+      current = readManifest(root)
+    } catch (e) {
+      throw refuse("write", `could not read ${file} — ${e?.message ?? String(e)}`)
+    }
+    if (!current.ok) {
+      if (current.reason === "missing") {
+        throw refuse("write", `${file} does not exist — run manifest action=init first (write never creates one)`)
+      }
+      if (!current.manifest) {
+        throw refuse("write", `${file} is not editable (fail-closed): ${(current.errors ?? []).join("；")}`)
+      }
+      // 现档可解析但校验非法：照常点改——编辑结果仍经落盘前 `validateManifest`（非法 ⇒ 拒 + 盘零变）
+    }
+    const value = parseValue(args.value)
+    const manifest = current.manifest
+    setKeyPath(manifest, String(key), value)
+    try {
+      writeManifest(root, manifest, { writer: "main" }) // 落盘前 validateManifest（编辑结果非法 ⇒ 拒 + 盘零变）
+    } catch (e) {
+      throw refuse("write", `the edited manifest fails the pre-write validation (disk unchanged) — ${e?.message ?? String(e)}`)
+    }
+    return `manifest write: set ${key} = ${JSON.stringify(value)}\npath=${file}`
+  },
+}

package/agent-tools/parent-channel.mjs

@@ -20,7 +20,7 @@
  *   生命周期与子代理生命周期**解耦**（settle / cancel 不迁移、不清队列——F3）。
  * - 父侧唤醒 = ask 入队尾调 `wakeAsyncWaiters(parent)`（**同步**，零 await；`note` 不唤醒）——
  *   零新字段 / 零新容器 / 零新注册：等待栓数组由挂起驱动注册，非挂起期数组空 ⇒ no-op。
- * - 父侧消费 = `drainChildUpstream(agent)`（`thincoder-core/agent.mjs` 循环头单点，紧邻
+ * - 父侧消费 = `drainChildUpstream(agent)`（`thincoder-core/agent/turn-loop.mjs` 循环头单点，紧邻
  *   `consumeInjected?.(agent)`——同址反向）：全部 pending **合并一条** user 消息（`pushReal`
  *   非 transient——事务性事件落盘，D-UC5），每条附结束注脚（已 settle / 已 cancel 两形态；
  *   其余态不附——不臆断）。
@@ -151,10 +151,13 @@ function endNote(agent, entry) {
   return ""
 }
 
+/** kind → 投递标识（单点渲染——机读面 / 日志留原 kind；用户 2026-10-06 裁定逐字）。 */
+const KIND_MARK = { ask: "[上抛·待裁]", note: "[上抛·知会]" }
+
 /**
- * 父侧消费点（回合边界单点——`agent.mjs` 循环头；空队列 no-op = 零历史变更、零开销）：
+ * 父侧消费点（回合边界单点——`agent/turn-loop.mjs` 循环头；空队列 no-op = 零历史变更、零开销）：
  * 全部 pending 消息**合并为一条** user 消息注入（`pushReal`——不带 `transient`，事件落盘），
- * 按入队序逐条列示（来源 `role#id` + `kind` + message（`escapeXml`）+ 结束注脚）。
+ * 按入队序逐条列示（来源 `role#id` + **kind 标识**（`ask` ⇒ `[上抛·待裁]` ∥ `note` ⇒ `[上抛·知会]`）+ message（`escapeXml`）+ 结束注脚）。
  * @param {object} agent 父（消费方）agent 形态。
  * @returns {number} 本次消费条目数（0 = 空队列 no-op）。
  */
@@ -168,7 +171,7 @@ export function drainChildUpstream(agent) {
       + "Answer with subagent action:'send' (id + message) if the decision is yours; an unanswered ask means that child skips the part and reports it as not done.]"
     : `[System reminder: in-flight message from your subagent ${entries[0].from} — it keeps working on the unaffected parts. `
       + "Answer with subagent action:'send' (id + message) if the decision is yours; an unanswered ask means the child skips that part and reports it as not done.]"
-  const rows = entries.map((e) => `${many ? "- " : ""}${e.kind} · ${e.from}: ${escapeXml(e.message)}${endNote(agent, e)}`)
+  const rows = entries.map((e) => `${many ? "- " : ""}${KIND_MARK[e.kind] ?? e.kind} · ${e.from}: ${escapeXml(e.message)}${endNote(agent, e)}`)
   pushReal(agent, { role: "user", content: [header, ...rows].join("\n") })
   return entries.length
 }