@thincoder/core 0.10.6 → 0.10.8

package/agent-tools/eng.mjs

@@ -12,6 +12,7 @@
  * (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）；
+ * **可拒面 = 仅「档非法」一格**（工作区 `workspace` 放行——零附着，模式照开）；
  * 拒翻 ⇒ 返回原因串 + **零副作用**（模式保持 OFF）。OFF 方向与幂等 enter 零改。
  */
 import { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "../agent.mjs"
@@ -74,15 +75,16 @@ export const engTool = {
         return "Engineering mode already active. Existing design tokens stay valid."
       }
       // #41 先判后翻（MANIFEST.md §2.8 F2 / KD-M1-21）：判据 = 入口决策树**单源**
-      // （resolveEngineeringManifest——KD-M1-20），判据通过才写态。拒翻 ⇒ 返回原因串 +
+      // （resolveEngineeringManifest——KD-M1-20），判据通过才写态。**可拒面 = 仅「档非法」格**
+      // （工作区 `workspace` ⇒ 放行——**零附着**：无项目档可附，模式照开）；拒翻 ⇒ 返回原因串 +
       // **零副作用**（不清 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) {
+      if (!r.ok && r.code !== "workspace") {
         return `Error: cannot enter engineering mode — ${r.message} (mode unchanged)`
       }
-      ctx.agent.manifest = r.manifest
+      ctx.agent.manifest = r.ok ? r.manifest : null // 工作区放行 ⇒ 零附着（显式置 null——§2.8 F2 放行行）
       ctx.agent.config.agent.engineering = true
       // FR31 ③ / KD10（翻转点①）：工程模式 ⇒ planMode 恒 false——中途开模式时清残留
       //（planMode 位 + reminder 计数 + 未注入的 plan 提示语），半状态（工程纪律 × plan 只读）不产生。

package/agent-tools/manifest.mjs

@@ -3,7 +3,7 @@
  * agent 侧读写出口（2026-10-08 · 台账 #1098；权威设计 = `docs/core/design/MANIFEST.md` §2.10）。
  *
  * 三动作（KD-M1-38）：
- *  - `read`  ⇒ `projectView(target)` 五态报明（稳定锚 `state=ok|missing|invalid|ambiguous|no-project`）；
+ *  - `read`  ⇒ `projectView(target)` 五态报明（稳定锚 `state=ok|missing|invalid|workspace|no-project`）；
  *              `ok` 态再 `readManifest(view.root)` 取细节面（`projectView` 面不含 `missingKeys` /
  *              `unknownKeys`）——**不抛**（缺档报明，非拒）。
  *  - `init`  ⇒ 缺档建默认档（`initManifest`——内容 = `DEFAULT_MANIFEST`）；**已带档 ⇒ 拒**
@@ -15,30 +15,35 @@
  * （`version` / `phase` / `promptsLanding` / `codePaths` 整键）+ `nestedKeys` 子键
  * （`docRoot.*` / `checkConfig.*` / `index.*`（含 `publicRepos`）/ `advisor.*`）；**四族整键写
  * （传整个对象）⇒ 拒**；白名单外 ⇒ 拒（拼写保护——未知键写盘 = 静默死键，KD-M1-36 问题本体）。
- * `value` 解析 = 同款口径 `settings.mjs:216-228`（先 `JSON.parse`，失败取字面串；`"null"` ⇒ `null`
+ * `value` 解析 = 同款口径 `settings.mjs` 的 `parseValue`（先 `JSON.parse`，失败取字面串；`"null"` ⇒ `null`
  * ——`docRoot.*` 的「本面无」，KD-M1-37）。
  *
  * 目标面（KD-M1-39——判据复用零新解析器）：`read` = `projectView`；`init` / `write` =
- * `projectRootView`（歧义 ⇒ 拒 + 候选全列——不猜）；`resolveProjectRoot` 对歧义塌缩 `null` 再回落 cwd
- * ⇒ 写 / 建两动作**不得**直用。
+ * `projectRootView`（工作区 ⇒ 拒 + 下辖项目全列 + 显式 `target` 指引）；`resolveProjectRoot` 对
+ * 工作区塌缩 `null` 再回落 cwd ⇒ 写 / 建两动作**不得**直用。
  *
  * 写路径复用（零新写路径）：落盘恒经 `writeManifest` / `initManifest`——`writer` 恒显式 `'main'`
  * （缺省 `'subagent'` = 写门 fail-closed 缺省，KD-M1-3 / AC-M1-5 零改）。
  *
  * 报告面随动（KD-M1-40）：本工具**不写** `agent.manifest`（第二值源否——工具目标可为非锚项目）——
  * 写盘 = 盘面变化，情境行经既有 ③b mtime 门控于下回合采纳（`agent/setup-reminders.mjs`）。
+ *
+ * 缓存失效（#1367 面⑦）：写档成功（init ∥ write——全部成功路径）⇒ `clearDeclarationCache()`——
+ * 「补档即回归」进程内即时（声明 ∥ 范围缓存同清）；失败路径不清（盘零变 ⇒ 缓存照旧）；
+ * 手工改档 ⇒ 重启生效（零文件侦听）。
  */
 import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { MANIFEST_REL, MANIFEST_SCHEMA, initManifest, projectRootView, projectView, readManifest, writeManifest } from "../manifest.mjs"
 import { DESC } from "../tools/shared.mjs"
+import { clearDeclarationCache } from "../conventions.mjs" // #1367 面⑦：写档成功 ⇒ 缓存失效（fix 轮接线）
 
 /** 拒面统一前缀（设计 §2.10：`manifest <action>: refused — …`）——盘零变类拒绝一律经此抛错。 */
 function refuse(action, reason) {
   return new Error(`manifest ${action}: refused — ${reason}`)
 }
 
-/** `target` 解析（先例 `eng.mjs:81` 缺省会话锚 ∥ `git.mjs:32-35` 相对形归一）：缺省 = 会话锚
+/** `target` 解析（先例 `eng.mjs` 的 `resolveEngineeringManifest` 缺省会话锚 ∥ `git.mjs` 的 `resolveBaseDir` 相对形归一）：缺省 = 会话锚
  *  （`ctx.agent.cwd ?? ctx.cwd ?? process.cwd()`）；显式相对形按会话锚归一（绝对形原样）。 */
 function resolveTarget(args, ctx) {
   const base = ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
@@ -60,7 +65,7 @@ function isWritableKey(key) {
   return false
 }
 
-/** `value` 解析（同款口径 = `settings.mjs:216-228`）：先 `JSON.parse`（`"null"` ⇒ `null`；数值 /
+/** `value` 解析（同款口径 = `settings.mjs` 的 `parseValue`）：先 `JSON.parse`（`"null"` ⇒ `null`；数值 /
  *  布尔 / 数组皆 JSON 形），失败取字面串（裸串如 `docs/design`）。 */
 function parseValue(raw) {
   const s = String(raw)
@@ -78,14 +83,14 @@ function setKeyPath(obj, path, value) {
   cur[segs[segs.length - 1]] = value
 }
 
-/** 歧义拒文案（候选全列——不猜；init / write 共用）：多候选 = 显式指定 target，机制不代选。 */
-function ambiguousReason(target, candidates) {
-  return `ambiguous target ${target} — ${candidates.length} candidate projects (the mechanism never picks one); pass target explicitly:\n` +
+/** 工作区拒文案（下辖项目全列 + 显式 `target` 下一步——init / write 共用；事实行，非二义框定）。 */
+function workspaceReason(target, candidates) {
+  return `${target} is a workspace holding ${candidates.length} projects — pass the project root explicitly via target:\n` +
     candidates.map((c) => `- ${c}`).join("\n")
 }
 
 /** read 动作（五态报明——**不抛**）：`state=` 稳定锚 + 各态附行（ok 细节面 / missing 引导 /
- *  ambiguous 候选全列 / invalid 错误行）。 */
+ *  workspace 下辖项目全列 / invalid 错误行）。 */
 function readAction(target) {
   const view = projectView(target)
   const lines = [`state=${view.state}`]
@@ -100,10 +105,10 @@ function readAction(target) {
     lines.push(`hint: run manifest action=init to create the default manifest here`)
   } else if (view.state === "no-project") {
     lines.push(`hint: no project on the ancestor chain and none below — manifest action=init can create one at the target`)
-  } else if (view.state === "ambiguous") {
-    lines.push(`candidates (${(view.candidates ?? []).length}):`)
+  } else if (view.state === "workspace") {
+    lines.push(`projects (${(view.candidates ?? []).length}):`)
     for (const c of view.candidates ?? []) lines.push(`- ${c}`)
-    lines.push(`hint: pass target explicitly — the mechanism never picks one`)
+    lines.push(`hint: pass target explicitly — the target must be one of the projects above`)
   } else if (view.state === "invalid") {
     if (view.errors?.length) lines.push(`errors=${view.errors.join("；")}`)
   }
@@ -117,13 +122,13 @@ export const manifestTool = {
     type: "object",
     properties: {
       action: { type: "string", enum: ["read", "init", "write"], description: "read — current manifest + validation state (five-state anchor, never throws); init — create the default manifest when missing (refused when one already exists); write — point-edit one node (key + value) of an existing manifest" },
-      target: { type: "string", description: "Explicit target directory — defaults to the session anchor; relative paths resolve against it. Ambiguous targets are refused with the full candidate list (never picks one)." },
+      target: { type: "string", description: "Explicit target directory — defaults to the session anchor; relative paths resolve against it. A workspace target (several projects below it) is refused with the full project list — pass the project root you mean." },
       key: { type: "string", description: "(write) Dot path of the node to set — version / phase / promptsLanding / codePaths, or a sub-key of docRoot / checkConfig / index / advisor (e.g. docRoot.design / index.publicRepos / advisor.docMap); whole-object writes of those four families are refused", },
       value: { type: "string", description: "(write) New value — parsed as JSON first (null / true / 5 / [\"a\"]), otherwise kept as a literal string; \"null\" is the explicit no-such-face for docRoot.<key>" },
     },
     required: ["action"],
   },
-  readonly: false, // 动作级分类（dispatch-gates `isSubagentReadonlyAction`）：read = 只读类；init / write 保持侧效门
+  readonly: false, // 动作级分类（dispatch-gates `isReadonlyAction`）：read = 只读类；init / write 保持侧效门
   async execute(args, ctx) {
     const action = args?.action
     if (!["read", "init", "write"].includes(action)) {
@@ -133,10 +138,10 @@ export const manifestTool = {
 
     if (action === "read") return readAction(target)
 
-    // init / write：目标面 = `projectRootView`（歧义直读形——不猜；KD-M1-39）
+    // init / write：目标面 = `projectRootView`（直读形——工作区不成目标；KD-M1-39）
     const rootView = projectRootView(target)
-    if (rootView.state === "ambiguous") {
-      throw refuse(action, ambiguousReason(target, rootView.candidates))
+    if (rootView.state === "workspace") {
+      throw refuse(action, workspaceReason(target, rootView.candidates))
     }
 
     if (action === "init") {
@@ -150,6 +155,7 @@ export const manifestTool = {
       } catch (e) {
         throw refuse("init", `could not write the default manifest at ${file} — ${e?.message ?? String(e)}`)
       }
+      clearDeclarationCache() // 写成功：补档 ⇒ 范围即回归（进程内——失败路径不清）
       return `manifest init: created default manifest (DEFAULT_MANIFEST)\npath=${file}`
     }
 
@@ -188,6 +194,7 @@ export const manifestTool = {
     } catch (e) {
       throw refuse("write", `the edited manifest fails the pre-write validation (disk unchanged) — ${e?.message ?? String(e)}`)
     }
+    clearDeclarationCache() // 写成功：声明 ∥ 范围逐字随动（进程内——失败路径不清）
     return `manifest write: set ${key} = ${JSON.stringify(value)}\npath=${file}`
   },
 }

package/agent-tools/parent-channel.mjs

@@ -34,7 +34,7 @@
  * 两端共用的提示行携参（队首 ask 的 `from` + 单行归一截断的 `message`）；两端各持一份 = 漂移源（D2）。
  *
  * 模块图：静态 import 核单点 `async-settle.mjs`（`carrierField` / `getAsyncPool` /
- * `tombstoneOf` / `wakeAsyncWaiters`——同层既有导出，同 `async-discard.mjs:35` 先例；唤醒走
+ * `tombstoneOf` / `wakeAsyncWaiters`——同层既有导出，同 `async-discard.mjs` 的 `async-settle.mjs` 静态导入先例；唤醒走
  * 既有静态边，零新增）+ `../context.mjs`（`pushReal`）
  * / `../agent/helpers.mjs`（`escapeXml`）/ `../log.mjs`（`logEvent`）；单向、叶子向、无环。
  * 登记册导出（`agent-tools.mjs`）→ 家族矩阵装配（`agent/family-tools.mjs` depth>0 段）。
@@ -55,7 +55,7 @@ export const UPSTREAM_ASK_MAX_INFLIGHT = 1
 
 /** 工具返回注（异步形——sync: false；答复按普通指令在下回合边界到达）。 */
 const ASYNC_NOTE =
-  "delivered to your parent's queue — consumed at the parent's next turn boundary (non-blocking). " +
+  "delivered to your parent's queue — consumed at the parent's next delivery round (idle wake or suspension window; not during a user turn), non-blocking. " +
   "Keep working on the unaffected parts; a reply arrives as an ordinary instruction at your next turn boundary. " +
   "If your run ends first, report the unanswered part as not done."
 
@@ -73,7 +73,7 @@ const refused = (error) => JSON.stringify({ status: "error", error })
  *   ① 父字段在场 ⇒ 父对象（CLI 形主容器——写侧不变）；
  *   ② 缺 ⇒ `carrierField` 回退 `history` 命中 ⇒ **借用同一容器**（不另建分叉）；
  *   ③ 两者皆无 ⇒ 建在父字段 + **载体别名**（`parent.history._childUpstream = parent._childUpstream`
- *      ——同 `writeTombstone` 借用规则扩张句的既有形态，`agent-tools/async-settle.mjs:73-83`）。
+ *      ——同 `writeTombstone` 借用规则扩张句的既有形态，`agent-tools/async-settle.mjs` 的 `writeTombstone`）。
  */
 function upstreamHolder(parent) {
   if (!Array.isArray(parent._childUpstream)) {

package/agent-tools/review-facts.mjs

@@ -142,11 +142,11 @@ export function noteReviewDelivered(agent, run) {
 }
 
 /** 分支③候选底座（`MANIFEST.md` §2.5「路径归一增量」族第四笔 · 2026-10-05 · #945）：现行
- *  `projectRootView(cwd)` 集（ok → [root]；ambiguous → candidates 按名序；none → 空集）＋
+ *  `projectRootView(cwd)` 集（ok → [root]；workspace → candidates 按名序；none → 空集）＋
  *  cwd 祖先链全量目录（自父目录起至盘根、最近→远、去重、现行集在前）——容器相对形在子仓锚下
  *  可解析；受理判据（目标解析位最近 manifest 声明面）∥ 围栏 ∥ 可读唯一化 ∥ fail-closed 歧义零改。 */
 function candidateRoots(view, cwd) {
-  const current = view.state === "ok" ? [view.root] : view.state === "ambiguous" ? view.candidates : []
+  const current = view.state === "ok" ? [view.root] : view.state === "workspace" ? view.candidates : []
   const ancestors = []
   for (let d = dirname(resolve(cwd)); ; ) {
     ancestors.push(d)

package/agent-tools/settings.mjs

@@ -127,7 +127,7 @@ function _checkShape(path, spec, value) {
     }
     return
   }
-  // nonEmptyString —— defaultModel 另加 provider:model 形态面（与 model-ref.mjs:25-36 同判据；
+  // nonEmptyString —— defaultModel 另加 provider:model 形态面（与 model-ref.mjs 的 `parseModelRef` 同判据；
   // 存在性面不查——D-S2.5）
   if (typeof value !== "string" || !value.trim()) throw _expectsError(path, spec.expects, value)
   if (spec.providerModel) {

package/agent-tools/spawn-gates.mjs

@@ -87,18 +87,20 @@ const MANIFEST_BASENAME = "project-manifest.json"
 
 /**
  * F6 files 声明面拦截谓词（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：
- * scripts/**（工程工具面不入域——内容产物 only）与过程档（父侧职责）→ 收集全部违规
- * 后抛合并错误（fail-closed——错误即工具结果 JSON——无排队残留）。目录声明不在本
- * 谓词（normalizeFileList 循环内先行拒——错误序不变）。调用点 = normalizeFileList
- * （subagent-scheduler.mjs——本谓词在循环后跑——目录错误先于过程档错误）。
+ * scripts/*（工程工具面不入域——**层级锚定：仅仓根与直接子层**——目录名在深层不携带
+ * face 信息（2026-10-14 收正：#1449——`deployment/<x>/scripts/*` 类交付物放行）——内容
+ * 产物 only）与过程档（父侧职责）→ 收集全部违规后抛合并错误（fail-closed——错误即工具
+ * 结果 JSON——无排队残留）。目录声明不在本谓词（normalizeFileList 循环内先行拒——错误
+ * 序不变）。调用点 = normalizeFileList（subagent-scheduler.mjs——本谓词在循环后跑——
+ * 目录错误先于过程档错误）。
  */
 export function rejectEngineeringFilePaths(files) {
   const violations = []
   for (const f of Array.isArray(files) ? files : []) {
     const segs = String(f).replace(/\\/g, "/").split("/").filter((s) => s)
     const base = (segs[segs.length - 1] ?? "").toLowerCase()
-    if (segs.some((s) => s.toLowerCase() === "scripts")) {
-      violations.push(`engineering-tools face path ${f} must not be listed in files — scripts/** is the engineering-tools face, not a content product (applies to every session, not engineering-mode-scoped; files carries source/test/design-doc paths only)`)
+    if (segs.slice(0, 2).some((s) => s.toLowerCase() === "scripts")) {
+      violations.push(`engineering-tools face path ${f} must not be listed in files — scripts/* at the repo root or a direct child package is the engineering-tools face, not a content product (applies to every session, not engineering-mode-scoped; files carries source/test/design-doc paths only)`)
     } else if (PROCESS_BASENAMES.has(base)) {
       violations.push(`Parent-side maintained file ${f} must not be listed in files — reconciliation is the parent's duty; use the design-doc path if you need to edit a design doc`)
     } else if (base === MANIFEST_BASENAME) {