@thincoder/core 0.9.1

package/agent-tools/eng.mjs

@@ -0,0 +1,102 @@
+/**
+ * eng tool: enter/exit engineering mode.
+ * In engineering mode the agent follows design-before-code methodology.
+ * Toggled here at session level (in-memory flag; the session slot is the sole authority —
+ * saveSession round-trips it at turn end; /eng writes the slot directly). The old ctx
+ * state-persist hook was removed 2026-09-08 (ENG-SESSION-PROVIDER-CLEANUP D1.2): no
+ * provider existed and its legacy payload keys were never read by applySession.
+ * R16 (2026-09-06): design tokens are session-level flow credentials — mode toggles
+ * do NOT clear them (ON→OFF keeps, OFF→ON does not require a fresh review); only TTL
+ * expiry cleans tokens, at three points: restore filtering (session.mjs applySession) /
+ * eng enter expired cleanup (below + cmd-eng ON) / spawn-gate expired rejection
+ * (subagent-spawn.mjs). See docs/design/ENG-TOKEN-BINDING-TUNING.md §5/§5.1 (F-R16).
+ * #41（2026-09-18）：enter 分支改「先判后翻」——判据 = 入口决策树单源
+ * `resolveEngineeringManifest`（docs/core/design/MANIFEST.md §2.8 F2 / KD-M1-20/21）；
+ * 拒翻 ⇒ 返回原因串 + **零副作用**（模式保持 OFF）。OFF 方向与幂等 enter 零改。
+ */
+import { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "../agent.mjs"
+import { purgeExpiredDesignTokens } from "../token-ttl.mjs"
+import { resolveEngineeringManifest } from "../manifest.mjs"
+
+// ─── 持久化镜像 / 面板提示注入缝（#91——「写盘镜像 / 面板提示按端注入」，形态参 §2.13.5 注入缝）──
+/**
+ * 工程模式切换通知注入位（**缺省不覆盖** = no-op——CLI 语义（只进会话），零行为变；端装配层
+ * 可覆盖为本端镜像写盘 / 面板提示）。核内零端名分支（契约 5——本档只认 `onToggle` 函数名）。
+ * 契约：`onToggle(enabled, ctx) → string | null | undefined | Promise<同>`——非空字符串 =
+ * 追加到结果文案尾（如镜像写入碰撞提示）；其余值 = 无提示。调用时机 = 状态翻转后（观察新态）。
+ */
+let injectedMirror = null
+export function configureEngMirror(impl) {
+  injectedMirror = impl && typeof impl.onToggle === "function" ? impl : null
+}
+/** 撤销注入（测试与端装配生命周期用——缺省态 = 无镜像 / 无面板提示）。 */
+export function resetEngMirror() { injectedMirror = null }
+
+/** 镜像通知串（缺省空串；仅非空字符串追加）。 */
+async function mirrorNotice(enabled, ctx) {
+  const out = await injectedMirror?.onToggle(enabled, ctx)
+  return typeof out === "string" && out.length > 0 ? ` ${out}` : ""
+}
+
+export const engTool = {
+  name: "eng",
+  description:
+    "Enter or exit engineering mode. In engineering mode, follow design-before-code: write a design document, run advisor design review, get user approval, then implement via eng-coder subagents. " +
+    "Returns the mode state — 'Engineering mode activated/exited' (an already-active state is acknowledged).",
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["enter", "exit"], description: "Enter or exit engineering mode" },
+    },
+    required: ["action"],
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    ctx.agent.config.agent ??= {}
+    if (args.action === "exit") {
+      ctx.agent.config.agent.engineering = false
+      // R16 (F-R16a): OFF 不清 token——有效 token 跨模式存活（设计评审过的产物不因
+      // 开关重复烧）。过期清理跑在另外三处（恢复过滤 / 开模式 / spawn 门禁拒）。
+      ctx.agent._advisorRound = 0          // reset convergence budget
+      ctx.agent._advisorRuns = new Map()   // §11.2 D-24b: per-review instances die with the mode (fresh cycles)
+      ctx.agent._touchedFiles = []         // clear mutation tracking
+      ctx.agent._lastEngState = false
+      ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
+      ctx.agent._pendingReminders.push(ENG_OFF_REMINDER)
+      return "Engineering mode exited. Standard discipline now applies. You may edit files directly." + await mirrorNotice(false, ctx)
+    }
+    if (args.action === "enter") {
+      // Idempotent enter (v2 2026-08-25): already in engineering mode → pure no-op
+      // (cleanup only runs on a real off→on transition — T-R16c precondition: first
+      // exit/OFF, then enter; an already-on enter must not touch tokens at all).
+      if (ctx.agent.config.agent.engineering) {
+        return "Engineering mode already active. Existing design tokens stay valid."
+      }
+      // #41 先判后翻（MANIFEST.md §2.8 F2 / KD-M1-21）：判据 = 入口决策树**单源**
+      // （resolveEngineeringManifest——KD-M1-20），判据通过才写态。拒翻 ⇒ 返回原因串 +
+      // **零副作用**（不清 token / 不重置 _advisorRuns / 不入列 ENG_ON_REMINDER /
+      // 不动 _lastEngState / 不触镜像缝）；准 ⇒ 缺档格就地建档（writer:'main'）+
+      // agent.manifest ← 结果（翻转面唯一赋值点——相位行当回合起活，§2.8 F2 放行行）。
+      const r = resolveEngineeringManifest(ctx.agent.cwd ?? ctx.cwd ?? process.cwd(), { writer: "main" })
+      if (!r.ok) {
+        return `Error: cannot enter engineering mode — ${r.message} (mode unchanged)`
+      }
+      ctx.agent.manifest = r.manifest
+      ctx.agent.config.agent.engineering = true
+      // R16 (F-R16b ②): off→on 不重评——只清过期 token（用户裁定"打开工程模式时
+      // 应该清理"），有效 token 原样保留——遍历 Map 删过期，返回文案含清理个数。
+      const cleared = purgeExpiredDesignTokens(ctx.agent)
+      ctx.agent._advisorRuns = new Map() // §11.2 D-24b: per-review instances die with the mode (fresh cycles)
+      ctx.agent._lastEngState = true
+      ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
+      ctx.agent._pendingReminders.push(ENG_ON_REMINDER)
+      let msg = "Engineering mode activated. Design-before-code enforced: write a design document first (location per your project's document conventions), run advisor with type='design', get user approval, then implement via eng-coder subagents."
+      if (cleared > 0) {
+        msg += ` Cleared ${cleared} expired design token${cleared === 1 ? "" : "s"} — 清 ${cleared} 个过期 token，有效 token 保留（TTL 内不重评）。`
+      }
+      msg += await mirrorNotice(true, ctx)
+      return msg
+    }
+    return "Invalid action: expected 'enter' or 'exit'"
+  },
+}

package/agent-tools/escalate-async.mjs

@@ -0,0 +1,302 @@
+/**
+ * escalate-async.mjs — async 飞刀 runner (AGENT-LOOP.md §25 D-R17b — R17, 2026-09-06).
+ *
+ * The subagent action:"escalate" is DEFAULT-async at depth 0 (decision ③: the
+ * depth-0-only escalate flips to async like every other background family;
+ * `async: false` keeps the legacy synchronous flight). An async escalate runs in
+ * the SHARED "other" pool domain (decision Q2 🅰 — the entry lives in
+ * `_asyncSubagents` with role "escalate"/_pool "other", so it shares the 4-slot
+ * other domain with explore/plan/coder spawns — capacity, queueing, refill,
+ * status and cancel all come from the generic machinery):
+ * - launch → ack {id, role:"escalate", status:"running"|"queued"[, position]};
+ *   the turn ends naturally, the session suspends (poolLive counts the entry).
+ * - settle THREE-WAY classification (review #4): done → merge-all mutations back
+ *   into the parent's bookkeeping + overlap warning appended to the report
+ *   (report-level, not a gate — round2 #4); error (child failure / turn cap) →
+ *   partial mutations merged ONLY when the parent did not touch overlapping
+ *   files since launch (overlap → no merge + differences listed in the report);
+ *   cancelled → never reaches the digest stream (D-M6 — no merge, stopped
+ *   reminder).
+ * - the classified report lands in `_pendingAsyncResults`（pending 单容器 +role——
+ *   ASYNC-RESULT-CONTAINER.md D2——挂起期 settle 移交）when the settle happens in a
+ *   suspension, or stays pooled for the turn-end collection otherwise;
+ *   injectAsyncResult's escalate
+ *   role branch delivers the digest ("报告已 merge——可继续处置" — the action
+ *   domain still follows the consuming turn's tier — no family exception).
+ */
+import { relative, isAbsolute } from "node:path"
+import { runAgent, createAgent, DEFAULT_SUBAGENT_TURNS } from "../agent.mjs"
+import { runWithContinue, TURN_CAP_MARK, wrapChildCallbacks } from "../agent/spawn-child.mjs"
+// TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口常量（单源——store 零依赖）。
+import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
+import { logEvent } from "../log.mjs"
+import { deathLine } from "../abort-provenance.mjs"
+import {
+  mergeChildMutations, runningPoolCount, poolDomainOf, poolLimitsFor, ASYNC_POOL_LIMITS, enqueueAsk,
+} from "./subagent-async.mjs"
+import { refreshQueuedTokens, nextSubagentId, consumeSubagentToken, assertPoolKeyFree } from "./subagent-scheduler.mjs"
+import { mutationSeqOf } from "./advisor-async.mjs"
+// ASYNC-RESULT-CONTAINER.md D3/D6：settle 公共收尾单点 + child signal 构建单点
+import { bindChildController, buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
+
+/** Parent-side mutations (absolute paths) committed AFTER the escalate launch —
+ *  the overlap scan feeds the settle classification (review #4/round2 #4: the
+ *  parent may have edited files while the flight ran). */
+function parentMutationsSince(parent, launchSeq) {
+  const out = []
+  for (const m of parent?._mutLog ?? []) {
+    if (m.seq <= (launchSeq ?? -1)) continue
+    for (const p of m.paths ?? []) if (!out.includes(p)) out.push(p)
+  }
+  return out
+}
+
+/** Files BOTH sides touched since launch (case-insensitive key on win32 —
+ *  filesOverlap precedent). */
+function overlapPaths(parent, launchSeq, childTouched) {
+  const since = parentMutationsSince(parent, launchSeq)
+  if (since.length === 0 || !childTouched?.length) return []
+  const key = (p) => (process.platform === "win32" ? String(p).toLowerCase() : String(p))
+  const sinceKeys = new Set(since.map(key))
+  const hits = childTouched.filter((p) => sinceKeys.has(key(p)))
+  // relative display form (touchedFilesNote precedent)
+  const cwd = parent?.cwd ?? process.cwd()
+  return hits.map((p) => {
+    const r = relative(cwd, p)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : p
+  })
+}
+
+/** Escalate-side touched files, relative display (or a placeholder). */
+function childTouchedDisplay(child, cwd) {
+  const touched = child?._touchedFiles ?? []
+  if (touched.length === 0) return "(none recorded)"
+  const shown = touched.map((f) => {
+    const r = relative(cwd ?? process.cwd(), f)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : f
+  })
+  return shown.join(", ")
+}
+
+/** Relative touched-file list (mirror of the sync path's note). */
+function touchedFilesNote(child, cwd) {
+  const touched = child?._touchedFiles ?? []
+  if (touched.length === 0) return ""
+  const shown = touched.map((f) => {
+    const r = relative(cwd ?? process.cwd(), f)
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : f
+  })
+  return `\nTouched files: ${shown.join(", ")}`
+}
+
+/**
+ * Async escalate settle — three-way classification (§25 D-R17b review #4):
+ *  - done: merge ALL mutations (the escalation's changes are the parent's —
+ *    verify/advisor guards must see them) + overlap warning into the report
+ *    (report-level hint — not a gate — round2 #4);
+ *  - error (child failure / turn cap): partial mutations merge ONLY without a
+ *    parent-side overlap — overlap → NO merge + differences listed (the report
+ *    carries both sides so the model can decide);
+ *  - cancelled: nothing merges, never reaches pending (D-M6 — stopped reminder).
+ * Runs BEFORE the pending transfer / digest injection. Mutates entry.report /
+ * entry.error into the FINAL digest body (the family wording rides
+ * injectAsyncResult's escalate branch).
+ */
+export function classifyEscalateSettle(parent, entry) {
+  if (entry.cancelled) return { cancelled: true }
+  // §23.3.1（TUI-OOM-ROOTCAUSE）——childAgent 语义面：settle 分类（touched 摘要/partial
+  // merge）与 status/observe 摘要的读取源；**消化注入完成后由 `releaseSettledEntry`
+  // （async-settle.mjs）置 null**（池内未消化窗口不释放——表 2 候选 2 否决）。
+  const child = entry.childAgent
+  const touched = child?._touchedFiles ?? []
+  const overlap = overlapPaths(parent, entry.launchSeq, touched)
+  const hasError = entry.error != null
+  const raw = hasError ? entry.error : entry.report
+  if (hasError) {
+    // error branch (child failure / turn cap — review #4): partial mutations
+    // merge ONLY when the parent did not touch overlapping files since launch.
+    // childAgent may be null when the flight died before child creation (advisor
+    // 复评 🟡2——防御：无 child 即无 partial mutations——不 merge 不崩）。
+    const merged = child != null && overlap.length === 0 && mergeChildMutations(parent, child)
+    let decision = ""
+    if (merged) {
+      decision = `\nPartial changes merged into the parent's bookkeeping (no parent-side overlap since launch).`
+    } else if (overlap.length > 0) {
+      decision = `\nPartial changes NOT merged — the parent changed overlapping files while this escalate ran: ${overlap.join(", ")}. Escalate-side changes: ${childTouchedDisplay(child, parent?.cwd)}. Review the conflict and decide what to keep (report-level — not a gate).`
+    }
+    // (nothing to merge + no overlap → the plain error report stands alone)
+    entry.error = `${raw}${decision}`
+    entry.report = null
+    return { cancelled: false, merged, overlap }
+  }
+  // done — merge-all + overlap warning into the report (report-level — not a gate)
+  const merged = mergeChildMutations(parent, child)
+  const overlapNote = overlap.length > 0
+    ? `\n⚠ Overlapping writes: the parent changed ${overlap.join(", ")} while this escalate ran — mutations merged all the same; review those files before building on the report (report-level warning — not a gate).`
+    : ""
+  entry.report = `${raw}${overlapNote}`
+  return { cancelled: false, merged, overlap }
+}
+
+/**
+ * Launch the async escalate (preflights already passed in executeEscalateAction):
+ * pool admission into the shared OTHER domain → entry in `_asyncSubagents`
+ * (generic queue/refill/status/cancel machinery) → ack. The flight starts on
+ * entry.start() (immediately, or later via maybeRefillAsync when a slot frees).
+ */
+export function launchEscalateAsync(parent, ctx, launch) {
+  const { task, provider, tag, effortNote } = launch
+  parent._asyncSubagents ??= new Map()
+  parent._asyncQueue ??= []
+  // Async id allocation (AGENT-LOOP.md §15 D-A1 precedent): reserve the relay
+  // counter at launch — the returned id stays stable while the entry sits queued.
+  // The [model] token (TUI block creation) is DEFERRED to actual start so queued
+  // flights don't paint an empty panel block (subagent-parity).
+  // SUBAGENT-ID-COUNTER-AGENT（2026-09-09）：取号统一走 nextSubagentId（池活续号
+  // 兜底——counter 载体= agent 本体 _subAgentCounter——跨 run/跨压缩存活）。
+  const id = nextSubagentId(parent)
+  // ED-5（AGENT-LOOP-SUBAGENT.md §6.21）一次性取号令牌消费（同步配对——本函数内取号 →
+  // 消费无 await 间隙）；断言通过即置 undefined（防同一令牌跨站点复用）。
+  consumeSubagentToken(parent, id, "escalate launch", "escalate")
+  const relayPrefix = `escalate#${id}/`
+  const entry = {
+    id, role: "escalate", relayPrefix,
+    _pool: poolDomainOf("escalate"), // other — shares the domain with explore/plan/coder (§11.1 D-24a)
+    status: "queued",
+    position: undefined,
+    report: null, error: null, done: false, cancelled: false,
+    promise: null, _settle: null, _settleSeq: 0,
+    model: provider.model ?? null,
+    startedAt: null,
+    turn: 0, maxTurns: 0,
+    controller: null,
+    _files: undefined, _dependsOn: undefined,
+    childAgent: null,
+    tag, effortNote, launchSeq: mutationSeqOf(parent),
+  }
+  const limits = poolLimitsFor(parent)
+  entry.status = runningPoolCount(parent, entry._pool) >= (limits[entry._pool] ?? ASYNC_POOL_LIMITS[entry._pool])
+    ? "queued" : "running"
+  entry.promise = new Promise((res) => { entry._settle = res })
+  const ctrl = new AbortController()
+  entry.controller = ctrl
+  // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md——D5 同款：_sessionSignal 兜底）·
+  // #98 链结单点（interrupt 豁免面——Ctrl+I 不逐链中止池内子代理）。
+  bindChildController(ctrl, buildChildSignal(parent, ctx))
+  // Turn mirror (⟦ev⟧turn from the child runAgent → entry.turn/maxTurns — status parity).
+  const flight = async () => {
+    entry.status = "running"
+    entry.position = undefined
+    entry.startedAt = Date.now()
+    ctx.callbacks?.onToken?.(relayPrefix + "⟦ev⟧async\x1e")
+    ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (provider.model ?? ""))
+    const child = createAgent({
+      provider,
+      tools: parent.tools,
+      config: parent.config,
+      cwd: parent.cwd,
+      memory: parent.memory,
+      // G3（施工②）：overlay 摘除——coder 人格槽由 assemblePrompt 场景表承载（G3 映射）。
+      role: "coder",
+    })
+    entry.childAgent = child // settle 分类/status touched 摘要绑定（start 时刻）
+    child._historyWindow = RECORD_WINDOW_MESSAGES // TUI-OOM-ROOTCAUSE §23.3.1：子代理人读线窗口（四处创建点同置）
+    child._logId = relayPrefix.slice(0, -1)
+    // SUBAGENT-UPSTREAM-CHANNEL（§6.27.4 W3——escalate **async**：工具返回注走异步形）。
+    child._upstream = { parent, label: relayPrefix.slice(0, -1), sync: false }
+    logEvent("child:spawn", { role: "escalate", id: child._logId, kind: "async", status: "running", ms: 0 })
+    const childCallbacks = wrapChildCallbacks(relayPrefix, ctx.callbacks ?? {})
+    const relayOnToken = childCallbacks.onToken
+    if (relayOnToken) {
+      childCallbacks.onToken = (t) => {
+        const ev = String(t).match(/^⟦ev⟧turn\x1e(\d+)\x1e(\d+)\x1e/)
+        if (ev) {
+          entry.turn = Number(ev[1]) || 0
+          entry.maxTurns = Number(ev[2]) || 0
+        }
+        return relayOnToken(t)
+      }
+    }
+    const runner = ctx.runAgent ?? runAgent
+    const runOpts = {
+      depth: 1,
+      maxTurns: parent.config?.agent?.subagentTurns ?? DEFAULT_SUBAGENT_TURNS,
+      signal: entry.controller.signal,
+      // §2.5 #78 并入：escalate 子代理输出流式（VSC subagent-escalate-async 同款豁免）。
+      streamOutput: true,
+    }
+    // 权限按 async 子代理同款装配：AUTO 直放行；手动档经父 _permQueue（并行子代理
+    // 审批不叠弹窗）——背景飞行撞门时无 handler → denied 不悬挂（D-S7 同规则）。
+    const childPermission = parent.autoApprove
+      ? async () => true
+      : async (name, toolArgs) => {
+          if (!ctx.onPermissionRequest) return false
+          // 残环批（2026-09-16）：询问名携归属键（`escalate#<id>/<tool>`——端侧键形解析的
+          // 输入契约；原裸 `escalate/${tool}` 无 id ⇒ 并行条目归属歧义）
+          const ask = () => ctx.onPermissionRequest(`${entry.relayPrefix.slice(0, -1)}/${name}`, toolArgs)
+          return enqueueAsk(parent, "_permQueue", ask)
+        }
+    const report = await runWithContinue(
+      (childAgent, input, cbs, opts) => runner(childAgent, input, cbs, opts),
+      child, task,
+      { ...childCallbacks, onPermissionRequest: childPermission },
+      runOpts,
+      {
+        // 后台飞行不弹 continue 面板（D-A3 §15 例外同款）：AUTO && engineering 自动
+        // resume——escalate 只在 normal 模式可用（engineering 拒）——恒自动拒 → partial。
+        askContinue: () => Promise.resolve(Boolean(parent.config?.agent?.engineering && parent.autoApprove)),
+        onDeclined: (e, output) => `escalate (${tag})${entry.effortNote} ${TURN_CAP_MARK} (${e.turn} turns) — work may be partial; review recent_changes before deciding next steps.\nPartial output: ${output.slice(0, 2000)}`,
+      },
+    )
+    // done: compose the post-op body (the settle classification appends the
+    // overlap warning / merge notes afterwards)
+    return `escalate (${tag})${entry.effortNote} post-op report:\n${report || (child._capturedOutput ?? "").slice(0, 4000)}${touchedFilesNote(child, parent.cwd)}`
+  }
+  entry.start = () => {
+    flight()
+      .then((report) => {
+        // Turn-cap partial (runWithContinue auto-declined) classifies as the ERROR
+        // branch (design: 撞 turn cap = error — partial-merge decision applies):
+        // move it to entry.error so the classification + error digest wording fire.
+        if (String(report).includes(TURN_CAP_MARK)) entry.error = report
+        else entry.report = report
+      })
+      .catch((e) => {
+        // 运行失败/中止：错误文本落 entry.error（子代理同款——cancel 分支忽略它；
+        // Ctrl+I 中止的残条目由收尾消化带错误文本——不落空 "(no report)" digest）。
+        const child = entry.childAgent
+        // §20.3 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
+        entry.error = `escalate (${tag}) error: ${deathLine(e, entry.controller?.signal)}\nPartial output: ${(child?._capturedOutput ?? "").slice(0, 2000)}`
+      })
+      .finally(() => {
+        // settle 公共收尾单点（ASYNC-RESULT-CONTAINER.md D3——settleAsyncEntry）：日志三连
+        // /cancelled 分支（出池+墓碑+⟦ev⟧stopped+提醒）/挂起分流（pending 单容器+出池——
+        // 统一守卫 !parentAborted——D4）/公共尾部（settleSeq/_settle/唤醒 waiter + 腾槽补位
+        // ——helper 尾部恒补）统一走共享 helper。族特有 hook = 三分类 merge 决策
+        // （classifyEscalateSettle——done/error 分类；cancelled 不经此——helper cancelled
+        // 分支先行）。
+        settleAsyncEntry(parent, entry, {
+          pool: parent._asyncSubagents,
+          ctx,
+          onAccounting: () => {
+            // Three-way settle classification (done/error/cancelled — review #4)：
+            // done → merge-all + 重叠警告；error → 无父侧重叠才 partial merge；
+            // cancelled 不经此（helper cancelled 分支先行）。
+            void classifyEscalateSettle(parent, entry)
+          },
+        })
+      })
+  }
+  // ED-5（§6.21）入池键守卫：同 id 二次入池 = 覆写（静默丢报告 + status/cancel 错址）⇒ 抛错。
+  assertPoolKeyFree(parent._asyncSubagents, id, "escalate")
+  parent._asyncSubagents.set(String(id), entry)
+  logEvent("child:spawn", { role: "escalate", id: `escalate#${id}`, kind: "async", status: entry.status, ms: 0 })
+  if (entry.status === "queued") {
+    parent._asyncQueue.push(entry)
+    entry.position = parent._asyncQueue.length
+    refreshQueuedTokens(parent, ctx.callbacks?.onToken)
+    return JSON.stringify({ id: String(id), role: "escalate", status: "queued", position: entry.position })
+  }
+  entry.start()
+  return JSON.stringify({ id: String(id), role: "escalate", status: "running" })
+}

package/agent-tools/goal.mjs

@@ -0,0 +1,119 @@
+/**
+ * goal tool: lifecycle management for long-running autonomous goals (completion contract).
+ * Three states: active / complete / blocked. Completion must pass a verify evidence threshold;
+ * blocked is only accepted after the same condition persists 3 consecutive times.
+ * The system injects status + budget progress + audit discipline every turn.
+ */
+export const goalTool = {
+  name: "goal",
+  description:
+    "Manage a long-running autonomous goal. " +
+    "action='set': create or replace the goal — must have a verifiable completion criterion (a machine-checkable proof, not vague effort). " +
+    "action='complete': mark achieved — only after the criterion's check has actually passed. " +
+    "action='blocked': report an impasse (requires 'reason') — only after 3 genuine attempts. " +
+    "action='cancel': abandon the goal. " +
+    "Returns a status line — the goal set/updated/completed/blocked/cancelled confirmation, or Error: ... with the reason.",
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["set", "complete", "blocked", "cancel"], description: "Goal lifecycle action" },
+      objective: { type: "string", description: "What you are trying to accomplish (for 'set')" },
+      criteria: { type: "string", description: "How completion is PROVEN: the exact check to run, e.g. 'npm test passes', 'grep finds no TODO marker' (required for 'set')" },
+      reason: { type: "string", description: "The blocking condition (required for 'blocked')" },
+    },
+    required: ["action"],
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    const agent = ctx.agent
+    if (args.action === "cancel") {
+      agent.goal = null
+      return "Goal cancelled. If the goal was blocked or impossible, explain why in your next message — the user can clarify, adjust scope, or confirm cancellation."
+    }
+    if (args.action === "set") {
+      if (!args.objective) return "Error: 'objective' required for 'set' action."
+      if (!args.criteria) {
+        return "Error: 'criteria' required for 'set' — a goal without a machine-checkable proof of completion is a wish, not a goal. Name the exact check (tests, command output, search result) that proves it's done."
+      }
+      agent.goal = {
+        objective: String(args.objective).slice(0, 500),
+        criteria: String(args.criteria).slice(0, 500),
+        setAt: Date.now(),
+        status: "active",
+        turnsUsed: 0,
+        _blockTally: null, // { reason, count } — consecutive count of the same blocking condition (for blocked audit)
+      }
+      return `Goal set: ${agent.goal.objective}\nDone when: ${agent.goal.criteria}\nThe system will inject goal status every turn. Completion and blocked claims are audited — see the reminders.`
+    }
+    if (!agent.goal || agent.goal.status !== "active") {
+      return `Error: no active goal to '${args.action}' (current: ${agent.goal?.status ?? "none"}). Set one first.`
+    }
+    if (args.action === "complete") {
+      // Evidence chain threshold: files were mutated this run without verify — refuse completion (aligns with completion guard)
+      if (agent._mutatedThisRun && !agent._verifiedThisRun) {
+        return "Error: files were modified but verify has not run. Run the check your criteria names AND the verify tool before marking the goal complete — false completion is the worst outcome of autonomous work."
+      }
+
+      // Independent judge: verify the goal was actually achieved
+      // Only applies when the agent is at depth 0 (not a subagent) and has history to review
+      if (ctx.depth === 0 && agent.history.length > 2) {
+        try {
+          // Extract recent activity: last 4 assistant messages (summarizing what was done)
+          const recent = agent.history.filter(m => m.role === "assistant").slice(-4)
+          const activity = recent.map(m => (m.content ?? "").slice(0, 500)).join("\n---\n")
+          const { chat } = await import("../provider/index.mjs")
+          const judgeRes = await chat(agent.provider, {
+            messages: [{
+              role: "user",
+              content: `You are an independent goal judge. Evaluate whether this goal has been achieved based on the agent's activity.
+
+Goal: ${agent.goal.objective}
+Success criteria: ${agent.goal.criteria}
+
+Recent agent activity:
+${activity || "(no activity recorded)"}
+
+Has this goal been achieved? Answer ONLY "YES" or "NO" followed by a one-sentence reason.`,
+            }],
+            tools: [],
+            signal: AbortSignal.timeout(10_000),
+            // §18.6 D-TR4/D-TR6（2026-09-04 fix round1）：goal 独立评审调用经 chat()
+            // 唯一采集点——补轨迹元数据 + traces 开关透传（agent.config.traces.enabled
+            // ——关=不落盘必须全覆盖——与 agent.mjs/context.mjs 同模式）
+            logCtx: {
+              stage: "goal", kind: "goal",
+              role: agent._role ?? null, depth: ctx.depth,
+              session: agent._sessionStart ?? null, cwd: agent.cwd,
+              traces: agent.config?.traces?.enabled !== false,
+            },
+          })
+          const verdict = (judgeRes.content ?? "").trim()
+          if (verdict.toUpperCase().startsWith("NO")) {
+            return `Goal NOT complete (judge says NO): ${verdict.slice(2).trim()}\n\nContinue working or report blocked if this is a true impasse.`
+          }
+          if (!verdict.toUpperCase().startsWith("YES")) {
+            return `Goal completion unverified — judge response ambiguous: "${verdict.slice(0, 200)}". Re-check your criteria and try again with clear evidence.`
+          }
+        } catch {
+          // Judge unavailable — allow completion but note it
+        }
+      }
+
+      agent.goal.status = "complete"
+      return `Goal verified complete ✓: ${agent.goal.objective}\nIn your next message, summarize the evidence (what check ran, what it showed) — the user should be able to audit this claim.`
+    }
+    if (args.action === "blocked") {
+      if (!args.reason) return "Error: 'reason' required for 'blocked' action."
+      // Blocked audit: same condition must appear 3 consecutive times (only counts as real blocking if different approaches still hit the same wall)
+      const tally = agent.goal._blockTally
+      const count = tally?.reason === args.reason ? tally.count + 1 : 1
+      agent.goal._blockTally = { reason: args.reason, count }
+      if (count < 3) {
+        return `Blocked not accepted yet (${count}/3 for this condition). Try a genuinely different approach first; report blocked only if the same condition stops you ${3 - count} more time(s).`
+      }
+      agent.goal.status = "blocked"
+      return `Goal marked blocked after 3 attempts: ${args.reason}\nExplain the blocker to the user in your next message — what you tried, and what you need (clarification, permission, a decision).`
+    }
+    return `Error: unknown action '${args.action}'.`
+  },
+}

package/agent-tools/panel-blocks.mjs

@@ -0,0 +1,24 @@
+/**
+ * panel-blocks.mjs — §19.6 D-P1 面板块列表（读时现算，纯函数）。
+ *
+ * 来源 = `thincoder-cli/src/tui/subagent-freeze.mjs` 的 `computePanelBlocks`——**逐字随迁**
+ * （CORE-UNIFICATION §2.5 #159：`panel` 动作以 CLI 为准；#99：VSC 无 panel ＝ **有意端差**
+ * ⇒ 其载荷面在 VSC 不存在，未挂载（`state` 缺省）即返 `null` = 无面板，消费面降级——
+ * 这正是「④ 段以注入剔除」在核内的形态：核只读注入进来的 state，不判端名）。
+ *
+ * 现算面板块列表（state.subTasks 活值纯推导——无时点快照语义）。
+ * status 三态映射：done+awaitingDigest → "awaitingDigest"；done → "done"；
+ * queued（waiting/等位未启动）→ "queued"；其余 → "running"（§20 D-SD3b queued 态入镜口径保留）。
+ */
+export function computePanelBlocks(state) {
+  const subs = state?.subTasks
+  if (!subs) return null // 未挂载（headless/mock 无 TUI state）——无面板
+  const blocks = []
+  for (const sub of Object.values(subs)) {
+    // §20 D-SD3b：waiting/等位块（sub.queued——未启动）以 queued 态入镜（视图与面板
+    // 所见一致——action:'panel' 视图 + freeze 门控读此态）。
+    const status = sub.done ? (sub.awaitingDigest ? "awaitingDigest" : "done") : (sub.queued ? "queued" : "running")
+    blocks.push({ key: sub.key, role: sub.role ?? null, status, startedAt: sub.started ?? Date.now() })
+  }
+  return blocks
+}