@thincoder/core 0.10.2 → 0.10.4

package/shell-identity.mjs

@@ -0,0 +1,107 @@
+/**
+ * shell-identity.mjs — bash 工具**执行器身份**探测单源（bash-executor-face 批 · 台账 #922——
+ * 设计权威 = `docs/core/design/BASH-EXECUTOR-FACE.md` §2 契约 + §3.1）。
+ *
+ * 探测源 = **spawn 同链镜像**（`tools/bash.mjs` spawn 的 `shell` 参数计算式）：
+ *   config.shell（trim 后非空即用）→ win32 %COMSPEC% → 兜底字面 `cmd.exe`；
+ *   非 win32 = `process.env.SHELL` → 兜底 `/bin/sh`（Node `shell:true` 兜底的事实陈述，非平台推断）。
+ * 探测值 = 实际执行器（不是环境快照）；探测不到（识别表未命中知名字）⇒ `unknown` 中性句
+ * （fail-open 零猜测——用户 2026-10-04 22:48 裁定③）；**零静态平台默认**（裁定①）。
+ *
+ * memo（进程生命周期 + 按配置值键控）先例 = `shell-candidates.mjs`（「shell 路径不热变化」同判据）；
+ * 配置值变化 ⇒ memo 未命中重探（K2 配置变更刷新 ∥ 裁定①零静态同时成立）。
+ * 测试缝 `_setComSpecForTest` 先例 = `shell-candidates.mjs:34` `_setShellDetectForTest`。
+ */
+
+// 识别表（raw 尾段词 → 显示名 + 语法族）。匹配大小写不敏感，尾段词先剥 `.exe` 后缀（U3——
+// `bash.exe` ∥ `cmd.exe` ∥ `pwsh.exe` 均须命中）；序 = 最特异优先：
+// `pwsh` 先于 `powershell`；`sh` 排末（防 `fish` 尾段误命中——fish 自目在前）。
+const IDENTITY_TABLE = Object.freeze([
+  { word: "pwsh", name: "PowerShell (pwsh)", kind: "powershell" },
+  { word: "powershell", name: "Windows PowerShell", kind: "powershell" },
+  { word: "cmd", name: "cmd.exe", kind: "cmd" },
+  { word: "bash", name: "bash", kind: "posix" },
+  { word: "wsl", name: "wsl", kind: "posix" },
+  { word: "fish", name: "fish", kind: "posix" },
+  { word: "zsh", name: "zsh", kind: "posix" },
+  { word: "sh", name: "sh", kind: "posix" },
+])
+
+/** 尾段词：raw 的最后一段非空词，剥尾 `.exe`（`C:\\...\\bash.exe` → `bash`；`pwsh` → `pwsh`）。 */
+function lastWord(raw) {
+  const parts = String(raw).trim().split(/[\\/:]+/).filter(Boolean)
+  const tail = parts[parts.length - 1] ?? ""
+  return tail.toLowerCase().replace(/\.exe$/i, "")
+}
+
+/**
+ * 探测执行器身份。`configShell` = spawn 侧同一取值（`ctx.agent?.config?.shell ?? null`）。
+ * 纯函数（不读环境外的状态；win32 分支内读 `%COMSPEC%`）；memo 按配置值键控。
+ * @param {string|null|undefined} configShell
+ * @returns {{ raw: string, name: string, kind: "cmd"|"powershell"|"posix"|"unknown", known: boolean }}
+ */
+export function resolveShellIdentity(configShell) {
+  const key = configShell == null ? null : String(configShell)
+  if (_memo.key === key) return _memo.value
+
+  // 链 = spawn 侧同式：config.shell trim 后非空即用 → 空/缺省时 win32 读 %COMSPEC%（兜底字面
+  // cmd.exe）∥ 非 win32 读 SHELL（兜底 /bin/sh）——探测值 = 实际执行器。
+  const trimmed = key == null ? "" : key.trim()
+  let raw
+  if (trimmed) {
+    raw = trimmed
+  } else if (process.platform === "win32") {
+    const comspec = _comSpecOverride !== null ? _comSpecOverride : process.env.ComSpec
+    raw = comspec && comspec.trim() ? comspec : "cmd.exe"
+  } else {
+    const shell = process.env.SHELL
+    raw = shell && shell.trim() ? shell : "/bin/sh"
+  }
+
+  const lw = lastWord(raw).toLowerCase()
+  // pwsh 分流总则（设计档 §2）：powershell 族值面按 raw 尾段词命中 /pwsh/i 分流——
+  // 命中 ⇒ pwsh 形；未命中 ⇒ Windows PowerShell（5.x）形。kind 枚举不动（识别表单目）。
+  const pwshForm = /pwsh/i.test(lw)
+  const hit =
+    IDENTITY_TABLE.find((e) => lw === e.word) ??
+    (pwshForm ? null : IDENTITY_TABLE.find((e) => lw.endsWith(e.word)))
+  const value = hit
+    ? { raw, name: hit.name, kind: hit.kind, known: true }
+    : { raw, name: raw, kind: "unknown", known: false }
+  _memo.key = key
+  _memo.value = value
+  return value
+}
+
+/** memo（进程生命周期 ∕ 按配置值键控——本档单点持有）。 */
+const _memo = { key: undefined, value: null }
+
+/** 测试缝：注入 %COMSPEC% 读数（undefined = 复位真实环境读数）；注入即清 memo。 */
+let _comSpecOverride = null
+export function _setComSpecForTest(value) {
+  _comSpecOverride = value === undefined ? null : value
+  _memo.key = undefined
+  _memo.value = null
+}
+
+/**
+ * kind ⇒ 注入值面（一行 Executor 声明 · 设计档 §2 值面表逐字）。powershell 族按 raw 尾段词
+ * `/pwsh/i` 分流（pwsh 形 ∥ Windows PowerShell 5.x 形）；identity.kind 为 unknown ⇒ 中性句。
+ * @param {{ raw: string, name: string, kind: string, known: boolean }} identity resolveShellIdentity 出参
+ * @returns {string}
+ */
+export function executorLine(identity) {
+  const { raw, name, kind } = identity
+  switch (kind) {
+    case "cmd":
+      return "- Executor: the bash tool runs commands through Windows cmd.exe (%COMSPEC%). Use cmd syntax: && works; NUL not /dev/null; %VAR% not $VAR; no single-quote grouping. For complex logic prefer the execute tool (node)."
+    case "powershell":
+      return /pwsh/i.test(lastWord(raw))
+        ? `- Executor: the bash tool runs commands through PowerShell (pwsh; ${raw}). && and || work; %VAR% does not expand (use $VAR); cmdlets differ (Remove-Item, Copy-Item). For complex logic prefer the execute tool (node).`
+        : `- Executor: the bash tool runs commands through Windows PowerShell (${raw}). PS 5.1 has NO &&/|| (use ; or separate calls); redirection differs (2>/dev/null is invalid); cmdlets differ (Remove-Item, Copy-Item). For complex logic prefer the execute tool (node).`
+    case "posix":
+      return `- Executor: the bash tool runs commands through a POSIX shell (${raw}). Standard POSIX syntax applies ($(...), $VAR, ;, >/dev/null).`
+    default:
+      return `- Executor: the bash tool shell could not be identified (raw: ${raw}) — write portable commands and trust the command's own error output.`
+  }
+}

package/stream-destroy.mjs

@@ -0,0 +1,62 @@
+/**
+ * stream-destroy.mjs — response body 终止守卫（单一权威源——PROXY.md §2 ∥ §7 D-PX7）
+ *
+ * 无监听者瞬间的 `destroy(err)` 会 emit 未处理 'error' ⇒ uncaughtException ⇒ 整个进程被杀
+ * （2026-09-22/23 三份 crash-report 签名 = `Response body timeout (idle)`，栈 = proxy.mjs
+ * 看门狗；GitHub #16）。`destroyBody(body, err)` 在终止前先挂**永久** no-op `'error'`
+ * 监听者——pipe 内部监听者触发即自摘后的重发同样被兜住；消费面语义零变（在场 ∥ 迟到
+ * `for-await` 消费者仍收原错误；`stream.errored` 保留原错误对象）。
+ *
+ * 契约四则（PROXY.md §2）：
+ * ① body 空 ∥ 非 destroy 形态（web `ReadableStream`）∥ 已 `destroyed` ⇒ 显式返回（no-op）；
+ * ② 首次调用挂永久 no-op 'error' 监听者（一次性标记防重复挂）；
+ * ③ 再 `destroy(err)`——原错误对象直传；
+ * ④ 禁 `listenerCount('error') === 0` 预检（pipe 监听者使计数失真——触发即自摘后重发）。
+ *
+ * 内部 abort 通道（2026-10-04 · #878 D-PX8）：直连 fetch 的 body = web `ReadableStream`（无
+ * `destroy`——本档形态①的 no-op 面）。断流改经 `IDLE_ABORT` 符号挂载的 `AbortController`：
+ * `terminateBody(response, err)` 对挂通道者 `controller.abort(err)`（body 随之中止）；无通道回落
+ * `destroyBody`（原契约零变）。建设点 = `proxy.mjs` `proxyFetch` 直连分支单点。
+ *
+ * 零 import——proxy ∥ provider 消费点共用（无环）。
+ */
+
+/** 一次性标记（模块私有 Symbol——不占 body 公开面）。 */
+const GUARDED = Symbol("thincoder.destroyBody.guarded")
+
+/**
+ * 终止 body，且未处理 'error' 不逃逸到进程（契约四则见档头）。
+ * @param {import("node:stream").Stream} body — response body（PassThrough）；
+ *   web `ReadableStream`（无 destroy）⇒ 显式 no-op
+ * @param {Error} err — 原错误对象（直传 destroy）
+ */
+export function destroyBody(body, err) {
+  if (!body || typeof body.destroy !== "function" || body.destroyed) return
+  if (!body[GUARDED]) {
+    body[GUARDED] = true
+    body.on("error", () => {})
+  }
+  body.destroy(err)
+}
+
+/** 内部 abort 通道符号（#878 D-PX8——直连 fetch 响应的断流通道；module-private 语义面）。 */
+export const IDLE_ABORT = Symbol("thincoder.idleAbort")
+
+/**
+ * body 终止分流单点（#878）：
+ * - response 挂有 `IDLE_ABORT`（直连 fetch——web `ReadableStream`）⇒ `controller.abort(err)`
+ *   （读循环随之终结；原错误对象即 abort reason——undici 以该对象拒读）；
+ * - 否则回落 `destroyBody(response.body, err)`（proxy PassThrough ∥ 无通道 web 流——原契约零变）。
+ * response 缺位 / 无 body ⇒ no-op 不抛（幂等——二次调用对 AbortController 原生安全）。
+ * @param {Response|{body?: import("node:stream").Stream}} response
+ * @param {Error} err — 原错误对象（abort reason ∥ destroy 直传）
+ */
+export function terminateBody(response, err) {
+  if (!response) return
+  const controller = response[IDLE_ABORT]
+  if (controller) {
+    controller.abort(err)
+    return
+  }
+  destroyBody(response.body, err)
+}

package/tool-docs/advisor.md

@@ -1,4 +1,4 @@
-Run an independent review of your work. `type` is REQUIRED — one of exactly two values: 'design' reviews design / requirement documents BEFORE implementation (documents=[...] with the explicit doc paths; plus batchDoc when a batch record is in flight); 'code' reviews the code you changed AFTER implementation (paths=[...] to scope files/directories; documents=[...] adds acceptance-criteria context). A call without a type (or with a conflicting object.type) is refused — no default, no silent fallback.
+Run an independent review of your work. `type` is REQUIRED — one of exactly two values: 'design' reviews design / requirement documents BEFORE implementation (documents=[...] with the explicit doc paths — relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/…, or absolute; relative forms are also tried against the session cwd's ancestor directories); plus batchDoc when a batch record is in flight); 'code' reviews the code you changed AFTER implementation (paths=[...] to scope files/directories; documents=[...] adds acceptance-criteria context). A call without a type (or with a conflicting object.type) is refused — no default, no silent fallback.
 
 The advisor is an independent read-only sub-agent (explores the codebase, reads files, traces callers via grep/lsp). Code review converges: round 1 full review → round 2 verifies the agent's fix claims → round 3+ re-checks only the fix claims. Design review is a single pass against methodology and requirements. Criteria come from .thincoder/advisor.md (if present) or sensible defaults. After the review you MUST produce a response table (format = discipline rules); on all-clear, call verify.
 

package/tool-docs/bash.md

@@ -30,7 +30,7 @@ Notes:
 - The environment sets GIT_PAGER=cat, PAGER=cat, EDITOR=true, TERM=dumb — but still always use non-interactive flags
 - Output is capped at ~200K chars; if you need more, redirect to a file and read it. Truncated output ends with a `[... truncated: N chars omitted]` marker — the missing tail may contain errors, so read the saved log file's tail before trusting success. Use `filter` to narrow instead of hand-piping.
 - Check `[stderr]` for error messages, warnings, and diagnostic output — it is separated from `[stdout]` so you can quickly identify problems.
-- On Windows the shell is **cmd.exe** (NOT Git Bash, NOT PowerShell): `&&`/`||` chaining works, use cmd built-ins (`del`, `dir`, `type`, `findstr`, `tasklist`) and `/dev/null`→`NUL`, `2>/dev/null`→`>nul 2>&1`. Bash-isms (`rm -rf`, `cp -r`, `head`, `$(...)`, `${VAR}`, single quotes, `;` separators) FAIL — the tool prepends a hint when it detects POSIX-only syntax, and still executes. For complex logic prefer the execute tool (node) over shell gymnastics.
+- Shell identity: the bash tool's shell is NOT fixed — it depends on configuration and environment. The current executor is declared in the Executor line above; write commands for THAT shell, and when a command fails read its error output to identify the actual shell.
 - Never use bash to read, copy, or transmit secret files (.env, keys, tokens)
 - Do NOT run destructive commands (rm -rf, force-push, drop table) without explicit user confirmation
 - After commands that change files (git checkout, npm install, etc.), repo_outline and code_search may be stale — re-run them to get current results.

package/tool-docs/batch.md

@@ -1 +1 @@
-Batch-record lifecycle tool (一段一作者 — six append-only sections, one author each). actions: create (depth-0 only — write a new six-section skeleton record; pass path + topic + source) · append (add text to the END of YOUR section — existing lines are never rewritten or deleted) · status (update YOUR section's `**状态行**：` line — the value must carry exactly ONE legal keyword of your section's STATUS_WORDS entry, decorated only by surrounding symbols / a trailing ISO date / whitespace; prose goes to the separate `note` field, which lands as a parenthetical) · close (depth-0 only — freeze the record: §1 → 「已收口 <date>」, every further write is refused). Identity fixes what you may write (段白名单): main agent (depth 0) — append §1/§4/§6, status §1 only, create/close; eng-designer — §2; eng-coder — §5; design review (review binding) — §3. A write outside your own section is refused. Skeleton placeholders (dead literals — `#<编号>` / `<板块>` and the older `<BATCH-ID>` / `<讨论来源>`) in the record header or in your target section block append/status: fill them first (the main agent fills the header right after create); `<§N 模板占位：…>` template lines are legal and never blocked. Target record: sub-agents and design reviews have NO path parameter in practice — the record arrives via the spawn binding / the review instance key (passing path is refused); depth-0 MAY pass path (若传则须可读), omitting it picks the unique in-flight record (0 or ≥2 in flight ⇒ refuse — pass path). A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). Credential values are stripped mechanically before writing (never write a token or designId value). Failures are hard and visible (no silent fallback): if a write is refused or fails, say so in your report — “§× 未写入”.
+Batch-record lifecycle tool (一段一作者 — six append-only sections, one author each). actions: create (depth-0 only — write a new six-section skeleton record; pass path + topic + source, plus optional ledger / board that fill the record's 台账 header line at creation) · append (add text to the END of YOUR section — existing lines are never rewritten or deleted) · status (update YOUR section's `**状态行**：` line — the value must carry exactly ONE legal keyword of your section's STATUS_WORDS entry, decorated only by surrounding symbols / a trailing ISO date / whitespace; prose goes to the separate `note` field, which lands as a parenthetical) · close (depth-0 only — freeze the record: §1 → 「已收口 <date>」, every further write is refused). Identity fixes what you may write (段白名单): main agent (depth 0) — append §1/§4/§6, status §1 only, create/close; eng-designer — §2; eng-coder — §5; design review (review binding) — §3. A write outside your own section is refused. Skeleton placeholders (dead literals — `#<编号>` / `<板块>` and the older `<BATCH-ID>` / `<讨论来源>`) in the record header's structural lines block append/status until filled: create with ledger / board fills them at creation; if omitted, the main agent fills the header by file edit right after create (citing these literals in a section's prose is fine — only the header is checked); `<§N 模板占位：…>` template lines are legal and never blocked. Target record: sub-agents and design reviews have NO path parameter in practice — the record arrives via the spawn binding / the review instance key (passing path is refused); depth-0 MAY pass path (若传则须可读), omitting it picks the unique in-flight record (0 or ≥2 in flight ⇒ refuse — pass path). A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). Credential values are stripped mechanically before writing (never write a token or designId value). Failures are hard and visible (no silent fallback): if a write is refused or fails, say so in your report — “§× 未写入”.

package/tool-docs/delete.md

@@ -1,13 +1,15 @@
-Delete a file. Use when the agent created a temporary or junk file that should be cleaned up, or when the user explicitly asks to delete something. Refuses to delete git-tracked files as a safety measure — tracked files should be edited or removed via bash with explicit user confirmation.
+Delete a file, or an empty directory. Use when the agent created a temporary or junk file or empty directory that should be cleaned up, or when the user explicitly asks to delete something.
+Refuses to delete git-tracked files as a safety measure — tracked files should be edited or removed via bash with explicit user confirmation.
 
-**Route to delete instead of bash:** `del file` / `rm file` → delete (single files). Use bash `rm -rf` only for directories (delete is single-file).
+**Route to delete instead of bash:** `del file` / `rm file` → delete (single files); an empty directory → delete (empty directories only). Non-empty directories have no delete path — stop and report to the user instead of hand-rolling a recursive shell delete.
 
 Parameters:
-- path (required): File path, relative to cwd or absolute
+- path (required): File or empty-directory path, relative to cwd or absolute
 - force: Allow deleting git-tracked files (default false)
 
 Notes:
 - Untracked or non-git files are deleted immediately
 - Tracked files require force=true (user must confirm separately)
-- Directories must be removed with bash (rm -rf)
-- Returns `Deleted <path>` (or `Error: ...` on failure/tracked refusal).
+- Directories: empty ones only — a non-empty directory is refused (a natural fuse; nothing recursive is ever removed); delete nested empty trees bottom-up
+- Symbolic links are removed as links — the link itself is deleted, never followed (its target is untouched)
+- Returns `Deleted <path>` (or `Error: ...` on failure / tracked / non-empty refusal).

package/tool-docs/ledger.md

@@ -0,0 +1,6 @@
+台账统一入口——action = add / update / close / query / count。query / count 只读全角色；add / update / close 写仅主 agent。
+- add：新增条目入待讨论。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）。
+- update：按六态允许表迁移：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外拒。status 缺省 = 仅更新字段。
+- close：勾销（待核销 → 已核销）；追认核销（待讨论 / 待设计 → 已核销，须有 evidence）；在途 → 已核销 不可跳；撤回（任意态 → 已废弃）。软删除（写 closed_at，行保留）。
+- query：SQLite 行集，过滤缺省 = 全部行。六态 = 待讨论 / 待设计 / 在途 / 待核销 / 已核销 / 已废弃。
+- count：未决四态（待讨论 / 待设计 / 在途 / 待核销）COUNT(*)。

package/tool-docs/subagent.md

@@ -18,6 +18,16 @@ Available roles (exposed per mode; the role is REQUIRED for action:'spawn' — a
 - eng-coder — engineering mode only (replaces coder): same toolset plus the design-driven methodology overlay; its delivery protocol (implementation → audit → self-fix → advisor re-review → converged delivery) runs fully inside the child. REQUIRES a valid designToken from a passed advisor(type='design') review (its reply also echoes a designId — pass it: required to pick between concurrent designs, optional for one; echo it back in the delivery report). REQUIRES a batchDoc — the batch record path, the task book this spawn implements (refused without it or when it does not resolve to a readable file).
 - eng-designer — engineering mode only: the SOLE author of the requirements/design documents and of the batch record's design section. Writes no implementation code, does not edit prompts, does not fire reviews, needs NO designToken. Surveys on its own; may only spawn read-only explore children (sync, ≤6 per batch). REQUIRES a batchDoc (same gate as eng-coder).
 
+Task book (eng-coder / eng-designer spawns — six mandatory fields): 目标与理由 (goal & why), round (initial|fix — the structured parameter), 已知事实 (known facts), 设计要点与禁止范围 (design points & forbidden scope), 验收标准 (acceptance criteria), 交付报告格式 (delivery-report format). Keep the labels (Chinese or the English equivalents) — the gate matches these markers; a missing field is a dispatch defect and the spawn is refused.
+
+Copy this skeleton verbatim into every task book — fill the blanks, do not relabel the six lines:
+**目标与理由**：…
+**round**：initial | fix（此字段=结构化参数——spawn 时同时传 `round`）
+**已知事实**：…
+**设计要点与禁止范围**：…
+**验收标准**：…
+**交付报告格式**：…
+
 Mode filtering: normal mode exposes explore/plan/coder; engineering mode exposes explore/eng-designer/eng-coder — off-mode roles are refused mechanically (enums filtered at assembly; the spawn gate re-checks).
 
 Async spawn: top-level spawns are async by default — never pass async:false at depth 0 (the spawn returns {id, status:"running"} immediately; the report arrives automatically; if your next step needs it, end the turn and let the digest deliver it — do not poll; the explicit async:false is a mechanism parameter, not for model use). Inside subagents (depth>0) spawns are always synchronous. Async spawns are pooled per role domain — 4 concurrent eng-coders plus 4 concurrent other-role spawns by default (agent.poolLimits overrides both); a full domain queues further spawns with a position while the other keeps starting.

package/tool-docs/verify.md

@@ -1 +1 @@
-Generic pre-completion verification gate — language/framework/project agnostic. verify does NOT run any test/verification command for you and does NOT require a test per change. You DECLARE your verification status via the verification argument ({ status: 'passed' | 'failed' | 'skipped', command?, summary? } — effects per parameter): the declaration is self-reported evidence — verify only mechanically gates on it ('passed' → allowed; 'failed' → blocked; 'skipped' → allowed but needs a reason). Whether/how to verify is described in natural language in the project's AGENTS.md and is decided + executed by you. The report also carries the changed files (git diff), an advisory node --check hint on changed .js/.mjs (not gating), the task list, and a self-review checklist. Call this BEFORE declaring a coding task complete — do not say 'done' until verify passes.
+Generic pre-completion verification gate — language/framework/project agnostic. verify does NOT run any test/verification command for you and does NOT require a test per change. You DECLARE your verification status via the verification argument ({ status: 'passed' | 'failed' | 'skipped', command?, summary?, basis? } — effects per parameter): the declaration is self-reported evidence — verify only mechanically gates on it ('passed' → allowed; 'failed' → blocked; 'skipped' → allowed but needs a reason). 'basis' (optional) is the 'what it stands on' dimension of the declaration — a judgment source, a read file:line coordinate, or an explicit 'unverified' (declaration-only: no format is enforced or machine-checked); a passed / skipped declaration with no basis gets one advisory hint line in the report — never blocking and never changing the gate — while the failed face gets no basis hint (already blocked). Whether/how to verify is described in natural language in the project's AGENTS.md and is decided + executed by you. The report also carries the changed files (git diff), an advisory node --check hint on changed .js/.mjs (not gating), the task list, and a self-review checklist. Call this BEFORE declaring a coding task complete — do not say 'done' until verify passes.

package/tools/bash.mjs

@@ -9,6 +9,7 @@ import { spawn } from "node:child_process";
 // 树杀单源（台账 #208② · TOOLS.md §6.14 落位表行 2）：本地副本删除——改用 `./process-tree.mjs`
 // （行为逐字同：win32 `taskkill /T /F` · POSIX 组杀 + 直杀兜底）。
 import { killProcessTree } from "./process-tree.mjs";
+import { resolveShellIdentity } from "../shell-identity.mjs";
 
 /** Maximum buffer size per stream (stdout / stderr) before truncation */
 const MAX_STREAM_BUF = 2_000_000
@@ -24,8 +25,10 @@ function applyLineFilter(output, filter) {
 
 /** POSIX-only constructs that cmd.exe reads literally (and thus breaks). Detected
  *  so the agent is told IMMEDIATELY instead of chasing a confusing failure — warning
- *  only, never a block (the approval layer is the real gate, same as destructive-command policy). */
-function posixSyntaxHint(command) {
+ *  only, never a block (the approval layer is the real gate, same as destructive-command policy).
+ *  身份门（bash-executor-face 批）：kind === cmd 才产出——PS/POSIX 执行器不再喊 cmd.exe
+ *  （态 4 实锤：hint 无身份门 = 同族缺陷）；提示语引用探测名（非死写）。 */
+function posixSyntaxHint(command, shellName) {
   const hits = []
   if (/\$\([^)]*\)/.test(command)) hits.push("$(...)")
   if (command.includes("`")) hits.push("backtick")
@@ -34,7 +37,7 @@ function posixSyntaxHint(command) {
   if (/'.*'/.test(command)) hits.push("single quotes (cmd.exe doesn't group)")
   if (/\$\{[A-Za-z_]/.test(command)) hits.push("${VAR} (use %VAR%)")
   if (!hits.length) return ""
-  return "[hint: POSIX-only construct(s) detected — " + hits.join(", ") + ". Current shell is cmd.exe; these will NOT work. Use && / NUL / %VAR%, or use the execute tool (node) for complex logic]"
+  return "[hint: POSIX-only construct(s) detected — " + hits.join(", ") + ". Current shell is " + shellName + "; these will NOT work. Use && / NUL / %VAR%, or use the execute tool (node) for complex logic]"
 }
 
 
@@ -256,7 +259,9 @@ export const bashTool = {
     // the wide matcher also covers variants like `git checkout HEAD -- .`).
     // 前置两件（guard ∥ hint）同步 ∥ 后台两径同保留（#9）。
     const guard = await gitGuardSnapshot(args.command, ctx.cwd)
-    const hint = posixSyntaxHint(args.command)
+    // hint 身份门：只有 cmd 执行器产出 POSIX-only 提示（PS/POSIX 下该提示误导——态 4）。
+    const identity = resolveShellIdentity(ctx.agent?.config?.shell ?? null)
+    const hint = identity.kind === "cmd" ? posixSyntaxHint(args.command, identity.name) : ""
     if (args.async === true) {
       // depth 第二道（schema 主门 = agent/helpers.mjs excludeSubagentTools 删参——异步面只到
       // 子代理实装亦拒：留一条显式文案，不静默转同步）。

package/tools/edit-batch.mjs

@@ -23,7 +23,8 @@ import { assertEditArgsExclusive, assertEditsContainer, assertEditEntries, valid
 
 /**
  * Apply the `edits` array form: multi-file atomic replacement. Throws on any
- * failure (atomic — nothing written). Returns the per-entry result text (joined).
+ * failure (atomic — nothing written). Returns the per-entry result text (joined)
+ * + the constant batch summary line at the end (#796 — EDIT.md §5).
  */
 export async function applyEditBatch(args, ctx) {
   assertEditsContainer(args.edits)
@@ -105,7 +106,11 @@ export async function applyEditBatch(args, ctx) {
       note: p.note,
     }))
   }
-  return results.join("\n")
+  // #796（核面小修批——EDIT.md §5 批量回执汇总行 ∥ §8 D-9）：末行**恒为**汇总行——大回执
+  // （>64K）落盘后双端 preview 保尾（TOOL-OUTPUT-LIMITS.md §2）⇒ 汇总结论恒可见；N = 条目数
+  // （全判后原子写 ⇒ 成功恒 N/N）；路径 = 条目原样形、去重保序首现序（groups 插入序即首现序）。
+  const summary = `edit batch: ${args.edits.length}/${args.edits.length} entries — ${[...groups.values()].map((g) => g.path).join(", ")}`
+  return [...results, summary].join("\n")
 }
 
 // ---------------------------------------------------------------------------

package/tools/index.mjs

@@ -60,7 +60,6 @@ export async function assembleBuiltinTools({ memory, cwd, projectDir = null, aut
   const { repoOutlineTool } = await import("./repomap.mjs");
   const { settingsTool } = await import("../agent-tools/settings.mjs");
   const { peerInstancesTool } = await import("../peer-instances.mjs");
-  const { ledgerQueryTool, ledgerCountTool } = await import("../ledger.mjs"); // 动态 import（ledger 链静态达 node:sqlite——W8 契约②）
   const imageOk = Boolean(specForModel(model)?.multimodal);
   return [
     ...builtinTools,
@@ -72,8 +71,6 @@ export async function assembleBuiltinTools({ memory, cwd, projectDir = null, aut
     repoOutlineTool(memory?.db, cwd),
     settingsTool(),
     peerInstancesTool,
-    // 台账查询命令族（M2 设计 §2.2 命令面接线——查询命令全角色面；写命令住 family-tools depthOnly 分支）
-    ledgerQueryTool,
-    ledgerCountTool,
+    // 台账工具面（统一入口 `ledger`——含读二）随家族段 `agent/family-tools.mjs`（2026-10-05 统一入口批：本基集清零）
   ];
 }

package/tools/patch.mjs

@@ -254,7 +254,7 @@ export const deleteTool = {
   parameters: {
     type: "object",
     properties: {
-      path: { type: "string", description: "File path (relative to cwd or absolute)" },
+      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)" },
     },
     required: ["path"],
@@ -269,7 +269,13 @@ export const deleteTool = {
     } catch {
       throw new Error(`File not found: ${args.path}`)
     }
-    if (s.isDirectory()) throw new Error(`"${args.path}" is a directory — use bash to remove directories`)
+    if (s.isDirectory()) {
+      try { await writeThroughPath(abs, null, { op: "rmdir" }) } catch (e) {
+        if (e?.code !== "ENOTEMPTY" && e?.code !== "EEXIST") throw e
+        throw new Error(`"${args.path}" is a directory and is not empty — only empty directories can be deleted (nothing recursive is ever removed). Remove the contents first (delete bottom-up for nested empty directories).`)
+      }
+      return `Deleted ${args.path}`
+    }
     // git-tracked files: refuse direct deletion (safety net); untracked: allow
     // Use resolved relative path (normalized forward slashes) to prevent backslash/unusual paths from bypassing ls-files matching
     const rel = relative(ctx.cwd, abs).replace(/\\/g, "/")

package/tools/write-path.mjs

@@ -19,7 +19,7 @@
  * 记账**（两段式全部成功后由调用方一次 `markDirty`——批级语义，与改前逐字同）。`file.mjs` 只做
  * 再导出，保既有 import 面稳定（模块拆分写优先纪律）。
  */
-import { writeFile, unlink, rename, cp, rm } from "node:fs/promises"
+import { writeFile, unlink, rename, cp, rm, rmdir } from "node:fs/promises"
 
 /** apply_patch 两段式的暂存后缀（单点定义——阶段一落暂存档、阶段二提交、失败清理均用它）。 */
 export const TMP_SUFFIX = ".thincoder-tmp"
@@ -106,7 +106,7 @@ async function tryInjectedPath(abs, content, meta) {
   if ((op === "move" || op === "rename" || op === "copy") && typeof meta.dest === "string" && meta.dest.length > 0) {
     gateOpenDoc(impl, meta.dest) // dest 面过门禁（覆盖目标档——与 src 同源拒写判据）
   }
-  // 编辑器径只承载**内容写点**（op="write"）；delete / 路径操作（copy/move/rename）与
+  // 编辑器径只承载**内容写点**（op="write"）；delete / rmdir / 路径操作（copy/move/rename）与
   // commit（默认径两段式的收尾）无端侧载体 ⇒ 门禁过后回默认径。
   if (!doc || op !== "write") return null
   if (typeof impl.applyEdit !== "function") return null
@@ -120,7 +120,7 @@ async function tryInjectedPath(abs, content, meta) {
  * 默认径（无注入面 / 注入面未处理）——**CLI 语义，零行为变**。
  *
  * meta:
- *   · `op`     "write"（默认）| "delete" | "copy" | "move" | "rename" | "commit"
+ *   · `op`     "write"（默认）| "delete" | "rmdir" | "copy" | "move" | "rename" | "commit"
  *   · `record` op="write"：写后记账快照（recordWrite 第二参——受影响区）
  *   · `dest`   op ∈ {copy, move, rename}：目标绝对路径
  *   · `stage`  op="write"：落到 `<abs>.thincoder-tmp`（**不提交、不记账**）——apply_patch
@@ -149,6 +149,8 @@ async function defaultPath(abs, content, meta) {
       markDirty(abs)
       return { written: true, via: "fs" }
     }
+    // #943：空目录移除（非空 ENOTEMPTY 上抛——调用面译拒）；不记 dirty（目录无行号语义）。
+    case "rmdir": { await rmdir(abs); return { written: true, via: "fs" } }
     case "copy": {
       await cp(abs, meta.dest, { recursive: true, force: true })
       return { written: true, via: "fs" }
@@ -174,7 +176,7 @@ async function defaultPath(abs, content, meta) {
  * 核内**单一写路径点**——全部工具写点经此落盘。
  *
  * @param {string} abs 目标绝对路径
- * @param {string|null} content 写入内容（op="write" 必填；delete / copy / move / rename 传 null）
+ * @param {string|null} content 写入内容（op="write" 必填；delete / rmdir / copy / move / rename 传 null）
  * @param {object} [meta] 见 defaultPath 的字段表
  * @returns {Promise<{written: boolean, via: "editor"|"fs"|"staged"|"committed"}>}
  *   `via` = 实际落盘径（"editor" = 注入面已提交；"staged" = 已落暂存待 `op="commit"`）；

package/undo-stack.mjs

@@ -6,13 +6,23 @@
  * 属核内面，函数本体零 TUI 依赖 ⇒ 按核内结构归位到核；`/undo` 命令面 `handleUndoCommand`
  * 留 CLI 壳——S2 由壳 import 本档）。
  *
+ * 双上界（#863 · TUI-COMMANDS.md §5.3）：单条备份超 `MAX_UNDO_BYTES` ⇒ **oversize 占位**条目
+ * （`oversize: true` · `backup: null`——列表可见 · 不可回退；与「文件创建」态靠 `oversize` 字段分判，
+ * 消费面 = `cmd-undo.mjs` 先判该字段再判 `backup === null`）；总量超 `MAX_UNDO_TOTAL_BYTES`
+ * ⇒ 逐最旧驱逐（条数上限 `MAX_UNDO` 保留）。
+ *
  * Tracks write/edit/delete/hashline_edit/apply_patch operations in agent._undoStack.
  */
 
-import { existsSync, readFileSync } from "node:fs"
+import { existsSync, readFileSync, statSync } from "node:fs"
 import { isAbsolute, join } from "node:path"
 
 const MAX_UNDO = 50
+const MAX_UNDO_BYTES = 10_000_000             // 10 MB — 单条备份上界（= tools/file.mjs 大档 read 守卫同值）
+const MAX_UNDO_TOTAL_BYTES = 64_000_000       // 64 MB — 备份总预算（超限逐最旧驱逐）
+
+/** 条目预算字节数（oversize 占位 ∥ 文件创建态（backup = null）不占预算）。 */
+const backupBytes = (e) => (typeof e?.backup === "string" ? Buffer.byteLength(e.backup, "utf8") : 0)
 
 /**
  * Snapshot a file before a side-effect tool modifies it.
@@ -26,22 +36,26 @@ export function snapshotForUndo(agent, toolName, args, cwd) {
   // 绝对路径直接用（path.join 对绝对段不重置——Windows 反斜杠路径也不按 "/" 切分）；相对路径整段 join(cwd)。
   const abs = isAbsolute(path) ? path : join(cwd, path)
   let backup = null
+  let oversize = false
   try {
     if (existsSync(abs)) {
-      backup = readFileSync(abs, "utf8")
+      if (statSync(abs).size > MAX_UNDO_BYTES) oversize = true // 大档不入内存——占位条目（与「文件创建」态分判）
+      else backup = readFileSync(abs, "utf8")
     }
   } catch {
     // can't read — maybe binary, skip
     return
   }
 
-  agent._undoStack.push({
-    tool: toolName,
-    path,
-    backup,
-    timestamp: Date.now(),
-  })
+  agent._undoStack.push(oversize
+    ? { tool: toolName, path, backup: null, oversize: true, timestamp: Date.now() }
+    : { tool: toolName, path, backup, timestamp: Date.now() })
   if (agent._undoStack.length > MAX_UNDO) agent._undoStack.shift()
+  // 总量上界：超限逐最旧驱逐（按字节预算计——条数上界保留）。
+  let total = agent._undoStack.reduce((n, e) => n + backupBytes(e), 0)
+  while (total > MAX_UNDO_TOTAL_BYTES && agent._undoStack.length > 0) {
+    total -= backupBytes(agent._undoStack.shift())
+  }
 }
 
-export { MAX_UNDO }
+export { MAX_UNDO, MAX_UNDO_BYTES, MAX_UNDO_TOTAL_BYTES }

package/tool-docs/ledger_add.md

@@ -1 +0,0 @@
-台账新增条目（写命令，仅主 agent）——入待讨论（六态状态机入口）。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）。

package/tool-docs/ledger_close.md

@@ -1 +0,0 @@
-台账收口（写命令，仅主 agent）——勾销：待核销 → 已核销；追认核销：待讨论 / 待设计 → 已核销（须已有 evidence，缺则拒）；在途 → 已核销 不可跳（仍经 待核销）；撤回：任意态 → 已废弃。归档 = 软删除（写 closed_at，行保留）。

package/tool-docs/ledger_count.md

@@ -1 +0,0 @@
-台账计数单源：未决四态（待讨论 / 待设计 / 在途 / 待核销）COUNT(*)，只读、全角色可用。

package/tool-docs/ledger_query.md

@@ -1 +0,0 @@
-台账查询（需求池 / 技术待办）——SQLite 行集，只读、全角色可用。未决四态 = 待讨论 / 待设计 / 在途 / 待核销；已核销 / 已废弃 = 归档态（软删除，行保留）。过滤参数缺省 = 全部行。

package/tool-docs/ledger_update.md

@@ -1 +0,0 @@
-台账更新条目（写命令，仅主 agent）——状态迁移按六态允许迁移表：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外迁移被拒。status 缺省 = 仅更新字段。