@thincoder/core 0.10.6 → 0.10.8

package/session-lifecycle.mjs

@@ -131,7 +131,7 @@ export function applySession(agent, data, opts = {}) {
   }
   // ENG-PLAN-EXCLUSION（FR31 ③ / KD10——恢复点①·CLI `applySession`）：工程模式 ⇒ planMode 恒
   // false（内存位 + 未注入的 plan 提示语）——防「工程纪律 × plan 只读」半状态随槽恢复复活。
-  // **槽不就地回写**：内存值在下一次 `saveSession` 随 `planMode` 字段自然收正（`session.mjs:128`）。
+  // **槽不就地回写**：内存值在下一次 `saveSession` 随 `planMode` 字段自然收正（`session.mjs`）。
   if (agent.config?.agent?.engineering === true) clearPlanMode(agent)
   if (data.advisor) {
     agent.config.advisor = { ...data.advisor }

package/session-slot-write.mjs

@@ -108,7 +108,7 @@ export function saveSlotData(cwd, slot, data) {
   if (data.createdBy === undefined && !existsSync(p)) data.createdBy = sessionEnd()
   writeSessionFile(p, data)
   // 写后取 mtime 单次采集（读失败 ⇒ `0` = 不可得）：缓存（本档路径键）+ 摘要 `ts` 地板入参
-  // （#503——保存面写后取 mtime，同族先例 `session-slot-verify.mjs:99`）。
+  // （#503——保存面写后取 mtime，同族先例 `session-slot-verify.mjs` 的 `runPass`）。
   const wroteMtime = (() => { try { return statSync(p).mtimeMs } catch { return 0 } })()
   slotMtimeCache.set(p, wroteMtime)
   try {
@@ -214,7 +214,7 @@ export function resolveEffortPatch(level, model) {
  * `activeModel`（不新增字段；`null` = 缺键语义——`provider` / `model` 无「未设」态）；`effort` 经
  * `resolveEffortPatch` 归一（`model` 取 `patch.model ?? 槽现值 activeModel`），归一 `null` = 未设
  * （回落配置面 / 渠道默认）——**值置 `null` 不删键**（与 `newSlotData` 规范结构同源）。
- * 只写盘：不碰当前内存态（施加面唯一 = `applySession`——§6.21 判据句 4 / 边界表第 5 行）。
+ * 只写盘：不碰当前内存态（施加面唯一 = `applySession`——§6.21 判据句 4 / 边界表「写非活动槽」行）。
  *
  * **值域面（#441② 明文——核侧有意不校）**：本出口只校**键闭集**，**不校值域**——`provider` /
  * `model` 传 `null`（或表外字面）按**缺键语义**零改（不报错；`null` 仅对 `effort` 有「未设」

package/session-slots-manifest.mjs

@@ -68,7 +68,7 @@ export function slotDigest(data, mtimeMs) {
 const isNum = (v) => typeof v === "number" && Number.isFinite(v)
 
 /** 摘要 `ts` 打点（**单源** · #503 地板）：`max(墙钟, mtimeMs)`；`mtimeMs` 不可得（缺省 / 非数）⇒
- *  裸墙钟回溯。沿先例 `session-slot-verify.mjs:99`（回写面地板）：**平台文件时间戳可领先
+ *  裸墙钟回溯。沿先例 `session-slot-verify.mjs` 的 `runPass`（回写面地板）：**平台文件时间戳可领先
  *  `Date.now()` 数 ms**——无地板则保存面刚写的摘要会被 `needsVerify`（`ts < mtime`）判「陈旧」
  *  一次（有界自纠，非数据面）；地板后 `ts ≥ mtime` 恒成立（同一 stat 值即比较对象）。 */
 export function digestTs(mtimeMs) {

package/session.mjs

@@ -183,7 +183,7 @@ export function saveSession(agent, opts = {}) {
   if (agent._recordStore) saveProjectedSlot(agent, p, fields, contextHistory)
   else writeSessionFile(p, { ...fields, history: legacyHistory(agent), contextHistory })
   // 记录我们刚写的 mtime——下次保存跳过解析（缓存 = `{p, mtimeMs}` 按路径命中：#386）+
-  // 摘要 `ts` 地板入参（#503：保存面**写后取** mtime——同族先例 session-slot-verify.mjs:99）。
+  // 摘要 `ts` 地板入参（#503：保存面**写后取** mtime——同族先例 `session-slot-verify.mjs` 的 `runPass`）。
   let wroteMtimeMs
   try {
     wroteMtimeMs = statSync(p).mtimeMs

package/shell-candidates.mjs

@@ -1,6 +1,6 @@
 /**
- * shell-candidates.mjs — 平台 shell 候选探测**单源**（B10 S17 收编：桌面 `settings-env.mjs:27-62` ∥
- * VSC `src/extension/settings.mjs:72-115` 两造 ≈逐字 ⇒ 候选表 ∕ 探测序 ∕ 超时 ∕ memo 上提本档；
+ * shell-candidates.mjs — 平台 shell 候选探测**单源**（B10 S17 收编：桌面 `settings-env.mjs` ∥
+ * VSC `src/extension/settings.mjs` 两造 ≈逐字 ⇒ 候选表 ∕ 探测序 ∕ 超时 ∕ memo 上提本档；
  * 两端薄壳只留 re-export —— 端侧零自持候选表）。
  *
  * 面：`shellCandidates()` ⇒ `Promise<{ name, value }[]>`——「System default」恒首 + 平台候选

package/shell-identity.mjs

@@ -10,7 +10,7 @@
  *
  * memo（进程生命周期 + 按配置值键控）先例 = `shell-candidates.mjs`（「shell 路径不热变化」同判据）；
  * 配置值变化 ⇒ memo 未命中重探（K2 配置变更刷新 ∥ 裁定①零静态同时成立）。
- * 测试缝 `_setComSpecForTest` 先例 = `shell-candidates.mjs:34` `_setShellDetectForTest`。
+ * 测试缝 `_setComSpecForTest` 先例 = `shell-candidates.mjs` `_setShellDetectForTest`。
  */
 
 // 识别表（raw 尾段词 → 显示名 + 语法族）。匹配大小写不敏感，尾段词先剥 `.exe` 后缀（U3——

package/team.mjs

@@ -1,8 +1,9 @@
 /**
  * team.mjs — 团队登录机制（TEAM.md §2——三端共用单源：CLI ∥ VSC ∥ 桌面同 import）。
  *
- * 面：登录 ∥ 退出 ∥ 登录态读面 ∥ 活校验（`teamVerify`——只读三值，登录面补全批增）∥ 端标签（自动生成）∥
- * 派生 provider 条目（登录写入 / 退出停用）∥ 服务地址归一 ∥ 失败分类。**写面单源** = 本档（`writeConfigAtomic`
+ * 面：登录 ∥ 退出 ∥ 轮换（`teamRotate`——team-token-rotation 批增）∥ 登录态读面 ∥ 活校验（`teamVerify`——只读三值，
+ * 登录面补全批增）∥ 端标签（自动生成）∥ 派生 provider 条目（登录写入 / 退出停用 / 轮换同步）∥ 服务地址归一 ∥
+ * 失败分类。**写面单源** = 本档（`writeConfigAtomic`
  * 一次 mutate——经 `persistRaw`；端侧零自写盘，三端同源）——`teamVerify` **只读**（零写盘、零状态）。
  *
  * 形（TEAM.md §2.1）：顶层 `team` 段 `{ server, member{username,name}, label, token }`——`token` 在场 ⇔
@@ -14,9 +15,11 @@
  * 返回形（B1 批端侧契约——父侧裁定 2026-10-10）：
  *   `teamLogin`  ⇒ `{ ok:true, notice?:"manual-name-conflict" }` ∥ `{ ok:false, reason }`
  *   `teamLogout` ⇒ `{ ok:true, revokeDelivered:boolean }` ∥ `{ ok:false, reason }`
+ *   `teamRotate` ⇒ `{ ok:true }` ∥ `{ ok:false, reason }`（子集：`network` ∥ `invalid`（401——旧 token 已失效）∥
+ *   `write_failed`——TEAM.md §2.7）
  *   `reason` 取值域：`network`（不可达 ∥ DNS/TLS ∥ 超时 ∥ 非 401/429 应答——服务不符合预期面）∥
- *   `credentials`（401——同措辞）∥ `rate_limited`（429——锁定期）∥ `write_failed`（服务端已应答、本地
- *   写盘失败——mtime 冲突 ∥ 畸形档拒写）。`notice` 携**码**不携文（文本归端侧 i18n）；
+ *   `credentials`（401——登录流程同措辞）∥ `invalid`（401——轮换流程：旧 token 已失效）∥ `rate_limited`（429——锁定期）∥
+ *   `write_failed`（服务端已应答、本地写盘失败——mtime 冲突 ∥ 畸形档拒写）。`notice` 携**码**不携文（文本归端侧 i18n）；
  *   `revokeDelivered:false` = 服务端吊销未达（网络失败——本地照清）。
  */
 import { hostname } from "node:os"
@@ -104,6 +107,60 @@ export async function teamVerify() {
   return { state: "unreachable" } // 其余（403 ∥ 404 地址非本服务 ∥ 5xx）⇒ 不判失效
 }
 
+/**
+ * 轮换（TEAM.md §2.7；三端同构——team-token-rotation 批）：`POST <server>/api/client/rotate`（Bearer = `team.token`；
+ * 体 `{}`——写端点 JSON 门照常）⇒ 成 ⇒ **一次写盘**：`team.token` = 新明文（替换）+ 派生条目 `apiKey` 同步
+ * （条目缺失 ∥ 同名手工 ⇒ 仅落 token——沿登录不覆盖口径）；败 ⇒ 零写盘 + 出词。**非 best-effort**：网络败 ⇒
+ * 服务端零变更（旧 token 仍有效——重试即复原）；401 ⇒ `invalid`（旧 token 已失效——端侧转「已失效」）。
+ * 无 token ∥ 无地址 ⇒ `network`（零请求旁路——端侧管理面本应已登录门）；服务端语义单源 = CLIENT.md §2 rotate 行。
+ */
+export async function teamRotate() {
+  const team = loadConfig().team
+  const token = typeof team?.token === "string" && team.token !== "" ? team.token : null
+  const server = typeof team?.server === "string" && team.server !== "" ? team.server : null
+  if (token === null || server === null) return { ok: false, reason: "network" } // 无凭据/无地址 ⇒ 兜底归类（零请求）
+  let res
+  try {
+    res = await fetch(`${server}/api/client/rotate`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: "{}",
+      signal: AbortSignal.timeout(TEAM_FETCH_TIMEOUT_MS),
+    })
+  } catch {
+    return { ok: false, reason: "network" } // 不可达 ∥ DNS ∥ TLS ∥ 超时（服务端零变更——旧 token 仍有效）
+  }
+  if (!res.ok) {
+    await res.text().catch(() => {}) // 错误体零消费面（分类只看状态——零新码）
+    if (res.status === 401) return { ok: false, reason: "invalid" } // 旧 token 已失效（端侧转「已失效」）
+    return { ok: false, reason: "network" } // 404（地址不是本服务）∥ 5xx 等——服务不符合预期面
+  }
+  let body = null
+  try {
+    body = await res.json()
+  } catch {
+    body = null
+  }
+  const next = typeof body?.token === "string" && body.token !== "" ? body.token : null
+  if (next === null) return { ok: false, reason: "network" } // 200 而形不符（代理 ∥ 非本服务应答）
+  try {
+    const result = persistRaw((raw) => {
+      assertWritableRoot(raw)
+      const section = raw.team
+      if (section === null || typeof section !== "object" || Array.isArray(section)) throw new Error("team 段缺失——拒写")
+      section.token = next // 新明文替换（一次写盘）
+      if (Array.isArray(raw.providers)) {
+        const entry = raw.providers.find((p) => p !== null && typeof p === "object" && p.name === TEAM_PROVIDER_NAME && p.derived === true)
+        if (entry !== undefined) entry.apiKey = next // 派生条目同步；缺失 ∥ 同名手工 ⇒ 仅落 token（零覆盖）
+      }
+    })
+    if (result !== null && result.ok === false) return { ok: false, reason: "write_failed" } // mtime 冲突（不自动合并）
+  } catch {
+    return { ok: false, reason: "write_failed" } // 畸形档拒写等（writeConfigAtomic fail-closed）
+  }
+  return { ok: true }
+}
+
 /**
  * 登录（TEAM.md §2.2；三端同构）：请求 `POST <server>/api/client/login` ⇒ 成 ⇒ **一次写盘**（`team` 段 +
  * 派生条目 upsert）；败 ⇒ 分类出词、零写盘。`label` 缺省 ⇒ 自动生成（`defaultTeamLabel()`）；显式传入

package/think-off.mjs

@@ -17,15 +17,15 @@ export function thinkOffShape(spec) {
 
 /** 有效 off 路径（「何时可宣称 OFF」判据本体 = §16.4）——由 `thinkOffShape` 派生（防两处漂移）：
  *  `null` 形只有 effort 族的载荷门据它补发 `reasoning_effort:"none"` ⇒ 须枚举含 `"none"`
- *  （无枚举 / 无 `none` ⇒ 形不发任何字段，§16.4 表第 1 行）；`{type:"disabled"}` 形 ⇒ 达载荷层。
- *  两形共门 = `thinkAlwaysOn !== true`（服务端强制族：形被拒 / 恒思考 ⇒ 无效，§16.3 / §16.4 表第 2 行）。 */
+ *  （无枚举 / 无 `none` ⇒ 形不发任何字段，§16.4 表「effort 族」行）；`{type:"disabled"}` 形 ⇒ 达载荷层。
+ *  两形共门 = `thinkAlwaysOn !== true`（服务端强制族：形被拒 / 恒思考 ⇒ 无效，§16.3 / §16.4 表「服务端强制族」行）。 */
 export function thinkOffPath(spec) {
   if (spec?.thinkAlwaysOn === true) return false
   if (thinkOffShape(spec) === null) return (spec?.reasoningEffortEnum ?? []).includes("none")
   return true
 }
 
-/** advisor 推理档写面三态（**写语义单源** —— 由 VSC `settings-panel-write.mjs:149-164` 上提；B10 S11：
+/** advisor 推理档写面三态（**写语义单源** —— 由 VSC `settings-panel-write.mjs` 的 `applyAdvisorEffort` 上提；B10 S11：
  *  桌面主侧 ∕ VSC 写面两端同引，零副本）：`advisor` 对象原地作用于 `{ thinking, reasoningEffort }` 两键 ——
  *  ① `"none"`（关思考）⇒ `thinking = thinkOffShape(spec)`（族别 off 形）+ 删 `reasoningEffort`；
  *  ② 非空档字面 ⇒ `reasoningEffort = 值` + 清 off 形残记（`thinking` 为 `null` 字面 ∕ `{type:"disabled"}`

package/token-ttl.mjs

@@ -277,7 +277,7 @@ export function persistEngTokens(agent) {
   data.updatedAt = Date.now()
   writeSessionFile(p, data)
   // 记录我们刚写的 mtime——下次保存/守卫跳过重复解析（saveSession 同款；缓存按路径命中 #386）
-  // + 摘要 `ts` 地板入参（#503：保存面写后取 mtime——同族先例 session-slot-verify.mjs:99）。
+  // + 摘要 `ts` 地板入参（#503：保存面写后取 mtime——同族先例 `session-slot-verify.mjs` 的 `runPass`）。
   let wroteMtimeMs
   try {
     wroteMtimeMs = statSync(p).mtimeMs

package/tool-docs/bash.md

@@ -10,7 +10,7 @@ Execute a shell command and return stdout+stderr. Use for running commands, buil
 
 Parameters:
 - command (required): Shell command to execute
-- timeout: Timeout in milliseconds (default 120000, max ~300000)
+- timeout: Timeout in milliseconds (default 120000 for synchronous runs; background runs have no default — an explicit timeout still applies; no upper bound)
 - filter: Optional — a regex; only output lines matching it are returned (case-insensitive). Use instead of hand-writing a pipe into `findstr`/`grep`.
 - async: Run in the background (default false) — returns an ack at once (bash#<id>, log path); the result arrives as a digest when the process exits. Depth-0 only.
 {{inject:bash-terminal-face}}

package/tool-docs/browser.md

@@ -45,4 +45,4 @@ Notes:
 - Session assumptions: the session may be closed externally or timed out — never assume it is alive; on `closed externally`, just run the action again (fresh session, login kept).
 - When not to use it: static page / API → `fetch`; a link needing no interaction → just produce the URL; a step needing a human (2FA, payment) → ask the user to do it in a headed session.
 
-CLI, VS Code and desktop share this description verbatim (single source: core `tool-docs/`).
+CLI, VS Code and desktop share this description verbatim.

package/tool-docs/doc_check.md

@@ -0,0 +1,31 @@
+Run a built-in documentation-discipline check on a project and report its findings.
+Read-only and non-gating: it reports, it never blocks, never sets an exit code, and its output is never a reason to refuse a task or a user instruction.
+
+What it checks — exactly two criteria, both driven by the checked project's declarations:
+- Anchors — every documentation pointer (a `*.md` token, optionally carrying directory segments, optionally followed by a section
+  indicator `§N` / `§N.M` / `§N.M.K`) must resolve: the file must exist on disk (`档缺` when it does not), and when a section
+  indicator is given the target file must carry a heading numbered with it (`节缺` when it does not). Line-number coordinates
+  (`file.md:12`) are not section references and are not judged as such. Files inside fenced code blocks and executable lines
+  (command / pattern code spans) are skipped whole.
+- Line width — a line whose character count (CJK counts as 1) exceeds the declared threshold, unless it is a table row, inside a
+  fenced code block, an executable line, a quote-block line, or inside an exempt zone.
+
+It cannot: write anything, gate anything, or turn a finding into a refusal.
+
+Arguments — `target` (optional): the project root to check; defaults to the session anchor, relative paths resolve against it.
+A workspace target (several projects below it) is reported with the full candidate list — pass the project root you mean.
+
+Routing — use it when you write or revise a project's documents and want the declared discipline checked in one pass. It is not
+a reader: use `doc_search` / `read` to read documents and `grep` to search them; this tool only reports discipline findings.
+Do not wire it as a gate or CI step, and do not treat a finding as a reason to refuse an instruction — a machine check never
+outranks a user instruction.
+
+Side effects and permissions — none. The tool is read-only: no writes, no approval prompt, safe to run in parallel with other calls.
+
+Parameter source and failure shape — every parameter comes from `<target>/PROJECT-MANIFEST.json` `checkConfig` (`scanDirs` /
+`lineWidth` / `widthExemptZones` / `anchors.exclude`); no repository path is hard-coded, so another project runs it with its own
+declarations. Changing those declarations changes the behavior. A missing or unreadable manifest is surfaced as an error line
+naming the file — the check never fabricates a result.
+
+Consistency — the checks and this description are one core implementation: every end that loads the core tool registry gets the
+same semantics.

package/tool-docs/manifest.md

@@ -1,11 +1,11 @@
 Read, initialize, or point-edit the project manifest (PROJECT-MANIFEST.json) — the project-level state file (phase / docRoot / checkConfig / codePaths / index / advisor). Attached to the main agent only; subagents can neither see nor write it.
 
 Actions:
-- read [target] — report the manifest state with a stable anchor `state=ok|missing|invalid|ambiguous|no-project`. The ok state prints the manifest JSON plus missingKeys / unknownKeys / errors rows (only when non-empty). Never throws — a missing manifest is reported, not refused.
+- read [target] — report the manifest state with a stable anchor `state=ok|missing|invalid|workspace|no-project`. The ok state prints the manifest JSON plus missingKeys / unknownKeys / errors rows (only when non-empty). Never throws — a missing manifest is reported, not refused.
 - init [target] — create the default manifest where the project root resolves (the target itself when no project is discoverable). Refused when a manifest already exists — init never overwrites.
 - write <key> <value> [target] — point-edit one node: read the current manifest, set the node, write it back through the writer gate. The resulting manifest must pass validation (a fault is refused with the disk byte-for-byte unchanged); a missing manifest is refused — run init first (write never creates one).
 
-target — explicit target directory; defaults to the session anchor, relative paths resolve against it. An ambiguous target (2+ candidate projects) is refused with the full candidate list — the mechanism never picks one.
+target — explicit target directory; defaults to the session anchor, relative paths resolve against it. A workspace target (several projects below it) is reported by `read` and refused by `init` / `write` — with the facts, the full candidate list and a next step: name the project root you mean and pass it as target.
 
 key — dot path into the manifest, one of the writable nodes: version / phase / promptsLanding / codePaths, or a sub-key of docRoot / checkConfig / index / advisor (e.g. docRoot.design / index.publicRepos / advisor.docMap). Whole-object writes of those four families are refused, as is any key outside the set (spelling protection).
 
@@ -14,3 +14,15 @@ value — parsed as JSON first (null / true / 5 / ["a","b"]), falling back to a
 Refusals throw `manifest <action>: refused — …` and leave the disk unchanged. The written file is picked up by the session's project-state line on the next turn (mtime-gated) — the tool never touches in-memory state.
 
 read is read-only (planMode passes, no approval); init / write are side effects (approval gate). Writes go through writeManifest / initManifest with writer "main" — the fail-closed subagent default is never used.
+
+Key catalog — the writable nodes: what each is; when to change it; wrong ⇒ consequence.
+- `version` — schema version (a number); change on file migration; wrong ⇒ validation refuses (disk unchanged).
+- `phase` — project stage, `initial-dev` / `production`; change when the stage is crossed; wrong ⇒ validation refuses.
+- `promptsLanding` — declared prompt-landing directory; change when it moves; no failure consequence (no shape check, no in-core reader — a registration face).
+- `codePaths` — path segment names (replaces the default `["src"]`); change when the layout moves; wrong ⇒ no segment is classified (the fallback still runs).
+- `docRoot.requirements` · `docRoot.specs` · `docRoot.design` · `docRoot.modules` · `docRoot.batches` — each doc-layer root path (a string | a multi-root array | `null` = absent); change when a layer moves root; wrong ⇒ validation refuses, or checks / batch landing / review roots point elsewhere.
+- `checkConfig.scanDirs` · `checkConfig.lineWidth` · `checkConfig.widthExemptZones` · `checkConfig.anchors` · `checkConfig.exemptions` — machine-check settings (scan dirs / width / exempt zones / anchors / exemptions); change when the check scope changes; wrong ⇒ checks run on a wrong scope silently (missed scans / wrong width / dead exemptions).
+- `index.codeExtensions` · `index.docExtensions` — extra code / doc extensions (unioned, add-only); change when a file type is missing from the index; wrong ⇒ that type stays out of the index (extras harmless; a missing entry = a miss).
+- `index.excludePaths` — project-root-relative path prefixes (for the index); change to keep a directory out of the index; wrong ⇒ that directory is still indexed, or another is wrongly excluded.
+- `index.publicRepos` — public-repo paths (resolvable from this repo root); change when wiring a public repo into the index or cross-repo refs; wrong ⇒ that repo is unreachable for retrieval (empty origin set / wrong path).
+- `advisor.docMap` · `advisor.standardsDoc` — review pointers (map file / single standards doc; empty = not declared); change when the review injection face changes; wrong ⇒ review injection lands nothing (an unreadable doc ⇒ review with no doc).

package/tool-docs/ssh.md

@@ -0,0 +1,34 @@
+Open and drive a persistent interactive SSH session (remote login shell) on a host. The session survives across tool calls; password hosts get a credential window — the value never appears in tool args, results, or on disk.
+
+**Route to ssh instead of bash:**
+- a one-shot non-interactive command over ssh → `bash` with `ssh host <command>` (cheaper, no session)
+- an interactive shell that must survive several calls (network device CLI, interactive prompts) → ssh
+
+Parameters:
+- action (required): connect | send | read | secret_input | close | list
+- host: connect — target host (IP or name)
+- user: connect — login user (optional: your local ssh config decides, else the user recorded for this host locally)
+- port: connect — TCP port (optional, default 22)
+- label: connect — short human label for this session (optional); secret_input — label for the value being sent
+- promptPattern: 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: send / read / secret_input / close — session id from connect (`ssh#N`)
+- data: send — text to type into the session (a trailing newline is passed as-is; otherwise Enter is sent as `\r`)
+- settle: send — wait for the ready verdict before returning (default true); false returns right after the bytes are written
+- timeoutMs: send / read — wait budget override (default 10000; the wait then returns partial output with a readable line)
+- maxChars: read — return cap override (default 8000; the full output stays in the session log)
+
+Output:
+- every result starts with the session status line: `[ssh (ssh#3) 10.0.0.5 — ready · idle 3s]`
+- connect returns the first screen; send returns the round's output plus the ready verdict (silence | prompt matched | timeout); read returns what arrived since the last read
+
+Notes:
+- Credential discipline: the password is asked for in a window and reaches ssh only through its child-process environment — never in tool args, never echoed in a result, never written to disk. Any captured output containing that value (or a value given to secret_input) is scrubbed from the returned text and from the session log.
+- secret_input is for device prompts (enable password, sudo, key passphrases): it opens the same kind of window, writes the value plus Enter, and returns only the output — the value is never shown.
+- Sessions: at most 4 live at once (a connect beyond the cap is refused — close one first). A session idle for 600s with no send/read is closed automatically. `close` ends it (stdin EOF → 1.5s grace → the process tree is killed). Ctrl+I (interrupt) does not kill sessions; a user Stop does.
+- Output is capped per return (8000 chars, tail kept); the full stream is always in the session log whose path connect returns.
+- Not for full-screen terminal UIs (vim/top/screen): output is read as a text stream — paged output such as `--More--` is shown as-is, not driven for you.
+- Host keys follow your local ssh config — the tool never rewrites known_hosts. A changed or untrusted key stops the connect with a readable error before any credential is asked for.
+- read / list are read-only (no approval prompt); connect / send / secret_input / close pass the approval gate like any side-effecting tool, and secret_input shows a masked placeholder — the value itself is never in the approval text.
+- Not for file transfer or port forwarding — run `scp` / `sftp` / `ssh -L` through bash.
+
+Availability: where the end has no UI to collect a credential (headless / ACP), connecting to a password host fails with a readable error — use keys or an ssh-agent there.

package/tool-docs/subagent.md

@@ -8,6 +8,8 @@ ONE tool, NINE actions — pick by what you need:
 - action:'cancel': STOP ONE background subagent — the id from the spawn return is REQUIRED (a blanket cancel is unsupported; Ctrl+C stops everything). Running aborts immediately ({id, status:'cancelled'}); queued is removed ({id, status:'cancelled', was:'queued'}; later positions shift). Other children and the session keep running. Cancel is a last resort: verify alarming signals with reliable checks (git/node — not guesses) first, and prefer scoped recovery — a running child's in-flight work dies with it, partial changes stay unmerged and unaudited. Background advisor reviews cancel the same way (pass the review id — no token is issued for a cancelled review).
 - action:'consume-design' (engineering mode, parent side): chain-terminal token consumption — after the delivery is verified and the chain closes out, consume this design's token slot. Selectors — pass exactly ONE: designId (a single slot; optional for a single-design session), designIds (an explicit non-empty list), expired:true (every expired slot), or olderThanDays:N (every slot older than N days). A consumed slot mechanically rejects further spawns for the same designId — new work (deviation fixes included) needs a fresh design review and token. Idempotent (unknown/already-consumed = a no-op notice); batch calls report per-slot lines + a `consumed N` count line. Do NOT call while the chain is still open — fix rounds reuse the same slot.
 - action:'design-slots' (engineering mode, parent side): READ-ONLY inventory of this session's approved design token slots — one line per slot (designId, live|expired, ageDays, expiresAt, batch), oldest first, ending with a total/live/expired count line. Nothing is written. Use it to see what still holds a slot before consuming; the expired / olderThanDays selectors act on the same set.
+  Filtering and recovery: pass designId to filter to a single slot (trimmed exact match; unknown = refused with the held id list; empty string = no filter); add reveal:true (requires designId) to read that slot's full designToken back — the recovery path for a token dropped from your context.
+  One slot at a time — never a bulk dump; expired / malformed slots are masked as designToken=—, a non-boolean reveal is refused, and the recovered designId + designToken go verbatim onto the eng-coder spawn (the gate checks exact equality).
 - action:'panel': DIAGNOSE + fix the subagent panel (the collapsible blocks the user sees; headless/VS Code degrade to a 'no panel' pool view). view (default): the live blocks (key, role, status: running|done|awaitingDigest) exactly as the user sees them — digested-stuck entries carry digested:true. freeze: pass a digested-stuck block key (e.g. 'eng-coder#9' — {action:'panel', freeze:'role#N'}) to reclaim it into the conversation — passes ONLY for awaitingDigest blocks with no live pool entry and no pending report (a still-pending report would break the digestion order — refused).
 
 Why delegate? The child's noise never reaches your window — delegation keeps your context lean and the child focused; parallel children save wall-clock time, and coder/eng-coder children self-review (verify + advisor) before their reports arrive.

package/tool-docs/timer.md

@@ -8,5 +8,6 @@ Beyond a one-shot countdown, three schedule forms are available, one per call (`
 All times are local to the host.
 `cancel` takes the id from the set confirmation and stops that timer; `list` shows every pending timer with its next due time. Repeating timers occupy one pending slot each until cancelled.
 Returns the set confirmation — the reminder fires at the deadline.
-Delivery: while a turn is running it lands at the next step boundary; when the session is idle it is delivered on the spot and starts a turn — the idle wake is available on the CLI / VSC / desktop foregrounds and suspension windows (headless is structurally unsupported); other paths keep the step-boundary behavior.
+Delivery: when the session is idle it is delivered on the spot and starts a turn — the idle wake is available on the CLI / VSC / desktop foregrounds and suspension windows (headless is structurally unsupported).
+A user turn gets no delivery: while a session turn is running, an expired timer waits for the next delivery round (suspension window / idle latch); other paths keep the step-boundary behavior.
 A pending timer survives across runs; at most 8 timers may be pending at once, and further timer calls are rejected until some expire.

package/tools/browser.mjs

@@ -6,7 +6,7 @@
  * `clipboard` 全量；免审 = `navigate` ∥ `type` ∥ `snapshot` ∥ `screenshot` ∥ `wait` ∥ `close` +
  * `hover` ∥ `wheel` ∥ `insert` ∥ `touch` 手势（swipe / pinch）——同一钩子按参数分类，机制零新增。
  * 失败回执**返回**（不 throw）——首行 `Error: …` = 模型面失败形（`bash`/`execute` 既例；dispatch 侧按该前缀
- * 判失败——`agent/dispatch-run.mjs:77` ∥ `:129` ∥ `:135`）。
+ * 判失败——`agent/dispatch-run.mjs` 的 `runPreparedItem`（三处））。
  * 异步面（§2.11——批 browser-async-fix）：`async:true`（depth-0 专项）⇒ `agent-tools/browser-async.mjs`
  * 起跑（ack 即返——本档薄接线；depth 第二道在此，schema 删参在 `agent/helpers.mjs` `excludeSubagentTools`）。
  */

package/tools/execute.mjs

@@ -61,7 +61,7 @@ function applyFilter(output, filter) {
 }
 
 /** 树杀单源 = `tools/process-tree.mjs`（TOOLS.md §6.14 落位表行 2：自本档抽出以断
- *  `shared → git-run → execute → shared` 环）；**再导出面保留**（`test/tool-seams.test.mjs:26` 消费，
+ *  `shared → git-run → execute → shared` 环）；**再导出面保留**（
  *  `configureProcessTreeKill` 缺省径零改）。 */
 export { killProcessTree }
 

package/tools/git-run.mjs

@@ -33,7 +33,7 @@ export const GIT_NET_TIMEOUT_MS = 300_000
 /** 网路面五动作（300s 档——合法耗时可远超本地；依据 = 需求档 §4.7 TTY-DRIVE N3 候选参照值）。 */
 const GIT_NET_ACTIONS = new Set(["push", "fetch", "pull", "clone", "ls-remote"])
 
-/** 测试态缝（模块级 · 缺省 null = 生产零行为变——先例 `manifest-discovery.mjs:15-20` · `session-gc.mjs:186`）。
+/** 测试态缝（模块级 · 缺省 null = 生产零行为变——先例 `manifest-discovery.mjs` 的 `_setProjectRootForTest` · `session-gc.mjs` 的 `_setSessionGcDelayForTest`）。
  *  用例 `finally` 复位；不经用户参数面（边界：不新增参数 / 用户选项）。 */
 let gitTimeoutOverride = null
 export function _setGitTimeoutForTest(ms) { gitTimeoutOverride = ms }
@@ -100,7 +100,7 @@ export function spawnGit(cwd, args, { timeout, maxBuffer } = {}) {
     }
     const treeKill = () => { try { killProcessTree(child) } catch { /* 尽力而为 */ } }
     // 超时动作序（§6.14）：① 直接子 → ② 逾 1.5s 树杀（`killProcessTree`，尽力而为）→ ③ 逾 1.5s 未 `close`
-    // 亦 settle（kick——孙进程持管道时 `close` 永不触发，`bash.mjs:200-217` 同款）。上界 = timeout + 3s。
+    // 亦 settle（kick——孙进程持管道时 `close` 永不触发，`bash.mjs` 的 `runBash` 同款）。上界 = timeout + 3s。
     // 平台分岔（§6.14 平台注的后果）：win32 上 SIGTERM 实为硬终止且**不连带子进程**——父一死，
     // `taskkill /PID <父> /T` 就够不到孙进程（实测：helper 孤儿存活、管道不放 ⇒ 只能等 kick）⇒
     // win32 直接走树杀（须在树仍可寻址时执行）；POSIX 保留宽限序（组杀在头进程死后仍可达全组）。

package/tools/git.mjs

@@ -40,14 +40,14 @@ function resolveBaseDir(cwd, workdir) {
  *  二者仍可经显式 `workdir` 指落点。 */
 const NO_REPO_DISCOVERY = new Set(["init", "clone"])
 
-/** 歧义（多态）消息：候选全列（绝对路径、按名排序）+ 指引显式 `workdir`——不猜（§6.13 解析序行 5）；
+/** 工作区（多仓）消息：下辖仓全列（绝对路径、按名排序）+ 指引显式 `workdir`（§6.13 解析序行 5）；
  *  **两档变体**（#188——按 `matched`）：带档级 ⇒ 「.git ∧ PROJECT-MANIFEST.json」；裸仓级 ⇒ 「.git」
- *  且注明 none carries …（不书带档句——§6.13 A22）。 */
-function ambiguousRepoMessage(candidates, cwd, matched) {
+ *  且注明 none carries …（不书带档句——§6.13 A22）。事实行，非错误框定（用户裁定「cwd 下多仓是常态」）。 */
+function workspaceRepoMessage(candidates, cwd, matched) {
   const head = matched === "git"
-    ? `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git (none carries ${MANIFEST_REL})`
-    : `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git and ${MANIFEST_REL}`
-  return `${head} — pass workdir to run git in the intended one (no silent pick):\n` + candidates.map((c) => `- ${c}`).join("\n")
+    ? `${cwd} is a workspace holding ${candidates.length} repositories — subdirectories carry .git (none carries ${MANIFEST_REL})`
+    : `${cwd} is a workspace holding ${candidates.length} repositories — subdirectories carry .git and ${MANIFEST_REL}`
+  return `${head} — pass workdir to run git in the intended one:\n` + candidates.map((c) => `- ${c}`).join("\n")
 }
 
 export const gitTool = {
@@ -96,13 +96,13 @@ export const gitTool = {
     if (args.workdir) ctx = { ...ctx, cwd: resolveBaseDir(ctx.cwd, args.workdir) }
     // 仓发现（§6.13 · #62）：缺省路径（无 workdir）⇒ 单源 = `discoverRepos`（仓梯——#188 含裸仓级）
     // ——工作区根（非仓）⇒ 唯一带档子仓 / 零档时唯一裸仓：重定向 `ctx.cwd` + 结果首行注记；零 ⇒ 原值
-    // 落 §6.12 fail-closed（零行为变）；多 ⇒ throw（列该级候选 + 指 workdir，不猜——消息按 `matched`
+    // 落 §6.12 fail-closed（零行为变）；多 ⇒ throw（下辖仓全列 + 指 `workdir`——消息按 `matched`
     // 两档变体）。判据 = workdir 真值在场（与上行同源——空串与缺省同判）；`init` / `clone` 例外
     // 不做发现。self / none 态 ctx 对象引用透传（不 clone）。
     let repoNote = ""
     if (!args.workdir && !NO_REPO_DISCOVERY.has(args.action)) {
       const discovered = discoverRepos(ctx.cwd)
-      if (discovered.kind === "ambiguous") throw new Error(ambiguousRepoMessage(discovered.candidates, ctx.cwd, discovered.matched))
+      if (discovered.kind === "workspace") throw new Error(workspaceRepoMessage(discovered.candidates, ctx.cwd, discovered.matched))
       if (discovered.kind === "unique") {
         ctx = { ...ctx, cwd: discovered.root }
         repoNote = `(repo: ${discovered.root})`

package/tools/index.mjs

@@ -14,6 +14,7 @@ import { executeTool } from "./execute.mjs";
 import { fileOpsTool, processTool, getCurrentTimeTool, waitForTool } from "./ops.mjs";
 import { treeTool } from "./tree.mjs";
 import { browserTool } from "./browser.mjs";
+import { sshTool } from "./ssh.mjs";
 
 // Instance-independent built-in table. `read_image` is deliberately NOT here:
 // its registration is capability-gated per model — see `assembleBuiltinTools`.
@@ -26,6 +27,7 @@ export const builtinTools = [
   fileOpsTool, processTool, getCurrentTimeTool, waitForTool,
   treeTool,
   browserTool,
+  sshTool,
 ];
 
 export {
@@ -37,6 +39,7 @@ export {
   fileOpsTool, processTool, getCurrentTimeTool, waitForTool,
   treeTool,
   browserTool,
+  sshTool,
 };
 
 // ── Full built-in registry (CORE-UNIFICATION TOOLS #70) ─────────────────────

package/tools/ops.mjs

@@ -60,7 +60,7 @@ export const processTool = {
       id: { type: "number", description: "kill target: background task id — a bash#N (bash async ack) or browser#N (browser async ack): bash ⇒ its process tree is terminated; browser ⇒ a queued task is dropped, a running one is aborted (the browser itself is not killed); either way the entry leaves the pool and no digest will arrive." },
     },
   },
-  // #9：动作分级——list 保持只读分类（dispatch-gates `isSubagentReadonlyAction`：planMode 放行/
+  // #9：动作分级——list 保持只读分类（dispatch-gates `isReadonlyAction`：planMode 放行/
   // 免审批）；kill 是破坏性动作（审批门）。`parallel` 保既有调度形（list 恒可批并行）。
   readonly: false,
   parallel: true,

package/tools/process-tree.mjs

@@ -1,8 +1,8 @@
 /**
  * tools/process-tree.mjs — 平台感知树杀单源（自 `execute.mjs` 抽出——TOOLS.md §6.14 落位表行 2）。
- * 抽出理由 = **断环**：`shared → git-run → execute → shared` 会 TDZ（`execute.mjs:29` 在模块求值期
+ * 抽出理由 = **断环**：`shared → git-run → execute → shared` 会 TDZ（`execute.mjs` 在模块求值期
  * 调 `DESC`（`const`））⇒ 树杀须住两不依赖档。行为逐字同（win32 `taskkill /T /F` · POSIX 组杀 + 直杀兜底）。
- * `execute.mjs` 保持再导出面（`test/tool-seams.test.mjs:26` 消费）。
+ * `execute.mjs` 保持再导出面。
  */
 import { execFileSync } from "node:child_process"
 

package/tools/ssh-askpass.mjs

@@ -0,0 +1,35 @@
+/**
+ * ssh-askpass.mjs — SSH 口令助手（独立进程入口；设计 = `docs/core/design/TOOLS.md` §6.22 ② · D-TO18）。
+ *
+ * 调用面 = ssh 经包装档（`<node> <本档> %*`）执行本档：argv[1] = 提示语本体
+ * （上游 `readpass.c` `ssh_askpass()`：`execlp(askpass, askpass, msg, NULL)`）。
+ * 输出面 = stdout **仅一行**（ssh 读首行作答复；`readpass.c` 取到首个 \r|\n 即止）。
+ * 秘密来源 = 环境变量 `TC_SSH_SECRET`（ssh 子进程环境——不入 argv / ps；§6.22 ②「秘密传递」行）。
+ * 零日志 / 零落盘 / 零回显——本档只写 stdout，不碰任何持久面。
+ *
+ * 答复判定（三分支，逐条有据）：
+ * 1. `SSH_ASKPASS_PROMPT === "confirm"` ⇒ `yes`——上游 `readpass.c` 的 `RP_ASK_PERMISSION`
+ *    径（如 `AddKeysToAgent=ask` 的 `ask_permission()`）；设计 §6.22 ② 同句。
+ * 2. 有秘密且提示语是主机确认句 ⇒ `yes`——**host-key 确认径不设该环境提示**
+ *    （`sshconnect.c` `confirm()` 走 `read_passphrase(msg, RP_ECHO)`，非 `RP_ASK_PERMISSION`
+ *    ⇒ 无 hint），故以提示语首行判定（确认句首行 = `The authenticity of host …`）。
+ * 3. 有秘密 ⇒ 秘密本体（password ∥ keyboard-interactive 两径同走 `read_passphrase`）。
+ *    无秘密 ⇒ `yes`——无秘密的场合 = 预探连（`NumberOfPasswordPrompts=0`），此刻**只可能**
+ *    收到确认类提问：password ∥ keyboard-interactive 被该选项短路（`sshconnect2.c`
+ *    `userauth_passwd` / `userauth_kbdint` 两处同判 `attempt++ >= number_of_password_prompts`）、
+ *    私钥口令提示亦被短路（`load_identity_file` 循环 `i <= number_of_password_prompts`）。
+ */
+const SECRET_ENV = "TC_SSH_SECRET"
+/** 主机确认句判据（首行；Windows `.cmd` 中介可能截断 argv——首行判据对截断不敏感）。 */
+const HOST_CONFIRM_RE = /authenticity of host|continue connecting/i
+
+const prompt = String(process.argv[2] ?? "")
+const hint = String(process.env.SSH_ASKPASS_PROMPT ?? "")
+const secret = process.env[SECRET_ENV]
+
+let answer
+if (hint === "confirm" || (secret && HOST_CONFIRM_RE.test(prompt))) answer = "yes"
+else if (secret) answer = secret
+else answer = "yes"
+
+process.stdout.write(`${answer}\n`)

package/tools/ssh.mjs

@@ -0,0 +1,92 @@
+/**
+ * tools/ssh.mjs — SSH 会话工具面（薄接线）：schema ∥ 参数校验 ∥ `isReadonlyAction` ∥ 回执/错误形
+ * （设计 = `docs/core/design/TOOLS.md` §6.22 —— D-TO17/D-TO18 · 台账 #1436；机制单点 =
+ * `agent-tools/ssh-session.mjs`；描述档 = `tool-docs/ssh.md`）。
+ *
+ * 分类钩子（KD-2 ∥ KD-11 同式——动作级，工具级只读位恒 false）：免审 = `list` ∥ `read`
+ * （只读豁免，NS3 判据）；过门 = `connect` ∥ `send` ∥ `secret_input` ∥ `close`——**携密动作仍属
+ * 写动作**，门不放松；携密径审批文案 = 掩码占位（`permission.mjs`，值不回显 ⇒ 不入上下文 / 审批记录）。
+ *
+ * 失败回执**返回**（不 throw）——首行 `Error: …` = 模型面失败形（`bash` / `browser` 既例）；
+ * 无 UI 考（缺 `ctx.onSecretInput` 回调）⇒ 机制档抛可读错（`question.mjs` 无 UI 抛例同旨）。
+ * 会话跨调用存活于池（非本档持有）；depth>0 排除（`agent/helpers.mjs` `SUBAGENT_TOOL_EXCLUSIONS`）。
+ * 动态 import（W8 契约②：agent-tools 静态链达 node:sqlite——端壳静态闭包须保持零命中）。
+ */
+import { DESC } from "./shared.mjs"
+
+export const SSH_ACTIONS = ["connect", "send", "read", "secret_input", "close", "list"]
+
+/** 参数校验（缺必填 / 形错 ⇒ `Error: …`——不执行；§6.22 动作表逐动作必填面）。 */
+export function validateArgs(args) {
+  const action = args?.action
+  if (!SSH_ACTIONS.includes(action)) {
+    return `Error: unknown ssh action "${action ?? ""}" — actions: ${SSH_ACTIONS.join(", ")}`
+  }
+  if (action === "connect") {
+    if (typeof args.host !== "string" || args.host.trim() === "") return "Error: connect requires host"
+    if (args.port !== undefined && args.port !== null && args.port !== "" && !Number.isFinite(Number(args.port))) {
+      return "Error: connect port must be a number"
+    }
+    return null
+  }
+  if (action === "list") return null
+  if (typeof args.id !== "string" || args.id.trim() === "") {
+    return `Error: ${action} requires id (the session id from connect, form "ssh#N")`
+  }
+  if (action === "send" && typeof args.data !== "string") return "Error: send requires data"
+  return null
+}
+
+export const sshTool = {
+  name: "ssh",
+  description: DESC("ssh"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: SSH_ACTIONS, description: "Action to run (one per call): connect | send | read | secret_input | close | list." },
+      host: { type: "string", description: "connect: 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: 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`)." },
+      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)." },
+    },
+    required: ["action"],
+  },
+  // 非工具级只读：动作级分类钩子接管（§6.22 NS3——`list` / `read` 免审）；也因此不进只读角色的子代工具表。
+  readonly: false,
+  isReadonlyAction(args) {
+    return args?.action === "list" || args?.action === "read"
+  },
+  async execute(args, ctx) {
+    const invalid = validateArgs(args)
+    if (invalid) return invalid
+    // 动态 import（W8 契约②——与 bash / browser 异步面同式）。
+    const mod = await import("../agent-tools/ssh-session.mjs")
+    const parent = ctx?.agent ?? null
+    const action = args.action
+    let res
+    if (action === "connect") {
+      res = await mod.connectSsh(parent, ctx, {
+        host: args.host, user: args.user ?? null, port: args.port ?? null,
+        label: args.label ?? null, promptPattern: args.promptPattern ?? null,
+      })
+    } else if (action === "send") {
+      res = await mod.sendSsh(parent, ctx, { id: args.id, data: args.data, settle: args.settle !== false, timeoutMs: args.timeoutMs })
+    } else if (action === "read") {
+      res = await mod.readSsh(parent, ctx, { id: args.id, timeoutMs: args.timeoutMs, maxChars: args.maxChars })
+    } else if (action === "secret_input") {
+      res = await mod.secretInputSsh(parent, ctx, { id: args.id, label: args.label ?? null })
+    } else if (action === "close") {
+      res = await mod.closeSsh(parent, ctx, { id: args.id })
+    } else {
+      res = mod.listSsh(parent)
+    }
+    if (res?.error) return res.error.startsWith("Error:") ? res.error : `Error: ${res.error}`
+    return res?.text ?? "(no output)"
+  },
+}