@thincoder/core 0.10.12 → 0.11.1

package/agent-tools/subagent-spawn.mjs

@@ -24,7 +24,7 @@ import { tokenExpired, removeDesignTokenSlot, reconcileEngTokensFromSlot } from
 import { resolveChildProvider, buildChildRunOpts, enqueueAsk } from "./subagent-async.mjs"
 import { nextSubagentId } from "./subagent-scheduler.mjs"
 import {
-  normalizeFileList, describeBlockers, assertNoDepCycle, depInfo,
+  normalizeFileList, describeBlockers, assertNoDepCycle, depInfo, batchDocInFlight,
 } from "./subagent-scheduler.mjs"
 // M5 F2（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.3）：任务书 round 枚举 + 五项结构化参数校验/拼装本体落
 // spawn-gates.mjs（纯谓词零依赖）——本处只加 import 调用。
@@ -37,7 +37,21 @@ import {
 import { buildAuditBlock } from "./audit-block.mjs"
 // 批次档路径解析单源（BATCH-RECORD.md §4.15 · 台账 #287）：门内解析改经叶档（读面非抛形），
 // 与 append / create 同源——门判据仍「参数在 + 路径可读」，错误文案逐字零变。
-import { resolveBatchReadPath } from "./batch-paths.mjs"
+import { resolveBatchReadPath, resolveBatchReadResult } from "./batch-paths.mjs"
+// `files` 落点单源 = 统一解析层（实调点 = `normalizeFileList`——`thincoder-core/agent-tools/subagent-scheduler.mjs`
+// 的 `const abs = resolvePathTarget(cwd, f, ...)`）：本档不再预解析（预解析会让该面的三条门判吃绝对形而漏判）。
+import { danglingSameNameHint } from "../path-resolve.mjs"
+
+/** 不可读拒文的追加提示（§2.6：既有文案逐字在前）——同名候选 ∥ 判不出唯一的候选全列；无提示 ⇒ 空串。 */
+function unreadableHint(cwd, given) {
+  const r = resolveBatchReadResult(cwd, given)
+  if (r.state === "dangling") {
+    const hint = danglingSameNameHint(r)
+    return hint ? `；${hint}` : ""
+  }
+  if (r.state === "ambiguous") return `；Candidates: ${r.candidates.join(" ∥ ")}`
+  return ""
+}
 
 /** 任务书播报文本：该角色名集拼装 + 可选 task 自由文本（拼装空 ⇒ 原 task 逐字——旧形零变）。 */
 function taskBriefOf(args, role) {
@@ -167,6 +181,16 @@ export function prepareScheduling(parent, filesRaw, dependsRaw, wantAsync) {
   return { files, dependsOn, errorJson: null }
 }
 
+/** S4 写域行（AGENT-LOOP-SUBAGENT.md §6.26「写域行（S4）」）：表头 + 逐条绝对路径 + 两句语义——
+ *  本档局部纯函数（D23-9：不外提模块）。两句不可省：缺① 子代理读成「我只能写这些」⇒ 该写的漏掉；
+ *  缺② 仍把任务书 §2 全文当成自己的改动面（本块的病因）。清单不截断——截断正是本块要消除的
+ *  「看不见」。返回块文本（块间分隔由装配侧 `join("\n\n")` 施加）。 */
+function filesBlockOf(files) {
+  return `Files declared for this spawn (the write domain this task declares, for scheduling):\n` +
+    files.map((f) => `- ${f}`).join("\n") +
+    `\n\nThis list is not an authorization boundary: touching a file outside it is allowed — report every out-of-list file you changed, with its reason. It is also not the whole change surface: other spawns on this task declare their own files, and what is listed here is your share only.`
+}
+
 /**
  * AGENT-LOOP-SUBAGENT.md §6.9 准入通过后的 child 装配（2026-09-05 module-split——自 execute 参数化提取，
  * 原 318-488 段 verbatim——语义零变）。副作用保留：relay 取号（sync 支 allocRelay——
@@ -194,25 +218,44 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   let batchDocAbs = null
   if (engineeringRole) {
     const given = typeof args.batchDoc === "string" ? args.batchDoc.trim() : ""
+    // 「无果 ⇒ 既有文案 + 追加同名候选」（§2.6——既有拒文逐字在前，层的提示只追加）。
     const refusal = (suffix = "") => new Error(
       `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)")
+    batchDocAbs = resolveBatchReadPath(parent.cwd, given)
+    if (!batchDocAbs) throw refusal(` (given path is not a readable file${unreadableHint(parent.cwd, given)})`)
   } else if (role === "coder") {
     const given = typeof args.batchDoc === "string" ? args.batchDoc.trim() : ""
     if (given) {
-      batchDocAbs = resolveBatchReadPath(parent.cwd ?? process.cwd(), given)
+      batchDocAbs = resolveBatchReadPath(parent.cwd, given)
       if (!batchDocAbs) {
-        throw new Error("batchDoc for role='coder' — 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); when provided it must resolve to a readable file (omit batchDoc to spawn without the §5 record-write binding).")
+        throw new Error("batchDoc for role='coder' — 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); when provided it must resolve to a readable file (omit batchDoc to spawn without the §5 record-write binding)." + unreadableHint(parent.cwd, given))
       }
     }
   }
 
+  // ── AGENT-LOOP-SUBAGENT.md §6.58 批次档复用护栏（2026-10-28 batchdoc-reuse-guard）──
+  // 同一档已有在飞 spawn ⇒ 拒发（2026-10-28 11:34 事故：两席共用一本批档、文件域互不重叠 ⇒
+  // 语法坏档 + 一席复原）。判据 = 池内在飞条目的 `_batchDoc` 与本次解析出的绝对路径按 fileKey
+  // 相等（谓词单源 = `batchDocInFlight`——池派生事实住 subagent-scheduler.mjs，读法同 `depInfo`）。
+  // 只用结构性事实（池 + 路径相等），不做文本匹配（TOOLS.md §6.4）。
+  // **不读 `round`**（KD-BG1）：修正轮靠「前一轮已 settle ⇒ 不在在飞集」自然放行；前一轮仍
+  // 在飞就派修正轮 = 同一种两写者病，照拒。
+  // **非对称是判据的一部分，勿「顺手统一」**：被检面只覆盖工程角色（本分支内），占用者是池内
+  // 任何带 `_batchDoc` 的条目、不分角色（普通面 coder 携 batchDoc 也算）；sync spawn 不入池 ⇒
+  // 它不是占用者（§6.58.7 第 7 条）。
+  // 拒因文案逐字模板 = §6.58.2（文案单源 = 本处——下游断言逐字对照）。
+  if (engineeringRole) {
+    const occupant = batchDocInFlight(parent, batchDocAbs)
+    if (occupant) {
+      throw new Error(`batchDoc is already in flight — spawn refused. Batch record: ${batchDocAbs}. Occupant: ${occupant.role}#${occupant.id} (status: ${occupant.status}). One batch record serves one concurrent spawn: wait for ${occupant.role}#${occupant.id} to settle, or cancel it, then spawn again.`)
+    }
+  }
+
   // M5 F2 + §6.22（2026-10-24）任务书门——按角色分流：
   //   工程角色（eng-coder / eng-designer）：零任务书文本参数——八个自由文本键命中即拒（键在场即拒）并点名
   //     （值全空白也拒）；随后 round 枚举（initial|fix）。
-  //   explore / plan / coder：四项核心 + `scope` 必带（判据三条零改：存在 ∧ string ∧ trim 非空）。
+  //   explore / plan / coder / tester：四项核心 + `scope` 必带（判据三条零改：存在 ∧ string ∧ trim 非空）。
   // 落点 = batchDoc 门之后、token 门之前（门序 = AGENT-LOOP-SUBAGENT.md §6.22.1）。
   if (engineeringRole) {
     rejectEngFreeTextParams(args, role)
@@ -232,6 +275,19 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   if (role === "explore" || role === "plan") {
     const allowed = readonlyToolNames(parent.tools)
     tools = parent.tools.filter((t) => allowed.has(t.name))
+  } else if (role === "tester") {
+    // tester = the THIRD tool face (AGENT-LOOP-SUBAGENT.md §6.59.2 ④): read-only set ∪ {execute, bash},
+    // minus {verify, advisor}.
+    //   · Allowlist form (D-TT1) — a new non-readonly tool stays OUT by default (the write face is fail-closed);
+    //     a new readonly tool joins automatically through the same formula.
+    //   · Why subtract `verify` / `advisor`: both produce a VERDICT, not a reading — "I declare this delivery
+    //     good" and "open a review, produce a judgment". A tester's product is readings (F-TT3: it does not
+    //     close a judgment on the parent's behalf), and `advisor` is `readonly: true`, so leaving it in would
+    //     make 「it does not run reviews」 a sentence nobody enforces. Both subtractions are by name, explicit,
+    //     and do not depend on the tool's `readonly` flag — that flag says "writes nothing", not "concludes nothing".
+    const allowed = readonlyToolNames(parent.tools)
+    const TRIMMED = new Set(["verify", "advisor"])
+    tools = parent.tools.filter((t) => (allowed.has(t.name) && !TRIMMED.has(t.name)) || t.name === "execute" || t.name === "bash")
   } else {
     tools = parent.tools
   }
@@ -331,8 +387,8 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // 两处（批次档路径行 + 审计模板块）原随 user 首条下发，压缩把首条并入摘要即丢（长任务中后期
   // 既看不到批次档路径、也看不到审计模板 ⇒ 过度勘察的真病根）；固块值在 child 生命周期内恒定
   // ⇒ run 内 system 前缀逐字节稳定（前缀缓存不破），且不在 `agent.history` 内 ⇒ 压缩结构上吞不掉。
-  // 收集序 = 原拼接序（批次档行 → 审计块）；空数组 ⇒ 不绑定（depth-0 / explore / plan / consult
-  // 的 system 逐字节同改前——§6.26 缓存契约兼容证明）。
+  // 收集序 = 批次档行 → 审计块 → 写域行（S4，见下）；空数组 ⇒ 不绑定（depth-0 / explore / plan /
+  // consult 的 system 逐字节同改前——§6.26 缓存契约兼容证明）。
   const spawnBlocks = []
   // §2.11 第 1 点（FR16 载体 + FR17 铁律 #5 的机械面）：批次档**绝对路径**下发给工程角色
   // （eng-coder 实现 / eng-designer 写稿）——任务书本体 = 本档 §2；本行让子代理"拿到本档路径"。
@@ -342,6 +398,9 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // `_touchedFiles` ∪ 批档 §2（审计子代理自读）——**不是** eng-coder 自述（自述可恰好漏掉应抓的
   // 越界档）。块文本（含模板逐字）住 `./audit-block.mjs`（D23-3 外提）。
   if (engAuditAttempt !== null) spawnBlocks.push(buildAuditBlock(ctx))
+  // §6.26「写域行（S4）」：`files`（本 spawn 的预期写域，`prepareScheduling` 已归一化）非空 ⇒ 追加
+  // 一格——写域此前只有调度器知道，子代理只能猜自己的改动面；空 / 未传 ⇒ 不推块，system 逐字节同改前。
+  if (files.length > 0) spawnBlocks.push(filesBlockOf(files))
   // The child's own task input rides the child object: D23-6 —— `_engTaskInput` 语义 = **一行机械
   // 任务书行**（批档绝对路径 + §2 指向句；不含固块）。
   if (engineeringRole) child._engTaskInput = input

package/agent-tools/subagent.mjs

@@ -121,7 +121,9 @@ export function buildSyncStoppedReport(role, capturedOutput, designId) {
  *   (suitable for codebase exploration); "coder" — full tool set, self-contained
  *   implementation tasks; "plan" — read-only planning; "eng-coder" —
  *   engineering-mode implementation (design-token gated); "eng-designer" —
- *   engineering-mode design writing (requirements + design docs, batchDoc gated).
+ *   engineering-mode design writing (requirements + design docs, batchDoc gated);
+ *   "tester" — verification runs and readings (read-only set ∪ execute/bash; no write tool in the table —
+ *   run-only is the role contract, not a sandbox).
  * - no role specified — invalid by design since the 2026-08-25 fail-closed gate
  *   (role is mandatory; "no role → same tool set as parent" was removed with the
  *   coder-leak fix and the header text above predates it)
@@ -139,22 +141,22 @@ export const subagentTool = {
       action: { type: "string", enum: ["spawn", "status", "escalate", "cancel", "panel", "consume-design", "observe", "send", "design-slots"], description: "Which action — spawn (default) / status / observe / send / escalate / cancel / panel / consume-design / design-slots; 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; 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: "For action:'spawn': normal-mode roles (explore/plan/coder) — OPTIONAL free-text supplement; the brief itself is the four core parameters (goal / knownFacts / acceptance / reportFormat) + scope. Engineering roles (eng-coder / eng-designer) take NO task-book text parameters — their task book is batch record §2 (batchDoc), read by the child itself. For action:'escalate': the brief (goal, constraints, entry files, acceptance criteria)." },
-      context: { type: "string", description: "Optional background for normal-mode spawns (explore/plan/coder) only; 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)." },
+      task: { type: "string", description: "For action:'spawn': non-engineering roles (explore / plan / coder / tester) — OPTIONAL free-text supplement; the brief itself is the four core parameters (goal / knownFacts / acceptance / reportFormat) + scope. Engineering roles (eng-coder / eng-designer) take NO task-book text parameters — their task book is batch record §2 (batchDoc), read by the child itself. For action:'escalate': the brief (goal, constraints, entry files, acceptance criteria)." },
+      context: { type: "string", description: "Optional background for non-engineering spawns (explore / plan / coder / tester) only; action:'spawn' only." },
+      role: { type: "string", enum: ["explore", "plan", "coder", "eng-coder", "eng-designer", "tester"], 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 for role='eng-coder': the exact token issued by advisor(type='design') after the review passed — copy it verbatim from the design-slots row (the text after designToken=). missing or mismatched = the spawn is refused; an expired token is refused with expired named. Pass it on every eng-coder spawn, fix rounds included (they reuse the same token)." },
       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 single-slot selector (required to pick between several; the gate refuses to guess); see designIds / expired / olderThanDays for batch consumption. action:'design-slots': filter the inventory to one slot (trimmed exact match; an empty string means no filter; an unknown id is refused with the held id list)." },
       designIds: { type: "array", items: { type: "string" }, description: "action:'consume-design' (batch): an explicit non-empty list of design ids to close out — pass exactly ONE selector per call (designId / designIds / expired / olderThanDays)." },
       expired: { type: "boolean", description: "action:'consume-design' (batch): true = close out every expired slot (exactly ONE selector per call)." },
       olderThanDays: { type: "number", description: "action:'consume-design' (batch): close out every slot older than N days (age > N; exactly ONE selector per call)." },
-      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. This IS the task book for engineering roles — batch record §2, read by the child itself. Refused when absent or when the path does not resolve to a readable file; the content is never validated. role='coder' (normal mode): optional — binds this spawn's §5 record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file." },
+      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. This IS the task book for engineering roles — batch record §2, read by the child itself. Refused when absent, when the path does not resolve to a readable file, or when that record already has an in-flight spawn — one batch record serves one concurrent spawn: wait for the occupant to settle (or cancel it) before spawning again. The content is never validated. role='coder' (normal mode): optional — binds this spawn's §5 record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file." },
       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." },
-      goal: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder' (normal-mode task book): the task book's goal & why — the problem this solves and the cost chain (content only, no label — the runtime composes the labels)." },
-      knownFacts: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder' (normal-mode task book): the facts and file paths the parent already verified — the child must not re-explore them." },
-      scope: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder' (normal-mode task book, the fifth parameter): scope & forbidden scope — what to read / search and what not to touch." },
-      acceptance: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder' (normal-mode task book): acceptance criteria — machine-verifiable (commands / thresholds / assertion counts)." },
-      reportFormat: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder' (normal-mode task book): the delivery-report format the child must produce." },
+      goal: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder'/'tester' (non-engineering task book): the task book's goal & why — the problem this solves and the cost chain (content only, no label — the runtime composes the labels)." },
+      knownFacts: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder'/'tester' (non-engineering task book): the facts and file paths the parent already verified — the child must not re-explore them." },
+      scope: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder'/'tester' (non-engineering task book, the fifth parameter): scope & forbidden scope — what to read / search and what not to touch." },
+      acceptance: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder'/'tester' (non-engineering task book): acceptance criteria — machine-verifiable (commands / thresholds / assertion counts)." },
+      reportFormat: { type: "string", description: "REQUIRED for role='explore'/'plan'/'coder'/'tester' (non-engineering task book): the delivery-report format the child must produce." },
       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." },
       dependsOn: { type: "array", items: { type: "string" }, description: "action:'spawn' only: ids from prior async returns whose outcome this task needs — queues until every dependency settles, then starts. Consumed ids count as satisfied; a cancelled/failed dependency stays queued marked 'dependency cancelled' until you decide (AUTO sessions auto-start). Unknown ids error." },
@@ -225,7 +227,7 @@ export const subagentTool = {
     // 工程角色 = 无任务书文本参数（任务书 = 批次档 §2）：此处不判——自由文本键由
     // buildSpawnChild 的任务书门键在场即拒并点名（空集拼装不得误报「缺任务书」）。
     if (!isEngineeringRole(args.role) && !composeTaskBookBrief(args, args.role) && (typeof args.task !== "string" || !args.task.trim())) {
-      throw new Error("subagent action:'spawn' requires the structured task-book parameters for normal-mode roles (four core: goal / knownFacts / acceptance / reportFormat + scope) — a free-text task alone is not the brief. Engineering roles take no task-book text parameters: their task book is batch record §2.")
+      throw new Error("subagent action:'spawn' requires the structured task-book parameters for non-engineering roles (explore / plan / coder / tester) (four core: goal / knownFacts / acceptance / reportFormat + scope) — a free-text task alone is not the brief. Engineering roles take no task-book text parameters: their task book is batch record §2.")
     }
     // §18 D-E1a depth-gated async default (2026-09-06 需求池 R12): depth-0 spawns
     // default to async for EVERY role (the old role-level default — eng-coder only —
@@ -238,9 +240,9 @@ export const subagentTool = {
     // variant roles ("Coder", " coder") bypass BOTH mode gates and fall through to
     // full tools / no overlay — a full-write coder without design review. Schema enums are
     // advisory; providers don't enforce them. Fail closed on unknown roles.
-    const ROLES = new Set(["explore", "plan", "coder", "eng-coder", "eng-designer"])
+    const ROLES = new Set(["explore", "plan", "coder", "eng-coder", "eng-designer", "tester"])
     if (!ROLES.has(role)) {
-      throw new Error(`Unknown subagent role: ${JSON.stringify(role)}. Valid roles: explore, plan, coder, eng-coder, eng-designer (exact spelling).`)
+      throw new Error(`Unknown subagent role: ${JSON.stringify(role)}. Valid roles: explore, plan, coder, eng-coder, eng-designer, tester (exact spelling).`)
     }
     // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E3 internal-spawn gate: an eng-coder sub-agent may only spawn sync
     // explore (audit) children — non-explore roles and async are refused here
@@ -254,7 +256,7 @@ export const subagentTool = {
     throw new Error("Engineering mode: role='coder' is disabled — use role='eng-coder' for implementation tasks (or role='eng-designer' for design writing).")
   }
   if (parent.config?.agent?.engineering && role === "plan") {
-    throw new Error("Engineering mode: role='plan' is disabled — the engineering-mode enum is explore / eng-designer / eng-coder (plan is a normal-mode role).")
+    throw new Error("Engineering mode: role='plan' is disabled — the engineering-mode enum is explore / eng-designer / eng-coder / tester (plan is a normal-mode role).")
   }
     if (!parent.config?.agent?.engineering && role === "eng-coder") {
       throw new Error("Engineering mode is not active — use role='coder' for implementation tasks.")

package/agent.mjs

@@ -73,6 +73,7 @@ export function createAgent({
     _pendingTimers: [],
     _sessionStart: sessionStart,
     _lastPromptTokens: null, _usageAtLen: null,
+    _tok: null, _tokRatio: 1, // §6.17 估算自校准池化比（{key,num,den}；采样 = turn-loop，清空 = /new）
     _compressFailures: 0,
     _emptyRetries: 0, // empty-response retry budget (per-run; reset on a fresh user turn)
     _runStartHistoryLen: 0, // machine-line length at the start of the current run — end-of-run exploration distillation slices from here

package/client-identity.mjs

@@ -0,0 +1,70 @@
+/**
+ * client-identity.mjs — 客户端标识单源（产品名 ∥ 端类型 ∥ 版本）——PROVIDER.md §6.17
+ *   「客户端标识头（`User-Agent`）」。
+ *
+ * 核件**不猜自己在哪个端**：不读 `process.argv` ∥ 环境变量 ∥ 任何 `package.json`。四端（cli ∥ vscode ∥
+ * desktop ∥ server）各在进程内 `setClientIdentity` 一次（前三端 = 启动期求值；server = 核装载成功处——
+ * 无核即无模型请求）；无人声明 ⇒ 哨兵 `core/0.0.0`（真实端版本恒不等于 `0.0.0`——四端进程内出现即声明漏了）。
+ *
+ * `withUserAgent` 是全部装配点的唯一入口：**先删任何大小写变体的 `user-agent` 键**，再写本产品值——
+ * 渠道配置 `providers[].headers` 因此盖不掉它（`fetch` 的 `Headers` 对大小写变体同名键是合并语义，
+ * 只靠「后写覆盖」会得 `evil, ThinCoder/…` 双值）。
+ *
+ * 同一入口也是定制头值位模板 `${sessionId}` 的解析单源（PROVIDER.md §6.17「会话标识头」）：
+ * **每次请求现取** `getSessionId()`，值不冻结进 provider 对象；只有声明该模板的渠道才发对应的头。
+ */
+
+import { getSessionId } from "./session-identity.mjs"
+
+/** 可声明的端 = 既有端名（单源 = 端名声明 `session-slots.mjs`），统一小写。`core` 不在其中——
+ *  它是「无人声明」的哨兵面，不是可声明的端。 */
+const SURFACES = Object.freeze(["cli", "vscode", "desktop", "server"])
+
+/** 进程级单值（初值 = 哨兵；见档头注）。 */
+let identity = { surface: "core", version: "0.0.0" }
+
+/** 会话标识头的值位变量（PROVIDER.md §6.17）：定制头值里的 `${sessionId}` 于每次请求装配时替换为
+ *  本进程会话 id。只认这一个固定串——别的 `${…}` 不是变量，不加变量词表。 */
+const SESSION_REF = "${sessionId}"
+
+/** 声明本进程的客户端标识（端壳在进程启动期一次）。两个入参都在声明点校验——场景 = 端接线笔误
+ *  （surface 写错字面 / 漏传 version），抛在启动期求值处，不进生产请求（落哨兵或 `undefined`
+ *  会把笔误永久藏成「编程调用」与「版本未知」）。 */
+export function setClientIdentity({ surface, version } = {}) {
+  if (!SURFACES.includes(surface)) {
+    throw new Error(`setClientIdentity: unknown surface "${surface}" — expected one of: ${SURFACES.join(" | ")}`)
+  }
+  if (typeof version !== "string" || version.trim() === "") {
+    throw new Error(`setClientIdentity: missing version for surface "${surface}" — expected the end's package.json version string`)
+  }
+  identity = { surface, version }
+}
+
+/** 当前标识（副本——调用方零共享可变态）。 */
+export function clientIdentity() {
+  return { ...identity }
+}
+
+/** 产品标识头值：`ThinCoder/<surface>/<version>`（三段固定——首段按产品名精确匹配即可聚合）。 */
+export function userAgent() {
+  return `ThinCoder/${identity.surface}/${identity.version}`
+}
+
+/** 值位模板解析（单串精确替换）：整值与内嵌同解、可多处。"${sessionId}" 之外的 `${…}` 按构造原样
+ *  出站——不做变量识别，故没有「识别失败」这一支、也没有兜底路径（写法笔误出站就是该字面）。
+ *  非字符串值原样通过（同 `env-ref.mjs:29` 的类型门；配置链路经装载面净化只到字符串值，该门只兜
+ *  直接调本函数的面：单测 ∥ 编程调用）。 */
+function resolveSessionRefs(value) {
+  return typeof value === "string" ? value.replaceAll(SESSION_REF, getSessionId()) : value
+}
+
+/** 装配面入口：① 解析值位模板 `${sessionId}` → ② **删任何大小写变体的 `user-agent` 键** →
+ *  ③ 写本产品值。消费形态 = 各 transport 的 header 对象内联展开：
+ *  `{ ...withUserAgent(provider.headers), ...内置头 }`。 */
+export function withUserAgent(headers = {}) {
+  const out = {}
+  for (const [key, value] of Object.entries(headers ?? {})) out[key] = resolveSessionRefs(value)
+  for (const key of Object.keys(out)) if (key.toLowerCase() === "user-agent") delete out[key]
+  out["User-Agent"] = userAgent()
+  return out
+}

package/config-presets.mjs

@@ -51,9 +51,11 @@ export const PROVIDER_PRESETS = {
   // `/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", 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", format: "anthropic", maxTokens: 65536, desc: "OpenCode Go — Anthropic Messages side (same sk- key as opencode-go; MiniMax/Qwen models)" },
+  // `x-opencode-session` 头 = **必需**（不带 ⇒ 上游回 `HTTP 400 {"type":"MissingSessionID"}`——实测见
+  // PROVIDER.md §6.17）；值形 = 模板 `${sessionId}`，每次请求现取本进程会话 id（解析单源 = `withUserAgent`）。
+  // 两条预设都携缺省值：新装即带上，用户无需手改配置；不声明该头的其它渠道出站头零变化。
+  "opencode-go": { baseURL: "https://opencode.ai/zen/go/v1", headers: { "x-opencode-session": "thincoder-${sessionId}" }, 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", format: "anthropic", maxTokens: 65536, headers: { "x-opencode-session": "thincoder-${sessionId}" }, 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

@@ -46,11 +46,11 @@ import { positiveInt, warnContextOnce } from "./model-context.mjs"
 // Window utilization ratio (CONTEXT-COMPACTION.md §6.2 / D-CC30 / §6.17 / D-CC32): auto threshold =
 // min(usableWindow(window, reserve), ⌊window × COMPACT_RATIO⌋) — reserve is the output budget
 // ACTUALLY sent as max_tokens (uncapped; §6.17 requestBudget is the single source). Rows with
-// reserve ≤ 20% of the window land on the ratio term; larger reservations pull the line down to
-// window − reserve — overflow-free outranks the 75–80% band (mathematically exclusive there, §6.2).
-// Headroom above the line absorbs injected context (directory tree, git context, outline, project
-// instructions, memory/doc search results — 30–50K tokens per turn).
-const COMPACT_RATIO = 0.8
+// reserve < 40% of the window land on the ratio term (line = 60.0% of the window); larger
+// reservations pull the line down to window − reserve — overflow-free outranks the ratio (the two
+// are mathematically exclusive once reserve ≥ 40%, §6.2). Headroom above the line absorbs injected
+// context (directory tree, git context, outline, project instructions, memory/doc search — 30–50K).
+const COMPACT_RATIO = 0.6
 
 /** Output reservation counted against the window: the value ACTUALLY sent as max_tokens —
  *  explicit `provider.maxTokens` when set (the transport faces send it verbatim), else the spec
@@ -64,9 +64,9 @@ export function outputReserve(provider, spec) {
 }
 
 /** Usable input window = window − output reservation. Degenerate guard: a reservation
- *  ≥ the window is non-physical (no input could ever fit — e.g. the doubao spec
- *  `maxOutput` 524_288 > `context` 256_000 ∥ the test harness&apos;s 1K window vs the default
- *  spec); collapsing the budget to 0 would be instant `context_limit` death — the very
+ *  ≥ the window is non-physical (no input could ever fit — e.g. `doubao-seed-2-1-turbo-260628`:
+ *  256_000 window / 256_000 `maxOutput` (官方口径) ∥ the test harness&apos;s 1K window vs the
+ *  default spec); collapsing the budget to 0 would be instant `context_limit` death — the very
  *  failure the reservation fold exists to prevent. Fall back to half the window.
  *  (2026-10-06——收口核验捕获：advisor-loop-split B5a 红。） */
 export function usableWindow(context, reserve) {
@@ -93,7 +93,10 @@ export function usableWindow(context, reserve) {
  *  - usable: usableWindow(window, reserve) (degenerate half-window guard).
  *  - threshold: min(usable, ⌊window × COMPACT_RATIO⌋) — the compaction trigger line.
  *  - limit: window − reserve — hard prompt ceiling; the guard's ONLY numeric criterion field
- *    (always a number; negative = any prompt overflows). */
+ *    (always a number; negative = any prompt overflows). `absent` rows (the transport sends no
+ *    max_tokens) take the floor max(window − reserve, threshold): only the degenerate
+ *    reserve ≥ window rows move (bare value 0 ⇒ every prompt would be rejected), and for
+ *    reserve < window threshold ≤ usable = window − reserve makes the floor a no-op. */
 export function requestBudget(provider, spec) {
   // windowSource = 五级链的同一次遍历出口（§6.15）——L1 / L3 命中也会如实报来源，不再二值猜。
   // 调用方传 spec（core.mjs 已算过 providerSpec）时窗口值用它，来源仍读 resolution（恒等映射，不并类）。
@@ -108,15 +111,18 @@ export function requestBudget(provider, spec) {
   const maxTokensSource = explicit != null ? "explicit" : anthropicAlwaysSends ? "spec" : "absent"
   const reserve = maxTokens ?? resolved?.maxOutput ?? 0
   const usable = usableWindow(window, reserve)
+  const threshold = Math.min(usable, Math.floor(window * COMPACT_RATIO))
+  const bare = window - reserve
   return {
-    window, windowSource, maxTokens, maxTokensSource, reserve, usable,
-    threshold: Math.min(usable, Math.floor(window * COMPACT_RATIO)),
-    limit: window - reserve,
+    window, windowSource, maxTokens, maxTokensSource, reserve, usable, threshold,
+    // §6.17 地板：absent 档 reserve 可能 ≥ window（退化行，bare ≤ 0）——裸式下任何 prompt 都判真、
+    // 该档永久发不出去；地板把它抬到 ≤ ⌊w/2⌋。非 absent 档逐位不变（仍是 bare）。
+    limit: maxTokensSource === "absent" ? Math.max(bare, threshold) : bare,
   }
 }
 
 /** Derive compaction threshold; explicit is the value explicitly set in config file (takes priority),
- *  otherwise auto = requestBudget().threshold (§6.17 single source — min(usable, ⌊window × 0.8⌋),
+ *  otherwise auto = requestBudget().threshold (§6.17 single source — min(usable, ⌊window × 0.6⌋),
  *  reserve uncapped). Second param accepts EITHER a model name string (pure spec lookup — compat shape,
  *  no caller passes a string today) OR a provider object (providerSpec — the providers[].context
  *  override in K units is honored, PROVIDER.md §15 T-C2). */

package/context.mjs

@@ -13,7 +13,7 @@
 
 import { chat } from "./provider/index.mjs"
 import { buildCompressMessages } from "./compress-form.mjs"
-import { contextUsage, estimateTokens, keepTailSize, splitHistory, tailBudgetTokens } from "./token-window.mjs"
+import { contextUsage, estimateTokens, keepTailSize, splitHistory, SUMMARY_TOKEN_ESTIMATE, tailBudgetTokens } from "./token-window.mjs"
 import { COMPACTION_PLACEHOLDER, withPlaceholderPrefix } from "./context-echo.mjs"
 import { shrinkOversized } from "./context-degrade.mjs"
 
@@ -36,6 +36,18 @@ const COMPACTION_PREFIX =
   "Treat it as notes, not proof — trust its conclusions (don't redo what it reports as done) " +
   "but re-verify transient state with tools. Check memory search for any missing decisions.]\n\n"
 
+/**
+ * 注记 + 占位的估算（§6.17 可达性门的 `note` 项）：摘要正文取 `SUMMARY_TOKEN_ESTIMATE`（§6.9 的 ~1K 目标，常量单源 =
+ * `token-window.mjs`），注记前缀与占位句按 §6.3 估算式（`estimateTokens` 走同一 `estimateText`）——零新常数、零新算式。
+ * 残余方向：真实摘要超 1K 时本值低估 `post`（门可能放行一次压不到线下的压缩），不会反向误拦——守卫面仍抛三实数。
+ * 另：`applyCompression` 压完还会追加任务表回注与 plan 提醒（`agent.tasks` / `planMode` 非空时），本值同样不含——
+ * 同向低估（大任务表会话里 `post` 偏小），不会把本该压的格拦下。
+ */
+const NOTE_ESTIMATE = SUMMARY_TOKEN_ESTIMATE + estimateTokens([
+  { role: "user", content: COMPACTION_PREFIX },
+  { role: "assistant", content: COMPACTION_PLACEHOLDER },
+])
+
 /** After this many consecutive compaction summary failures, degrade to deterministic truncation (losing info is better than task-killing 400 errors) */
 export const COMPRESS_FAILURE_LIMIT = 3
 
@@ -150,7 +162,22 @@ function applyCompression(agent, headEnd, tailStart, note) {
 }
 
 /**
- * If history exceeds threshold, compact it. Returns whether compaction happened.
+ * 可达性门（CONTEXT-COMPACTION.md §6.17「压缩触发判据（可达性门）」）：压完之后 `total` 能不能落到阈值之下。
+ * `post` 按 `applyCompression` 实际留下的形态估——head（KEEP_HEAD = 0 ⇒ 恒空）+ 注记 + 占位 + tail；`middle` = 本次会摘掉的
+ * 那段（与本次压缩同一次 `splitHistory` 产出）。压缩后 `_lastPromptTokens` 失效 ⇒ 只有估算支可比，故走 estimated 支并乘同一
+ * `_tokRatio`（与 `contextUsage` 的估算支同尺）。
+ * 为什么要有它：`system + tools` 是固定开销、压不掉，把它算进判据左侧会让「固定开销本身逼近阈值」的会话反复触发压缩却压不出
+ * 任何东西——每触发一次白付一次摘要请求（台账 `#1833`）。
+ */
+function postCompactionTotal(agent, usage, middle) {
+  const ratio = agent?._tokRatio ?? 1
+  return Math.round((usage.history - estimateTokens(middle) + NOTE_ESTIMATE + usage.overhead) * ratio)
+}
+
+/**
+ * Compact when the prompt is over the threshold AND compaction can actually get back under it
+ * (CONTEXT-COMPACTION.md §6.17 reachability gate); `extras.force` skips both early-exit criteria.
+ * Returns whether compaction happened.
  * Only called at safe points in the loop (history ends with user or tool message — a complete exchange boundary).
  * Automatically re-injects task list state after compaction.
  * @param {object} agent
@@ -160,14 +187,14 @@ function applyCompression(agent, headEnd, tailStart, note) {
  *   internal mechanism, not a model reply); onCompressStart fires right before the summary call
  *   (§6.8 D-C1, compression lifecycle visibility — panel start state)
  * @param {object} extras - { systemPrompt?, tools?, force?, focus? } — 固定开销面（system + tools 估计）+
- *   模型主动压缩面（§6.16.2）：`force` **只跳过** `tokens <= threshold` 早退，其余全同；`focus` 追加在摘要指令尾段。
+ *   模型主动压缩面（§6.16.2）：`force` **跳过阈值面的全部早退判据**（`total <= threshold` 与 §6.17 可达性门的
+ *   `post > threshold` 两条），其余全同（同切分 / 同尾部预算 / 同摘要链 / 同回注 / 同基线失效）；`focus` 追加在摘要指令尾段。
  */
 export async function compressIfNeeded(agent, threshold, callbacks, extras = {}, signal) {
   const history = agent.history
-  // 单源（§6.16.4）：total / overhead 与 stats 面同一函数（既有内联式改调 contextUsage，判定语义零改）
+  // 单源（§6.16.4）：total 与 stats 面同一函数（既有内联式改调 contextUsage，判定语义零改）
   const usage = contextUsage(agent, extras)
   const tokens = usage.total
-  const overhead = usage.overhead
   if (!extras.force && tokens <= threshold) return false
 
   const keepTail = keepTailSize(agent.provider, history.length)
@@ -179,6 +206,9 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
   }
 
   const middle = history.slice(split.headEnd, split.tailStart)
+  // 可达性门（§6.17）：压完落不到线下 ⇒ 不压——不为一次没有净减的摘要白付请求。`force` 全文豁免（模型主动压缩 ∥
+  // 守卫强压：模型判定优先于阈值，压后仍超由守卫面抛三实数）。到不了线下的格仍由守卫 `enforceContextFit` 兜住。
+  if (!extras.force && postCompactionTotal(agent, usage, middle) > threshold) return false
 
   // Compression request form v2/v3 (§6.14 / D-CC20): continuation — same system + same tools declaration (the turn's own
   // array) + the middle's verbatim messages + one tail instruction. 首现即复用回合所建前缀 ⟺ 带 tools 声明（无 tool_choice）
@@ -222,11 +252,12 @@ export async function compressIfNeeded(agent, threshold, callbacks, extras = {},
 
   // Completion info for the compression panel (D-C2): tokens freed = the pre-compression prompt
   // estimate (`tokens` — the value that tripped the threshold, incl. system/tools overhead on the
-  // pure-estimation path) minus the post-compression estimate on the same basis. Elapsed = the
-  // summary call + splice duration. agent.mjs forwards this to onCompress unchanged.
+  // pure-estimation path) minus the post-compression estimate on the SAME basis (`contextUsage`
+  // — a bare `estimateTokens` sum would skip the §6.17 `_tokRatio` and overstate the freed tokens).
+  // Elapsed = the summary call + splice duration. agent.mjs forwards this to onCompress unchanged.
   agent._lastCompressInfo = {
     mode: "summary",
-    tokensFreed: Math.max(0, Math.round(tokens - (estimateTokens(agent.history) + overhead))),
+    tokensFreed: Math.max(0, Math.round(tokens - contextUsage(agent, extras).total)),
     elapsedMs: performance.now() - startedAt,
   }
   return true

package/declaration.mjs

@@ -6,7 +6,7 @@
  * 原档 `conventions.mjs` 经 `export { … } from` 转口保名（消费面 / 单元测试档 import 面零改）。
  */
 import { existsSync, readdirSync, statSync } from "node:fs"
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path"
+import { basename, dirname, isAbsolute, join, parse, relative, resolve } from "node:path"
 import { DEFAULT_MANIFEST, MANIFEST_REL, docRootPaths, manifestFilePath, onManifestInit, owningProject, readManifest } from "./manifest.mjs"
 import { isSkippedRelPath } from "./memory/file-walk.mjs" // 面⑦ 子目录扫描的跳过段谓词单源（零环：file-walk 不引本档）
 import { logEvent } from "./log.mjs"
@@ -365,7 +365,7 @@ export function loadProjectDeclaration(cwd) {
  * @returns {Readonly<object>|null} 所属项目的声明对象 / null = 出辖
  */
 export function declarationForTarget(targetAbs) {
-  const root = owningProject(targetAbs)
+  const root = owningProject(targetAbs, parse(targetAbs).root) // 取根面的界 = 目标所在盘根（与 `projectRootView` 同一口径）
   if (!root) return null
   return loadProjectDeclaration(root)
 }