@thincoder/core 0.10.2 → 0.10.4

package/agent-tools/subagent-panel.mjs

@@ -9,6 +9,11 @@
  * computePanelBlocks(ctx.state)（ctx.state = agent._tuiState——TUI 装配处接线——单账本）；
  * 未挂载（headless/VSC/子代理）→ 现算返 null → 降级/报不可用照旧
  * （T-P5 语义零变）。门控语义零动（F-4）——仅数据源从镜像换现算。
+ * **子代理面板批（2026-10-04 · `docs/desktop/design/PANEL-READBACK.md`）——回读源链**：数据源不再单源现算——
+ * `readPanelSource(ctx)` = `ctx.readout()`（桌面渲染面实况快照——上报缓存读面）优先 ⇒ `ctx.state` 现算 ⇒
+ * 二者皆空报不可用；视图面快照非空 ⇒ `{ source:"renderer", asOf, ageMs, panel[] }`（awaitingDigest 条读时
+ * 交叉核池/pending 标 `digested`——与 CLI 面同判据）；freeze 门控两源同判（桌面块 `awaitingDigest`/`region` 为
+ * 独立字段），键统一规范化（`sub:` 前缀剥除——**有意放宽且两端同宽**；发射键 = 规范化键，relay 文法不吃 `:`）。
  * subagent-actions.mjs 尾部 re-export executePanelAction 保 subagent.mjs 既有 import 面。
  */
 import { getAsyncPool } from "./async-settle.mjs"
@@ -41,67 +46,129 @@ function consultChildUndigested(agent, key) {
   return false
 }
 
+/**
+ * 回读源链（子代理面板批 · 2026-10-04 · `PANEL-READBACK.md` §2.1/§2.3）：渲染面快照
+ * （`ctx.readout()`——桌面实况回读上报；`{ blocks, receivedAt }`，块形 = 判别六键 + `role`/`id` 随行）优先
+ * ∥ CLI 现算（`computePanelBlocks(ctx.state)`——F-3 单账本）∥ 二者皆空 ⇒ `null`（拒因照旧）。
+ * 返回 `{ blocks, readout }`：`readout` 非空 = 桌面快照源（`awaitingDigest` / `region` 为块独立字段）。
+ */
+function readPanelSource(ctx) {
+  const snapshot = typeof ctx.readout === "function" ? ctx.readout() : null
+  if (snapshot && Array.isArray(snapshot.blocks)) return { blocks: snapshot.blocks, readout: snapshot }
+  const snap = computePanelBlocks(ctx.state)
+  return Array.isArray(snap) ? { blocks: snap, readout: null } : null
+}
+
+/** 键归一（**有意放宽且两端同宽**——§2.3）：`sub:` 前缀剥除后比对（桌面块键 `sub:role#id` ∥ CLI 块键
+ *  `role#id` 两写法皆接受）；命中后比对与发射全用规范化键（relay 前缀文法 `^\w-+#\d+/` 不吃 `:`）。 */
+function normalizePanelKey(key) {
+  const k = String(key ?? "")
+  return k.startsWith("sub:") ? k.slice("sub:".length) : k
+}
+
+/** 两源同判——等待消化：CLI 块 = 现算 status 位；桌面块 = 判别键 `awaitingDigest`。 */
+function awaitingOf(src, block) {
+  return src.readout ? block.awaitingDigest === true : block.status === "awaitingDigest"
+}
+
+/** 活态标签（live 列表 ∥ 拒因文案共用）：桌面块把 awaiting 态折进 status 位（与 CLI 现算同形）。 */
+function liveStatusOf(src, block) {
+  return awaitingOf(src, block) ? "awaitingDigest" : String(block.status ?? "unknown")
+}
+
+/** 桌面回读条目（视图面——判别六键 + `role`/`id` 随行；awaitingDigest 条读时交叉核池/pending 标 `digested`
+ *  —— 判据与 CLI 面同源；consult 子块按消费判据——键经归一后入判）。 */
+function readoutPanelEntry(agent, block) {
+  const key = normalizePanelKey(block.key)
+  const out = {
+    key: block.key,
+    role: block.role ?? null,
+    id: block.id ?? null,
+    status: block.status ?? null,
+    frozen: block.frozen === true,
+    awaitingDigest: block.awaitingDigest === true,
+    region: block.region === "flow" ? "flow" : "activity",
+    dom: block.dom === true,
+  }
+  if (out.awaitingDigest) {
+    out.digested = consultChildKey(key)
+      ? !consultChildUndigested(agent, key)
+      : !blockKeyIn(agent._pendingAsyncResults, key)
+        && !blockKeyIn(getAsyncPool(agent, "subagent"), key) && !blockKeyIn(getAsyncPool(agent, "advisor"), key)
+  }
+  return out
+}
+
 /**
  * AGENT-LOOP-SUBAGENT.md §6.7.2 D-P3 冻结门控（安全）：仅允许冻结 awaitingDigest 且池（_asyncSubagents/
  * _asyncAdvisors——经 getAsyncPool accessor——D1）无对应运行条目 + pending 单容器
  * （_pendingAsyncResults——D2）无对应条目的块（= 已消化驻留块——报告已入模型上下文
  * ——pending 已消费——状态滞后——补发冻结不破坏任何顺序）。
+ * - 数据源 = **回读源链**（子代理面板批 · 2026-10-04）：`ctx.readout`（桌面渲染面快照——块判别键
+ *   `awaitingDigest`/`region` 独立字段）优先 ∥ `ctx.state` 现算；命中后比对与发射全用**规范化键**
+ *   （`sub:` 前缀剥除——有意放宽且两端同宽，§2.3）。
  * - pending 仍有对应（报告未达模型）→ 拒绝（提前回收破坏消化顺序——T-P3）
  * - 不存在的 key / 仍 running / done 的块 → 拒绝（T-P4——running 块 settle 时自冻）
- * - 无面板（现算返 null）→ 拒绝（headless/VS Code——freeze 不可用——T-P5）
+ * - 无面板（两源皆空）→ 拒绝（headless/VS Code——freeze 不可用——T-P5）
+ * - 已入流（桌面快照 `region:"flow"`——已归档）→ 追加拒因（无卡可收；CLI 源无该字段 ⇒ 零改）
  * - consult 子块（#748）：会话在跑 ∥ 会话条目在 pending（`childIds` 携该号）→ 拒绝（同判据——与回收 ∥ 补发同源）
- * 错误信息明确（模型可解释 + 自助修正）。返回 { ok:true } 或 { err }。
+ * 错误信息明确（模型可解释 + 自助修正）。返回 `{ ok:true, renderer }` 或 `{ err }`。
  */
 function panelFreezeGate(ctx, key) {
-  // F-3（2026-09-10）：镜像退役——经 ctx.state 读时现算（CLI-ACTIVITY-DEBLOAT）。
-  // 门控语义零动（F-4）：awaitingDigest 限定/池归属查/pending 查逐字保留——仅数据源换现算。
-  const snap = computePanelBlocks(ctx.state)
-  if (!Array.isArray(snap)) {
+  const src = readPanelSource(ctx)
+  if (src === null) {
     return { err: "panel unavailable — no CLI TUI panel in this session (headless / VS Code / subagent contexts — freeze unavailable; panel is CLI-TUI-only, AC-P4)" }
   }
-  const block = snap.find((b) => b.key === key)
+  const want = normalizePanelKey(key)
+  const block = src.blocks.find((b) => normalizePanelKey(b.key) === want)
   if (!block) {
-    const live = snap.map((b) => `${b.key}(${b.status})`).join(", ")
+    const live = src.blocks.map((b) => `${b.key}(${liveStatusOf(src, b)})`).join(", ")
     return { err: `unknown panel block key: ${key} — the live panel holds: ${live || "(no blocks)"}` }
   }
-  if (block.status !== "awaitingDigest") {
-    if (block.status === "done") {
-      return { err: `block ${key} is already done — nothing to freeze; it was (or is about to be) reclaimed into the conversation by the freeze sweep at the turn end / settle (only digested-stuck awaitingDigest blocks need a manual freeze)` }
+  // 已入流 = 已归档（桌面快照判别键）——无卡可收（CLI 源无 region 字段 ⇒ 零改）。
+  if (src.readout && block.region === "flow") {
+    return { err: `block ${want} is already in the conversation flow (region "flow") — it has been archived; there is nothing left to freeze` }
+  }
+  if (!awaitingOf(src, block)) {
+    const status = String(block.status ?? "unknown")
+    if (status === "done") {
+      return { err: `block ${want} is already done — nothing to freeze; it was (or is about to be) reclaimed into the conversation by the freeze sweep at the turn end / settle (only digested-stuck awaitingDigest blocks need a manual freeze)` }
     }
-    if (block.status === "running") {
-      return { err: `block ${key} is still running — freeze only reclaims awaitingDigest blocks whose report is already digested; a running block freezes on its own settle (or stop it with action:'cancel' if it is a background async child)` }
+    if (status === "running") {
+      return { err: `block ${want} is still running — freeze only reclaims awaitingDigest blocks whose report is already digested; a running block freezes on its own settle (or stop it with action:'cancel' if it is a background async child)` }
     }
-    return { err: `block ${key} is in state ${block.status} — freeze only reclaims awaitingDigest blocks whose report is already digested` }
+    return { err: `block ${want} is in state ${status} — freeze only reclaims awaitingDigest blocks whose report is already digested` }
   }
-  if (blockKeyIn(getAsyncPool(ctx.agent, "subagent"), key) || blockKeyIn(getAsyncPool(ctx.agent, "advisor"), key)) {
-    return { err: `block ${key} still has a live pool entry — it is NOT a digested-stuck block (freeze refused; status action shows the pool)` }
+  if (blockKeyIn(getAsyncPool(ctx.agent, "subagent"), want) || blockKeyIn(getAsyncPool(ctx.agent, "advisor"), want)) {
+    return { err: `block ${want} still has a live pool entry — it is NOT a digested-stuck block (freeze refused; status action shows the pool)` }
   }
   // ASYNC-RESULT-CONTAINER.md D2：pending 单容器（四族统一——原 escalate/consult
   // 独立族退役）。#748：consult 子块键不经裸键比对（会话条目键 `consult#<sessionId>` 与
   // 子块键可数字撞键）——改判消费判据（会话在跑 ∥ 会话条目在 pending——与回收 ∥ 补发同源）。
-  if (!consultChildKey(key) && blockKeyIn(ctx.agent._pendingAsyncResults, key)) {
-    return { err: `block ${key} is still genuinely awaiting digestion — its report is still pending and has NOT reached the model yet; freezing now would break the digestion order (wait for the digest run, which reclaims it automatically)` }
+  if (!consultChildKey(want) && blockKeyIn(ctx.agent._pendingAsyncResults, want)) {
+    return { err: `block ${want} is still genuinely awaiting digestion — its report is still pending and has NOT reached the model yet; freezing now would break the digestion order (wait for the digest run, which reclaims it automatically)` }
   }
-  if (consultChildUndigested(ctx.agent, key)) {
-    return { err: `block ${key} belongs to a consultation whose digest has not been consumed — the session is still running, or its session entry is still pending (freeze refused; the block is reclaimed at the consumption window)` }
+  if (consultChildUndigested(ctx.agent, want)) {
+    return { err: `block ${want} belongs to a consultation whose digest has not been consumed — the session is still running, or its session entry is still pending (freeze refused; the block is reclaimed at the consumption window)` }
   }
-  return { ok: true }
+  return { ok: true, renderer: src.readout !== null }
 }
 
 /**
  * AGENT-LOOP-SUBAGENT.md §6.7.2 subagent action:"panel"（D-P2——readonly 视图面 + 门控干预面——单动作双参，
  * freeze 优先）：
- * - view（缺省——返回面板块列表）：ctx.state（= agent._tuiState——CLI TUI 装配）经
- *   computePanelBlocks **读时现算**（F-3 单账本——与用户所见一致）。awaitingDigest 条目
- *   **读时交叉**
- *   _pendingAsyncResults/池 标注 digested（round1 #3——digested:true
- *   = 报告已消化但块仍驻留——异常块——freeze 候选；模型可定位解释 UI 怪相）。
- * - freeze:key（D-P3 门控通过 → 发 key + "/" + ⟦ev⟧done 哨兵字面 token——
- *   onToken——TUI routeSubToken 冻结回收——落位复用 sub._freezeAt settle 锚点
- *   splice，无锚点尾推兜底——AGENT-LOOP-ASYNC-POOL.md §6.8 同口径——round1 #2）。
- * 无 TUI state（headless/VS Code——D-P2 round1 #1：webview 无 state.subTasks 对应物——
- * 7.2.3.2 #8 先例）→ view 恒降级池视图（双池经 getAsyncPool + pending 单容器
- * 合成）+ no panel 注；freeze 报不可用。CLI-only 完整能力（AC-P4）。
+ * - view（缺省——返回面板块列表）：**回读源链**（子代理面板批 · 2026-10-04）：渲染面快照非空 ⇒
+ *   `{ source:"renderer", asOf, ageMs, panel[] }`（判别六键 + role/id 随行；awaitingDigest 条读时交叉
+ *   核池/pending 标 `digested`）∥ 快照空 ⇒ 现链回落——ctx.state（= agent._tuiState——CLI TUI 装配）经
+ *   computePanelBlocks **读时现算**（F-3 单账本——与用户所见一致），awaitingDigest 条目**读时交叉**
+ *   _pendingAsyncResults/池 标注 digested（round1 #3——digested:true = 报告已消化但块仍驻留——异常块——
+ *   freeze 候选；模型可定位解释 UI 怪相）。
+ * - freeze:key（D-P3 门控通过 → 发 key + "/" + ⟦ev⟧done 哨兵字面 token——onToken——TUI routeSubToken
+ *   冻结回收 ∥ 桌面经桥 relay ⇒ 渲染面归档机入流 + record——同字面、零新消费者；发射 = 规范化键。
+ *   落位复用 sub._freezeAt settle 锚点 splice，无锚点尾推兜底——AGENT-LOOP-ASYNC-POOL.md §6.8 同口径——round1 #2）。
+ * 两源皆空（headless/VS Code——D-P2 round1 #1：webview 无 state.subTasks 对应物——7.2.3.2 #8 先例）
+ * → view 恒降级池视图（双池经 getAsyncPool + pending 单容器合成）+ no panel 注；freeze 报不可用。
+ * CLI-only 完整能力（AC-P4）。
  */
 export function executePanelAction(args, ctx) {
   const agent = ctx.agent
@@ -115,17 +182,22 @@ export function executePanelAction(args, ctx) {
     }
     const gate = panelFreezeGate(ctx, freezeKey)
     if (gate.err) return JSON.stringify({ status: "error", error: gate.err })
+    const panelKey = normalizePanelKey(freezeKey)
     if (!ctx.callbacks?.onToken) {
-      return JSON.stringify({ status: "error", error: `panel present but no token relay in this context — the freeze of ${freezeKey} cannot reach the TUI` })
+      return JSON.stringify({ status: "error", error: `panel present but no token relay in this context — the freeze of ${panelKey} cannot reach the TUI` })
     }
     // 门控通过 → 发 done 冻结事件（settle 同机制字面格式——TUI routeSubToken done
     // 分支冻结回收——落位 _freezeAt settle 锚点 splice；无锚点（旧会话残留）时
     // freezeSubTaskLines 尾推兜底——注明两种落位，模型不被误导（advisor 🟡1）。
-    ctx.callbacks.onToken(`${freezeKey}/⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
+    // 桌面（回读源）：同字面经桥 relay 分流 ⇒ 渲染面归档机（归档入流 + record）——零新消费者；
+    // 发射键 = 规范化键（`sub:` 前缀不入 relay 文法——§2.3）。
+    ctx.callbacks.onToken(`${panelKey}/⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
     return JSON.stringify({
-      key: freezeKey,
+      key: panelKey,
       status: "frozen",
-      note: "done freeze event issued — the TUI reclaimed the block into the conversation (spliced at its settle anchor when one is recorded, else appended at the current stream end — same-rule position)",
+      note: gate.renderer
+        ? "done freeze event issued — the desktop renderer reclaimed the block into the conversation flow (archived there, record appended)"
+        : "done freeze event issued — the TUI reclaimed the block into the conversation (spliced at its settle anchor when one is recorded, else appended at the current stream end — same-rule position)",
     })
   }
   // ── view 面（缺省——readonly）──
@@ -133,6 +205,17 @@ export function executePanelAction(args, ctx) {
   if (args?.view === false) {
     return JSON.stringify({ status: "error", error: "panel has nothing to do — view:false with no freeze key; pass freeze:'role#N' to reclaim a digested-stuck block, or omit view (defaults to true)" })
   }
+  // 回读源链（子代理面板批 · 2026-10-04 · `PANEL-READBACK.md` §2.1）：渲染面快照非空 ⇒ 实况回读面
+  // （判别六键 + role/id 随行 + awaitingDigest 读时交叉；asOf/ageMs 携龄——不设截断，卡留块状态恒定）。
+  const readout = typeof ctx.readout === "function" ? ctx.readout() : null
+  if (readout && Array.isArray(readout.blocks)) {
+    return JSON.stringify({
+      source: "renderer",
+      asOf: readout.receivedAt ?? null,
+      ageMs: typeof readout.receivedAt === "number" ? Math.max(0, Date.now() - readout.receivedAt) : null,
+      panel: readout.blocks.map((b) => readoutPanelEntry(agent, b)),
+    })
+  }
   const snap = computePanelBlocks(ctx.state)
   if (!Array.isArray(snap)) {
     // F-P3 降级：无 TUI state（headless/VS Code/子代理上下文——CLI TUI-only 完整能力）→
@@ -174,7 +257,8 @@ export function executePanelAction(args, ctx) {
     if (b.status === "running") {
       out.elapsedSec = b.startedAt ? Math.max(0, Math.floor((Date.now() - b.startedAt) / 1000)) : 0
     } else if (b.status === "awaitingDigest") {
-      // 读时交叉（round1 #3）：pending/池均无对应 = 报告已消化（注入即从两者移除）——
+      // 读时交叉（round1 #3）：pending/池均无对应 = 报告已消化（fallback 面注入即从两者移除；
+      // 会话面注入后不随即移除——留容器至销账 / 升级，移除 = `accountDigestRound` 的 splice；§6.31）——
       // 块驻留 = 状态滞后——digested:true（freeze 候选——模型可定位异常块）。
       // ASYNC-RESULT-CONTAINER.md D2：pending 单容器参与比对（四族统一）。
       // #748：consult 子块按消费判据（会话在跑 ∥ 会话条目在 pending ⇒ 未消化）——与门控同源。

package/agent-tools/subagent-spawn.mjs

@@ -243,7 +243,7 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   if (role === "eng-coder" || role === "eng-designer") {
     const given = typeof args.batchDoc === "string" ? args.batchDoc.trim() : ""
     const refusal = (suffix = "") => new Error(
-      `batchDoc is required for role='${role}' — pass the batch record path (docs/batches/<batch>-<topic>.md); spawn refused without it.` + suffix)
+      `batchDoc is required for role='${role}' — pass 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); spawn refused without it.` + suffix)
     if (!given) throw refusal()
     batchDocAbs = resolveBatchReadPath(parent.cwd ?? process.cwd(), given)
     if (!batchDocAbs) throw refusal(" (given path is not a readable file)")

package/agent-tools/subagent.mjs

@@ -132,14 +132,14 @@ export const subagentTool = {
     properties: {
       action: { type: "string", enum: ["spawn", "status", "escalate", "cancel", "panel", "consume-design", "observe", "send"], description: "Which action — spawn (default) / status / observe / send / escalate / cancel / panel / consume-design; 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; requires the CLI TUI panel mirror." },
+      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)." },
       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 slot to close out (required to pick between several; the gate refuses to guess)." },
-      batchDoc: { type: "string", description: "REQUIRED for role='eng-coder'/'eng-designer': the batch record path (docs/batches/<batch>-<topic>.md) — 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." },
+      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." },
       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." },
       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." },
@@ -188,7 +188,9 @@ export const subagentTool = {
       // CLI-ACTIVITY-DEBLOAT F-3（2026-09-10）接线：executePanelAction 经 ctx.state
       // （= agent._tuiState——startTUI 反向挂载）读时现算面板块（computePanelBlocks）——
       // 手工面板镜像已退役。headless/VSC 无挂载 → 现算返 null → 降级照旧。
-      if (action === "panel") return executePanelAction(args, { ...ctx, state: ctx.agent?._tuiState })
+      // 子代理面板批（2026-10-04）：另携 ctx.readout（= agent._panelReadout——桌面渲染面实况回读
+      // 上报缓存读面；agent-host 装配挂）——核内读源链 readout → state → 降级（PANEL-READBACK.md §2.1）。
+      if (action === "panel") return executePanelAction(args, { ...ctx, state: ctx.agent?._tuiState, readout: ctx.agent?._panelReadout })
       // SUBAGENT-OBSERVE-SEND：observe = readonly 查询（同 status——digest/planMode 放行）；
       // send = 控制类豁免（同 cancel——父回合内显式调用即授权）。深度门在各自执行器内。
       if (action === "observe") return executeObserveAction(args, ctx)

package/agent-tools/verify.mjs

@@ -87,6 +87,7 @@ export const verifyTool = {
           status: { type: "string", enum: ["passed", "failed", "skipped"], description: "The verification outcome you declare: 'passed' → allowed; 'failed' → blocked; 'skipped' → allowed but requires a summary reason." },
           command: { type: "string", description: "Optional: the verification command you ran (self-reported)." },
           summary: { type: "string", description: "Optional: the result. Required when status='skipped' — a concrete reason (e.g. \"project has no automated tests — verified by manual review\")." },
+          basis: { type: "string", description: "Optional: what the conclusion stands on — a judgment source, a read file:line coordinate, or an explicit \"unverified\" (declaration-only: no format is enforced or machine-checked). A passed/skipped declaration without it gets one advisory hint line in the report — never blocking, never changing the gate." },
         },
         required: ["status"],
       },
@@ -239,12 +240,16 @@ export const verifyTool = {
         lines.push("Verification declared passed.")
         if (v.command) lines.push(`  command: ${v.command}`)
         if (v.summary) lines.push(`  summary: ${v.summary}`)
+        if (v.basis) lines.push(`  basis: ${v.basis}`)
+        else lines.push("  basis: not declared (advisory — does not affect the gate) — note what the conclusion stands on: a judgment source, a read file:line, or an explicit \"unverified\".")
         ctx.agent._verifyPassed = true
       } else if (status === "skipped") {
         const reason = (v.summary ?? "").trim()
         if (reason) {
           lines.push("")
           lines.push(`Verification skipped with reason: ${reason}`)
+          if (v.basis) lines.push(`  basis: ${v.basis}`)
+          else lines.push("  basis: not declared (advisory — does not affect the gate) — note what the conclusion stands on: a judgment source, a read file:line, or an explicit \"unverified\".")
           ctx.agent._verifyPassed = true
         } else {
           lines.push("")

package/agent-tools/zero-write-watch.mjs

@@ -0,0 +1,77 @@
+/**
+ * zero-write-watch.mjs — 零落笔看门狗叶（批 subagent-zero-write-watchdog · 台账 #934）。
+ * 设计权威 = `docs/core/design/AGENT-LOOP-UPSTREAM.md` §6.32；需求 = `docs/core/requirements/AGENT-LOOP.md` §4.16。
+ *
+ * 两族（§6.32.2）：子代理族 = eng-coder / eng-designer **连续** N 轮零文件写（采集点邻单点 =
+ * `agent/turn-loop.mjs` 轮顶——streak 更新与越阈判定同点）；评审族 = 异步评审 **连续** N 轮零评审
+ * 文本产出（`advisor/loop.mjs` 循环局部计数 + 可选钩子 `seams.onStallRound`）。
+ *
+ * 送达 = 复用 §6.27 上行通道（`pushChildUpstream`——note 类：同队列同消费点、零唤醒、零新容器）；
+ * **只推提醒**——不自动杀 / 不自动转向 / 不代父侧动作（§6.32.10-1）。
+ * 防轰炸 = 闩 + 写后重臂（子代理族：`_zeroWriteAlerted`；评审族：单次运行闩——§6.32.3）。
+ * 文案单源 = 本档两族文本函数（§6.32.4 逐字——父侧定稿；`from` + 轮数为唯一变量）。
+ * 零依赖叶：静态 import 只取 `parent-channel.mjs` 的 `pushChildUpstream`（不引池 / 端面 / 循环）。
+ */
+import { pushChildUpstream } from "./parent-channel.mjs"
+
+/** 阈值单源（连续轮数——两族共用；§6.32.2 阈值固定 50，不做配置键）。 */
+export const ZERO_WRITE_ALERT_ROUNDS = 50
+
+/** 子代理族触面（用户点名三角色中的两位——有文件写面；explore / plan / consult / 普通 coder / depth-0 不设）。 */
+const WATCH_ROLES = new Set(["eng-coder", "eng-designer"])
+
+/** 子代理族文案（§6.32.4 逐字——父侧定稿；`from` = `_upstream.label`，形 `role#id`）。 */
+export function zeroWriteAlertText(from, rounds) {
+  return `[zero-write watchdog] ${from}: ${rounds} consecutive rounds with no file write — take a look (subagent action:'status' for the live view).`
+}
+
+/** 评审族文案（§6.32.4 逐字——父侧定稿；`from` = `advisor#<entry id>`）。 */
+export function advisorAlertText(from, rounds) {
+  return `[zero-write watchdog] ${from}: ${rounds} consecutive rounds with no review output — take a look (subagent action:'status' / 'cancel').`
+}
+
+/**
+ * 子代理族判定 + 推送（§6.32.6）——门 = `_role` ∈ 触面 ∧ `_upstream.parent` 在场 ∧
+ * `_zeroWriteStreak` **为整数** ≥ 阈值（缺字段 / 非整数 ⇒ 不判——不冒充 `0`）∧ 未闩；
+ * 命中 ⇒ `pushChildUpstream({parent, from: _upstream.label, kind: "note", message})` + 置闩。
+ * **恒零抛**（兜底捕获兑现——自动源无模型可报错；失败面静默跳过）。
+ * @param {object} child 子 agent（eng-coder / eng-designer 形态；`_upstream` 由 spawn 站点装配）。
+ * @returns {boolean} 是否命中推送（测试面）。
+ */
+export function maybeZeroWriteAlert(child) {
+  try {
+    if (!WATCH_ROLES.has(child?._role)) return false
+    const upstream = child._upstream
+    if (!upstream?.parent) return false
+    const streak = child._zeroWriteStreak
+    if (!Number.isInteger(streak) || streak < ZERO_WRITE_ALERT_ROUNDS) return false
+    if (child._zeroWriteAlerted) return false
+    pushChildUpstream({
+      parent: upstream.parent,
+      from: upstream.label,
+      kind: "note",
+      message: zeroWriteAlertText(upstream.label, streak),
+    })
+    child._zeroWriteAlerted = true
+    return true
+  } catch {
+    return false // 恒零抛兑现（§6.32.6——失败面静默跳过）
+  }
+}
+
+/**
+ * 评审族推送（组合文案 + push——呼点 = 评审环路钩子 `seams.onStallRound`，单次运行至多一次）。
+ * **恒零抛**（实现面兜底捕获兑现——抛错不得上抛为评审 failed 面；§6.32.6）。
+ * @param {object} parent 父 agent（接收方——`pushChildUpstream` 载体吸收同款）。
+ * @param {string} from 来源标签（`advisor#<entry id>`）。
+ * @param {number} rounds 连续无产出轮数。
+ * @returns {boolean} 是否推送成功（测试面）。
+ */
+export function pushAdvisorAlert(parent, from, rounds) {
+  try {
+    pushChildUpstream({ parent, from, kind: "note", message: advisorAlertText(from, rounds) })
+    return true
+  } catch {
+    return false
+  }
+}

package/agent.mjs

@@ -100,6 +100,6 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     // 2026-09-05 实践轮：回合收尾（consult 清理/async 池分流/guard 继承——原 425-462
     // 段 + collectSettledAsync 466-494 整体迁 agent/run-stages.mjs finalizeAgentTurn——
     // CLI 对位 VS run-stages——finally 只剩一行调用 + 骨架注释）。
-    await finalizeAgentTurn(agent, { signal, autoTurn, suspDriven, thrownError, depth })
+    await finalizeAgentTurn(agent, { signal, autoTurn, upstreamTurn, timerTurn, suspDriven, thrownError, depth })
   }
 }

package/auto-think.mjs

@@ -16,6 +16,8 @@
  */
 import { chat } from "./provider/core.mjs"
 import { specForModel } from "./config.mjs"
+// #860（AGENT-LOOP.md §6.1 ∥ §7 D-AL26）：off 形族的单一实现源（写面取形 + 有效 off 路径判据）
+import { thinkOffPath, thinkOffShape } from "./think-off.mjs"
 
 const CLASSIFY_PROMPT = `Classify this coding task's difficulty: low, medium, or high.
 
@@ -31,6 +33,10 @@ const EFFORT_MAP = {
   high: ["max", "max", "xhigh", "max"],
 }
 
+/** #860（D-AL26）：不可关思考的跳过警示 ∕ 分类失败——进程级一次性（按 model ∕ 错误签名去重，防逐轮刷屏）。 */
+const warnedThinkGuard = new Set()
+const warnedClassifyFailure = new Set()
+
 /**
  * Build classifier input from history: the latest real user message (reminders and
  * interrupt injections excluded), plus the previous user message as context when the
@@ -67,13 +73,25 @@ export async function classifyAndApply(agent, turn) {
   const validEfforts = spec.reasoningEffortEnum
   if (!validEfforts) return null // Model doesn't support reasoning effort
 
+  // #860 守卫（D-AL26）：无法关思考的模型（thinkAlwaysOn ∕ 枚举无 none）⇒ 分类调用必然失败
+  //（思考吃光小预算 ∕ 400）——不调用；一次可见警示（按 model 去重），语义回退 null。
+  if (!thinkOffPath(spec)) {
+    if (!warnedThinkGuard.has(agent.provider.model)) {
+      warnedThinkGuard.add(agent.provider.model)
+      console.warn(`[auto-think] model "${agent.provider.model}" cannot disable thinking — difficulty classification skipped (reasoning effort unchanged)`)
+    }
+    return null
+  }
+
   const prompt = buildClassifierInput(agent.history)
   if (prompt == null) return null
 
   // Classification call: use same provider, minimal tokens, no tools, no streaming
   let level
   try {
-    const classifierProvider = { ...agent.provider, maxTokens: 10 }
+    // #860：关思考形（族别 off 形）+ 小预算 32（原 10 token 被思考吃光）+ reasoningEffort 清空
+    //（防父档外溢；effort 族 off 形由载荷门补发 reasoning_effort:"none"）。
+    const classifierProvider = { ...agent.provider, maxTokens: 32, thinking: thinkOffShape(spec), reasoningEffort: null }
     const response = await chat(classifierProvider, {
       messages: [
         { role: "system", content: CLASSIFY_PROMPT },
@@ -101,7 +119,13 @@ export async function classifyAndApply(agent, turn) {
     else if (word.startsWith("medium") || word.startsWith("med")) level = "medium"
     else if (word.startsWith("high")) level = "high"
     else return null // Unparseable
-  } catch {
+  } catch (e) {
+    // #860（D-AL26）：失败一次可见（按错误签名进程级去重——不再静默）；回退 null 语义不变。
+    const sig = e?.message ?? String(e)
+    if (!warnedClassifyFailure.has(sig)) {
+      warnedClassifyFailure.add(sig)
+      console.warn(`[auto-think] classification failed: ${sig}`)
+    }
     return null // Classification failure → fall back to current setting
   }
 

package/config-presets.mjs

@@ -42,6 +42,14 @@ export const PROVIDER_PRESETS = {
   siliconflow: { baseURL: "https://api.siliconflow.cn/v1", model: "deepseek-ai/DeepSeek-V3", maxTokens: 32_000, desc: "SiliconFlow (硅基流动)" },
   openrouter: { baseURL: "https://openrouter.ai/api/v1", model: "anthropic/claude-sonnet-4", maxTokens: 32_000, desc: "OpenRouter" },
   groq:     { baseURL: "https://api.groq.com/openai/v1", model: "llama-3.3-70b-versatile", maxTokens: 32_000, desc: "Groq" },
+  // OpenCode Go 订阅网关（opencode.ai/zen 取 sk- key ∥ 无 OAuth）——官方档（go.mdx）双协议混装 ⇒ 拆双预设
+  // （PROVIDER.md §6.11）：本键 = OpenAI 兼容 `/chat/completions` 侧；`opencode-go-anthropic` = Anthropic
+  // `/messages` 侧（同 key——模型按侧选）。字段集 = 最小面：`thinking` / `reasoningEffort` 不设 = 不发
+  // （D-13 同口径）；`maxTokens` 仅 anthropic 侧设 `65536`（该 transport `max_tokens` 必发——不设即落规格
+  // 行值 131072，超渠道口径）。**待验（无 key——未实拉 `/models` ∕ 载荷未实测；接入后按实拉复核）**；
+  // `x-opencode-session` 头 = 可选遥测——**不发**（亦不动 `providers[].headers` 面）。
+  "opencode-go": { baseURL: "https://opencode.ai/zen/go/v1", model: "glm-5.2", desc: "OpenCode Go subscription (sk- key from opencode.ai/zen; OpenAI-compatible models — MiniMax/Qwen via opencode-go-anthropic)" },
+  "opencode-go-anthropic": { baseURL: "https://opencode.ai/zen/go/v1", model: "qwen3.7-max", format: "anthropic", maxTokens: 65536, desc: "OpenCode Go — Anthropic Messages side (same sk- key as opencode-go; MiniMax/Qwen models)" },
 }
 
 /** Build the stored provider entry from a preset — strip the display field, keep the rest

package/config.mjs

@@ -188,6 +188,31 @@ function warnConsultModelsFiltered(dropped, path) {
     `\n  Fix: clean agent.consultModels in ${path} or use /config → consult/escalate pool menu.`)
 }
 
+/** #861（AGENT-LOOP-SUBAGENT.md §6.7.1）：subagent 模型覆盖加载期清洗——单源纯函数（核 loadConfig ∥ VSC 端壳 raw 读点同消费）；非法形态不 throw（`subagentModel` 非法 ⇒ null、`subagentModels` 非对象 ⇒ {}、值非法 ⇒ 剔除该键）。 */
+export function sanitizeSubagentModel(v) {
+  const ok = typeof v === "string" && v.trim()
+  const dropped = ok || v == null ? [] : [`agent.subagentModel must be a non-empty string ("provider:model" | provider | model) — got ${Array.isArray(v) ? "array" : typeof v} — ignored (inherits the parent provider)`]
+  return { value: ok ? v : null, dropped }
+}
+export function sanitizeSubagentModels(v) {
+  if (v == null) return { value: {}, dropped: [] }
+  if (typeof v !== "object" || Array.isArray(v)) return { value: {}, dropped: [`agent.subagentModels must be an object mapping role → model override — got ${Array.isArray(v) ? "array" : typeof v} — ignored`] }
+  const value = {}, dropped = []
+  for (const [role, val] of Object.entries(v)) {
+    if (typeof val === "string" && val.trim()) { value[role] = val; continue }
+    dropped.push(`agent.subagentModels.${role} must be a non-empty string ("provider:model" | provider | model) — got ${Array.isArray(val) ? "array" : typeof val} — dropped`)
+  }
+  return { value, dropped }
+}
+
+let warnedSubagentModels = false // #861：清洗警告——进程级一次性（同 consultModels 先例）
+function warnSubagentModelsFiltered(dropped, path) {
+  if (warnedSubagentModels || dropped.length === 0) return
+  warnedSubagentModels = true
+  console.warn(`[config] agent.subagentModel/subagentModels: ${dropped.length} invalid entr${dropped.length === 1 ? "y ignored" : "ies ignored"} (filtered — startup continues; no crash):\n` +
+    `${dropped.map((d) => `  - ${d}`).join("\n")}\n  Fix: clean it in ${path} — "provider:model" | provider | model.`)
+}
+
 /**
  * Find provider by name in providers[].
  * Throws if name is non-empty but not found — a typo in activeProvider silently falling to the first provider would use the wrong key on the wrong endpoint.
@@ -311,6 +336,11 @@ export function loadConfig() {
   merged.agent.consultModels = cmClean.keep
   if (cmClean.dropped.length) merged.agent.consultModelsFiltered = cmClean.dropped
 
+  const smClean = sanitizeSubagentModel(merged.agent.subagentModel), smsClean = sanitizeSubagentModels(merged.agent.subagentModels) // #861（§6.7.1）：加载期清洗——非法形态不采纳 + 一次性警告（不 throw——同 F-4 范式）
+  warnSubagentModelsFiltered([...smClean.dropped, ...smsClean.dropped], path)
+  merged.agent.subagentModel = smClean.value
+  merged.agent.subagentModels = smsClean.value
+
   // Backward compatibility: promote root-level config fields to agent sub-object
   if (config.verifyGuard !== undefined) {
     merged.agent.verifyGuard = config.verifyGuard

package/conventions.mjs

@@ -26,9 +26,10 @@
  *   code — inside a declared code segment (default: the path segment `src`), or the
  *          fallback;  doc — documentation extension outside any code segment and not
  *          scratch;  temp — tmp-* name or .tmp/.temp extension;  aux — a default
- *          auxiliary-path segment sequence (test / tests / scripts / .thincoder/tmp —
- *          F9) that matched no code segment and neither doc nor temp.
- * Precedence: code segment → temp → doc → aux → fallback code.
+ *          auxiliary-path segment sequence (test / tests / scripts / .thincoder/tmp — F9)
+ *          that matched no code segment and neither doc nor temp;  state — a project state
+ *          file (`PROJECT-MANIFEST.json` basename ∥ `.thincoder/conventions.json` pair — #941).
+ * Precedence: code segment → temp → doc → aux → state → fallback code.
  *
  * Segment matching runs on the PROJECT-ROOT-RELATIVE FACE of a path (D17 · 2026-09-28): the
  * machine layout ABOVE the project root never participates. An absolute path outside the
@@ -128,18 +129,32 @@ function hasAuxSegment(p, conv) {
   return hasSegmentSequence(p, DEFAULT_AUX_PATHS, conv?.root, false)
 }
 
-/** "code" | "doc" | "temp" | "aux" — the single classification decision.
+/** Project state-file markers (data — #941 · PORTABILITY D19): manifest basename (any layer) ∥
+ *  retired-carrier pair; single sources: `MANIFEST_REL` ∥ `RETIRED_REL_PATH`. */
+const STATE_BASENAME = "project-manifest.json"
+const STATE_PAIR = ".thincoder/conventions.json"
+
+/** True when `s` names a project state file (basename any layer ∥ segment pair; case-insensitive — no face, D17). */
+function isStateFile(s) {
+  const segs = segmentsOf(s)
+  if (segs.length > 0 && lowerSeg(segs[segs.length - 1]) === STATE_BASENAME) return true
+  return hasSequenceIn(segs, [STATE_PAIR])
+}
+
+/** "code" | "doc" | "temp" | "aux" | "state" — the single classification decision.
  *  Precedence: code segment first (src/** stays product code even when the name
  *  looks scratch — the pre-existing unconditional-src rule), then temp, then a
  *  documentation extension, then an auxiliary-path segment sequence (test / tests
- *  / scripts / .thincoder/tmp — F9), else code (anything not doc/temp/aux is product
- *  code). Both segment checks run on the project-root-relative face (D17 — `faceOf`). */
+ *  / scripts / .thincoder/tmp — F9), then a project state file (#941), else code
+ *  (anything not doc/temp/aux/state is product code). Segment checks face-bound (D17);
+ *  state matches by name marker. */
 export function classifyPath(p, conv) {
   const s = String(p ?? "")
   if (hasCodeSegment(s, conv)) return "code"
   if (TEMP_FILE.test(s)) return "temp"
   if (DOC_FILE.test(s)) return "doc"
   if (hasAuxSegment(s, conv)) return "aux"
+  if (isStateFile(s)) return "state"
   return "code"
 }
 
@@ -165,6 +180,11 @@ export function isAuxPath(p, conv) {
   return classifyPath(p, conv) === "aux"
 }
 
+/** True when the path is a project state file (`classifyPath === "state"` — #941; derived form). */
+export function isStatePath(p, conv) {
+  return classifyPath(p, conv) === "state"
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // 迁出面（2026-10-01 拆分批 · #755 ∥ #786）：声明装载面外提 `declaration.mjs`——本档经
 // 转口保名（消费面 / 批内件 import 面零改；`DEFAULT_DECLARATION` 另供本档分类裁判缺省取用）。

package/declaration.mjs

@@ -5,8 +5,8 @@
  * name / shape / defaults = schema 面 `docs/core/design/MANIFEST.md` §2.2）。迁出块逐字；
  * 原档 `conventions.mjs` 经 `export { … } from` 转口保名（消费面 / 批内件 import 面零改）。
  */
-import { existsSync } from "node:fs"
-import { dirname, isAbsolute, join, relative, resolve } from "node:path"
+import { existsSync, statSync } from "node:fs"
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path"
 import { DEFAULT_MANIFEST, manifestFilePath, readManifest } from "./manifest.mjs"
 import { logEvent } from "./log.mjs"
 
@@ -140,6 +140,30 @@ export function declaredPublicRoots(cwd) {
   return out
 }
 
+/** 引用解析单点（§6.1 口径 4/5——写门 ∥ 迁移旗同消费，不得二写）：① 仓根解析 `resolve(base, part)`
+ *  为存在的档 ⇒ 命中；② 声明源前缀解析序：首段命中声明公共仓目录名（消费既有 `declaredPublicRoots`
+ *  ——同名多仓 ⇒ 声明序首者）⇒ 于该声明根解析余段；未声明 ∥ 声明根缺位 ∥ 目标档缺 ⇒ `{ ok: false, abs }`。
+ *  @param {string} base 仓根基准（写门口径 2 同一子表达式）
+ *  @param {string} part task_book 文件部分（首个 `§` 前子串，trim——调用面已判缺位）
+ *  @returns {{ok: boolean, abs: string}}
+ */
+export function resolveDeclaredRef(base, part) {
+  const abs = resolve(base, part)
+  if (isFile(abs)) return { ok: true, abs }
+  const segs = String(part).replace(/\\/g, "/").split("/").filter(Boolean)
+  for (const root of declaredPublicRoots(base)) {
+    if (segs[0] !== basename(root)) continue
+    if (segs.length > 1) {
+      const hit = resolve(root, segs.slice(1).join("/"))
+      if (isFile(hit)) return { ok: true, abs: hit }
+    }
+    break
+  }
+  return { ok: false, abs }
+}
+
+const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
+
 const _cache = new Map()
 
 /** Drop the per-data-file-path cache (test seam — declarations are read once per path). */