@thincoder/core 0.9.5 → 0.10.1

package/agent-tools/batch-paths.mjs

@@ -7,20 +7,33 @@
  * 契约（§4.15 逐字）：**候选序** = cwd → 项目根 → 逐基底（基底 = `batchDocBases` 声明面单源）；
  * **判据分野** = 读面取首个**可读**文件 / create 取首个**落基底根内**者；**锚定防嵌套** = 串以任一基底的
  * 「项目根相对前缀」打头且前缀后为**路径段边界** ⇒ 只解析项目根形（不二次拼接；不落基底内 ⇒ fail-closed）；
- * **零变面** = 绝对路径照旧、三个错误文案逐字、「参数在 + 路径可读」判据句。
+ * **歧义锚**（条 5 · 2026-10-02 · #828）= create 按目标所属项目落基底 ∥ 无所属显式拒；读面候选腿追加；
+ * 在飞 ∥ 写门基底集 = 候选并集（`batchDocBases`）；**零变面** = 绝对路径照旧、三个错误文案逐字、
+ * 「参数在 + 路径可读」判据句、`ok` / `none` 两态。
  *
  * 依赖（KD-4 单向）：本档为**叶档**——只 import `node:*` 与 `../manifest.mjs`；主档 re-export 保既有面。
  */
 import { existsSync, statSync } from "node:fs"
 import { isAbsolute, relative, resolve, sep } from "node:path"
 
-import { docRootBase, docRootPaths, readManifest, resolveProjectRoot } from "../manifest.mjs"
+import { docRootBase, docRootPaths, owningProject, projectRootView, readManifest, resolveProjectRoot } from "../manifest.mjs"
 
 /** 可读文件判据（存在且为文件——目录 / 缺失同判不可读）。 */
 function readableFile(abs) {
   try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
 }
 
+/** 歧义锚候选（判定单点 = `projectRootView`——`ambiguous` 态 ⇒ 候选全列**按名排序**；余者 null）。 */
+function ambiguousCandidates(cwd) {
+  const view = projectRootView(cwd ?? process.cwd())
+  return view.state === "ambiguous" ? view.candidates : null
+}
+
+/** 路径同一性比较（win32 大小写不敏感——同越基底判据口径）。 */
+function samePath(a, b) {
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b
+}
+
 /** 「项目根」取根单源（§4.15 条 1——归属 ∨ 发现，无 manifest ⇒ `resolve(cwd ?? ".")` 兜底且**单值**）：
  *  同式 = 台账库键 / 写门指针基准的同一子表达式（`design/LEDGER.md` §6.1 口径 2）。 */
 export function batchProjectRoot(cwd) {
@@ -37,9 +50,16 @@ function declaredBases(cwd) {
 
 /** 批次档基底根数组（**声明面单源**——create / 在飞扫描 / 锚定判据共用）：manifest `docRoot.batches`
  *  （串 | 多根数组）→ 声明基底；缺失 / 非法 ⇒ 回退默认基底 `"docs/batches"`（恒返回非空数组）。
+ *  **歧义锚**（条 5）⇒ 候选项目基底**并集**（候选按名排序、并集保序）——在飞扫描 / 写门基底集同取此值。
  *  @param {string} cwd
  *  @returns {string[]} */
 export function batchDocBases(cwd) {
+  const amb = ambiguousCandidates(cwd)
+  if (amb) {
+    const union = []
+    for (const c of amb) for (const b of batchDocBases(c)) if (!union.includes(b)) union.push(b)
+    return union
+  }
   const roots = declaredBases(cwd)
   return roots.length ? roots : [resolve(docRootBase(cwd), "docs/batches")]
 }
@@ -76,6 +96,21 @@ function insideBases(abs, bases) {
 const outsideBasesError = (raw) => new Error(`batch: create path resolves outside the batch-record base roots — a batch record must live under the declared docRoot.batches base (fail-closed). Path: ${raw}`)
 /** create 锚定但落基底外（§4.15 新文案逐字——不二次拼接）。 */
 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(", ")}`)
+
+/** 歧义锚读面候选腿（条 5）：逐候选项目——项目根形（`resolve(candidate, p)`）∥ 声明基底形
+ *  （候选按名排序、并集保序——「首个可读」在此即为确定判读）。 */
+function ambiguousReadLegs(cwd, p) {
+  const amb = ambiguousCandidates(cwd)
+  if (!amb) return []
+  const out = []
+  for (const c of amb) {
+    out.push(resolve(c, p))
+    for (const b of declaredBases(c)) out.push(resolve(b, p))
+  }
+  return out
+}
 
 /**
  * **读面**解析（append / status / close 与评审门 / spawn 门共用）：首个**可读**候选胜；无 ⇒ null
@@ -93,7 +128,7 @@ export function resolveBatchReadPath(cwd, given) {
     const abs = resolve(batchProjectRoot(base), p)
     return readableFile(abs) ? abs : null
   }
-  const candidates = [resolve(base, p), resolve(batchProjectRoot(base), p), ...declaredBases(base).map((b) => resolve(b, p))]
+  const candidates = [resolve(base, p), resolve(batchProjectRoot(base), p), ...declaredBases(base).map((b) => resolve(b, p)), ...ambiguousReadLegs(base, p)]
   for (const abs of candidates) if (readableFile(abs)) return abs
   return null
 }
@@ -116,6 +151,8 @@ export function resolveBatchDocPath(cwd, given) {
 /**
  * **create 面**解析（§4.15 条 2/3）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
  * 根内**者（新档不存在——可读性无判别力）；锚定串只解析项目根形，不落基底内 ⇒ fail-closed 新文案。
+ *  **歧义锚**（条 5）：目标所属项目（`owningProject`）∈ 锚候选集 ⇒ 基底 = 该项目声明面（落其基底内；
+ *  越出 ⇒ 既有 fail-closed）；无所属 ⇒ **显式拒**（列候选 + 显式路径指引——不静默落锚）。
  * @param {string} cwd 会话锚
  * @param {string} given create `path` 原值
  * @param {string[]} bases 已解析的基底根数组（`batchDocBases` 单源；调用方传入以免重复读档）
@@ -125,18 +162,25 @@ export function resolveBatchCreatePath(cwd, given, bases) {
   const base = cwd ?? process.cwd()
   const raw = String(given ?? "").trim()
   const p = raw.replace(/\\/g, "/")
+  let roots = bases
+  const amb = ambiguousCandidates(base)
+  if (amb) {
+    const owner = owningProject(isAbsolute(raw) ? resolve(raw) : resolve(base, p))
+    if (!owner || !amb.some((c) => samePath(c, owner))) throw ambiguousCreateError(raw, amb)
+    roots = batchDocBases(owner)
+  }
   if (isAbsolute(raw)) {
     const abs = resolve(raw)
-    if (!insideBases(abs, bases)) throw outsideBasesError(raw)
+    if (!insideBases(abs, roots)) throw outsideBasesError(raw)
     return abs
   }
-  if (anchoredPrefix(p, basePrefixes(base, bases))) {
+  if (anchoredPrefix(p, basePrefixes(base, roots))) {
     const abs = resolve(batchProjectRoot(base), p)
-    if (!insideBases(abs, bases)) throw anchoredEscapeError(raw)
+    if (!insideBases(abs, roots)) throw anchoredEscapeError(raw)
     return abs
   }
-  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p), ...bases.map((b) => resolve(b, p))]) {
-    if (insideBases(abs, bases)) return abs
+  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p), ...roots.map((b) => resolve(b, p))]) {
+    if (insideBases(abs, roots)) return abs
   }
   throw outsideBasesError(raw)
 }

package/agent-tools/batch-skeleton.mjs

@@ -117,7 +117,7 @@ export function readBatchStatusLine(src) {
   nextRe.lastIndex = s1.index + s1[0].length
   const next = nextRe.exec(src)
   const body = src.slice(s1.index + s1[0].length, next ? next.index : src.length)
-  const m = body.split("\n").map((line) => STATUS_LINE_RE.exec(line)).find(Boolean)
+  const m = body.split(/\r?\n/).map((line) => STATUS_LINE_RE.exec(line)).find(Boolean)
   if (!m) return "unknown"
   const value = m[1].trim()
   if (value.includes(STATUS_WORDS[1].closed)) return "closed"
@@ -125,6 +125,24 @@ export function readBatchStatusLine(src) {
   return "unknown"
 }
 
+/**
+ * §N 段内「`**状态行**：` 行存在性」判据（#422③——close 对无状态行档自建机读位的**采集面**：
+ * 与 readBatchStatusLine 的「值可解析」正交——无行 ⇒ 可自建；有行而值不可解析 ⇒ 仍 fail-closed）。
+ * 段界定消费 sectionHeaderRe（同单源——`## §20` 不误命中 `§2`）。
+ * @param {string} src — 档全文
+ * @param {number|string} seg — 段号
+ * @returns {boolean} 段内是否存在形态匹配行（段头缺失同判 false）
+ */
+export function sectionHasStatusLine(src, seg) {
+  const hdr = sectionHeaderRe(seg).exec(src)
+  if (!hdr) return false
+  const nextRe = /^## §\d/gm
+  nextRe.lastIndex = hdr.index + hdr[0].length
+  const next = nextRe.exec(src)
+  const body = src.slice(hdr.index + hdr[0].length, next ? next.index : src.length)
+  return body.split(/\r?\n/).some((line) => STATUS_LINE_RE.test(line))
+}
+
 /**
  * create 骨架模板（BATCH-RECORD.md §4.10 行为规格的**代码单源**——红线：模板只覆盖骨架与
  * 占位，不模板化内容）：`## §1–§6` 段头（含职责署名）+ 档头 boilerplate（六段一段一作者句 +

package/agent-tools/batch.mjs

@@ -4,8 +4,8 @@
  *
  * 单工具 `batch`，action = create（建档，§4.11）/ append（段写入——原 batch-segment.mjs 语义
  * 逐字迁移，§4.1 全表）/ status（段属主状态行流转，§4.12）/ close（收口冻结，§4.13）。
- * 权威规格 = `docs/core/design/BATCH-RECORD.md` §4（契约/挂载/用例 BR-1–26/骨架 §4.10/
- * 参数面 §4.11–§4.13/别名 §4.14）；骨架与判定字面单源 = `batch-skeleton.mjs`；lifecycle 面 =
+ * 权威规格 = `docs/core/design/BATCH-RECORD.md` §4（契约/挂载/用例 §4.8/骨架 §4.10/
+ * 参数面 §4.11–§4.13）；骨架与判定字面单源 = `batch-skeleton.mjs`；lifecycle 面 =
  * `batch-lifecycle.mjs`。**依赖单向（KD-4）：skeleton ← lifecycle ← 主档**。
  *
  * 身份判据（D-BR17/D-BR18/D-BR21）：主 agent 调用 ctx 带 `depth === 0`（dispatch 装配）；
@@ -17,11 +17,9 @@
  * ——轮 2 #3 裁定②）。append 迁移面错误串**逐字保持 "batch_segment:" 前缀**（§4.1 全表锚断言）；
  * "batch:" 前缀 = 本批新增错误面（create/close/status/findInFlight/path 门/dispatch）。
  *
- * 导出面：`batchTool`（主名）· `batchSegmentTool`（**过渡别名**——name 仍 "batch_segment"，
- * schema 仅 {segment,text}、描述逐字，execute ⇒ append 同一执行体；撤除判据 = BATCH-RECORD
- * §4.14）· `resolveBatchDocPath` · `batchDocBases` · `batchDocForReview` ·
+ * 导出面：`batchTool`（主名）· `resolveBatchDocPath` · `batchDocBases` · `batchDocForReview` ·
  * `configureBatchSegment` / `resetBatchSegment`（#84 记账缝——契约名不变，AC-11 零改）·
- * `MAX_TEXT_CHARS` · `SEGMENT_BY_ROLE`（re-export——shim 导出全超集需要）。
+ * `MAX_TEXT_CHARS` · `SEGMENT_BY_ROLE`。
  *
  * #84 记账面（CORE-UNIFICATION §2.13.4）：写入成功后的记账**按端注入**——核内缺省 no-op = CLI
  * 语义零行为变；端装配经 `configureBatchSegment({ onWrite })` 覆盖（VSC 侧现形 = `_touchedFiles`
@@ -29,6 +27,8 @@
  */
 import { readFileSync, writeFileSync } from "node:fs"
 
+// 描述面 = `tool-docs/batch.md`（#15 描述外置统一——工厂形描述经 DESC 单一解析面，工厂调用期取值）
+import { DESC } from "../tools/shared.mjs"
 import { SEGMENT_BY_ROLE, readBatchStatusLine, sectionHeaderRe, findPlaceholderResidue, placeholderResidueError } from "./batch-skeleton.mjs"
 import { batchDocBases, resolveBatchDocPath } from "./batch-paths.mjs"
 import { closeBatchRecord, createBatchRecord, findInFlightBatch, statusBatchRecord } from "./batch-lifecycle.mjs"
@@ -36,8 +36,7 @@ import { closeBatchRecord, createBatchRecord, findInFlightBatch, statusBatchReco
 export { SEGMENT_BY_ROLE, batchDocBases, resolveBatchDocPath }
 
 /** text 单次上限（BATCH-RECORD.md §4.1——超出引导分段追加，不承诺"不新盖戳"）。append 迁移域私有区常量
- *  （随执行体自 batch-segment.mjs 迁入——骨架档只住骨架/状态行单源，lifecycle 档头枚举口径）；
- *  export = shim 导出全超集（旧 `batch-segment.mjs` 导出面等价保持）。 */
+ *  （随执行体自 batch-segment.mjs 迁入——骨架档只住骨架/状态行单源，lifecycle 档头枚举口径）。 */
 export const MAX_TEXT_CHARS = 20000
 /** 工具写入的轮次节标题形态（N 计数口径 = 该形态行；`### 轮次与发现（…）` 骨架行不匹配）。 */
 const ROUND_HEADING_RE = /^### 轮次 \d+（评审子代理）/
@@ -182,7 +181,7 @@ function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
     }
     abs = resolveBatchDocPath(cwd, givenPath)
   } else if (depth0) {
-    abs = findInFlightBatch(cwd, batchDocBases(cwd))
+    abs = findInFlightBatch(cwd, batchDocBases(cwd)) // 歧义锚 ⇒ 基底 = 候选并集（#828——唯一在飞批照取 / ≥2 照列）
   } else {
     if (!batchDoc) {
       throw new Error("batch_segment: no batch record is bound to this caller — there is no path parameter by design (the target arrives via the spawn binding / the review instance key). Report the section as not written.")
@@ -195,7 +194,7 @@ function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
     throw new Error("batch_segment: 已收口档不回改 — the bound batch record's §1 status line contains 「已收口」, so the record is frozen: its body is never written to again (整档冻结；改 = 新批新档). Nothing was written. Report the section as not written.")
   }
   if (status === "unknown") {
-    throw new Error("batch_segment: 状态行不可解析或缺失 — the bound batch record has no §1 `**状态行**：` line whose value contains 已收口 or 进行中 (fail-closed: the write is refused as if frozen). Ask the record's creator to set the §1 status line, then call again. Nothing was written.")
+    throw new Error("batch_segment: 状态行不可解析或缺失 — the bound batch record has no §1 `**状态行**：` line whose value contains 已收口 or 进行中 (fail-closed: the write is refused as if frozen). Ask the record's creator to set the §1 status line, then call again. Nothing was written. Do NOT close the record after a refused append — nothing landed, and closing freezes the missing section for good (失败 ⇒ 勿 close).")
   }
   if (typeof args?.text !== "string") {
     throw new Error("batch_segment: text must be a string (the markdown to append).")
@@ -204,7 +203,7 @@ function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
     throw new Error(`batch_segment: text is ${args.text.length} characters — the limit is ${MAX_TEXT_CHARS} per call. Split it into multiple calls: each call becomes its own section and the round number N continues (分段追加——每次调用各成节、N 顺延).`)
   }
   if (/^## §\d/m.test(args.text)) {
-    throw new Error("batch_segment: the text contains a section header line matching `^## §N` — that would break section location and the append-only guarantee. Rewrite it (escape the heading, or drop the leading `## §N`), then call again (骨架保护). Nothing was written.")
+    throw new Error("batch_segment: the text contains a section header line matching `^## §N` — that would break section location and the append-only guarantee. Rewrite it (escape the heading, or drop the leading `## §N`), then call again (骨架保护). Nothing was written. Do NOT close the record after a refused append — nothing landed, and closing freezes the missing section for good (失败 ⇒ 勿 close).")
   }
   const body = sanitizeText(args.text, n === 3).replace(/^\n+/, "").replace(/\s+$/, "")
   if (!body.trim()) {
@@ -230,18 +229,7 @@ function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
 export function batchTool(batchDoc = null, { review = false } = {}) {
   return {
     name: "batch",
-    description:
-      "Batch-record lifecycle tool (一段一作者 — six append-only sections, one author each). " +
-      "actions: create (depth-0 only — write a new six-section skeleton record; pass path + topic + source) · " +
-      "append (add text to the END of YOUR section — existing lines are never rewritten or deleted) · " +
-      "status (update YOUR section's `**状态行**：` line — the value must carry exactly ONE legal keyword of your section's STATUS_WORDS entry, decorated only by surrounding symbols / a trailing ISO date / whitespace; prose goes to the separate `note` field, which lands as a parenthetical) · " +
-      "close (depth-0 only — freeze the record: §1 → 「已收口 <date>」, every further write is refused). " +
-      "Identity fixes what you may write (段白名单): main agent (depth 0) — append §1/§4/§6, status §1 only, create/close; eng-designer — §2; eng-coder — §5; design review (review binding) — §3. A write outside your own section is refused. " +
-      "Skeleton placeholders (dead literals — `#<编号>` / `<板块>` and the older `<BATCH-ID>` / `<讨论来源>`) in the record header or in your target section block append/status: fill them first (the main agent fills the header right after create); `<§N 模板占位：…>` template lines are legal and never blocked. " +
-      "Target record: sub-agents and design reviews have NO path parameter in practice — the record arrives via the spawn binding / the review instance key (passing path is refused); depth-0 MAY pass path (若传则须可读), omitting it picks the unique in-flight record (0 or ≥2 in flight ⇒ refuse — pass path). " +
-      "A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). " +
-      "Credential values are stripped mechanically before writing (never write a token or designId value). " +
-      "Failures are hard and visible (no silent fallback): if a write is refused or fails, say so in your report — “§× 未写入”.",
+    description: DESC("batch"), // 模型可见文本 = tool-docs/batch.md
     parameters: {
       type: "object",
       properties: {
@@ -292,7 +280,7 @@ export function batchTool(batchDoc = null, { review = false } = {}) {
     async execute(args, ctx) {
       const agent = ctx?.agent ?? {}
       const cwd = agent.cwd ?? process.cwd()
-      const bases = batchDocBases(cwd)
+      const bases = batchDocBases(cwd) // 歧义锚 ⇒ 候选项目基底并集（#828——create / 在飞 / 写门基底集同源）
       const onWritten = injectedOnWrite
       /** depth-0 目标定位（D-BR21）：path 传 ⇒ 可读性门；缺省 ⇒ 唯一在飞批（depth-0）/
        *  绑定解析（子代理/评审）。status/close 经此注入 lifecycle；append 自带同款分支。 */
@@ -323,44 +311,3 @@ export function batchTool(batchDoc = null, { review = false } = {}) {
     },
   }
 }
-
-/**
- * 过渡别名（BATCH-RECORD §4.14——撤除判据见该节）：name 仍 "batch_segment"、schema 仅
- * {segment, text}、描述**逐字**保持原 batch-segment.mjs 基准；execute ⇒ append（同一执行体，
- * 行为等价——AC-2/AC-9）。生产挂载面已全切主名 `batch`（BATCH-RECORD §4.3）；本工厂仅供
- * 过渡 shim 导出面（旧测试 / VSC 侧 import 消费）与撤除判据实跑使用。
- * @param {string|null} batchDoc — 绑定的目标档（spawn：`child._batchDoc`；评审：实例键）
- * @param {{review?: boolean}} [opts] — review=true 表示"设计评审实例"形态（写 §3 + 工具盖戳）
- */
-export function batchSegmentTool(batchDoc = null, { review = false } = {}) {
-  const tool = batchTool(batchDoc, { review })
-  const own = review ? "§3" : null
-  return {
-    name: "batch_segment",
-    description:
-      "Append your own section of the batch record (一段一作者). " +
-      "There is NO path parameter: the target record is bound to you (at spawn for eng-designer/eng-coder, per review instance for a design review) and your identity fixes the section you may write " +
-      "(eng-designer → §2, design review → §3, eng-coder → §5) — a write outside your own section is refused. " +
-      "Append-only: the text lands at the end of your section; existing lines are never rewritten or deleted. " +
-      "Credential values are stripped mechanically before writing (never write a token or designId value). " +
-      "A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). " +
-      "Failures are hard and visible (no silent fallback): if the write is refused or fails, say so in your report — “§× 未写入”.",
-    parameters: {
-      type: "object",
-      properties: {
-        segment: {
-          type: "string",
-          description: `The batch-record section you are writing${own ? ` — yours is ${own}` : ""}. Declares the section number only; your identity decides what is actually writable.`,
-        },
-        text: {
-          type: "string",
-          description: "The markdown to append (verbatim — findings table + VERDICT + counts for a design review §3). Limit 20000 characters per call; longer content is refused — split it into multiple calls (each call becomes its own section, N continues).",
-        },
-      },
-      required: ["segment", "text"],
-    },
-    async execute(args, ctx) {
-      return tool.execute({ action: "append", segment: args?.segment, text: args?.text }, ctx)
-    },
-  }
-}

package/agent-tools/checkpoint.mjs

@@ -0,0 +1,121 @@
+/**
+ * checkpoint.mjs — 撞帽续期检查点叶（TURN-CAP-CONTINUE.md §1 #7 / §3.1）。
+ *
+ * 异步族（后台子代理 / 异步飞刀 / 会诊）撞帽 ⇒ 不发用户卡：登记「挂起 + 父侧 ask」，
+ * 等父代理决定——`send` 兑现（新段预算、history 保留、任务文本不重注入）或
+ * `cancel` / 会话收尾 / Stop 降级（既有 partial 路径 + `TURN_CAP_MARK`）。
+ * 挂起不 settle、不重派：池条目仍在飞（status / observe 可见）、无新 child / 无新池条目、
+ * 兑现后同一 id 继续（D-TC12）。
+ *
+ * 三档逃逸（§3.1）：
+ *   ① 兑现 = 父 `send` 两处（池条目 `settleTurnCheckpoint` · 会诊会话 `settleConsultCheckpoint`）；
+ *   ② 中止信号（Stop / cancel / 会话中止）⇒ resolve(false) ⇒ 既有 onDeclined 降级；
+ *   ③ 不可答（无 `_upstream.parent` ∨ `sync === true`）⇒ 不登记 ⇒ 既有路径（零新挂起）。
+ *
+ * 零依赖叶（只引父侧通道 + 池 accessor）：端壳不经本档静态闭包。
+ */
+import { pushChildUpstream } from "./parent-channel.mjs"
+import { getAsyncPool } from "./async-settle.mjs"
+
+/**
+ * 段数 / 累计轮次二元文本（§4 留痕口径——两值同读一次）：
+ * `_continueSegments`（链内段数，首段 1）· `_turnSeq`（链内累计轮次，跨段不重置）。
+ * 两值均挂子 agent 本体。
+ * #417 追加第三元「本段零落盘轮数」（`_zeroWriteTurns`——核回合环采集，与 `_turnSeq` 同源面）：
+ * **只报数**（零阈值 / 零自动动作——父侧据此判断「在推进」还是「在原地读」）。缺该字段的
+ * 执行面（端侧自有回合环、未跟踪）不渲染该元——缺省不冒充 `0`（「未跟踪」不得读作「零消耗」）。
+ */
+function traceText(child) {
+  const base = `segments ${child?._continueSegments ?? 1} · accumulated ${child?._turnSeq ?? 0} turns`
+  return Number.isInteger(child?._zeroWriteTurns) ? `${base} · zero-write rounds this segment: ${child._zeroWriteTurns}` : base
+}
+
+/** 留痕片段（§3.1 池条目留痕行）：挂池条目摘要**文本**面（status / observe）——桥字段零新增。 */
+export function turnCapTrace(entry) {
+  return traceText(entry?.childAgent)
+}
+
+/** 去向一句话（ask 载荷末项）：答复通道随族——池条目 = `send` / `cancel`；
+ *  会诊会话 = `send` / `consult_stop`（会话级停；`cancel` 只认子代理池）。 */
+function replyHint(parent, carrier, key) {
+  const consult = getAsyncPool(parent, "consult")?.get(key) === carrier
+  const stop = consult ? `consult_stop (id ${key})` : `subagent action:'cancel' (id ${key})`
+  return `reply with subagent action:'send' (id ${key}) to grant a new segment, or ${stop} to stop it (partial)`
+}
+
+/**
+ * 登记检查点并挂起（异步族 askContinue 的唯一实现——逃逸 ①②③）：
+ * 登记 `carrier._turnCapRec` + 父侧 ask（载荷 = 段数 / 累计轮次 + 去向一句话）——
+ * ask 入队即唤醒父侧挂起驱动（`pushChildUpstream`）。
+ * @param {object} child   撞帽的子 agent（`_upstream` 携父与来源标签）。
+ * @param {object} carrier 兑现载体：池条目（子代 / 飞刀）或会诊 session。
+ * @param {{turn?: number, signal?: AbortSignal}} payload 撞帽轮次 + 中止信号。
+ * @returns {Promise<boolean>} true = 父 `send` 兑现 ⇒ 重入新段；false = 中止 / 不可答 / 兑现 miss。
+ */
+export function registerTurnCapCheckpoint(child, carrier, { turn = 0, signal } = {}) {
+  const parent = child?._upstream?.parent
+  // ③ 不可答降级：无父（headless 内嵌）或同步族（后台检查点只服务异步族——同步族保留用户卡）
+  if (!parent || child?._upstream?.sync === true || !carrier) return Promise.resolve(false)
+  if (signal?.aborted) return Promise.resolve(false) // ② 已中止 ⇒ 立即降级（不进挂起）
+  const key = String(carrier.id ?? "")
+  const rec = { child, carrier, turn }
+  // 先臂后报请（顺序即防御）：`rec.resolve` 与中止监听在入队**前**就位——否则
+  // `pushChildUpstream` 同步唤醒等待栓的窗口里「登记已写、resolve 未挂」，兑现假成功而挂起不收敛。
+  let abortedNow = signal?.aborted === true
+  const promise = new Promise((resolve) => {
+    // 注销单点（幂等）：兑现 / 中止两路共用——登记清除后重复兑现 miss（回落既有路径）。
+    const finish = (ok) => {
+      if (carrier._turnCapRec === rec) delete carrier._turnCapRec
+      signal?.removeEventListener?.("abort", onAbort)
+      resolve(ok)
+    }
+    const onAbort = () => finish(false)
+    rec.resolve = finish
+    signal?.addEventListener?.("abort", onAbort, { once: true })
+    // 注册后复检（`permission-gate.mjs:80-81` 同款序）：监听只认注册后的状态转移，
+    // 窗口内已中止 ⇒ 监听不落地，此处兜住。
+    if (signal?.aborted) { abortedNow = true; onAbort() }
+  })
+  if (abortedNow) return promise // ② 窗口内已中止 ⇒ 不登记、不报请（直接走既有 partial 降级）
+  carrier._turnCapRec = rec
+  pushChildUpstream({
+    parent,
+    from: child._upstream.label,
+    kind: "ask",
+    message: `[turn cap] ${traceText(child)} — this child hit its per-segment turn cap and is suspended `
+      + `(history kept, no re-dispatch). ${replyHint(parent, carrier, key)}`,
+  })
+  return promise
+}
+
+/** ① 池条目兑现（send 面第一条）：读登记 → 注销 → resolve(true)。
+ *  miss（无挂起 / 非检查点 send）⇒ false——调用方回落既有注入路径；兑现后幂等 miss。 */
+export function settleTurnCheckpoint(carrier) {
+  const rec = carrier?._turnCapRec
+  if (!rec) return false
+  rec.resolve?.(true)
+  return true
+}
+
+/** ① 会诊会话兑现（send 面第二条——id 不属子代理池时试会诊会话）：父方向注入该会话在飞
+ *  子代理的注入队列（下一回合边界消费；`consumeInjected` 同族）⇒ 兑现登记。
+ *  miss ⇒ false——调用方回落 `unknown async subagent id`。 */
+export function settleConsultCheckpoint(agent, key, message) {
+  const rec = getAsyncPool(agent, "consult")?.get(String(key))?._turnCapRec
+  if (!rec) return false
+  rec.child._injected ??= []
+  rec.child._injected.push(String(message).trim())
+  rec.resolve?.(true)
+  return true
+}
+
+/** ① 兑现后的 send 早返体（既有 send 结果同形 + 检查点语汇）：兑现即不落「未命中 / 静默丢弃」
+ *  ——父侧可见它确实续了新段。 */
+export function resumedSendResult(key, label) {
+  return JSON.stringify({
+    id: String(key),
+    status: "delivered",
+    resumed: true,
+    note: `turn-cap checkpoint delivered — ${label} ${key} resumes with a fresh segment budget (history kept, no task-text re-injection); the message is consumed as an ordinary user instruction at its next turn boundary.`,
+  })
+}

package/agent-tools/child-permission.mjs

@@ -29,15 +29,17 @@ export function childOwnerLabel(role, id, model) {
  * 构建 child 权限通道。返回 null（无 `ctx.callbacks.onPermissionRequired`——headless /
  * 无关角色调用侧未挂；AUTO 判定走父门询问时 live 读——同判据单源，ED-2 2026-09-16）或
  * `async (toolName, args, diffInfo) => boolean`。
- * @param {{ ctx: object, id: number, role: string, model?: string|null, signal?: AbortSignal|null }} deps
+ * `forceAsk`（默认 false）= 本询 AUTO 豁免**透传**（续期恒须人答——TURN-CAP-CONTINUE.md §1 #7；
+ * 置位点唯一 = VSC `panel-callbacks.mjs` 的 `continue` 名分支）——其余调用逐字零变化。
+ * @param {{ ctx: object, id: number, role: string, model?: string|null, signal?: AbortSignal|null, forceAsk?: boolean }} deps
  */
-export function makeChildPermission({ ctx, id, role, model = null, signal = null }) {
+export function makeChildPermission({ ctx, id, role, model = null, signal = null, forceAsk = false }) {
   if (!ctx?.callbacks?.onPermissionRequired) return null
   const owner = { label: childOwnerLabel(role, id, model), role, id }
   return async (toolName, args, diffInfo) => {
     ctx.callbacks.onSubagentApproval?.({ id, role, model, tool: toolName })
     try {
-      return await ctx.callbacks.onPermissionRequired(toolName, args, diffInfo, { owner, signal })
+      return await ctx.callbacks.onPermissionRequired(toolName, args, diffInfo, { owner, signal, forceAsk })
     } finally {
       ctx.callbacks.onSubagentApproval?.({ id, role, model, tool: null })
     }