@thincoder/core 0.9.4 → 0.10.1

package/declaration.mjs

@@ -0,0 +1,194 @@
+/**
+ * declaration.mjs — 声明装载面（PROJECT-MANIFEST.json 三族 `codePaths` / `index.*` / `advisor.*`）
+ * · 自 `conventions.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786。
+ * 投影单源 = `manifest.mjs`（ONE reader / ONE root resolution——`readManifest` + `manifestFilePath`；
+ * name / shape / defaults = schema 面 `docs/core/design/MANIFEST.md` §2.2）。迁出块逐字；
+ * 原档 `conventions.mjs` 经 `export { … } from` 转口保名（消费面 / 批内件 import 面零改）。
+ */
+import { existsSync } from "node:fs"
+import { dirname, isAbsolute, join, relative, resolve } from "node:path"
+import { DEFAULT_MANIFEST, manifestFilePath, readManifest } from "./manifest.mjs"
+import { logEvent } from "./log.mjs"
+
+/** Retired declaration carrier (project-root relative). Its EXISTENCE is checked, its
+ *  content is never read — the declaration surface = the manifest three families (KD-M1-34). */
+const RETIRED_REL_PATH = ".thincoder/conventions.json"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Declaration loading — the three families of PROJECT-MANIFEST.json, projected
+// through manifest.mjs (ONE reader / ONE root resolution) and cached per DATA-FILE
+// PATH (`clearDeclarationCache()` is the test seam; declarations change rarely).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function normalizeExtensions(v) {
+  if (!Array.isArray(v)) return []
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const t = e.trim().toLowerCase()
+    if (!t) continue
+    const ext = t.startsWith(".") ? t : `.${t}`
+    if (!out.includes(ext)) out.push(ext)
+  }
+  return out
+}
+
+/** Declared code paths replace the default (replacement, not union — §3.1). An EMPTY
+ *  array is a legal declaration ("no segment-based code face") — only a non-array value
+ *  falls back to `null` (⇒ caller keeps the default). */
+function normalizeCodePaths(v) {
+  if (!Array.isArray(v)) return null
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const s = e.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "")
+    if (!s || out.includes(s)) continue
+    out.push(s)
+  }
+  return out
+}
+
+/** 路径列表归一（单源——`index.excludePaths` §6.14 ∥ `index.publicRepos` §6.15 同款）：首部 `./` 剥离 · `\`→`/` · 去尾斜杠 · 空 ∕ 非串剔除 · 去重保序。 */
+function normalizePathList(v) {
+  if (!Array.isArray(v)) return []
+  const out = []
+  for (const e of v) {
+    if (typeof e !== "string") continue
+    const s = e.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "")
+    if (!s || out.includes(s)) continue
+    out.push(s)
+  }
+  return out
+}
+
+function normalizeString(v) {
+  return typeof v === "string" && v.trim() ? v.trim() : ""
+}
+
+/** Project the manifest three families into the frozen declaration object.
+ *  `declared` = VALUE comparison against the defaults — at least one family deviates
+ *  (a key written with its default value still counts as NOT declared; the design-gate
+ *  hint reads it to decide whether to point at the manifest, PORTABILITY §3.1).
+ *  `root` = the project root this declaration belongs to (`dirname(manifestFilePath(cwd))` —
+ *  the segment-matching face's anchor, D18); NOT a declared value (excluded from `declared`);
+ *  `null` = unknown root (`DEFAULT_DECLARATION`). */
+function buildDeclaration(m, root = null) {
+  const codePaths = normalizeCodePaths(m?.codePaths) ?? [...DEFAULT_MANIFEST.codePaths]
+  const codeExtensions = normalizeExtensions(m?.index?.codeExtensions)
+  const docExtensions = normalizeExtensions(m?.index?.docExtensions)
+  const excludePaths = normalizePathList(m?.index?.excludePaths)
+  const publicRepos = normalizePathList(m?.index?.publicRepos)
+  const docMap = normalizeString(m?.advisor?.docMap)
+  const standardsDoc = normalizeString(m?.advisor?.standardsDoc)
+  const defaults = normalizeCodePaths(DEFAULT_MANIFEST.codePaths) ?? []
+  const pathsDiffer = codePaths.length !== defaults.length || codePaths.some((p, i) => p !== defaults[i])
+  const declared = pathsDiffer || codeExtensions.length > 0 || docExtensions.length > 0 || excludePaths.length > 0 || publicRepos.length > 0 || Boolean(docMap) || Boolean(standardsDoc)
+  return Object.freeze({
+    declared,
+    codePaths: Object.freeze(codePaths),
+    index: Object.freeze({
+      codeExtensions: Object.freeze(codeExtensions),
+      docExtensions: Object.freeze(docExtensions),
+      excludePaths: Object.freeze(excludePaths),
+      publicRepos: Object.freeze(publicRepos),
+    }),
+    advisor: Object.freeze({ docMap, standardsDoc }),
+    root,
+  })
+}
+
+/** Full-default declaration (no manifest / unusable manifest) — the fallback every
+ *  consumer gets; built from `DEFAULT_MANIFEST` so the default values stay single-source. */
+export const DEFAULT_DECLARATION = buildDeclaration(null)
+
+/** 排除前缀谓词（单源——§6.14 面①）：`rel`（**`base` 相对**——缺省视为根相对）命中声明前缀（恰等
+ *  ∨ 后随 `/`——`openclaw` 不吞 `openclaw-fork`）⇒ true；缺省 `[]` ⇒ 恒 false（零行为变化）。
+ *  `base`（调用面 cwd/origin·#700）= `rel` 的相对基：`resolve` + `relative` 换算至 `decl.root` 根面
+ *  再比前缀（cwd = 项目根时与既有行为逐字等义）；换算越出根面（`..` 头 ∥ 根外绝对形）⇒ **不命中**
+ *  （保守不排除——沉默洞方向收窄，与 D17 aux 面「indeterminate ⇒ 不匹配」同向）；`decl.root` 缺
+ *  ⇒ `rel` 原样（根起步调用面等义）。 */
+export function isExcludedRelPath(rel, decl, base = null) {
+  const list = decl?.index?.excludePaths
+  if (!Array.isArray(list) || list.length === 0) return false
+  let s = String(rel ?? "").replace(/\\/g, "/")
+  const root = decl?.root
+  if (base != null && root) {
+    const converted = relative(root, resolve(base, s)).replace(/\\/g, "/")
+    if (converted === ".." || converted.startsWith("../") || isAbsolute(converted)) return false
+    s = converted
+  }
+  return list.some((p) => p && (s === p || s.startsWith(`${p}/`)))
+}
+
+/**
+ * 声明公共仓**绝对根集**（§6.15 解析层——检索同步 ∥ 读面 origin 集 ∥ 引用解析三消费面共用的单一定义，
+ * 不得二写）：值形层逐项 `resolve(decl.root, p)` ⇒ 绝对根集（去重保序）；存在性判归消费面（本层不判）。
+ * 缺省 `[]` ⇒ `[]`（零行为）。
+ * @param {string} [cwd] 会话锚（项目根经 manifest.mjs 解析）
+ * @returns {string[]} 绝对路径（去重保序）
+ */
+export function declaredPublicRoots(cwd) {
+  const decl = loadProjectDeclaration(cwd)
+  const list = decl?.index?.publicRepos
+  if (!Array.isArray(list) || list.length === 0) return []
+  const base = typeof decl.root === "string" && decl.root !== "" ? decl.root : resolve(cwd ?? ".")
+  const out = []
+  for (const p of list) {
+    const abs = resolve(base, p)
+    if (!out.includes(abs)) out.push(abs)
+  }
+  return out
+}
+
+const _cache = new Map()
+
+/** Drop the per-data-file-path cache (test seam — declarations are read once per path). */
+export function clearDeclarationCache() {
+  _cache.clear()
+}
+
+/** Retired-carrier warning (existence check only — zero content parsing, zero fallback). */
+function warnRetiredCarrier(root) {
+  console.warn(`[declaration] ${RETIRED_REL_PATH} is retired and no longer read — move codePaths / index.*Extensions / advisor.{docMap,standardsDoc} into PROJECT-MANIFEST.json`)
+  logEvent("declaration:retired-file", { cwd: root })
+}
+
+/**
+ * Load (and cache) the normalized project declaration for a project.
+ * The data file is located through `manifestFilePath(cwd)` (ONE root resolution — a cwd
+ * deeper than the project root still reads the project's manifest) and read through
+ * `readManifest` (ONE reader — this module carries no second parse of the manifest).
+ * Missing manifest → defaults, silently (the returned `root` is still the project root —
+ * `dirname(manifestFilePath(cwd))`, the face's anchor). Unusable manifest (invalid shape /
+ * read error) → defaults + `console.warn` + a log event (visible degradation, never a throw).
+ * A retired `.thincoder/conventions.json` at the manifest's project root → one warning
+ * per cache miss (content zero-parsed, zero effect on the readings — KD-M1-34).
+ * @param {string} cwd — project dir / anchor (root resolved by manifest.mjs)
+ * @returns {Readonly<{declared: boolean, codePaths: readonly string[],
+ *   index: {codeExtensions: string[], docExtensions: string[], excludePaths: string[], publicRepos: string[]},
+ *   advisor: {docMap: string, standardsDoc: string}, root: string|null}>}
+ */
+export function loadProjectDeclaration(cwd) {
+  const file = manifestFilePath(cwd) // data-file path (single source — manifest.mjs KD-M1-18)
+  const hit = _cache.get(file)
+  if (hit) return hit
+  const root = dirname(file) // project root the manifest belongs to (cwd may be deeper) — the face's anchor
+  if (existsSync(join(root, RETIRED_REL_PATH))) warnRetiredCarrier(root)
+  let decl = buildDeclaration(null, root) // missing / unusable manifest → the defaults, root still known
+  try {
+    const r = readManifest(cwd)
+    if (r.ok) {
+      decl = buildDeclaration(r.manifest, root)
+    } else if (r.reason !== "missing") {
+      // Usable-file expectation broken (invalid JSON / wrong shape) → defaults, visible.
+      console.warn(`[declaration] ${file} is not a usable declaration (${(r.errors ?? []).join("; ") || r.reason}) — falling back to defaults`)
+      logEvent("declaration:error", { path: file, err: `invalid: ${(r.errors ?? []).join("; ")}`.slice(0, 200) })
+    }
+  } catch (e) {
+    // Read error (EACCES …) — same visible degradation, never a throw.
+    console.warn(`[declaration] ${file} not readable (${e?.message ?? e}) — falling back to defaults`)
+    logEvent("declaration:error", { path: file, err: String(e?.message ?? e).slice(0, 200) })
+  }
+  _cache.set(file, decl)
+  return decl
+}

package/embedding.mjs

@@ -6,6 +6,7 @@
  */
 
 import { RETRYABLE_STATUS } from "./provider/index.mjs"
+import { resolveEnvRefs } from "./env-ref.mjs"
 const MAX_RETRIES = 3
 const BATCH_SIZE = 32 // max texts per request (within SiliconFlow limits)
 
@@ -16,7 +17,8 @@ export function createEmbedder(config) {
   if (!config?.model) throw new Error("embedding config: model is required — configure embedding.model in ~/.thincoder/config.json")
   return {
     baseURL: config.baseURL.replace(/\/+$/, ""),
-    apiKey: config.apiKey,
+    // #57（provider-config-family 批）：值位 `${env:VAR}` 消费侧解析（CONFIG.md §6.3）——embedder 持解析值，请求侧零改。
+    apiKey: resolveEnvRefs(config.apiKey),
     model: config.model,
   }
 }

package/env-ref.mjs

@@ -0,0 +1,81 @@
+/**
+ * env-ref.mjs — 值位 `${env:NAME}` 引用的消费侧解析（单源叶档；机制 = `docs/core/design/CONFIG.md` §6.3）。
+ *
+ * 语义（零 import 纯函数）：
+ *  - 整值与内嵌同解（`sk-${env:K}` 式）；同一值可含多引用；非字符串值原样通过。
+ *  - 变量未设 ∕ 空串 ⇒ 抛错（点名变量；无「未设即缺省」回退——不静默字面透传）。
+ *  - 畸形引用（`${env:` 起头不构成合法引用）同抛错（点名畸形片段）。
+ *  - 解析单遍：替换产物不再二次扫描；解析产物永不回显、永不回写（调用方纪律——写盘链按磁盘原文）。
+ */
+const REF_PREFIX = "${env:"
+const REF_RE = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g
+
+/** 读一个变量（未设 ∕ 空串 ⇒ 抛错，点名变量；错误句零含解析产物 ∕ 前置字面）。 */
+function readVar(name) {
+  const v = process.env[name]
+  if (v === undefined || v === "") {
+    throw new Error(`env reference \${env:${name}}: variable "${name}" ${v === undefined ? "is not set" : "is empty"} — set the variable or replace the reference with a literal value`)
+  }
+  return v
+}
+
+/** 畸形引用抛错（快照自 `${env:` 起截——引用串之前的字面不进错误句）。 */
+function badRef(value, idx) {
+  return new Error(`malformed env reference ${JSON.stringify(value.slice(idx, idx + 24))} — expected \${env:NAME} with NAME matching [A-Za-z_][A-Za-z0-9_]*`)
+}
+
+/** 字符串值解析：无引用 ⇒ 原串返回；逐引用替换（每次 `${env:` 出现必须构成合法引用）。 */
+export function resolveEnvRefs(value) {
+  if (typeof value !== "string" || !value.includes(REF_PREFIX)) return value
+  const out = []
+  let pos = 0
+  while (pos < value.length) {
+    const idx = value.indexOf(REF_PREFIX, pos)
+    if (idx === -1) { out.push(value.slice(pos)); break }
+    REF_RE.lastIndex = idx
+    const m = REF_RE.exec(value)
+    if (!m || m.index !== idx) throw badRef(value, idx)
+    out.push(value.slice(pos, idx), readVar(m[1]))
+    pos = idx + m[0].length
+  }
+  return out.join("")
+}
+
+/** 键值对象解析（headers ∕ env 族）：无引用 ⇒ 原对象返回（零拷贝）；值非字符串原样。 */
+export function resolveEnvRefMap(map) {
+  if (map === null || typeof map !== "object" || Array.isArray(map)) return map
+  let changed = false
+  const out = {}
+  for (const [k, v] of Object.entries(map)) {
+    const rv = resolveEnvRefs(v)
+    if (rv !== v) changed = true
+    out[k] = rv
+  }
+  return changed ? out : map
+}
+
+/** providers[] 条目适配：`apiKey` ∥ `headers.*`（无引用 ⇒ 原对象返回——零拷贝零写回）。 */
+export function resolveProviderSecrets(provider) {
+  if (provider === null || typeof provider !== "object") return provider
+  const apiKey = resolveEnvRefs(provider.apiKey)
+  const headers = resolveEnvRefMap(provider.headers)
+  if (apiKey === provider.apiKey && headers === provider.headers) return provider
+  const out = { ...provider }
+  if (apiKey !== provider.apiKey) out.apiKey = apiKey
+  if (headers !== provider.headers) out.headers = headers
+  return out
+}
+
+/** mcp.servers[] 条目适配：`token` ∥ `headers.*` ∥ `env.*`（无引用 ⇒ 原对象返回）。 */
+export function resolveMcpServerSecrets(config) {
+  if (config === null || typeof config !== "object") return config
+  const token = resolveEnvRefs(config.token)
+  const headers = resolveEnvRefMap(config.headers)
+  const env = resolveEnvRefMap(config.env)
+  if (token === config.token && headers === config.headers && env === config.env) return config
+  const out = { ...config }
+  if (token !== config.token) out.token = token
+  if (headers !== config.headers) out.headers = headers
+  if (env !== config.env) out.env = env
+  return out
+}

package/explore-distill.mjs

@@ -1,6 +1,5 @@
 /**
- * explore-distill.mjs — End-of-run exploration distillation (AGENT-LOOP §13 +
- * CONTEXT-COMPACTION §6.9 H1, 2026-08-23). 2026-09-05 module-split: moved verbatim out of
+ * explore-distill.mjs — End-of-run exploration distillation (CONTEXT-COMPACTION.md §6.9 H1, 2026-08-23). 2026-09-05 module-split: moved verbatim out of
  * context.mjs (524 > 500 hard limit). The main agent's machine line is flooded by inline
  * step-by-step exploration (read/grep/...). At run end we distill THIS run's exploration
  * tool-results into one semantic summary note that replaces them in the machine line,
@@ -99,7 +98,7 @@ async function distillExplorations(history, start, provider, signal, agent, dept
       messages: buildCompressMessages(history, cut, extras?.systemPrompt, EXPLORE_SUMMARY_PROMPT),
       tools: extras?.tools,
       signal,
-      // §18.6 D-TR4：轨迹元数据增补——kind=distill（探索蒸馏面——agent 元数据透出；
+      // TRACES.md §6.1 D-TR4：轨迹元数据增补——kind=distill（探索蒸馏面——agent 元数据透出；
       // depth 经 summarizeRunExplorations 参数透传——agent.mjs 主作用域传入）
       logCtx: {
         stage: "distill", child: agent?._logId ?? null, kind: "distill",

package/file-links.mjs

@@ -0,0 +1,53 @@
+/**
+ * file-links.mjs — 工具结果文本的**验存**文件链接抽取（上提核件 —— 处理流批 R2 · 2026-09-28）。
+ * 上提源 = VSC `thincoder-vscode/src/extension/file-links.mjs`（token 抽取 ∕ 去重 ∕ 封顶）× 桌面同档
+ * （相对径需项目根——无根 ⇒ 相对 token 零判据，不落 `process.cwd()` 第二解析基）；本档 = 单源
+ * （消费面 = 桌面 `thincoder-desktop/src/main/file-links.mjs` · VSC `thincoder-vscode/src/extension/file-links.mjs`——已随
+ * parity-b4 迁移轮改指本档（2026-09-29，双写窗口收口））。
+ * 判据 = **盘上存在闸**（存在 ∧ 是文件）：路径 token 只在真实存在时才成链接 —— URL ∕ 日志噪音 ∕
+ * 版本号恒不成链接（存在检查 = 最后一道闸）。**验存（`existsSync` ∕ `statSync`）转注入缝**：本档零
+ * `node:fs`——盘面探针由调用方注入（`probe = { existsSync, statSync }`）；缺 ∕ 形违 ⇒ 抛（fail-loud——
+ * 存在闸未接线不得静默扮成「零链接」）。返回 `[{ raw, path, line }]`：`raw` = 含行后缀原文 · `path` =
+ * 盘上绝对路径 · `line` = 数 ∕ 缺 ⇒ `null`；零抛面 = fs 判据（探针逐条 try/catch：不可达 = 不成链接）。
+ */
+
+import { isAbsolute, resolve } from "node:path"
+
+/** 路径 token：可选 Windows 盘符 + 路径字符 + 点扩展名 + 可选 `:line` / `:line:col` 后缀；m[1] = 路径本体（供探针）、m[2] = 行号、m[0] = 渲染面包裹面 `raw`。 */
+const PATH_TOKEN_RE = /((?:[A-Za-z]:)?[~./\\\w][\w./\\~-]*\.\w{1,10})(?::(\d+)(?::\d+)?)?/g
+
+/** 逐结果封顶（值同源 = VSC 同档 `MAX_LINKS`）。 */
+export const MAX_LINKS = 50
+
+/**
+ * 工具结果文本 ⇒ 验存文件链接（去重 + 封顶）。`cwd` = 项目根（相对 token 的解析基）；缺 ∕ 空 ⇒ 相对 token
+ * 一律不检（禁假链接）；绝对 token 与 cwd 无关，照检。`probe` = 盘面探针注入缝（`{ existsSync(p), statSync(p) }`——
+ * `node:fs` 同名面；桌面端侧注入）。零文本（`""` ∕ 非串）先于探针校验早退（零判据面 —— 探针不检）。
+ */
+export function extractFileLinks(cwd, text, probe) {
+  if (typeof text !== "string" || text === "") return []
+  if (typeof probe?.existsSync !== "function" || typeof probe?.statSync !== "function") {
+    throw new TypeError("extractFileLinks: probe seam missing — inject { existsSync, statSync } (the existence guard must not silently degrade)")
+  }
+  const base = typeof cwd === "string" && cwd !== "" ? cwd : null
+  const links = []
+  const seen = new Set()
+  for (const m of text.matchAll(PATH_TOKEN_RE)) {
+    const pathPart = m[1]
+    // 协议相对 URL 残体（`//example.com/a.png`）—— 恒非工作区路径。
+    if (pathPart.startsWith("//") || pathPart.startsWith("\\\\")) continue
+    const absolute = isAbsolute(pathPart)
+    if (!absolute && base === null) continue // 无项目根 ⇒ 相对 token 零判据（禁假链接）
+    const line = m[2] ? Number(m[2]) : null
+    const abs = absolute ? pathPart : resolve(base, pathPart)
+    const key = `${abs}:${line ?? ""}`
+    if (seen.has(key)) continue
+    try {
+      if (!probe.existsSync(abs) || !probe.statSync(abs).isFile()) continue
+    } catch { continue }
+    seen.add(key)
+    links.push({ raw: m[0], path: abs, line })
+    if (links.length >= MAX_LINKS) break
+  }
+  return links
+}

package/file-refs.mjs

@@ -0,0 +1,103 @@
+/**
+ * file-refs.mjs — @ 文件引用**注入 ∕ 剥离核件**（缺面族批补 #632 · 2026-09-29 上提）。
+ * 上提源 = VSC `thincoder-vscode/src/extension/file-refs.mjs` 自持档（逐字搬——regex ∕ 4000 截断 ∕
+ * `[File: …]` 围栏 ∕ 摘要块格式零语义改良）；本档 = **单源**；两端各持薄壳（端侧 `node:fs` 探针注入）：
+ * VSC `thincoder-vscode/src/extension/file-refs.mjs` ∥ 桌面 `thincoder-desktop/src/main/file-refs.mjs`。
+ * 消费面：VSC 注入 `panel-chat.mjs:187` ∕ 恢复剥离 `panel-session.mjs:185` ∕ 标题剥离
+ * `panel-session-write.mjs:139`；桌面注入缝 = `turn-driver.mjs`（起跑前单点，`turn-face.mjs`）∥
+ * 恢复剥离 = `session-slots.mjs` `pageHistory` ∥ 标题剥离 = 核 `generate-title.mjs:132`（读源处）。
+ * 文本形逐字冻结（`docs/vsc/design/WEBVIEW.md:154`「落线文本逐字不变」契约）：上提不携任何行为面改动。
+ * 判据 = **盘面探针注入缝**（`probe = { readFileSync, existsSync, statSync }` —— `node:fs` 同名面；
+ * 缺 ∕ 形违 ⇒ 抛 —— fail-loud：盘面闸未接线不得静默扮成「零引用」，沿 `file-links.mjs:29-31` 先例）。
+ * `stripAtRefs` = 注入语法的逆变换：fail-closed 判据逐字依赖注入输出格式 —— 语法与其逆变换同住一处，
+ * 零第二实现（本档为唯一产者）。
+ */
+import { join } from "node:path"
+
+/** 探针三件（`node:fs` 同名面）——缺一即缝违。 */
+const PROBE_KEYS = ["readFileSync", "existsSync", "statSync"]
+
+/** 探针校验（fail-loud）：三件皆须为函数 —— 缺 ∕ 形违 ⇒ 抛。 */
+function probeOf(probe) {
+  if (PROBE_KEYS.some((key) => typeof probe?.[key] !== "function")) {
+    throw new TypeError("injectAtRefs: probe seam missing — inject { readFileSync, existsSync, statSync } (the disk probe must not silently degrade)")
+  }
+  return probe
+}
+
+/** Scan text for @path references and replace with inline file content.
+ *  零文本（非串 ∥ 空串）先于探针校验早退（零判据面——探针不检，同序沿核 `file-links.mjs:28`）。 */
+export function injectAtRefs(text, cwd, probe) {
+  if (typeof text !== "string" || text === "") return text
+  const io = probeOf(probe)
+  const re = /@([^\s,;:()[\]{}"'`]+)/g
+  const refs = []
+  let m
+  while ((m = re.exec(text)) !== null) {
+    const raw = m[1]
+    // Skip things that aren't paths (emails, mentions like @user)
+    if (!/^[a-zA-Z0-9_./\\-]+$/.test(raw)) continue
+    if (raw.includes("@")) continue
+    // Resolve relative to cwd
+    const abs = join(cwd, raw)
+    if (!io.existsSync(abs)) continue
+    try {
+      const stat = io.statSync(abs)
+      if (!stat.isFile()) continue
+      let content = io.readFileSync(abs, "utf8")
+      if (content.length > 4000) content = content.slice(0, 4000) + "\n... (truncated)"
+      refs.push({ raw, abs, content })
+    } catch (e) {
+      console.error(`[file-refs] failed to read @${raw}:`, e.message)
+    }
+  }
+  if (refs.length === 0) return text
+
+  // Replace @refs in the text with inline content blocks
+  for (const ref of refs) {
+    const placeholder = `@${ref.raw}`
+    const injection = `[File: ${ref.raw}]\n\`\`\`\n${ref.content}\n\`\`\``
+    text = text.split(placeholder).join(injection)
+  }
+
+  // Append a summary of referenced files
+  const list = refs.map(r => `  - ${r.raw} (${r.content.length} chars)`).join("\n")
+  text += `\n\n[Referenced files:\n${list}\n]`
+
+  return text
+}
+
+/**
+ * 复原注入前的用户原文（F-W15 端侧显示边界剥离 · D-W17）。
+ *
+ * 契约：同一会话中用户消息的**恢复面**文本 ≡ 活面气泡文本（= 用户所打原文，`@路径` 保持简洁形）。
+ * 与产者同档（本档 = 注入语法的唯一产者——语法与其逆变换同住一处，零第二实现）。
+ *
+ * 剥离判据（fail-closed）：仅当文本尾部为注入**摘要块**（`[Referenced files:` 头 +
+ * 逐行 `  - <raw> (<N> chars)` + 尾 `]`）时，按「`[File: <raw>]` 头 + 围栏 + 恰 N 字符正文 +
+ * 收尾围栏 ⇒ `@<raw>`」逐条还原并删摘要块；**任一条不吻合 ⇒ 整条原样返回**（用户手打的
+ * `[File: x]` / 形近文本零误伤）。落线 / 机读线（模型输入）零触碰——本函数只服务显示边界。
+ */
+export function stripAtRefs(text) {
+  const s = typeof text === "string" ? text : ""
+  const tail = /(?:^|\n\n)\[Referenced files:\n([\s\S]*)\n\]$/.exec(s)
+  if (!tail) return s
+  const entries = []
+  for (const line of tail[1].split("\n")) {
+    const m = /^ {2}- (.*) \((\d+) chars\)$/.exec(line)
+    if (!m) return s // 摘要块形近（行不吻合）⇒ 原样返回
+    entries.push({ raw: m[1], len: Number(m[2]) })
+  }
+  if (entries.length === 0) return s
+  let head = s.slice(0, tail.index) // 删摘要块（含其前空行）
+  for (const { raw, len } of entries) {
+    const open = `[File: ${raw}]\n\`\`\`\n`
+    const at = head.indexOf(open)
+    if (at < 0) return s // 头部缺 / 不对应 ⇒ 原样返回
+    const bodyStart = at + open.length
+    const bodyEnd = bodyStart + len
+    if (head.slice(bodyEnd, bodyEnd + 4) !== "\n\`\`\`") return s // 字符数不符 ⇒ 原样返回
+    head = head.slice(0, at) + `@${raw}` + head.slice(bodyEnd + 4)
+  }
+  return head
+}

package/generate-title.mjs

@@ -9,9 +9,17 @@
  */
 
 import { proxyFetch } from "./proxy.mjs"
+import { resolveProviderSecrets } from "./env-ref.mjs"
 // D7（2026-09-21 块标题行对齐批——标题链单源）：首条真实 user 消息谓词收核单源
 // （`isRealUserMsg`——纯函数零依赖，无环）。
 import { isRealUserMsg } from "./history-window.mjs"
+// #632（缺面族批补 · @ 文件引用对齐 · 2026-09-29）：标题源剥离单源——注入形不得进标题请求（核件
+// `file-refs.mjs`；CLI 无注入 ⇒ 零动作；VSC 同位转口 = `panel-session-write.mjs:139`）。
+import { stripAtRefs } from "./file-refs.mjs"
+// #363③（off 形族单源——MODEL-SPECS.md §16.2 / §16.4）：禁思考形与「是否可禁」一律引核
+// （`thinkOffShape` / `thinkOffPath`——本档零副本）；spec 查表同单源（`specForModel`）。
+import { specForModel } from "./model-specs.mjs"
+import { thinkOffShape, thinkOffPath } from "./think-off.mjs"
 
 // Test seam (_-prefix, mirrors run.mjs seams): lets the proxy-branch regression
 // test swap the proxy fetch. The branch it exercises used to carry a dynamic
@@ -31,7 +39,16 @@ export async function generateTitle(userContent, provider) {
   if (typeof userText !== "string" || userText.length < 10) return null
   if (!provider?.apiKey || !provider?.baseURL || !provider?.model) return null
 
+  // #363③：禁思考形（三格式支共用）——off 取形与可宣称性引核单源：`thinkOffPath` 假
+  // （thinkAlwaysOn 族）或 `thinkOffShape` 为 `null`（effort 族——`null` 形是核载荷门的
+  // 约定，本档无门）⇒ 不发禁形（假标记：被服务端拒 / 静默失效）。
+  const spec = specForModel(provider.model)
+  const offShape = thinkOffPath(spec) ? thinkOffShape(spec) : null
+
   try {
+    // #57（provider-config-family 批）：凭据值位 `${env:VAR}` 消费侧解析（CONFIG.md §6.3）——解析抛错
+    // 落本函数既有非致命兜底（下方 catch ⇒ 标题回落 null——不破坏回合，与「无 key 不生成标题」同形）。
+    provider = resolveProviderSecrets(provider)
     const system = "Generate a concise title (max 40 chars, no quotes) for this conversation. Reply ONLY with the title."
     const text = userText.slice(0, 200)
     let url, body, extract
@@ -43,7 +60,7 @@ export async function generateTitle(userContent, provider) {
         messages: [{ role: "user", content: text }],
         max_tokens: MAX_TITLE_TOKENS,
         stream: false,
-        thinking: { type: "disabled" }, // IK9UZ8：不让 reasoning 吃掉输出预算
+        ...(offShape !== null ? { thinking: offShape } : {}), // IK9UZ8：不让 reasoning 吃掉输出预算
       })
       extract = (data) => data.content?.map((b) => b.text || "").join("")
     } else if (provider.format === "google") {
@@ -51,7 +68,11 @@ export async function generateTitle(userContent, provider) {
       body = JSON.stringify({
         systemInstruction: { parts: [{ text: system }] },
         contents: [{ role: "user", parts: [{ text }] }],
-        generationConfig: { maxOutputTokens: MAX_TITLE_TOKENS, thinkingConfig: { thinkingLevel: "none" } }, // IK9UZ8
+        generationConfig: {
+          maxOutputTokens: MAX_TITLE_TOKENS,
+          // google 格式自身的关思考形（wire 原生——非族别取形副本）；无有效 off 路径 ⇒ 零发
+          ...(offShape !== null ? { thinkingConfig: { thinkingLevel: "none" } } : {}),
+        }, // IK9UZ8
       })
       extract = (data) => data.candidates?.[0]?.content?.parts?.map((p) => p.text || "").join("")
     } else {
@@ -65,7 +86,9 @@ export async function generateTitle(userContent, provider) {
         // leave content empty (IK9UZ8). Providers that don't accept the field ignore it
         // (OpenAI-compatible convention). A 40-char title wants ~60–80 tokens, so 100 is
         // ~2.5x headroom (design decision — docs/core/design/SESSION.md §6.7).
-        thinking: { type: "disabled" },
+        // #363③：形自核单源（`thinkOffShape`——type 族 = `{type:"disabled"}`；无有效 off 路径
+        // 族不发——见上方 offShape 取形）。
+        ...(offShape !== null ? { thinking: offShape } : {}),
         max_tokens: MAX_TITLE_TOKENS,
         stream: false,
       }
@@ -113,7 +136,8 @@ export async function ensureSessionTitle(agent) {
     let firstUser = agent._recordStore?.firstUserMessage?.() ?? null
     if (!firstUser) firstUser = (agent._fullHistory ?? agent.history).find(isRealUserMsg)
     if (firstUser) {
-      const title = await generateTitle(firstUser.content, agent.provider)
+      // #632：读源处剥离（注入形不得入标题请求——与恢复面同读一函数，零第二实现）
+      const title = await generateTitle(stripAtRefs(firstUser.content), agent.provider)
       if (title) agent.title = title
     }
   } catch {

package/git/checkpoint.mjs

@@ -13,6 +13,10 @@ import { existsSync, readFileSync, statSync } from "node:fs"
 import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { configDir } from "../config.mjs"
+// normalizeCwd 单源（2026-09-25 批 ledger-key-normalize · 台账 #286）：盘符大写契约归一住
+// `session-slots.mjs`（session / checkpoint / traces / peers 同契约消费面）；本档原私有副本删除，
+// 跨端 cwdHash12（CHECKPOINT.md F5/T7）赖同一实现，不再各自持字面。
+import { normalizeCwd } from "../session-slots.mjs"
 
 const CWD_HASH_LEN = 12
 
@@ -33,14 +37,6 @@ function git(cwd, args, { allowFail = false } = {}) {
   }
 }
 
-/** Normalize cwd for hashing: uppercase the Windows drive letter so the VS Code
- *  extension's uri.fsPath (lowercased) produces the SAME cwdHash12 as the CLI's
- *  process.cwd() — cross-end snapshot sharing (CHECKPOINT.md F5/T7) depends on this
- *  contract. Same normalization as session storage (session-slots.mjs normalizeCwd). */
-function normalizeCwd(cwd) {
-  return cwd.replace(/^([a-z]):/, (_, d) => d.toUpperCase() + ":")
-}
-
 function checkpointRoot(cwd) {
   const hash = createHash("sha1").update(normalizeCwd(cwd)).digest("hex").slice(0, CWD_HASH_LEN)
   return join(configDir, "checkpoints", hash)

package/history-window.mjs

@@ -9,6 +9,11 @@
  *
  * 承接：会话数据面的「人读线」窗口切分（分段恢复 / 逐页回看）——与磁盘会话档
  * 同源（`{hash}.json.N`），本档只读数组、不触盘。
+ *
+ * 留档记录直通（opt-in · 消化面留档批 · #719）：`digest` ∕ `subagent` 两型记录
+ * 原样入窗（携 `idx`；字段零改名）；默认关 ⇒ 输出与改前逐字等价（CLI ∕ VSC 读面
+ * 零改零破）——`kindOf` 认 `kind` 键；形 / 在场 / 判据单源 =
+ * `docs/desktop/design/RENDERER.md` §1.1「留档记录」条。
  */
 
 /** Real user message predicate (shared by the slot metadata digest and the window).
@@ -32,7 +37,7 @@ function tsOf(m) {
 }
 
 function kindOf(m) {
-  return m?.type ?? m?.role
+  return m?.type ?? m?.role ?? m?.kind
 }
 
 function toolCallsOf(m) {
@@ -103,10 +108,16 @@ function pairToolEntries(history) {
  * takes the LAST page (first paint); otherwise the page [s, e) ending just before
  * `before`. Half-open [s, e) keeps loadOlder pages from re-rendering the boundary
  * message. `idx` values are GLOBAL history indexes — pagination never renumbers.
+ *
+ * `opts.records === true`（opt-in —— 留档批 · #719）⇒ `digest` ∕ `subagent` 两型
+ * 记录原样入窗（`{ ...record, idx }`，字段零改名）并占条目位（游标按条目推进）；
+ * 记录不参与 turn ∕ 可见性谓词（`visible` 面语义不动）。**默认关** ⇒ 输出与改前
+ * 逐字等价（负控腿）；缺 `opts` ∕ 非 `true` ⇒ 同默认径。
  */
-export function historyWindow(history, before, pageSize = HISTORY_PAGE_SIZE) {
+export function historyWindow(history, before, pageSize = HISTORY_PAGE_SIZE, opts = {}) {
   const total = Array.isArray(history) ? history.length : 0
   if (total === 0) return { messages: [], hasOlder: false }
+  const records = opts?.records === true
   const { frameResults, ownerOf } = pairToolEntries(history)
   const end = before == null ? total : Math.max(0, Math.min(before, total))
   const start = Math.max(0, end - pageSize)
@@ -161,6 +172,10 @@ export function historyWindow(history, before, pageSize = HISTORY_PAGE_SIZE) {
         turnStart: prevVisibleKind === null || prevVisibleKind === "user",
         tools,
       })
+    } else if (records && (kind === "digest" || kind === "subagent")) {
+      // 留档记录直通（opt-in）：人读线条目原样入窗 + 携位次（字段零改名 —— 形单源 =
+      // `docs/desktop/design/RENDERER.md` §1.1「留档记录」条）
+      messages.push({ ...m, idx: i })
     } else if (kind === "tool") {
       // A consumed tool entry produces no message of its own (rendered with its frame) —
       // only a true orphan falls back to the top level (rules 3/4)

package/i18n.mjs

@@ -46,6 +46,8 @@ export const CORE_MESSAGES = Object.freeze({
   "status.rateLimited": { en: "Rate-limited 429, retry in ${s}s", zh: "限流 429，${s}s 后重试" },
   "status.overloaded": { en: "Server overloaded, retrying in ${s}s", zh: "服务过载，${s}s 后重试" },
   "status.quota": { en: "quota exhausted: ${msg}", zh: "配额耗尽：${msg}" },
+  // ── 停滞轻显形（在飞回合静默读数——TUI.md §7.7 · stall-indicator 批 2026-09-29）──
+  "status.quiet": { en: "Quiet ${s}s", zh: "已静默 ${s}s" },
   // ── 异步池状态词 ──
   "sub.running": { en: "running", zh: "运行中" },
   "sub.queued": { en: "queued", zh: "排队中" },