@thincoder/core 0.10.13 → 0.11.1

package/tools/git.mjs

@@ -2,7 +2,9 @@ import {
   DESC,
   truncate,
   runGit,
-  gitFailureMessage
+  gitFailureMessage,
+  LEDGER_PARAM_DESC_GIT,
+  PROJECT_PARAM_DESC,
 } from "./shared.mjs";
 import { spawnGit } from "./git-run.mjs";
 import { resolve } from "node:path";
@@ -86,10 +88,34 @@ export const gitTool = {
       create: { type: "boolean", description: "(switch) create the branch then switch (-c)" },
       dest: { type: "string", description: "(mv) destination path (file or directory)" },
       worktreeAction: { type: "string", enum: ["list", "add", "remove"], description: "(worktree) list / add (path, ref) / remove (path)" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC_GIT },
+      // 项目声明面（决策 40）：`path` ∥ `workdir` 缺位时才被读（定位参数优先）；纯声明，不改执行目录。
+      project: { type: "string", description: PROJECT_PARAM_DESC },
     },
     required: ["action"],
   },
   readonly: false,
+  /**
+   * 动作级只读分类（决策 37 · 2026-11-03 笔-账绑定批——**本钩子是单源**）。
+   * 消费面两处：`thincoder-core/agent/dispatch-gates.mjs` 的 `readonlyActionOf(tool, "git", args)`
+   * （planMode 门 ∥ 权限短路 ∥ 写门的 `git` 写型/只读判定）——三面（CLI ∥ desktop ∥ vscode）同答案。
+   * 名单与 `thincoder-vscode/src/tools/index.mjs` 原端装饰体逐条同形（该覆写随本钩子同笔删除）：
+   * 六项平铺 + 六条子动作分支。`checkpoint` 的 `list` ∥ `cat` 判只读——`checkpoint list` 有 F6 清理副作用
+   * （`lazyClearIfCommitted` 可能删除整个 checkpoint 目录），但清的是 commit 后已失去意义的过期快照 ⇒
+   * 保留只读分类免审批（`docs/core/design/CHECKPOINT.md` F6/D3 设计意图）。
+   * 缺此钩子的面回落到核名面谓词（无 `git` 分支 ⇒ false ⇒ 写型 ⇒ 要号），fail-closed，不出洞。
+   */
+  isReadonlyAction(args) {
+    if (!args || typeof args.action !== "string") return false
+    if (["diff", "status", "log", "show", "ls-remote", "blame"].includes(args.action)) return true
+    if (args.action === "checkpoint") return ["list", "cat"].includes(args.checkpointAction)
+    if (args.action === "tag") return args.tagAction === "list"
+    if (args.action === "branch") return args.branchAction === "list"
+    if (args.action === "stash") return args.stashAction === "list"
+    if (args.action === "remote") return args.remoteAction === "list"
+    if (args.action === "worktree") return args.worktreeAction === "list"
+    return false // add/rm/commit/push/fetch/pull/reset/revert/merge/cherry-pick/checkout/restore + tag/branch/stash 写操作
+  },
   async execute(args, ctx) {
     // workdir: run git in a subdirectory (monorepo / multi-repo). Shadow ctx.cwd so
     // every action + snapshotBefore + checkpoint resolves against the workdir.

package/tools/ops.mjs

@@ -7,7 +7,7 @@
  * wait_for 条件族 +`bash id:N done`。list ∥ 既有条件面零变。批 browser-async-fix（#1045）：kill id
  * 路由先 bg 后 browser（同一 id 命名空间）∥ wait_for 条件族 +`browser id:N done`。
  */
-import { DESC, resolveInCwd, truncate } from "./shared.mjs"
+import { DESC, resolveInCwd, truncate, LEDGER_PARAM_DESC } from "./shared.mjs"
 // 单一写路径点（编辑器编辑径注入缝——CORE-UNIFICATION §2.13.5）：路径操作也经它落盘
 // （默认径 = 既有 cp / rename / EXDEV 回退语义，零行为变）。
 import { writeThroughPath } from "./write-path.mjs"
@@ -26,6 +26,7 @@ export const fileOpsTool = {
       action: { type: "string", enum: ["move", "copy", "rename"], description: "move | copy | rename" },
       source: { type: "string", description: "Source path, relative to cwd or absolute" },
       dest: { type: "string", description: "Destination path" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["action", "source", "dest"],
   },

package/tools/patch.mjs

@@ -4,9 +4,10 @@ import {
   resolveInCwd,
   normalizeEOL,
   detectFileEol,
-  majorityEol
+  majorityEol,
+  LEDGER_PARAM_DESC
 } from "./shared.mjs";
-import { writeThroughPath, TMP_SUFFIX, markDirty } from "./write-path.mjs";
+import { writeThroughPath, TMP_SUFFIX, markDirty, clearLastWrite } from "./write-path.mjs";
 import { spawnGit } from "./git-run.mjs";
 import { mkdir, readFile, lstat, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -175,6 +176,7 @@ export const applyPatchTool = {
     type: "object",
     properties: {
       patch: { type: "string", description: "Unified diff. May span multiple files (multiple --- / +++ header pairs — including creating MULTIPLE new files via --- /dev/null); --- / +++ headers per file, @@ -old,count +new,count @@ hunks (a bare @@ header is also accepted — coordinate-less hunks are located by their anchor lines: context lines plus the removed (-) lines, matched as a contiguous sequence — a unique match applies; a zero/one-context hunk is accepted only when it removes (-) at least one line and that anchor sequence is unique, while anchor-free pure-+ (insert) hunks need at least 2 context lines). The +++ b/<path> pair may be omitted for existing files — a lone --- a/<path> (or --- b/<path>) header followed directly by hunks applies to that path (new files still need --- /dev/null + +++ b/<path>)." },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["patch"],
   },
@@ -234,7 +236,13 @@ export const applyPatchTool = {
     const summary = planned.map((p) => `  ${p.isNew ? "created " : "modified"} ${p.path}`).join("\n")
     // Mark every touched file dirty — insert_after must not run on stale line numbers.
     // 整批记账（dirty）= apply_patch 的批级语义（两段式全成功后一次落账——与改前逐字同）。
-    for (const p of planned) markDirty(p.abs)
+    // 2026-11-02：落 dirty 同时清写入快照——apply_patch 不记快照，留着旧 `startLine` 就是
+    // 陈旧的锚：行号锚护栏第 2 行（dirty ∧ 快照在场）会拒，而第 4 行会拿旧值判「目标区在之前
+    // ⇒ 放行」——两种结果都不该由一笔没更新快照的写来决定（EDIT-HELPERS §7.1）。
+    for (const p of planned) {
+      markDirty(p.abs)
+      clearLastWrite(p.abs)
+    }
     const syntaxChecks = await Promise.all(planned.map(async (p) => {
       const r = await autoSyntaxCheck(p.abs)
       return r ? `${p.path}:${r.replace("Syntax: ", "")}` : ""
@@ -256,6 +264,7 @@ export const deleteTool = {
     properties: {
       path: { type: "string", description: "File or empty-directory path (relative to cwd or absolute)" },
       force: { type: "boolean", description: "Allow deleting git-tracked files (default false)" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
     },
     required: ["path"],
   },

package/tools/process-doc-mark.mjs

@@ -0,0 +1,139 @@
+/**
+ * process-doc-mark.mjs — 工具输出里的过程档标记（单源小档；机制 = `docs/core/design/TOOLS.md` §6.28）。
+ *
+ * 依赖面说清楚：本档**不**是零依赖叶档——谓词都来自判据单源 `../declaration.mjs`，而它的静态闭包
+ * 经 `memory/file-walk.mjs` 达 `memory/schema.mjs`（`node:sqlite`）。因此端壳里静态引本档 = 把那条链拉进静态闭包；
+ * 当前端装配面本已静态可达同一链（`setup-tooltable.mjs` → 核 `agent-tools/verify.mjs` → `conventions.mjs`），
+ * 零新增风险，但别把它当零依赖档随手引。
+ *
+ * 一句话：输出里**判定得出**来源档落在索引排除集（batches 段 ∥ `_archive` 前缀）的行，
+ * 行首加 `[process doc: not a design basis]`（原行整体后随）；其余行一个字节不动。**不是门**——
+ * 不拦、不筛、不改命中集，只加可读信息。
+ *
+ * 两套判据、一份文案、一个谓词、一个 helper：
+ * - `grep` 面按命中行的**档**判（消费面直调 `isProcessDocPath`——grep 自己已有 `h.file`，本档不参与拼装）；
+ * - 命令面（`bash` 同步 ∥ `bash` 后台摘要 ∥ `execute` ∥ VSC 端 `bash`）的输出是任意文本，只能按
+ *   **行首路径 token 真解析到盘上**判（`markProcessDocLines`）——解析不到 = 判不了 = 不动输出。
+ *
+ * 判据单源 = `../declaration.mjs` 的 `isExcludedRelPath`（面① 前缀 ∪ 面⑥ 段序列）：本档零新排除名单、
+ * 零新谓词。第三参必须传 `decl.root`——`isExcludedRelPath` 内 `resolve(base, s)` 对绝对参恒等，
+ * 再由 `relative(root, …)` 换成根相对面，面① 前缀才判得住（只被面① 命中的 `_archive` 靠这一点）。
+ *
+ * 零 console 噪声：本档不调用 `console`。判据只走 `declarationForTarget` → `loadProjectDeclaration`，
+ * 后者按档缓存，只在声明档不可用 / 读不出时 warn（既有降级面，非本档新增）。
+ */
+import { existsSync } from "node:fs"
+import { isAbsolute, resolve } from "node:path"
+import { declarationForTarget, isExcludedRelPath } from "../declaration.mjs"
+
+/** 逐字文案（33 字符 · 全 ASCII · 方括号闭合）：工具输出面全英文，同一行混中英破坏「一词一物」。 */
+export const PROCESS_DOC_MARK = "[process doc: not a design basis]"
+
+/** 末尾汇总行（仅命令面）：N = 本次输出被判为过程档的行数；N = 0 不加（`grep` 面不加此形）。 */
+export const processDocSummary = (n) =>
+  `[process doc: ${n} of this output's lines come from process docs — not a design basis]`
+
+/** 行首 token 的字符帽（步骤 ①）：超过即成不了路径，该行跳过不解析。 */
+const MAX_TOKEN_CHARS = 260
+
+/**
+ * 档判据（一次调用内按档记忆：`Map<absoluteFile, boolean>`）。
+ * @param {string} absFile 档的绝对路径（grep 面 = 命中行的 `h.file`；命令面 = 盘上解析出的绝对路径）
+ * @param {Map<string, boolean>} [cache] 记忆表（缺省自建——不传就没有跳调用的记忆）
+ * @returns {boolean} 所属档在索引排除集内 ⇒ true；出辖（祖先链无 manifest）⇒ false（无档类可判）
+ */
+export function isProcessDocPath(absFile, cache) {
+  const key = String(absFile ?? "")
+  if (!key) return false
+  const memo = cache instanceof Map ? cache : new Map() // 缺省自建：一次调用内按档记忆
+  if (memo.has(key)) return memo.get(key)
+  const decl = declarationForTarget(key) // null = 出辖（场景：会话锚在无 manifest 的目录里跑检索）
+  const marked = decl ? isExcludedRelPath(key, decl, decl.root) : false
+  memo.set(key, marked)
+  return marked
+}
+
+/** 剥两侧成对引号（步骤 ①）——行首字段被引起来的输出很常见。 */
+function stripPairedQuotes(s) {
+  if (s.length < 2) return s
+  const first = s[0]
+  const last = s[s.length - 1]
+  if ((first === '"' && last === '"') || (first === "'" && last === "'")) return s.slice(1, -1)
+  return s
+}
+
+/**
+ * 行首路径 token（步骤 ①–③）。判不了 ⇒ null（调用方原样保留该行）。
+ * @param {string} line 输出行
+ * @returns {string|null}
+ */
+function headPathToken(line) {
+  const head = /^\S+/.exec(String(line ?? "").trimStart())
+  if (!head) return null // 空行 / 纯空白行
+  const raw = stripPairedQuotes(head[0])
+  if (!raw || raw.length > MAX_TOKEN_CHARS) return null
+  // ② 剥尾：内层 `grep` ∥ `rg` ∥ `findstr` 的 `path:12: text` 形与尾随冒号一并剥掉
+  const token = raw.replace(/[:\-]\d+[:\-]?$/, "").replace(/:+$/, "")
+  if (!token) return null
+  // ③ 预筛：不含 `/` `\` `.` 的字段不做盘上解析（`[stdout]:` ∥ `(exit code 0)` ∥ 纯数字过不了这一关）
+  if (!/[/\\.]/.test(token)) return null
+  return token
+}
+
+/**
+ * 盘上解析（步骤 ④）：驱动绝对形 → MSYS 形 → 相对基准 `base`，取**第一个在盘上存在**者。
+ * 三支都不存在 ⇒ null（= 判不了）。UNC（`\\server\share\…`）走驱动绝对形一支。
+ * @param {string} token 行进字段（已剥尾）
+ * @param {string} [base] 解析基准：`bash` 同步 = `ctx.cwd` ∥ 后台径 = entry 记下的 `cwd` ∥ `execute` = `baseDir`
+ * @returns {string|null}
+ */
+function resolveOnDisk(token, base) {
+  const candidates = []
+  if (/^[A-Za-z]:[\\/]/.test(token) || token.startsWith("\\\\")) {
+    candidates.push(token) // 驱动绝对形 ∥ UNC
+  } else {
+    // MSYS 形（`/c/teamcode/…`）在 win32 上 `isAbsolute` 也为真，会落成当前盘的 `/c/…`
+    // ⇒ 必须显式把首段 `^/([A-Za-z])/` 映射为 `X:/`，否则这一支恒不命中。
+    const msys = /^\/([A-Za-z])(\/.*)?$/.exec(token)
+    if (msys) candidates.push(`${msys[1].toUpperCase()}:${msys[2] ?? "/"}`)
+    else if (isAbsolute(token)) candidates.push(token) // POSIX 绝对形（`resolve` 对绝对参恒等，同一支）
+  }
+  if (base) candidates.push(resolve(String(base), token))
+  for (const c of candidates) if (existsSync(c)) return c
+  return null
+}
+
+/**
+ * 命令面打标（§6.28「命令输出面」六步，`bash` ∥ `execute` ∥ VSC 端 `bash` 共用）：
+ * 逐行取行首 token → 真解析到盘上 → 判归属 → 命中者行首加前缀（行其余部分原样）。
+ * N > 0 ⇒ 正文之后追加一行汇总；N = 0 ⇒ **原样返回入参**（一个字节不动，无空汇总行）。
+ *
+ * 纪律：不许按「看起来像路径」打标——解析不到盘上就不标（误标比不标更坏）。
+ *
+ * @param {string} text 输出文本
+ * @param {string} [base] 解析基准（见 `resolveOnDisk`）
+ * @returns {string}
+ */
+export function markProcessDocLines(text, base) {
+  const src = String(text ?? "")
+  if (!src) return src
+  const fileCache = new Map() // 档 → boolean
+  const tokenCache = new Map() // token → boolean（一次调用内按 token 记忆；不设解析上限）
+  let n = 0
+  const out = src.split("\n").map((line) => {
+    const token = headPathToken(line)
+    if (!token) return line
+    let marked = tokenCache.get(token)
+    if (marked === undefined) {
+      const abs = resolveOnDisk(token, base)
+      marked = abs ? isProcessDocPath(abs, fileCache) : false
+      tokenCache.set(token, marked)
+    }
+    if (!marked) return line
+    n += 1
+    return `${PROCESS_DOC_MARK} ${line}`
+  })
+  if (n === 0) return src
+  const body = out.join("\n")
+  return `${body}${body.endsWith("\n") ? "" : "\n"}${processDocSummary(n)}`
+}

package/tools/search.mjs

@@ -6,8 +6,12 @@ import {
   splitGlobPatterns,
   compileGlobMatchers,
   normalizeEOL,
-  IGNORED_DIRS,
 } from "./shared.mjs";
+// 排除名单单源（零依赖叶档 `../skip-dirs.mjs`——2026-10-27 四份名单合一）：旧名 `IGNORED_DIRS`
+// 退场，本档三处直接引 `SKIP_DIRS`（一词一物）。
+import { SKIP_DIRS } from "../skip-dirs.mjs";
+// 过程档标记（TOOLS.md §6.28）：命中行的**档**在索引排除集内 ⇒ 行首逐字前缀。只加可读信息，不改命中集。
+import { PROCESS_DOC_MARK, isProcessDocPath } from "./process-doc-mark.mjs";
 import { readFile, readdir, stat, lstat } from "node:fs/promises";
 import { join } from "node:path";
 
@@ -60,7 +64,7 @@ export const globTool = {
   },
 }
 
-/** Recursively traverse files, yield relative paths (skip IGNORED_DIRS) */
+/** Recursively traverse files, yield relative paths (skip SKIP_DIRS) */
 async function* walkFiles(dir, rel = "") {
   let entries
   try {
@@ -71,7 +75,7 @@ async function* walkFiles(dir, rel = "") {
   for (const e of entries) {
     // Skip ignored dirs AND symbolic links (symlinks to directories would cause infinite loops)
     if (e.isSymbolicLink()) continue
-    if (e.isDirectory() && IGNORED_DIRS.has(e.name)) continue
+    if (e.isDirectory() && SKIP_DIRS.has(e.name)) continue
     const relPath = rel ? `${rel}/${e.name}` : e.name
     if (e.isDirectory()) {
       yield* walkFiles(join(dir, e.name), relPath)
@@ -169,7 +173,7 @@ export const grepTool = {
         return
       }
       for (const e of entries) {
-        if (e.isDirectory() && IGNORED_DIRS.has(e.name)) continue
+        if (e.isDirectory() && SKIP_DIRS.has(e.name)) continue
         await walk(join(target, e.name), rel ? `${rel}/${e.name}` : e.name)
       }
     }
@@ -177,9 +181,14 @@ export const grepTool = {
     await walk(base, "")
     if (hits.length === 0) return "(no matches)"
 
+    // §6.28：一次调用一个档记忆表；命中行与上下文行都在原有文案前镀前缀（判据是**档**不是行——
+    // 不标则同一档的上下文行读起来像普通档的内容）。打标在 `truncate` 之前，不新增截断点。
+    const markCache = new Map()
+    const mark = (f) => (isProcessDocPath(f, markCache) ? `${PROCESS_DOC_MARK} ` : "")
+
     // No context: keep original path:line: content format
     if (!wantCtx) {
-      return truncate(hits.map((h) => `${h.file}:${h.line}: ${h.text}`).join("\n"))
+      return truncate(hits.map((h) => `${mark(h.file)}${h.file}:${h.line}: ${h.text}`).join("\n"))
     }
 
     // With context: matching lines use ':', context lines use '-' (like ripgrep); overlapping ranges in same file are merged and de-duplicated
@@ -197,7 +206,7 @@ export const grepTool = {
       }
       for (const l of [...lineSet].sort((a, b) => a - b)) {
         const sep = matchedLines.has(l) ? ":" : "-"
-        out.push(`${file}${sep}${l}${sep} ${lines[l - 1]}`)
+        out.push(`${mark(file)}${file}${sep}${l}${sep} ${lines[l - 1]}`)
       }
     }
     return truncate(out.join("\n"))

package/tools/shared.mjs

@@ -21,10 +21,33 @@ export const DESC = (name) => loadToolDoc(name)
 export const MAX_READ_LINES = 2000
 export const MAX_OUTPUT_CHARS = 200_000
 
+// ─── 写门 `ledger` 参数（2026-11-03 笔-账绑定批 · 设计档 §2.3「工具 schema 面」）───────────────
+// 描述单源：十二把入口工具的 `parameters.properties.ledger` 共用下面这一条（文面逐字 = 设计档 §2.3）。
+// 为什么放这里：同一个参数在十二处各写一遍 = 同一机制十二份描述，措辞一旦漂移，模型读到的规则就有十二版；
+// 而 `git` ∥ `manifest` ∥ `memory` 的差异只是各接一句「本工具的哪一径要号」——差异走后缀，不复制全文。
+// 为什么不进 `required`（决策 35）：`required` 是静态字面，而这十二把工具在两模式、子代理、出辖目标下共用；
+// 静态必填会让普通模式读到一条不成立的强制（写锁仅工程模式），也让子代理读到一条没人核的要求。
+// 机械强制在门（缺号即拒），schema 只负责让模型知道有这个参数；拒文因此是唯一教学面（决策 38）。
+export const LEDGER_PARAM_DESC = '本笔调用服务的在途台账号，`"#N"` 或 `"N"`；工程模式下父侧不带 = 拒'
+/** `git`：写型 action 要号、只读 action 不要（决策 37——枚举可判，不猜命令字面）。 */
+export const LEDGER_PARAM_DESC_GIT = LEDGER_PARAM_DESC
+  + '；只读 action（`diff` ∥ `status` ∥ `log` ∥ `show` ∥ `ls-remote` ∥ `blame` ∥ 各 `*Action:"list"`）不需传号'
+/** `manifest`：只有 `init` ∥ `write` 写项目内档（决策 39）。 */
+export const LEDGER_PARAM_DESC_MANIFEST = LEDGER_PARAM_DESC + '；仅 `init` ∥ `write` 要号，`read` 不要'
+/** `memory`：只有 `layer:"project"` 写项目内 `.thincoder/memory/**`（决策 39；`put` 缺省 `personal`）。 */
+export const LEDGER_PARAM_DESC_MEMORY = LEDGER_PARAM_DESC
+  + '；仅落 project 层的写型 action 要号：`layer:"project"`，或省略 `layer`、单条删除且 id 以 `project:` 开头（此时层由前缀定；`personal` ∥ `team` 落用户数据目录，不要号）'
+/** 写门 `project` 参数（2026-11-03 项目声明面批 · 设计档 §2.3「工具 schema 面」/ 决策 40）：项目根路径（带
+ *  `PROJECT-MANIFEST.json` 的那个目录）—— 台账按项目根算键，所以「传项目」就是把这个根传进来，零映射表。
+ *  五把可能缺定位参数的工具（`bash` ∥ `memory` ∥ `execute` ∥ `git` ∥ `manifest`）共用这一条（文面逐字 = 设计档
+ *  §2.3）；写盘七件不加——目标路径恒在。定位参数在场时以它为准，`project` 只补位；纯声明，不改执行目录。 */
+export const PROJECT_PARAM_DESC = '本笔调用服务的项目根——带 `PROJECT-MANIFEST.json` 的那个目录（绝对路径，或相对会话 cwd）；工程模式下父侧 `bash` ∥ `memory` 必带，`execute` ∥ `git` ∥ `manifest` 在定位参数缺位时必带。纯声明：不改执行目录（`bash` 仍在会话 cwd 执行，`workdir` 才是改执行目录的那个）。'
+
 const ENCODING_DETECT_MAX_TRIM = 3
 const SYNTAX_CHECK_TIMEOUT = 10000
 export const BASH_TIMEOUT_MS = 120_000
-export const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".turbo", "coverage"])
+// `IGNORED_DIRS` 退场（2026-10-27 四份名单合一）：单源 = `../skip-dirs.mjs` 的 `SKIP_DIRS`，
+// 消费面 `search.mjs` 直接引它（一词一物——同一集合不再两个名字）。
 
 /** SSRF guard: check if a hostname is private/internal. Shared by web.mjs and codemode.mjs.
  *  Returns TRUE for private hosts — callers block them. */

package/tools/ssh.mjs

@@ -12,9 +12,11 @@
  * 会话跨调用存活于池（非本档持有）；depth>0 排除（`agent/helpers.mjs` `SUBAGENT_TOOL_EXCLUSIONS`）。
  * 动态 import（W8 契约②：agent-tools 静态链达 node:sqlite——端壳静态闭包须保持零命中）。
  */
-import { DESC } from "./shared.mjs"
+import { DESC, LEDGER_PARAM_DESC } from "./shared.mjs"
+// `~` 展开单源（`touchedPaths` 钩子与传输件同一件叶子——`config.mjs` 已 import 同一处）。
+import { expandHome } from "../expand-home.mjs"
 
-export const SSH_ACTIONS = ["connect", "send", "read", "secret_input", "close", "list", "credentials", "forget"]
+export const SSH_ACTIONS = ["connect", "send", "read", "secret_input", "close", "list", "credentials", "forget", "put", "get"]
 
 /** 参数校验（缺必填 / 形错 ⇒ `Error: …`——不执行；§6.22 动作表逐动作必填面）。 */
 export function validateArgs(args) {
@@ -30,6 +32,19 @@ export function validateArgs(args) {
     return null
   }
   if (action === "list" || action === "credentials") return null
+  if (action === "put" || action === "get") {
+    // 两个传输动作 = 单文件（目录参数不收——递归归边界句）；主机 / 凭据全取会话记录值（S10）。
+    if (typeof args.localPath !== "string" || args.localPath.trim() === "") return `Error: ${action} requires localPath`
+    if (typeof args.remotePath !== "string" || args.remotePath.trim() === "") return `Error: ${action} requires remotePath`
+    if (args.protocol !== undefined && args.protocol !== null && args.protocol !== "" && args.protocol !== "scp" && args.protocol !== "sftp") {
+      return `Error: ${action} protocol must be "scp" (classic, the default) or "sftp"`
+    }
+    // S10「`put` 参数面没有 `host` / `user` / `port`」：传了就拒——静默忽略会让模型以为换了目标主机。
+    const stray = ["host", "user", "port"].filter((k) => args[k] !== undefined && args[k] !== null && args[k] !== "")
+    if (stray.length) {
+      return `Error: ${action} takes the host / user / port from the session — remove ${stray.join(" / ")} (the session already names the target host)`
+    }
+  }
   if (action === "forget") {
     if (typeof args.host !== "string" || args.host.trim() === "") return "Error: forget requires host"
     if (args.port !== undefined && args.port !== null && args.port !== "" && !Number.isFinite(Number(args.port))) {
@@ -50,18 +65,24 @@ export const sshTool = {
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: SSH_ACTIONS, description: "Action to run (one per call): connect | send | read | secret_input | close | list | credentials | forget." },
+      action: { type: "string", enum: SSH_ACTIONS, description: "Action to run (one per call): connect | send | read | secret_input | close | list | credentials | forget | put | get." },
       host: { type: "string", description: "connect / forget: target host (IP or name)." },
       user: { type: "string", description: "connect: login user (optional: your local ssh config decides, else the user recorded for this host locally)." },
       port: { type: "number", description: "connect / forget: TCP port (optional, default 22)." },
       label: { type: "string", description: "connect: short human label for this session (optional); secret_input: label for the value being sent." },
-      promptPattern: { type: "string", description: "connect: regex that marks the shell prompt as ready (optional): send/read then settle the moment the prompt appears instead of waiting out the silence window." },
-      id: { type: "string", description: "send / read / secret_input / close: session id from connect (`ssh#N`)." },
+      promptPattern: { type: "string", description: "connect: regex that marks the shell prompt as ready (optional; the default recognises lines ending in # > $ %): without a hit, send/read on a slow device wait out the full timeout instead of returning early." },
+      id: { type: "string", description: "send / read / secret_input / close / put / get: session id from connect (`ssh#N`)." },
       data: { type: "string", description: "send: text to type into the session (a trailing newline is passed as-is; otherwise Enter is sent as `\\r`)." },
       settle: { type: "boolean", description: "send: wait for the ready verdict before returning (default true); false returns right after the bytes are written." },
-      timeoutMs: { type: "number", description: "send / read: wait budget override (default 10000) — on expiry the call returns partial output with a readable line." },
-      maxChars: { type: "number", description: "read: return cap override (default 8000; the full output stays in the session log)." },
+      timeoutMs: { type: "number", description: "send / read: wait budget override (default 60000) — a return happens the moment the device is waiting for input (prompt, `--More--`, a y/n or password prompt); on expiry the call returns partial output plus a line naming what was not seen. put / get: transfer budget override (default 600000) — on expiry the process tree is killed." },
+      maxChars: { type: "number", description: "read: return-window override (default 8000) — head 60% + a note + tail 40%; the omitted middle is kept in the session, so the next read collects it." },
       identityFile: { type: "string", description: "connect: private-key path to offer (`-i`, `~` expands); remembered for this host and reused when omitted (optional)." },
+      localPath: { type: "string", description: "put / get: local file path (`~` expands; a file, never a directory)." },
+      remotePath: { type: "string", description: "put / get: path of the file on the session host (`/flash/img.bin`)." },
+      overwrite: { type: "boolean", description: "get only: replace an existing local file (default false — an existing target is refused, never overwritten silently). put follows scp's own semantics: a same-named remote file is replaced." },
+      protocol: { type: "string", enum: ["scp", "sftp"], description: "put / get: `scp` = classic SCP protocol, the default and what network devices speak; `sftp` = the SFTP subsystem, for hosts that only offer that. No automatic fallback between them." },
+      // 写门接面（⑬ ④）：`get` 往项目内落盘 ⇒ 与 `write` 同一道门——那一道门读的就是本参数。
+      ledger: { type: "string", description: LEDGER_PARAM_DESC + "；仅 `get` 要号，`put` 写的是远端主机，不要" },
     },
     required: ["action"],
   },
@@ -70,6 +91,19 @@ export const sshTool = {
   isReadonlyAction(args) {
     return args?.action === "list" || args?.action === "read" || args?.action === "credentials"
   },
+  // 写门接面（§6.22 ⑬ ④ · D-TO26）：只有 `get` 往本地落盘；其余动作不写项目内档。
+  // 钩子契约 = `agent/helpers.mjs` 的 `toolTouchPaths`（`const hook = tool?.touchedPaths`）——
+  // 光有这个钩子不够：门还要把 `ssh` 收进入口集并按 action 判要号，三处缺一不可。
+  // `~` 在这里就展开成绝对形：钩子拿不到 `ctx`（契约形 = `touchedPaths(args)`，`toolTouchPaths` 以 `hook(a)` 调用），
+  // 而各消费面都在其后按会话 cwd 归一（`resolve(agent.cwd, p)`；`agent.cwd` 即工具 ctx 的 `cwd`，见
+  // `agent/dispatch-run.mjs` 的 `toolCtx`）⇒ 原样回 `~/x` 会被拼成 `<项目>/~/x` 这个虚构路径，工程模式下
+  // `get` 到 `~`（本工具最常见的备份落点）因此被无故要号、判据点也不是真实落点。回 `expandHome` 的绝对形后，
+  // 消费面的 `resolve(agent.cwd, …)` 对它恒等 ⇒ 判据点 = 真实落点，与传输件起跑点同一件叶子（D2）。
+  // 空 ∥ 非字符串 ⇒ `[]`（不虚报——缺参由 execute 的 `validateArgs` 出可读句）。
+  touchedPaths(args) {
+    const localPath = String(args?.action ?? "") === "get" ? args?.localPath : null
+    return typeof localPath === "string" && localPath.trim() !== "" ? [expandHome(localPath)] : []
+  },
   async execute(args, ctx) {
     const invalid = validateArgs(args)
     if (invalid) return invalid
@@ -96,6 +130,13 @@ export const sshTool = {
       res = mod.credentialsSsh()
     } else if (action === "forget") {
       res = mod.forgetSsh({ host: args.host, port: args.port ?? null })
+    } else if (action === "put" || action === "get") {
+      // 传输面自成一件（非交互原语：无剥离 / 无就绪判据 / 无遮蔽——塞进会话件会把两套语义混在一档）。
+      const xfer = await import("../agent-tools/ssh-transfer.mjs")
+      res = await xfer.transferSsh(parent, ctx, {
+        action, id: args.id, localPath: args.localPath, remotePath: args.remotePath,
+        overwrite: args.overwrite === true, protocol: args.protocol ?? null, timeoutMs: args.timeoutMs,
+      })
     } else {
       res = mod.listSsh(parent)
     }

package/tools/tree.mjs

@@ -7,10 +7,13 @@
 import { DESC, truncate, resolveInCwd } from "./shared.mjs"
 import { readdir, stat } from "node:fs/promises"
 import { join, basename, extname } from "node:path"
+// 排除名单单源（零依赖叶档 `skip-dirs.mjs`——2026-10-27 四份名单合一）：本档不再持本地副本。
+// 两项旧值随之退场：`turbo`（无点，笔误——另三份都是 `.turbo`）、`bin`（`thincoder-cli/bin/**`
+// 是 CLI 入口、产品代码，不该从任何面上被剪掉）。
+import { SKIP_DIRS } from "../skip-dirs.mjs"
 
 const MAX_ENTRIES = 200
 const DEFAULT_DEPTH = 3
-const SKIP_DIRS = new Set(["node_modules", "bin", "obj", "dist", "build", "coverage", "turbo", ".git", ".thincoder", ".vs", ".venv", "__pycache__", ".idea"])
 const BINARY_EXTS = new Set([".exe", ".dll", ".png", ".jpg", ".jpeg", ".gif", ".pdf", ".docx", ".xlsx", ".pptx", ".zip", ".7z", ".mp3", ".mp4", ".woff", ".woff2", ".ico"])
 
 // ─── cwd 归一注入缝（#56——「cwd 归一开关按端注入」，形态参 §2.13.5 注入缝）─────────

package/tools/write-path.mjs

@@ -34,9 +34,9 @@ export function markDirty(abs) { dirtyPaths.add(abs) }
 export function clearDirty(abs) { dirtyPaths.delete(abs) }
 export function isDirty(abs) { return dirtyPaths.has(abs) }
 
-// 写入工具记录受影响行范围——insert_after 精确判定：after_line 在未受影响区
-// （< lastWrite.startLine）→ 行号未漂移 → 允许；受影响区内 → 拒绝（护栏保留）；
-// write 全文重写 → 全文件受影响，任何 after_line 拒绝。
+// 写入工具记录受影响行范围（受影响区 = 从 startLine 起、净漂移 shift 行）——行号锚护栏
+// 的数据源：目标区整体在受影响区之前 → 行号未漂移 → 允许；区内或其下 → 拒；
+// write 全文重写 → 全文件受影响，任何行号都拒。判据本体 = 下方 `lineAnchorVerdict`。
 const lastWrites = new Map() // abs → { type: 'write'|'edit'|'insert', startLine, shift }
 export function recordWrite(abs, write) {
   lastWrites.set(abs, write)
@@ -74,6 +74,67 @@ export function resetWritePath() { injected = null }
 export const dirtyRefusalMessage = (abs) =>
   `File has unsaved changes in the editor: ${abs}. Save or discard before allowing automated edits.`
 
+// ────────────────────────────────────────
+// 行号锚护栏（edit 行号形 ∥ insert_after 共用的唯一判据）
+// ────────────────────────────────────────
+/**
+ * 判据（六行按序判）：放行 ⇒ `null`；拒绝 ⇒ 命中行的实况
+ * `{ row, type?, startLine?, shift? }`（row = §7.1 的行号 1–6）。
+ *
+ * @param {string} abs 目标绝对路径（记账键）
+ * @param {number|null} startLine 目标区首行；`null` = 调用方没有行号目标（正则定位形）
+ * @param {number|null} endLine 目标区末行（单行形与 startLine 同值）
+ */
+export function lineAnchorVerdict(abs, startLine, endLine) {
+  const lw = lastWrites.get(abs)
+  const dirty = dirtyPaths.has(abs)
+  if (!lw) return dirty ? { row: 6 } : null // 行 1 放行 / 行 6 拒
+  if (dirty) return { row: 2, type: lw.type, startLine: lw.startLine, shift: lw.shift }
+  // 行 3–5 判的是「模型给的行号」，没有行号目标就无从判——只判到记账态这一层
+  if (startLine == null) return null
+  if (lw.type === "write") return { row: 3, type: "write" }
+  // 「整体在之前」的边界按记账类型分：替换要读也写目标行（`<`），插入只落在两行之间（`<=`）
+  const last = endLine ?? startLine
+  const untouched = lw.type === "insert" ? last <= lw.startLine : last < lw.startLine
+  if (untouched) return null // 行 4 放行
+  return { row: 5, type: lw.type, startLine: lw.startLine, shift: lw.shift }
+}
+
+/** 第 1 / 3 / 5 行的首句之后共用的三要素（两条下一步 + 第二条路的成立条件）。 */
+const LINE_ANCHOR_NEXT_STEPS =
+  `Editing by the old numbers would land on the wrong lines and still report success.\n` +
+  `Two ways on:\n` +
+  `  1. read this file again and retry with the new line numbers;\n` +
+  `  2. address the region without line numbers — pass its current content as old_string, or use hashline_edit,\n` +
+  `     which needs old_hashes from a read with hashes=true and is only valid while that block's content is unchanged.`
+
+/**
+ * 拒文（单点构造——edit 行号形与 insert_after 同句；四要素固定：路径与漂移事实 / 重 read /
+ * 改走位置无关寻址 / 那条路的成立条件）。事实取自 `lineAnchorVerdict`，不另算一份。
+ *
+ * 第 2 行（脏 ∧ 陈旧快照）与第 6 行（无快照但脏）报不出「上次写入点 + 漂移量」——首句改成
+ * 说清这两个数不可得，其余三要素不变（照填一个不可信的数字等于把它重新递给模型）。
+ */
+export function lineAnchorRefusal(abs, startLine, endLine) {
+  const hit = lineAnchorVerdict(abs, startLine, endLine)
+  if (!hit) {
+    throw new Error("lineAnchorRefusal: the call passes the line-anchor criterion — no refusal to build")
+  }
+  const range = startLine == null ? null : endLine == null || startLine === endLine ? `L${startLine}` : `L${startLine}-L${endLine}`
+  const head = hit.row === 2
+    ? `${abs} — these line numbers are stale, and the drift cannot be measured: a write in this session changed\n` +
+      `this file after the recorded write point, so neither that line nor an offset from it can be trusted.`
+    : hit.row === 6
+      ? `${abs} — this file was modified since your last read; line numbers may be stale, and there is no recorded\n` +
+        `write point to check them against.`
+      : hit.row === 3
+        ? `${abs} — these line numbers are stale: this file was rewritten in full by a write since your last read,\n` +
+          `so no line number from that read can still be trusted.`
+        : `${abs} — these line numbers are stale: the last write to this file was at L${hit.startLine}\n` +
+          `(line numbers are now offset by ${hit.shift >= 0 ? "+" : ""}${hit.shift}), and the target range ${range} falls inside or below it.`
+  return `${head}\n${LINE_ANCHOR_NEXT_STEPS}`
+}
+
 /**
  * 门禁单点（src 面与 dest 面共用——每面各问一次 `openDoc`）：
  * fail-closed（给了 `applyEdit` 却没给 `isDirty` ⇒ 脏态不可知 ⇒ 抛配置错，不静默退化为

package/traces/trace-store.mjs

@@ -222,11 +222,12 @@ export function recordChatTrace(provider, opts = {}, result = null, error = null
   const logCtx = opts.logCtx ?? {}
   if (!tracesEnabled(logCtx)) return
   // cwd/session 经 logCtx 增补（调用点传 agent.cwd / agent._sessionStart——
-  // D-TR3 的 cwdHash/命名与 D-TR1 的 session 字段所需）；无 agent 作用域的调用点
-  // 回退 process.cwd()——CLI 会话即工作区。该类点开关状态：distill 已含
+  // D-TR3 的 cwdHash/命名与 D-TR1 的 session 字段所需）；logCtx 未携 cwd（无 agent 作用域
+  // 的调用点）⇒ 该值缺失即失败，不回落进程 cwd（换界会静默写错会话目录）。
+  // 该类点开关状态：distill 已含
   // traces 开关（D-TR6 fix round1）；auto-think 已闭环（D-TS12——chat 调用点
   // logCtx 全字段补传：traces/session/cwd/role/depth/kind——无残留点）。
-  const cwd = logCtx.cwd ?? process.cwd()
+  const cwd = logCtx.cwd
   // D-TR3（fix round1）：分日按本地时区（_traceHooks.now——T-TR12 注入点）；
   // ts 与 dateStr 同源（同一时刻）——记录时间戳与目录日不撕裂。
   const now = _traceHooks.now()

package/agent/light-round.mjs

@@ -1,63 +0,0 @@
-/**
- * agent/light-round.mjs — 轻通道代码笔通路谓词（F-LC5 · 设计 = `docs/core/design/LIGHT-CHANNEL.md` §2.8）。
- *
- * `lightRoundOpen(agent)`：闸读判据——**两件双在盘**才算轻通道轮在盘：
- *   ① 轮次台账行：`status = 在途` ∧ `title` 携「收尾链待跑」（轮型标记 = 闸凭据）∧ `task_book` 非空；
- *   ② 该指针指向的轮次批档：`§1` 状态行 = 「进行中」（判定器单源 = `readBatchStatusLine`）。
- * 查找面（纯向下）= 会话锚 + 其直接子目录一层（候选枚举单源 = `ledgerChildren`——与族发现同级判据
- * 同源；不递归 ∥ 不取同胞）：逐候选查行 ∥ 以各候选为基解析指针（台账写门同式）。歧义候选
- * （`projectRootView` 判 `workspace`——如工作区锚自身）⇒ 跳过该候选、照查其余（既定观察态，非读错）；
- * 候选读错 ∥ 不可判 ⇒ 停本候选（总判不因他候选读错而失——开路凭据仍是「两件校验全过」）。
- * 语义：开门动作 ≡ 开轮两件落盘（「启动即挂账」本体——无独立于账的开门面）；单件不放行
- * （轮档独在 ∥ 行独在 ∥ 无标记 ∥ 行非在途 ∥ 指针失据 ∥ 档已收口 ⇒ 皆 false）；收口即自闭
- * （信号生命周期 = 账生命周期——零撤销动作 ∥ 零跨轮残留）。
- * 读错 ∥ 不可判 ⇒ `false`（fail-closed——照拦；被拦时文案不因读错而变）。
- * 只读：台账 = `ledgerQuery` **动态 import**（`ledger-db.mjs` 静态 import node:sqlite ⇒
- * 消费侧静态 import 破 W8 契约②）；批档 = 一次 `readFileSync`。
- */
-import { readFileSync } from "node:fs"
-import { resolve } from "node:path"
-import { projectRootView, resolveProjectRoot } from "../manifest.mjs"
-import { resolveDeclaredRef } from "../declaration.mjs"
-import { readBatchStatusLine } from "../agent-tools/batch-skeleton.mjs"
-
-/** 轻通道轮在盘谓词（异步 · 只读 · fail-closed）。契约见头注。
- * @param {object} agent — 会话 agent（读 `cwd`）
- * @returns {Promise<boolean>} true = 放行（在盘轮次）；读错 ∥ 不可判 ⇒ false（照拦）
- */
-export async function lightRoundOpen(agent) {
-  try {
-    const cwd = agent?.cwd
-    if (typeof cwd !== "string" || cwd.trim() === "") return false
-    // W8 契约②：node:sqlite 链只经动态 import 进入（勿升静态）——候选枚举与逐候选查行同取本档公共面。
-    const { ledgerChildren, ledgerQuery, ROUND_MARKER } = await import("../ledger.mjs")
-    const anchor = resolve(cwd)
-    // 候选面 = 锚自身 + 直接子目录一层（纯向下；子项枚举单源 = `ledgerChildren`）。
-    const candidates = [anchor, ...ledgerChildren(anchor).map((p) => p.root)]
-    for (const cand of candidates) {
-      // 工作区候选（下辖 ≥2 项目——`projectRootView`）⇒ 跳过、照查其余（工作区锚不充当项目 = AC-M2-19 同判；
-      // 该态判据 = 根推导单源「已注册」的库臂排除（键控库在盘 ≠ 可作项目）——既定观察态，非读错）。
-      if (projectRootView(cand).state === "workspace") continue
-      let rows
-      try { rows = ledgerQuery({ cwd: cand, status: "在途" }) } catch { continue } // 候选读错 ⇒ 停本候选
-      if (!Array.isArray(rows) || rows.length === 0) continue
-      // 指针基准 = 台账写门同式（`ledger-cmd.mjs` assertTaskBookGate 同一子表达式）——以各候选为基。
-      const base = resolveProjectRoot(cand) ?? resolve(cand ?? ".")
-      for (const row of rows) {
-        if (!String(row?.title ?? "").includes(ROUND_MARKER)) continue // 无标记 ⇒ 非轻通道轮（全链批行）
-        const taskBook = row?.task_book
-        if (typeof taskBook !== "string" || taskBook.trim() === "") continue // 缺指针 ⇒ 单件不放行
-        const part = taskBook.split("§")[0].trim() // 台账写门同式：首个 § 前子串
-        if (part === "") continue
-        const hit = resolveDeclaredRef(base, part)
-        if (!hit.ok) continue // 指针失据 ⇒ 不放行
-        let src
-        try { src = readFileSync(hit.abs, "utf8") } catch { continue } // 档读不到 ⇒ 不放行
-        if (readBatchStatusLine(src) === "open") return true // 两件双在盘 ⇒ 放行
-      }
-    }
-    return false
-  } catch {
-    return false // 读错 ∥ 不可判 ⇒ fail-closed（照拦）
-  }
-}