@thincoder/core 0.10.3 → 0.10.5

package/agent-tools/advisor-async.mjs

@@ -31,7 +31,7 @@
  *     non-stale code review marks _calledAdvisorThisRun; a passing design review
  *     issues its token under the designId slot at settle time.
  *     2026-09-11 第 11 批拆分：settle 记账 + 变更日志 + 陈旧/冻结判定迁 `advisor-settle.mjs`
- *     （本文件 500 行 = 硬帽在册）；既有 import 面经本文件 re-export 保持不变。
+ *     （本文件 500 行——2026-09-11 拆分时）；既有 import 面经本文件 re-export 保持不变。
  *
  * The sync path (depth>0 eng-coder self-review / explicit async:false) reuses
  * the same instance resolution (rounds/prior/cap) — its accounting still lands
@@ -47,13 +47,13 @@ export {
 // 第 11 批拆分（2026-09-11）：settle 记账 + 变更日志（noteMutations）+ 陈旧判定
 // （reviewIsStale）+ 冻结冲突（inflightDesignReviewConflict）迁 advisor-settle.mjs——
 // 既有 import 面（dispatch / subagent-async / escalate-async / 测试）经此 re-export 不变。
-import { normAbs, mutationSeqOf, settleAdvisorRun } from "./advisor-settle.mjs"
+import { mutationSeqOf, settleAdvisorRun } from "./advisor-settle.mjs"
 export {
   mutationSeqOf, noteMutations, reviewIsStale, settleAdvisorRun, inflightDesignReviewConflict,
 } from "./advisor-settle.mjs"
 // 第 33 批（评审失败护栏）：doc-set 键迁事实面档（实例续跑与陈旧判定同锚单源；原为私有——零 import 面）。
 // 本文件继续在实例解析 / 池 entries 上消费它。
-import { docSetKey } from "./review-facts.mjs"
+import { docSetKey, resolveReviewDocPaths, scopeAdvisorMirror } from "./review-facts.mjs"
 // F31（2026-09-18 顾问面治理批）：拒回文案对象标识行单源。
 import { withIdentityLine, scopeSummary } from "../advisor/notice.mjs"
 import { runAdvisorReview, resolveAdvisorProvider, ADVISOR_THINKING_PLACEHOLDER } from "../advisor/run.mjs"
@@ -65,6 +65,8 @@ import { deathLine } from "../abort-provenance.mjs"
 // ASYNC-RESULT-CONTAINER.md D3/D6：settle 公共收尾单点 + child signal 构建单点
 import { bindChildController, buildChildSignal, carrierField, getAsyncPool, settleAsyncEntry, tombstoneOf, writeTombstone } from "./async-settle.mjs"
 import { nextSubagentId, consumeSubagentToken, assertPoolKeyFree, entryTerminal } from "./subagent-scheduler.mjs"
+// #934（零落笔看门狗——AGENT-LOOP-UPSTREAM.md §6.32.6 触发接线②）：评审族推送单源（叶档——恒零抛）。
+import { pushAdvisorAlert } from "./zero-write-watch.mjs"
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Review-instance registry (_advisorRuns — per-review rounds/prior/cap)
@@ -161,9 +163,9 @@ export function resolveAdvisorLaunch(agent, reviewType, { documents = null } = {
       runs.set(reviewId, run)
     }
   }
-  // Scope the legacy mirror fields (message builder + run.mjs cap + displays).
-  agent._advisorRound = run.priorOutput ? run.round : 0
-  agent._lastAdvisorOutput = run.priorOutput
+  // Scope the mirror fields to THIS instance (message builder + run.mjs cap +
+  // displays; #949 ① — the queued-launch window is re-secured at entry.start).
+  scopeAdvisorMirror(agent, run)
   return { run, isNew: run.round === 0 && !run.priorOutput, reviewId: run.reviewId, designId: run.designId }
 }
 
@@ -390,8 +392,11 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
     id, role: "advisor", reviewType, run,
     reviewId: run.reviewId, designId, designToken, documents, paths, object,
     launchSeq: mutationSeqOf(parent),
+    // docAbs 产出面同源归一（2026-10-04 · #921 · A 随件）：四分支单源 resolved（裸形/前缀形
+    // 命中候选项目根即归一为绝对路径）——冻结窗/陈旧判定对**裸形受理档**照护成立（否则 A
+    // 开冻结窗保护洞）；绝对形与旧 normAbs 面逐字等价。
     docAbs: reviewType === "design" && Array.isArray(documents)
-      ? documents.filter((d) => typeof d === "string").map((d) => normAbs(d, parent.cwd))
+      ? [...resolveReviewDocPaths(documents, parent.cwd).resolved.values()]
       : [],
     relayPrefix: `advisor#${id}/`,
     status: queued ? "queued" : "running", position: undefined,
@@ -420,9 +425,12 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
     // Async mark + [model] — the TUI block opens at ACTUAL start (⏹ gating reads it).
     ctx?.callbacks?.onToken?.(entry.relayPrefix + "⟦ev⟧async\x1e")
     ctx?.callbacks?.onToken?.(entry.relayPrefix + "[model]" + (entry.model ?? ""))
+    // #949 ①：排队 / 延迟窗口封死——构建前按本评审实例复核镜像（消费点定域；幂等）。
+    scopeAdvisorMirror(parent, run)
     runAdvisorReview(parent, reviewType, {
       onOutput: (chunk) => relayAdvisorOutput(ctx?.callbacks, entry.relayPrefix, chunk),
       signal: entry.controller.signal,
+      onStall: (rounds) => pushAdvisorAlert(parent, `advisor#${id}`, rounds), // #934：连续无产出越阈 ⇒ 自动上行提醒（只推——§6.32）
     }, designToken, documents, paths, object, designId)
       .then((report) => { entry.report = report })
       // §6.12 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀

package/agent-tools/advisor-settle.mjs

@@ -1,7 +1,7 @@
 /**
  * advisor-settle.mjs — advisor settle accounting + mutation log + stale / freeze
- * determination（2026-09-11 第 11 批自 advisor-async.mjs 拆出——500 行 = 硬帽在册，
- * 任何新增必越；既有 import 面经 advisor-async.mjs **re-export 保持不变**
+ * determination（2026-09-11 第 11 批自 advisor-async.mjs 拆出；
+ * 既有 import 面经 advisor-async.mjs **re-export 保持不变**
  * （noteMutations / mutationSeqOf / reviewIsStale / settleAdvisorRun）。
  *
  * 内容 = 迁入（逐字搬移含注释）+ 本批两处接线：

package/agent-tools/advisor.mjs

@@ -9,12 +9,11 @@
  */
 import { runAdvisorReview, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
 import { resolveBatchDocPath } from "./batch.mjs"
-// M6（模块设计 §2.1 F3）：评审对象来源读 manifest docRoot（声明面）——复用 M4 的
-// write-gate.mjs 单一权威源（KD-M6-1），替代 v1 的逐档分类面（isDocPath）；
-// normAbs 同源 re-export（指针非副本）。不 import dispatch.mjs（簇间回边，环风险）。
-import { resolveReviewTargetPaths, resolveReviewRootsFor, normAbs } from "../agent/write-gate.mjs"
-import { owningProject } from "../manifest-discovery.mjs"
-import { sep } from "node:path"
+// M6（模块设计 §2.1 F3）：评审对象来源读 manifest docRoot（声明面）——单一权威源 =
+// review-facts.mjs 的 resolveReviewDocPaths（2026-10-04 · #921 · KD-2——分类四分支 + B 文案
+// 诊断数据单源；write-gate 同名再出口保 normAbs 面）。不 import dispatch.mjs（簇间回边，环风险）。
+import { normAbs } from "../agent/write-gate.mjs"
+import { resolveReviewDocPaths } from "./review-facts.mjs"
 import {
   generateDesignToken,
   settleDesignReview,
@@ -63,11 +62,11 @@ export const advisorTool = {
       documents: {
         type: "array",
         items: { type: "string" },
-        description: "Doc paths to review (design / requirements / referenced docs). The advisor reviews ONLY these — no git diff scan. Use for both review types to pass the task's docs list.",
+        description: "Doc paths to review (design / requirements / referenced docs). Relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/…, or absolute). The advisor reviews ONLY these — no git diff scan. Use for both review types to pass the task's docs list.",
       },
       batchDoc: {
         type: "string",
-        description: "Design review only: the in-flight batch record path — validated whenever passed (unreadable ⇒ refused, not ignored); the reviewer then also gets the `batch` write channel to record its findings + verdict. Omit when no batch record is in flight (no write channel — zero regression).",
+        description: "Design review only: the in-flight batch record path — validated whenever passed (unreadable ⇒ refused, not ignored); the reviewer then also gets the `batch` write channel to record its findings + verdict. Relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/batches/…, or absolute). Omit when no batch record is in flight (no write channel — zero regression).",
       },
     },
     required: ["type"],
@@ -112,34 +111,36 @@ export const advisorTool = {
       )
     }
 
-    // Design review: the review scope must be documentation files. Classification
-    // comes from the manifest-declared review-target roots (M4 write-gate.mjs single
-    // authority — FR12: no directory-name hardcoding; a project whose docs live
-    // elsewhere declares them in PROJECT-MANIFEST.json docRoot).
+    // Design review: the review scope must be documentation files. Classification =
+    // resolveReviewDocPaths (2026-10-04 · #921 · the four-leg single authority in
+    // review-facts.mjs): legs ① session-root set / ② owning-project root set keep the
+    // legacy behavior verbatim; leg ③ probes candidate project roots for bare
+    // project-root-relative forms; leg ④ disambiguates by readable-file uniqueness
+    // (fail-closed — criterion=scope-doc-ambiguous when ≥2 candidates are readable).
     if (reviewType === "design" && documents) {
-      const roots = resolveReviewTargetPaths(agent).map((r) => r.replace(/[\\/]/g, sep))
-      // 按用点解析（2026-09-21 之裁收口 · 台账 #828）：逐文档按**其所属项目**（最近带档祖先）
-      // 的 docRoot 判定；无主档文档回退会话根集判定（原行为零变）。
-      const ownerRootsCache = new Map()
-      const ownRoots = (abs) => {
-        const owner = owningProject(abs)
-        if (!owner) return []
-        let r = ownerRootsCache.get(owner)
-        if (!r) {
-          r = resolveReviewRootsFor(owner).map((x) => x.replace(/[\\/]/g, sep))
-          ownerRootsCache.set(owner, r)
-        }
-        return r
-      }
-      const invalidDocs = documents.filter((doc) => {
-        const n = normAbs(doc, agent.cwd).replace(/[\\/]/g, sep)
-        const under = (r) => n === r || n.startsWith(r + sep)
-        return !roots.some(under) && !ownRoots(n).some(under)
-      })
-      if (invalidDocs.length > 0) {
+      const { resolved, invalid, ambiguous, candidates } = resolveReviewDocPaths(documents, agent.cwd)
+      if (invalid.length > 0 || ambiguous) {
         if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+        if (ambiguous) {
+          // 歧义拒（KD-4 独立判据——不混入 not-doc；列全部可读命中——fail-closed 不静默挑一）。
+          return withIdentityLine(
+            `Advisor: design review document is ambiguous — "${ambiguous.doc}" matches several candidate projects: ${ambiguous.hits.join(", ")}. Pass a project-root-relative or absolute path.`,
+            { type: reviewType, scope: scopeSummary(documents), round: "—", criterion: "scope-doc-ambiguous" },
+          )
+        }
+        // not-doc 拒：既有稳定前缀逐字（行首）+ 解析诊断尾（B 面根治——逐文档「解析后绝对
+        // 路径 ← 基面 = 会话 cwd」+ 候选项目根提示 cap 5 + 重试指引——纠正「误报因」缺陷）。
+        const invalidList = invalid.map((v) => v.doc).join(", ")
+        const attemptedList = invalid
+          .map((v) => `${v.doc} → ${v.attempted.length > 0 ? v.attempted.join(" | ") : normAbs(v.doc, agent.cwd)}`)
+          .join("; ")
+        const shown = candidates.slice(0, 5)
+        const more = candidates.length - shown.length
+        const candidateNote = shown.length > 0
+          ? `(candidates: ${shown.join(", ")}${more > 0 ? ` +${more} more` : ""}) — pass project-root-relative (e.g. ${shown[0]}/docs/…) or absolute paths`
+          : "— pass project-root-relative or absolute paths"
         return withIdentityLine(
-          `Advisor: design review documents must be documentation files (per the project's conventions). Invalid: ${invalidDocs.join(", ")}`,
+          `Advisor: design review documents must be documentation files (per the project's conventions). Invalid: ${invalidList}\nDiagnosis: resolved against session cwd ${agent.cwd} → ${attemptedList}; no candidate project docRoot contains it ${candidateNote}.`,
           { type: reviewType, scope: scopeSummary(documents), round: "—", criterion: "scope-not-doc" },
         )
       }

package/agent-tools/async-discard.mjs

@@ -17,6 +17,8 @@
  * ——其控制器链只作**判据**（杀 ⟺ 控制器已中止），杀树动作经本收尾面 `spec.dispose` 钩子落
  * `bash-async.mjs` 杀单点（`killBgTree`）；回合中断（Ctrl+I）经 `bindChildController`
  * interrupt 豁免不中止控制器 ⇒ 本面零动作（F2 同款豁免——池保留）。
+ * 批 browser-async-fix（2026-10-07）：browser 后台动作族同面并入（`BROWSER_SPEC`——dispose = 条目
+ * 控制器 abort ⇒ 动作展开 / 排队丢队；**不杀浏览器**）。
  *
  * 判据口径（D-AD6）：两接线点**均不传 `ctx`** ⇒ 实走 controller 支（`parentAborted(null, entry)`）
  * ——与对侧有效判据同判（对侧传入的 `ctx` 为死参）；`ctx` 保留为签名备用面（直调用例 / 对侧收敛）。
@@ -59,6 +61,11 @@ const bgReminderText = (n, list) =>
   `[System reminder: ${n} background bash task(s) were killed by the user's Stop — their processes are gone and no digest will arrive: ${list}. ` +
   "Full output logs remain on disk (paths were given in the start ack).]"
 
+/** browser 后台动作族提醒模板（同族形态——取消无摘要：终止凭据 = 墓碑 + 杀点确认；浏览器本体不杀）。 */
+const browserReminderText = (n, list) =>
+  `[System reminder: ${n} background browser task(s) were cancelled by the user's Stop — no digest will arrive: ${list}. ` +
+  "The browser session itself was not killed (run `close` to reset it).]"
+
 /** 列表词（wasStatus 数据源）：queued → "(was queued — never started)"；其余 "(was running)"。 */
 const wasPhrase = (wasStatus) => (wasStatus === "queued" ? " (was queued — never started)" : " (was running)")
 
@@ -151,6 +158,21 @@ const BG_SPEC = {
   },
 }
 
+/** browser 后台动作族 spec（批 browser-async-fix——收尾档同面）：dispose = 中止在飞（条目控制器
+ *  abort ⇒ running 动作展开 / queued 丢队从未运行）+ 标记 discarded（settle 面据此不注入——摘要不可达）；
+ *  无队列面（帽 = 起跑显式拒）。**不杀浏览器**（会话重置是独立动作 `close`）。 */
+const BROWSER_SPEC = {
+  pool: "browser",
+  describe: (entry) => ({ id: entry.id, role: "browser", action: entry.action }),
+  roleOf: () => "browser",
+  listPhrase: (d) => `browser#${d.id} (${d.action})`,
+  reminder: browserReminderText,
+  dispose: (entry) => {
+    entry.discarded = true
+    entry.controller?.abort?.({ abortTrigger: "discard" })
+  },
+}
+
 /**
  * 中止收尾（F1–F3）：只清已死子代理条目——写 `discarded` 墓碑 + 出池 + 队列剔除 + 整批一次提醒。
  * @param parent agent 形态（载体双形经 `getAsyncPool` / `writeTombstone` 吸收）
@@ -184,3 +206,15 @@ export function discardAbortedAdvisors(parent, ctx = null) {
 export function discardAbortedBgTasks(parent, ctx = null) {
   return discardRole(parent, BG_SPEC, ctx)
 }
+
+/**
+ * 中止收尾（browser 后台动作族——同面并入）：只清已死条目——逐条中止在飞（running ⇒ 动作展开；
+ * queued ⇒ 丢队从未运行）+ `discarded` 墓碑 + 出池 + 整批一次提醒；回合中断（Ctrl+I）不中止控制器
+ * ⇒ 本面零动作（池保留——与 bg 同豁免）。
+ * @param parent agent 形态
+ * @param ctx 判据 ctx（接线点不传——controller 支，同上）
+ * @returns {{discarded: Array<{id, role: "browser", action}>, kept: number}}
+ */
+export function discardAbortedBrowserTasks(parent, ctx = null) {
+  return discardRole(parent, BROWSER_SPEC, ctx)
+}

package/agent-tools/async-settle.mjs

@@ -113,11 +113,12 @@ export function bindChildController(ctrl, baseSignal) {
 
 /** 池 accessor（D1）：role "advisor" → `_asyncAdvisors`（独立评审池——无队列独立调度）·
  *  role "consult" → `_consultSessions`（会话池）· role "bg" → `_bgTasks`（#9 后台 bash
- *  任务池）· 其余 → `_asyncSubagents`（子代理/飞刀共享槽位队列池）。载体经 `carrierField`
+ *  任务池）· role "browser" → `_browserTasks`（批 browser-async-fix 后台浏览器动作池）·
+ *  其余 → `_asyncSubagents`（子代理/飞刀共享槽位队列池）。载体经 `carrierField`
  *  吸收（#94）；未初始化返 null——调用方以 `?? new Map()` / 可选链处置。 */
 export function getAsyncPool(parent, role) {
   const field = role === "advisor" ? "_asyncAdvisors" : role === "consult" ? "_consultSessions"
-    : role === "bg" ? "_bgTasks" : "_asyncSubagents"
+    : role === "bg" ? "_bgTasks" : role === "browser" ? "_browserTasks" : "_asyncSubagents"
   return carrierField(parent, field) ?? null
 }
 
@@ -134,6 +135,17 @@ export function parkAsyncPending(parent, entry) {
   pend.push(entry)
 }
 
+/**
+ * §6.31.5 升级账本写助手（消化账务批）：`_unsettledDigests` 追加一行
+ * （`{ id, role, failures, report, at }`）。载体吸收（父字段优先 / history 借用——形态同
+ * `parkAsyncPending`）；行序 = 升级序（读面 = `digest-account.mjs` `unsettledRows`）。
+ */
+export function appendUnsettledDigest(parent, row) {
+  const existing = carrierField(parent, "_unsettledDigests")
+  const list = (parent._unsettledDigests ??= Array.isArray(existing) ? existing : [])
+  list.push(row)
+}
+
 // ─── D4 守卫统一（严格版）+ D6 信号兜底单点 ──────────────────────────────────
 
 /** D4 settle 守卫统一（escalate 严格版）：父侧中止 = 回合 signal aborted（#98 VSC 侧
@@ -161,7 +173,9 @@ export function buildChildSignal(parent, ctx) {
  * 对子代理对象的引用（`childAgent`/`report`——条目前此从不显式释放，挂起期 = 分钟级驻留）。
  * 幂等（重入不抛）；池内/挂起未消化窗口语义零变（settle 时刻不释放——表 2 候选 2 否决：
  * status/observe 在窗口内仍读 child 摘要）。三消费点（回合尾收集 / run 起始 pending 注入 /
- * 挂起残差注入）在注入完成后调本 helper。
+ * 挂起残差注入）——fallback 面（无 `_daSession`）注入完成后调本 helper（逐字沿用）；会话态
+ * （`_daSession`）注入后改调 `releaseChildHold`（仅释放 `childAgent`——`report` 保留至销账 /
+ * 升级；§6.31.4 ∥ KD-DA7）。
  */
 export function releaseSettledEntry(entry) {
   if (!entry || typeof entry !== "object") return
@@ -169,6 +183,16 @@ export function releaseSettledEntry(entry) {
   entry.report = null
 }
 
+/**
+ * §6.31.4 投递面（消化账务批 · 2026-10-05 · 台账 #930）：会话态注入后**仅**释放 `childAgent`——
+ * `report` 保留至销账 / 升级（重投需原文；驻留增量以报告量级 ∥ 重投上限封顶）。fallback 面零调用
+ * （既有 `releaseSettledEntry` 逐字沿用——注入即释放）。
+ */
+export function releaseChildHold(entry) {
+  if (!entry || typeof entry !== "object") return
+  entry.childAgent = null
+}
+
 /**
  * D3 settle 共享 helper——四族 settle 回调公共收尾单点（ASYNC-RESULT-CONTAINER.md
  * AC1：settle 记账单点，无逐字重复）。流程：
@@ -273,10 +297,11 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
       parkAsyncPending(parent, entry)
       pool?.delete(String(entry.id))
     }
-    // 发射单点（块到达时点归位批 · #746｜§6.8「settle 延迟冻结（两态统一）」）：settle 一律 ⟦ev⟧settled
-    // （区块头恒中间态「done · awaiting digestion」驻留面板）；⟦ev⟧done = 消费面补发（消费窗清单单源
-    // = §6.8）⇒ 冻结 ∥ 归档恒落消费时点——回合运行中零归档触发器（「S 不夹运行中回合」结构不变式）。
-    ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
+  // 发射单点（块到达时点归位批 · #746｜§6.8「settle 延迟冻结（两态统一）」）：settle 一律 ⟦ev⟧settled
+  // （区块头恒中间态「done · awaiting digestion」驻留面板）；⟦ev⟧done = 消费面补发（消费窗清单单源
+  // = §6.8）⇒ 冻结 ∥ 归档恒落投递时点（消化账务批 · 2026-10-05——归档 ≠ 销账；销账后移见账 = §6.31）；
+  // 回合运行中零归档触发器（「S 不夹运行中回合」结构不变式）。
+  ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
   }
   // ④ 公共尾部：settleSeq 递增 + _settle 唤醒（never rejects）+ 唤醒挂起驱动 waiter
   entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)

package/agent-tools/audit-block.mjs

@@ -2,7 +2,7 @@
  * audit-block.mjs — 审计块构造器（AGENT-LOOP-SUBAGENT.md §6.26 · 台账 #23）。
  *
  * 自 `subagent-spawn.mjs` **逐字搬移**（D23-3 外提：spawn 档越 300 软线 + 块构造成纯函数
- * ⇒ 判据面可直测；D23-4：块内文本零改——含块内自指词，整块搬移不改真值）。本档承载
+ * ⇒ 判据可直测；D23-4：块内文本零改——含块内自指词，整块搬移不改真值）。本档承载
  * spawn 级固定机制性指令的第二块（审计模板 + A2 任务书摘要 + touched 快照）：
  * 装配侧只收集（`thincoder-core/agent-tools/subagent-spawn.mjs`），下发面 = system 固块
  * （`child._spawnSystemBlock` → 核 `prepareRun` 拼接——`thincoder-core/agent/setup.mjs`）。

package/agent-tools/bash-async.mjs

@@ -56,7 +56,7 @@ const TAIL_KEEP_CHARS = 32 * 1024
 /** exit→close 宽限（同同步径后台注记面：孙进程握管道时 close 不来——`bash.mjs` 1500ms 同值）。 */
 const EXIT_GRACE_MS = 1500
 
-/** 测试缝：log 目录重定向（单测沙箱——生产从不调用；`_setDigestOffloadDirForTest` 同式）。 */
+/** 测试缝：log 目录重定向（单元测试沙箱——生产从不调用；`_setDigestOffloadDirForTest` 同式）。 */
 let _bgTaskLogDir = null
 export function _setBgTaskLogDirForTest(dir) { _bgTaskLogDir = dir }
 function bgTaskLogDir() { return _bgTaskLogDir ?? join(configDir, "tool-results") }

package/agent-tools/batch-lifecycle.mjs

@@ -12,14 +12,15 @@
  * 身份判据（D-BR17/D-BR18/D-BR21）：主 agent 的工具调用 ctx 带 `depth === 0`（dispatch 装配）；
  * eng 子代理 `ctx.depth > 0`；评审实例 ctx 无 depth 但工具以 `review: true` 绑定。create/close
  * 仅 depth-0 放行（BR-19/BR-24「… is main-agent-only」）；status 写域 = 调用者自己段
- * （eng-designer → §2 · 评审 → §3 · eng-coder → §5 · 主 agent → §1——轮 2 #3 裁定②，§4/§6
- * 状态面走普通文档写）；depth-0 的 status/path 面按 D-BR21（可选 path，缺省 = 在飞批唯一时取）。
+ * （eng-designer → §2 · 评审 → §3 · eng-coder → §5 · coder → §5【普通模式分支增表】· 主 agent →
+ * 工程 §1 ∥ 普通 §1/§2/§5【取段——§4.16】——§4/§6 状态面走普通文档写）；depth-0 的 status/path 面
+ * 按 D-BR21（可选 path，缺省 = 在飞批唯一时取）。
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 
 import {
-  SEGMENT_BY_ROLE, STATUS_WORDS, STATUS_LINE_RE, readBatchStatusLine, sectionHasStatusLine, sectionHeaderRe, batchSkeleton,
+  SEGMENT_BY_ROLE, SEGMENT_BY_ROLE_NORMAL, DEPTH0_SEGMENTS, STATUS_WORDS, STATUS_LINE_RE, readBatchStatusLine, sectionHasStatusLine, sectionHeaderRe, batchSkeleton,
   TEMPLATE_PLACEHOLDERS, findPlaceholderResidue, placeholderResidueError,
 } from "./batch-skeleton.mjs"
 import { resolveBatchCreatePath } from "./batch-paths.mjs"
@@ -49,6 +50,18 @@ function segmentNumber(raw) {
   return m ? Number(m[1]) : null
 }
 
+/** 档头两可选参归一（`BATCH-RECORD.md` §4.11 契约——逐字文本面 = `TOOLS.md` §6.20）：trim ∥
+ *  单行（拒句逐字）∥ 空串 ≡ 未给（null）；`ledger` 前导 `#` 补齐（board 无补齐）。给参 ⇒ 建即填
+ *  台账行（batchSkeleton 实参面）；未给（任一）⇒ 占位留存 + 回执填法句。 */
+function normalizeHeaderParam(name, raw) {
+  const v = typeof raw === "string" ? raw.trim() : ""
+  if (!v) return null
+  if (/\r?\n/.test(v)) {
+    throw new Error("batch: create ledger / board must be single lines — a multi-line value would break the header's 台账 line. Nothing was written.")
+  }
+  return name === "ledger" && !v.startsWith("#") ? `#${v}` : v
+}
+
 /** main-agent-only 门（BR-19/BR-24）：create/close 仅 depth-0 放行（eng 子代理 / 评审皆拒）。 */
 function assertMainAgentOnly(ctx, action, review) {
   if (review || !isDepthZero(ctx)) {
@@ -108,6 +121,10 @@ export function findInFlightBatch(cwd, bases) {
  * 路径解析 = `resolveBatchCreatePath`（§4.15 单源：候选序首个落基底内者 / 锚定串只解析项目根形）。
  * F11-B：`source` **必填**（topic 同款空拒——骨架编制行实参化；不传 = 死占位残留必被 F11-C 拒
  * ⇒ create 即拒，不留死锁）；`prev` 传入值**幂等剥**「前情 = 」前缀（值规范化；默认值零变）。
+ * 2026-10-05（A-2）：`ledger` / `board` 可选参**建即填**台账行（归一契约 = §4.11；回执两态 =
+ * 两参皆给 ⇒ 标注已填 ∥ 未给（任一）⇒ 填法句）。
+ * 2026-10-09（§4.16）：骨架**按模式位取形**（`batchSkeleton({…, mode})`——执行期实读；普通面
+ * 作者标签四处替换，工程面骨架产出逐字不变）。
  * @returns {string} 成功消息（含落盘绝对路径）
  */
 export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten }) {
@@ -138,15 +155,24 @@ export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten })
   if (/\r?\n/.test(source)) {
     throw new Error("batch: create source must be a single line — a multi-line source would break the header's 编制 line. Nothing was written.")
   }
+  // 档头两可选参（§4.11 契约——给则建即填台账行；未给任一 ⇒ 占位留存 + 回执填法句）
+  const ledger = normalizeHeaderParam("ledger", args?.ledger)
+  const board = normalizeHeaderParam("board", args?.board)
   const date = typeof args?.date === "string" && args.date.trim() ? args.date.trim() : todayLocal()
   // F11-B：prev 幂等 strip——调用方自带「前情 = 」前缀（单或重复）一并剥净（`+` 量词；归一化目的
   // = 值规范化，无前缀值原样通过）。默认值形态「无（独立批）」零变。
   const prevRaw = typeof args?.prev === "string" ? args.prev.trim() : ""
   const prev = prevRaw ? (prevRaw.replace(/^(?:前情\s*[=：:]\s*)+/g, "").trim() || "无（独立批）") : "无（独立批）"
   mkdirSync(dirname(abs), { recursive: true })
-  writeFileSync(abs, batchSkeleton({ date, topic, source, prev }))
+  // 模式位执行期实读（§4.16——骨架取形时点 = 建档即固；翻转不回写既有骨架）
+  const mode = ctx?.agent?.config?.agent?.engineering ? "engineering" : "normal"
+  writeFileSync(abs, batchSkeleton({ date, topic, source, prev, ledger, board, mode }))
   onWritten?.(ctx?.agent ?? {}, abs)
-  return `batch: created ${abs} — six-section skeleton written (§1 status line carries the gate-legal 「进行中」 placeholder; register the ledger entry yourself — create does not).`
+  // 回执两态（`TOOLS.md` §6.20 逐字）：两参皆给 ⇒ 标注已填；未给（任一）⇒ 填法句（填法 = 文件编辑）
+  const headerNote = ledger !== null && board !== null
+    ? `header 台账 line filled (${ledger} · ${board})`
+    : "header 台账 placeholder(s) remain — fill them by file edit before the record's first append/status opens"
+  return `batch: created ${abs} — six-section skeleton written (§1 status line carries the gate-legal 「进行中」 placeholder; register the ledger entry yourself — create does not). ${headerNote}`
 }
 
 /**
@@ -260,24 +286,40 @@ function assertStatusNote(note) {
 }
 
 /**
- * status——状态行流转（§4.12，段属主）。写域 = 调用者自己段内 `**状态行**：` 行（eng-designer →
- * §2 · 评审 → §3 · eng-coder → §5 · 主 agent → §1——轮 2 #3 裁定②）；值域 = STATUS_WORDS 该段项
- * 恰一词（**余核 = 关键词**——F11-A 谓词收紧），散文说明走独立 `note` 字段（落状态行括注）；
- * 冻结真值不变（gate 只读 §1）。path 参数 = 仅 depth-0（D-BR21）——子代理/评审传 path
- * ⇒ 拒（目标 = spawn/实例注入，语法上写不到别处）。F11-C 挂点 = 写盘前（assertStatusValue 后）：
- * 档头 / 目标段含骨架死占位 ⇒ 拒（close 不拦——收口是主 agent 终态动作）。
+ * status——状态行流转（§4.12，段属主；§4.16 模式感知）。写域 = 调用者自己段内 `**状态行**：`
+ * 行（评审 → §3 · eng-designer → §2 · eng-coder / coder → §5 · 主 agent：工程 §1 ∥ 普通
+ * §1/§2/§5 取段——缺省 §1）；值域 = STATUS_WORDS 该段项恰一词（**余核 = 关键词**——F11-A
+ * 谓词收紧），散文说明走独立 `note` 字段（落状态行括注）；冻结真值不变（gate 只读 §1）。
+ * path 参数 = 仅 depth-0（D-BR21）——子代理/评审传 path ⇒ 拒（目标 = spawn/实例注入，语法上
+ * 写不到别处）。F11-C 挂点 = 写盘前（assertStatusValue 后）：档头结构行含骨架死占位 ⇒ 拒
+ * （段体引用豁免；close 不拦——收口是主 agent 终态动作）。
  * @returns {string} 成功消息
  */
 export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten }) {
   const depth0 = isDepthZero(ctx)
-  const seg = review ? 3 : depth0 ? 1 : SEGMENT_BY_ROLE[ctx?.agent?._role] ?? null
+  // 模式位执行期实读（§4.16——同款先例 = task.mjs execute 门；翻转即时生效——D-BR26）。
+  // 写域：评审 → §3 · 子代理 → 身份段（普通模式分支合并 coder 增表——工程模式分支不查）·
+  // depth-0 工程 → §1 ∥ 普通 → §1/§2/§5（取段——缺省 §1）。
+  const engineering = !!ctx?.agent?.config?.agent?.engineering
+  let seg = review ? 3 : depth0 ? 1 : SEGMENT_BY_ROLE[ctx?.agent?._role] ?? (engineering ? null : SEGMENT_BY_ROLE_NORMAL[ctx?.agent?._role] ?? null)
   if (seg === null) {
     throw new Error("batch: no segment is writable by this caller — status writes the caller's OWN section (eng-designer → §2, design review → §3, eng-coder → §5, main agent → §1).")
   }
-  // 声明段核对（BR-22「eng-designer 对 §1 调 status ⇒ 段白名单拒绝」——镜像 append 面：
-  // segment 可声明，但声明段 ≠ 身份写域段 ⇒ 拒；身份写域段可省略——身份即写域）。
+  // 段域判据（BR-22「eng-designer 对 §1 调 status ⇒ 段白名单拒」——镜像 append 面）：
+  // depth-0 普通面（§4.16）= **取段**——写域集 §1/§2/§5、缺省 §1、越出集合 ⇒ 拒（模式化新串）；
+  // depth-0 工程面 ∥ 子代理 ∥ 评审 = **声明段核对**（声明段 ≠ 身份写域段 ⇒ 拒；身份写域段可省略）。
   const declared = args?.segment === undefined || args?.segment === null ? null : segmentNumber(args.segment)
-  if (declared !== null && declared !== seg) {
+  // 传值而解析不可得 ⇒ 显式拒（#1116——镜像 append 面「unknown segment」串形；未传 = 缺省语义零变）。
+  if (declared === null && args?.segment !== undefined && args?.segment !== null) {
+    throw new Error(`batch: unknown segment ${JSON.stringify(args?.segment ?? null)} — pass the section number you write (e.g. "§${seg}"), or omit it. Nothing was written.`)
+  }
+  if (depth0 && !review && !engineering) {
+    const target = declared ?? 1
+    if (!DEPTH0_SEGMENTS.status.normal.includes(target)) {
+      throw new Error(`batch: §${declared} is not yours to write — in normal mode status writes §1/§2/§5 only (一段一作者: §3 = design review; §4/§6 carry no status word list). Nothing was written.`)
+    }
+    seg = target
+  } else if (declared !== null && declared !== seg) {
     throw new Error(`batch: §${declared} is not yours to write — status writes YOUR OWN section §${seg} only (一段一作者: eng-designer → §2, design review → §3, eng-coder → §5, main agent → §1). Nothing was written.`)
   }
   if (args?.path !== undefined && args?.path !== null && !depth0) {
@@ -298,8 +340,8 @@ export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten })
   const abs = pickTarget(args?.path)
   const src = readFileSync(abs, "utf8")
   assertGateOpen(src)
-  // F11-C（写盘前）：档头 + 本段死占位残留 ⇒ 拒（他段占位不归本段作者管）
-  const residues = findPlaceholderResidue(src, seg)
+  // F11-C（写盘前）：档头结构行死占位残留 ⇒ 拒（段体引用豁免——判据可辨性收正，`TOOLS.md` §6.20）
+  const residues = findPlaceholderResidue(src)
   if (residues.length) throw new Error(placeholderResidueError(residues))
   const written = updateSectionStatusLine(src, seg, lineValue)
   writeFileSync(abs, written)

package/agent-tools/batch-paths.mjs

@@ -7,9 +7,10 @@
  * 契约（§4.15 逐字）：**候选序** = cwd → 项目根 → 逐基底（基底 = `batchDocBases` 声明面单源）；
  * **判据分野** = 读面取首个**可读**文件 / create 取首个**落基底根内**者；**锚定防嵌套** = 串以任一基底的
  * 「项目根相对前缀」打头且前缀后为**路径段边界** ⇒ 只解析项目根形（不二次拼接；不落基底内 ⇒ fail-closed）；
- * **歧义锚**（条 5 · 2026-10-02 · #828）= create 按目标所属项目落基底 ∥ 无所属显式拒；读面候选腿追加；
+ * **歧义锚**（条 5 · 2026-10-02 · #828）= create 按目标所属项目落基底 ∥ 无所属显式拒；读面候选分支追加；
  * 在飞 ∥ 写门基底集 = 候选并集（`batchDocBases`）；**零变面** = 绝对路径照旧、三个错误文案逐字、
  * 「参数在 + 路径可读」判据句、`ok` / `none` 两态。
+ * **基底自有项目根分支 + 基底相对单段收窄**（条 6 · 2026-10-05 · #942）= 逐基底 `owningProject` 恰一落点收 ∥ 多落点显式拒（`ambiguousLandingError`）；基底相对分支限单段（多段串不二次拼接）。
  *
  * 依赖（KD-4 单向）：本档为**叶档**——只 import `node:*` 与 `../manifest.mjs`；主档 re-export 保既有面。
  */
@@ -98,8 +99,9 @@ const outsideBasesError = (raw) => new Error(`batch: create path resolves outsid
 const anchoredEscapeError = (raw) => new Error(`batch: create path is anchored at a batch base root but does not resolve under the declared docRoot.batches root(s) — refusing to nest it (fail-closed). Path: ${raw}`)
 /** 歧义锚 create 拒面（**文案逐字** = `BATCH-RECORD.md` §4.15 条 5——机检锚 `ambiguous session anchor`）。 */
 const ambiguousCreateError = (raw, candidates) => new Error(`batch: ambiguous session anchor — create target "${raw}" belongs to no candidate project; pass an explicit project path (e.g. "${candidates[0]}/docs/batches/<file>.md"). Candidates: ${candidates.join(", ")}`)
+const ambiguousLandingError = (raw, landings) => new Error(`batch: create path resolves under more than one declared batch-record base — refusing to pick one (fail-closed); pass an explicit path (absolute preferred). Path: ${raw}. Candidates: ${landings.join(", ")}`)
 
-/** 歧义锚读面候选腿（条 5）：逐候选项目——项目根形（`resolve(candidate, p)`）∥ 声明基底形
+/** 歧义锚读面候选分支（条 5）：逐候选项目——项目根形（`resolve(candidate, p)`）∥ 声明基底形
  *  （候选按名排序、并集保序——「首个可读」在此即为确定判读）。 */
 function ambiguousReadLegs(cwd, p) {
   const amb = ambiguousCandidates(cwd)
@@ -149,7 +151,7 @@ export function resolveBatchDocPath(cwd, given) {
 }
 
 /**
- * **create 面**解析（§4.15 条 2/3）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
+ * **create 面**解析（§4.15 条 2/3/6）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
  * 根内**者（新档不存在——可读性无判别力）；锚定串只解析项目根形，不落基底内 ⇒ fail-closed 新文案。
  *  **歧义锚**（条 5）：目标所属项目（`owningProject`）∈ 锚候选集 ⇒ 基底 = 该项目声明面（落其基底内；
  *  越出 ⇒ 既有 fail-closed）；无所属 ⇒ **显式拒**（列候选 + 显式路径指引——不静默落锚）。
@@ -179,8 +181,26 @@ export function resolveBatchCreatePath(cwd, given, bases) {
     if (!insideBases(abs, roots)) throw anchoredEscapeError(raw)
     return abs
   }
-  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p), ...roots.map((b) => resolve(b, p))]) {
+  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p)]) {
     if (insideBases(abs, roots)) return abs
   }
+  // ③ 基底自有项目根形（#942 条 6）：owningProject 可判者逐基底取值；distinct 落点 ≥2 ⇒ 拒
+  const owned = []
+  for (const b of roots) {
+    const ownRoot = owningProject(b)
+    if (!ownRoot) continue
+    const abs = resolve(ownRoot, p)
+    if (insideBases(abs, roots) && !owned.some((x) => samePath(x, abs))) owned.push(abs)
+  }
+  if (owned.length > 1) throw ambiguousLandingError(raw, owned)
+  if (owned.length === 1) return owned[0]
+  // ④ 基底相对形收窄单段（归一后无 `/` 才走原基底分支——多段串不二次拼接）
+  const leafRel = roots.length ? relative(roots[0], resolve(roots[0], p)) : ""
+  if (leafRel && !leafRel.startsWith("..") && !leafRel.includes(sep)) {
+    for (const b of roots) {
+      const abs = resolve(b, p)
+      if (insideBases(abs, roots)) return abs
+    }
+  }
   throw outsideBasesError(raw)
 }