@thincoder/core 0.10.12 → 0.11.1

package/tool-docs/ledger.md

@@ -1,8 +1,8 @@
 台账统一入口——action = add / update / close / query / count。query / count 只读全角色；add / update / close 写仅主 agent。
 - add：新增条目入待讨论。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）；resume_when = 复启条件句（可空；值非空——空串 / 全空白拒；句内可带锚 `@YYYY-MM-DD`（机判到期）或 `@事件件名`（机器不判））。task_book 写门（add ∥ update 同判，判本笔写入面）：结果行 在途 / 待核销 ∥ trigger = 归批 ⇒ task_book 必填（缺 / 空串 / 全空白拒）；本笔新写 task_book（非空值）∥ 本笔新写 trigger = 归批 ⇒ 该指针的文件部分（首个 `§` 前子串）须可解析且指出的档在盘，否则拒。本笔不动指针 ⇒ 零判零阻——旧指针所指档已被清理不阻 status / evidence / 其它字段更新（「档在不在盘」是读数 taskBookOnDisk，不是门）。
-- update：按六态允许表迁移：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外拒；迁移入 已核销 时结果行标题携「收尾链待跑」同拒（同笔携清标记 title 放行）。id ∥ batch 恰携其一。status 缺省 = 仅更新字段；executor 缺省 = 进入待设计 / 在途自动写本会话，出在途 / 撤回清空；resume_when 同 update 可空字段（缺省 = 不变）。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`——「｜」零空格；旧空直写）；`evidenceReplace: true` 与 evidence 同传 = 整段替换；旗独传（无新文）∥ 新值全空白 ⇒ 拒。
+- update：按六态允许表迁移（逐边枚举，表外拒）：待讨论→待设计 / 待讨论→在途 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 待核销→在途 / 任意非 已废弃 态→已废弃（已废弃 无出边）。`待讨论→在途` 是点火与建档的正路——批档一开就把覆盖行直接落到 在途，不过 待设计（待设计 = 已排设计，不是点火发生的事）；`待核销→在途` 是重开回收——批档重开 ⇒ 行回工作位，六态唯一的回退边。id ∥ batch 恰携其一。status 缺省 = 仅更新字段；executor 缺省 = 进入待设计 / 在途自动写本会话，出在途 / 撤回清空；resume_when 同 update 可空字段（缺省 = 不变）。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`——「｜」零空格；旧空直写）；`evidenceReplace: true` 与 evidence 同传 = 整段替换；旗独传（无新文）∥ 新值全空白 ⇒ 拒。
 - update --batch：批级批量迁移（batch = 批档指针，与该档 task_book 同址的行一次处理）——携 status ⇒ 逐行按迁移表重判；不携 status ⇒ 纯字段补丁（status 零写）。回执 { batch, status, applied, skipped }；被跳过的行逐行点名 { id, from, why }（why = 逐行拒因原文），其余行照落；事务级失败整批回滚。batch 值须可解析且批档在盘，否则拒。
-- close：勾销（待核销 → 已核销）；追认核销（待讨论 / 待设计 → 已核销，须有 evidence——可随本调用传入（一跳核销），判结果值：缺 / 全空白拒）；在途 → 已核销 不可跳；核销标记门：结果行标题携「收尾链待跑」⇒ 拒（收尾链未跑完，不许核销——先跑收尾全链，再由父侧清标记）；撤回（任意态 → 已废弃）不拦。软删除（写 closed_at，行保留）。id ∥ batch 恰携其一。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`；旧空直写）；`evidenceReplace: true` 同传 = 整段替换；旗独传 / 新值全空白 ⇒ 拒；缺省 = 判行值。
-- close --batch：批级批量结算——只销已到 待核销 的行（勾销）；待讨论 / 待设计 逐行点名跳过（追认核销不入批量面，转单行 close），在途 逐行点名跳过（不可跳）；已核销 / 已废弃 行静默不计。status 可不给（缺省 = 已核销），给了只能是 已核销。
-- query：SQLite 行集，等值过滤（status / kind / board / trigger / task_book）缺省 = 全部行；行集逐行携 aged（未决四态 ∧ 行龄 > 30 天）/ evidenceOversize（evidence 超软上限 300 字——读数非拒写）/ taskBookOnDisk（task_book 文件部分解析成立 ∧ 该档在盘 ⇒ true；缺指针 / 不可解析 / 不在盘 ⇒ false——读数非门，不拦任何写入）/ overdue（出口态字串 ∥ null：resume_due / dangling / unlabeled / aged，首中优先）。六态 = 待讨论 / 待设计 / 在途 / 待核销 / 已核销 / 已废弃。
-- count：回报 { count, overdue, evidenceOversize }——count = 未决四态（待讨论 / 待设计 / 在途 / 待核销）行数；overdue = 其中命中出口态的行数；evidenceOversize = 其中 evidence 超限行数。task_book 等值过滤。
+- close：勾销（待核销 → 已核销）——**只有这一条核销边**：待讨论 / 待设计 / 在途 一律拒（拒文点名现态 + 该现态的出路句）；撤回（任意态 → 已废弃）不拦。软删除（写 closed_at，行保留）。id ∥ batch 恰携其一。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`；旧空直写）；`evidenceReplace: true` 同传 = 整段替换；旗独传 / 新值全空白 ⇒ 拒；缺省 = 判行值。
+- close --batch：批级批量结算——只销已到 待核销 的行（勾销）；待讨论 / 待设计 逐行点名跳过（须先 update 到 在途 认领）；在途 逐行点名跳过（不可跳）；已核销 / 已废弃 行静默不计。status 可不给（缺省 = 已核销），给了只能是 已核销。
+- query：SQLite 行集，等值过滤（status / kind / board / trigger / task_book）缺省 = 全部行；行集逐行携 aged（未决四态 ∧ 行龄 > 30 天）/ evidenceTooLong（evidence 文字太长，难于阅读——读数非拒写；超 300 字即算命中）/ taskBookOnDisk（task_book 文件部分解析成立 ∧ 该档在盘 ⇒ true；缺指针 / 不可解析 / 不在盘 ⇒ false——读数非门，不拦任何写入）/ overdue（出口态字串 ∥ null：resume_due / dangling / unlabeled / aged，首中优先）。六态 = 待讨论 / 待设计 / 在途 / 待核销 / 已核销 / 已废弃。
+- count：回报 { count, overdue, evidenceTooLong }——count = 未决四态（待讨论 / 待设计 / 在途 / 待核销）行数；overdue = 其中命中出口态的行数；evidenceTooLong = 其中文字太长、难于阅读的行数。task_book 等值过滤。

package/tool-docs/lint.md

@@ -1,5 +1,6 @@
 Run the appropriate linter/checker for a file. Auto-detects based on file extension and project config.
 Without 'full', runs a fast node --check (JS/TS syntax only, catches parse errors in milliseconds).
+
 With 'full', runs the language-aware cascade: tsc –noEmit (TS); ruff (Python); cargo check (Rust); go vet (Go). JS/JSX files fall back to node --check; TS uses tsc --noEmit (requires tsconfig.json).
 Use the fast default after every write/edit; use 'full' before declaring a task complete.
 

package/tool-docs/manifest-read.md

@@ -1,4 +1,5 @@
-Read the project manifest (PROJECT-MANIFEST.json) — the project-level state file: version / phase / docRoot (the root of each document layer: requirements / specs / design / modules / batches) / codePaths / index.
+Read the project manifest (PROJECT-MANIFEST.json) — the project-level state file: version / phase / docRoot (the root of each document layer: requirements / specs / design / modules / batches, plus `standards` = the project's standards document, by file path) / codePaths / index.
+
 Read-only: the only action is `read`. Creating or editing a manifest belongs to the main agent — this subagent variant has no init / write action.
 
 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.

package/tool-docs/manifest.md

@@ -7,7 +7,9 @@ Actions:
   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. A workspace target
+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.
 
@@ -19,11 +21,16 @@ Refusals throw `manifest <action>: refused — …` and leave the disk unchanged
 
 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 12 writable nodes (3 whole keys + docRoot's 5 sub-keys + index's 4 sub-keys): what each is; when to change it; wrong ⇒ consequence.
+Key catalog — the 13 writable nodes (3 whole keys + docRoot's 6 sub-keys + index's 4 sub-keys): 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.
 - `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.
+- `docRoot.standards` — the project's standards document, by FILE path (a string | a multi-file array | `null` = undeclared); the reviewer judges methodology compliance against it; change when that document moves; wrong ⇒ the review says the declaration is unreadable and names the path (never a guessed default — there is none).
 - `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).
+
+- **`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it for `write`; for `init`, only when the target sits inside an existing project (a `PROJECT-MANIFEST.json` exists on its ancestor chain) — a bootstrap outside any project needs none; omitted when required = refused. `read` does not need it.
+
+**`project`** — the project this call belongs to (absolute path of the project root). Read only when `target` is absent — `target` wins when present. Pure declaration: it does not change the target directory (`target` does).

package/tool-docs/memory.md

@@ -5,7 +5,17 @@ Manage long-term memory in ONE tool — the action parameter picks the operation
 - delete — SINGLE: {id, layer} removes the entry shown in put/search/list output — layer is optional: passed, it is validated against the id prefix (a mismatch is refused — guards against deleting the wrong entry); omitted, the id prefix routes the delete (any id from put/search/list is directly deletable). BATCH (no id): {layer, type and/or keyword} removes every matching entry in that layer — layer + at least one of type/keyword required; without confirm:true it returns the count + preview instead; layer-wide wipes without filters are refused on every layer
 - clear — {layer: "personal", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing layer or a project/team layer is refused (use delete batch filters on shared layers)
 - maintain — index self-maintenance (dry-run by default in tool calls): ghost-row GC (rows whose files are gone from disk — ENOENT-only; live rows untouched; ghost-row deletions take a backup first and read back after), compaction (VACUUM past the freelist thresholds), backup rotation (keeps the newest N maintenance backups). The automatic startup pass runs the same engine and executes directly; every run reports its readings. confirm:true executes — without it you get the plan + readings only
+
 Layer = the memory tier: personal (private) / project (shared via this repo's .thincoder/memory/) / team (CLI only, git-synced); the [layer] tag, the id prefix, and the layer parameter are the same concept — pass a result row's [layer] as layer.
+
 Deleting project/team entries removes the local markdown file and its index row — team deletion is local only; a later team sync may resurrect the file while the remote still has it.
+
 Save bugs, conventions, and preferences here — they persist across sessions.
-Session message history (what was said in this or past sessions) is NOT in memory — search session messages with read_history.
+Session message history (what was said in this or past sessions) is NOT in memory — search session messages with read_history.
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`.
+
+In engineering mode the parent agent must pass it for any write that lands in the project layer: either `layer: "project"`, or a single delete whose id starts with `project:` while `layer` is omitted (`personal` / `team` entries live in the user data directory, so they need no number).
+
+**`project`** — the project this call belongs to (absolute path of the project root). Needed for exactly those project-layer writes: they also refuse without it. `personal` / `team` entries need neither. Pure declaration: it changes no execution directory.
+

package/tool-docs/notify_parent.md

@@ -1,7 +1,7 @@
 A one-way channel to your PARENT (the agent that spawned you) — you are a subagent, so there is no user to ask. Queue a message on the parent's side; your turn is not interrupted and nothing is consumed from it.
 
 - kind:'ask' — a question whose answer changes your next step and that you cannot answer from the materials you can read (task book / design doc / repo). The parent replies with subagent action:'send'; you receive it as an ordinary instruction at your next turn boundary. One ask at a time while a previous one still waits in the parent's queue.
-  Read the materials first and carry the evidence you already checked (`file:line` + the key text) — the parent should not have to re-read for you.
+  Read the materials first and carry the evidence you already checked (the file path + the exact words you read) — the parent should not have to re-read for you.
 - kind:'note' — an FYI that needs no answer (a premise you found broken, a conflict you resolved and want visible early).
 - Delivery markers: the message your parent receives is headed `[上抛·待裁]` (ask — awaiting the
   parent's decision) or `[上抛·知会]` (note — FYI) — added for you, so do not write these markers

package/tool-docs/plan.md

@@ -1,5 +1,7 @@
 Enter or exit plan mode.
+
 In plan mode you are restricted to READ-ONLY tools: read files, search code, run read-only shell commands.
 Use plan mode before complex multi-step tasks — explore the codebase, design the architecture, present a plan to the user.
+
 Exit plan mode to present the plan for the user's approval; implement only after they approve.
 For simple single-file edits, skip plan mode and just make the change.

package/tool-docs/question.md

@@ -14,5 +14,5 @@ Notes:
 - Keep the question text short — one or two sentences. Background, context, and analysis belong in your normal reply text, NOT in the question.
 - Routine confirmations (confirm gates) belong in your plain reply text — the user answers in their next message. Use this tool ONLY when you need the user's decision or input to proceed.
 - Ask here when no default can carry the work forward (new scope, a ruling on a criterion) — this blocks; when a reasonable default exists, ask in your ordinary reply text and keep going — a reply arriving while you work steers the work from there.
-  Read the materials first and carry the evidence you already checked (`file:line` + the key text) — the user should not have to re-read for you.
+  Read the materials first and carry the evidence you already checked (the file path + the exact words you read) — the user should not have to re-read for you.
 - After receiving an answer about a design convention, tool preference, or recurring pattern: save it with the memory tool (action: put). This prevents asking the same question in future sessions — the user shouldn't have to repeat their preferences.

package/tool-docs/read_history.md

@@ -1,7 +1,19 @@
 Query message history — THIS session by default, any session on disk with `path`. Recall what was said or done earlier: design decisions, tool-call timing, past rulings.
 
-Default (no path): this session's full record (never compacted, audit-complete). Filters combine with AND (role / keyword / tool / since-until / limit / direction — semantics per parameter; keyword with path="all" matches FTS words / phrases). Returns a JSON array in chronological order: [{ts, role, name?, tool_call_id?, content (≈500 chars, truncated marker), tool_calls ([{name, arguments}] — arguments capped at 300 chars)}]. Messages without ts return ts:null; content is truncated — the full text is in the session file.
+Default (no path): this session's full record (never compacted, audit-complete).
 
-Cross-session (`path`, optional): a session file path deep-queries THAT session with the same filters (relative paths resolve against the project cwd) — from the derived session index when it covers that session, otherwise from the session file itself (a file over 50,000 messages or 200,000 lines is refused as "session too large"). "cwd:<dir>" lists that directory's session slots (slot + file path + title + count + updatedAt; copy one into path= to deep-query it). "all" searches every INDEXED session (cross-project; rows carry session.file) — sessions never indexed yet are invisible (query them with path=<file>, or index first with the CLI `thincoder session index --rebuild`).
+Filters combine with AND (role / keyword / tool / since-until / limit / direction — semantics per parameter; keyword with path="all" matches FTS words / phrases).
 
-检索/记忆族选哪个：查**本会话**说过/裁定过 → read_history（默认）；查**别的会话/项目**旧对话 → read_history 带 path/cwd 参数；查**本 run 改过哪些文件** → recent_changes；查**跨会话已存知识/约定**（memory）→ memory search；查**项目设计文档** → doc_search；查**代码实现** → code_search；查 git 历史快照 → checkpoint cat/versions。read_history 只查会话消息——文件级改动用 recent_changes——知识与约定用 memory——互相不替代。
+Returns a JSON array in chronological order: [{ts, role, name?, tool_call_id?, content (≈500 chars, truncated marker), tool_calls ([{name, arguments}] — arguments capped at 300 chars)}]. Messages without ts return ts:null; content is truncated — the full text is in the session file.
+
+Cross-session (`path`, optional): a session file path deep-queries THAT session with the same filters (relative paths resolve against the project cwd) — from the derived session index when it covers that session,
+
+otherwise from the session file itself (a file over 50,000 messages or 200,000 lines is refused as "session too large").
+
+"cwd:<dir>" lists that directory's session slots (slot + file path + title + count + updatedAt; copy one into path= to deep-query it).
+
+"all" searches every INDEXED session (cross-project; rows carry session.file) — sessions never indexed yet are invisible (query them with path=<file>, or index first with the CLI `thincoder session index --rebuild`).
+
+检索/记忆族选哪个：查**本会话**说过/裁定过 → read_history（默认）；查**别的会话/项目**旧对话 → read_history 带 path/cwd 参数；查**本 run 改过哪些文件** → recent_changes；
+
+查**跨会话已存知识/约定**（memory）→ memory search；查**项目设计文档** → doc_search；查**代码实现** → code_search；查 git 历史快照 → checkpoint cat/versions。read_history 只查会话消息——文件级改动用 recent_changes——知识与约定用 memory——互相不替代。

package/tool-docs/read_image.md

@@ -1,4 +1,6 @@
-Read an image file and return it as multimodal content visible to the model. Use this to view screenshots, UI mockups, diagrams, or any visual content. The model only sees images through this tool — it cannot "see" files directly. Supports png, jpg, gif, webp. The image is base64-encoded and included in the response. Large images (>15MB) are rejected.
+Read an image file and return it as multimodal content visible to the model. Use this to view screenshots, UI mockups, diagrams, or any visual content. The model only sees images through this tool — it cannot "see" files directly.
+
+Supports png, jpg, gif, webp. The image is base64-encoded and included in the response. Large images (>15MB) are rejected.
 
 Parameters:
 - path (required): Path to image file (relative to cwd or absolute). Supports png, jpg, gif, webp; svg is returned as text source.

package/tool-docs/recent_changes.md

@@ -1 +1,3 @@
-Show files modified in this agent run (write/edit/insert_after/delete). Use when you need to remember which files you've already touched — during long multi-file tasks, it's easy to lose track. This is scoped to the current run, unlike git status which shows all uncommitted changes. For session-level history (what was said in a session), use read_history.
+Show files modified in this agent run (write/edit/insert_after/delete). Use when you need to remember which files you've already touched — during long multi-file tasks, it's easy to lose track. This is scoped to the current run, unlike git status which shows all uncommitted changes.
+
+For session-level history (what was said in a session), use read_history.

package/tool-docs/repo_outline.md

@@ -1 +1,3 @@
-Show the project's file dependency outline: which files import/export from which, and what symbols they export. Use when you need to understand the project structure, find where a function is defined, or see what files depend on a module. Pass a path to focus on a single file's relationships. Find code by keyword or snippet with code_search.
+Show the project's file dependency outline: which files import/export from which, and what symbols they export. Use when you need to understand the project structure, find where a function is defined, or see what files depend on a module.
+
+Pass a path to focus on a single file's relationships. Find code by keyword or snippet with code_search.

package/tool-docs/settings.md

@@ -1,6 +1,14 @@
 Adjust ThinCoder runtime configuration — persisted to config.json AND hot-applied to the live agent config.
 Actions: list (all keys + values, flattened) | get <key> | set <key> <value> — dot paths into config.json, any nesting.
+
 set persists to disk (only the set key is written — defaults are never baked in) and takes effect in the running session immediately (turn-boundary keys apply next turn); the value survives restarts.
-Known keys are type-checked: scalar keys against the built-in defaults (agent.maxTurns a number, traces.enabled a boolean); keys whose default is null against their real consumption shape — defaultModel "provider:model", agent.subagentModel / shell non-empty string, memory.team object with a repo — so a value the app would silently drop is refused (null clears the key: the entry is removed from config.json and the built-in default applies; string-typed keys refuse null — no "unset" state to fall back to). Unknown keys under a known section are stored as given.
+
+Known keys are type-checked: scalar keys against the built-in defaults (agent.maxTurns a number, traces.enabled a boolean);
+
+keys whose default is null against their real consumption shape — defaultModel "provider:model", agent.subagentModel / shell non-empty string, memory.team object with a repo — so a value the app would silently drop is refused
+
+(null clears the key: the entry is removed from config.json and the built-in default applies; string-typed keys refuse null — no "unset" state to fall back to). Unknown keys under a known section are stored as given.
+
 SENSITIVE keys (path segment matching apiKey/key/token/secret/password/authorization/auth/cookie/credential, or any key under a headers/env segment) are NEVER echoed in plaintext — list/get/set replies show ••••（masked）; setting a sensitive key is allowed and stored, but never echoed back.
-list/get are read-only (planMode ok, no approval); set is a side effect (approval gate). The /config TUI command is the human equivalent.
+
+list/get are read-only (planMode ok, no approval); set is a side effect (approval gate). The /config TUI command is the human equivalent.

package/tool-docs/skill.md

@@ -1,5 +1,7 @@
 Load a project skill from .thincoder/skills/.
+
 Skills contain reusable instructions, workflows, or reference material.
 Use this when the user references a skill by name, or when a task matches a known skill's description.
+
 Call with action='list' to see available skills; call with action='load' and name=<skill> to activate one.
 Returns the skill list ('list'), the load confirmation ('load' — instructions arrive in the next message), or Error: ... with the available skills.

package/tool-docs/ssh.md

@@ -1,26 +1,36 @@
-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 or results (an explicit opt-in can store it as ciphertext on this machine).
+Open and drive a persistent interactive SSH session (remote login shell) on a host, and move single files to or from that host (`put` / `get`).
+
+A session survives across tool calls. Password hosts get a credential window — the value never appears in tool args or results (an explicit opt-in can store it as ciphertext on this machine).
 
 **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
+- one file to or from a host you already have a session on → `put` / `get` (they reuse the session's host and credential chain; `bash scp` cannot reach that chain, so a password host would ask again or fail)
+- a whole directory tree, a resumable transfer or a progress bar → not this tool (single file only)
 
 Parameters:
-- action (required): connect | send | read | secret_input | close | list | credentials | forget
+- action (required): connect | send | read | secret_input | close | list | credentials | forget | put | get
 - host: connect / forget — 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 / forget — 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
+- promptPattern: connect — regex that marks the shell prompt as ready (optional; the default recognises lines ending in `#` `>` `$` `%`)
 - identityFile: connect — private-key path to offer as `-i` (`~` expands); remembered for this host and reused when omitted (optional)
-- id: send / read / secret_input / close — session id from connect (`ssh#N`)
+- id: send / read / secret_input / close / put / get — 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)
+- timeoutMs: send / read — wait budget override (default 60000; the wait ends as soon as the device is waiting for input — a prompt, `--More--`, a y/n or password prompt); put / get — transfer budget override (default 600000; on expiry the process tree is killed)
+- maxChars: read — return-window override (default 8000): head 60% + a note + tail 40%, and the omitted middle stays in the session for the next read
+- localPath: put / get — local file path (`~` expands; a file, never a directory)
+- remotePath: put / get — path of that file on the session host (e.g. `/flash/img.bin`)
+- overwrite: get — 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: put / get — `scp` (classic SCP protocol, the default, what network devices speak) | `sftp` (the SFTP subsystem, for hosts that only offer that). There is no automatic fallback between them
+- ledger: the in-flight ledger row this call serves (`"#N"` or `"N"`) — required for `get` in engineering mode (the same write gate `write` goes through; `put` writes the remote host and needs no number)
 
 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
+- connect / send / read / secret_input / close / list / put / get results start 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 (answer prompt such as `--More--` | prompt matched | timeout); read returns what arrived since the last read
+- put / get return the status line, then exactly one more line — `put <localPath> → <remotePath> · N bytes · exit 0` (and the mirrored form for get). The file's content never enters the context: the bytes travel over the disk only, never through a result, a log or a message. On failure you get an `Error:` line plus the tail of scp's stderr (≤ 600 characters), with the exit code named
 
 Notes:
 - Key-first: keys, your ssh config and ssh-agent are always tried before any saved credential — a connect succeeds without a window
@@ -30,22 +40,25 @@ 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 stored in plaintext. Any captured output containing that value (or a value given to secret_input)
   is scrubbed from the returned text and from the session log.
-- Saving a credential is opt-in: the credential window carries a `save` checkbox (off by default). When checked and authentication succeeds,
-  the password is stored encrypted with your OS user account (Windows DPAPI) in a per-user file outside the repository; the store holds only
-  ciphertext. A saved credential is reused silently — the next connect skips the window, and only after key
-  authentication fails. The residual risk is honest: another process running as the same logged-in user can decrypt it; this protects the
-  file at rest, not a compromised account. Saving is Windows-only for now; on other platforms the checkbox does not appear and the window
-  keeps asking.
+- Saving a credential is opt-in and belongs to `connect`: that credential window carries a `save` checkbox (off by default). When checked and authentication succeeds,
+  the password is stored encrypted with your OS user account (Windows DPAPI) in a per-user file outside the repository; the store holds only ciphertext. A saved credential is reused silently — the next connect skips the window, and only after key authentication fails.
+
+  The residual risk is honest: another process running as the same logged-in user can decrypt it; this protects the file at rest, not a compromised account. Saving is Windows-only for now; on other platforms the checkbox does not appear and the window keeps asking.
 - Fail-soft: an unreadable/undecryptable entry, a damaged store or a missing backend falls back to the credential window (the connection is
   not broken; undecryptable entries are kept). If the server rejects a saved credential it is deleted and the window is shown. A failed save
   never affects the connection.
 - 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.
+- Output is a cleaned text stream: terminal escape sequences and CRLF noise are stripped, and the session log holds the same cleaned text as the result. Each return is a window (8000 chars: head + a note + tail); the omitted middle stays in the session, so another read collects it and a large configuration comes back in full.
 - 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.
+- Transfers are binary safe and single-file: no recursive directory sync, no resume, no progress bar, and the parameters take files only (a directory is not a valid `localPath` / `remotePath`). That status line under the header is the whole receipt — do not expect a byte-by-byte progress.
+- `get` never overwrites silently and never creates directories: an existing local file is refused unless you pass `overwrite:true`, and the local parent directory must already exist (create it first — a mistyped `get` would otherwise land somewhere you cannot see).
+- `put` on a password host re-runs the same credential decision as connect: keys first, then the saved credential (no window), then the credential window. That transfer window only asks for user / password — it carries no save checkbox (storing a credential belongs to `connect`); a session built by typing a password into the window without saving it has no password kept, so the next transfer asks again.
+- If a transfer is killed at `timeoutMs`, a `get` removes the partial local file only when it was actually written by that transfer (an existing file scp never touched is kept — the receipt then says the target was left as it stands); after a `put` the remote host may keep a partial file — this tool does not clean it (resend the whole file with `overwrite:true`, or delete it on the host).
+- Ready means the device is waiting for you, not that output stopped: a prompt or an answer prompt (`--More--`, y/n, password) ends the wait, and a slow operation that goes quiet keeps waiting instead of returning half of its output. If a device's prompt does not look like a shell prompt, pass `promptPattern` on connect — otherwise each command waits out the full timeout.
 - 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 / credentials are read-only (no approval prompt); connect / send / secret_input / close / forget 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.
+- read / list / credentials are read-only (no approval prompt); connect / send / secret_input / close / forget / put / get 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. A transfer's approval text names both ends (`localPath` → `remotePath`) and never the file's content.
 - credentials lists saved entries (host / user / saved / last used — never a value); forget deletes the entry for a host (and optional port) and is idempotent — the next connect asks in the window again.
-- Not for file transfer or port forwarding — run `scp` / `sftp` / `ssh -L` through bash.
+- Not for port forwarding (`ssh -L` / `-R`) — run that 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,17 +8,27 @@ ONE tool, NINE actions — pick by what you need:
 - action:'send': STEER a running async subagent mid-flight — id + message (a direction, e.g. "check X, don't fixate on Y"). The child consumes it at its next turn boundary as an ORDINARY user instruction (non-interrupting; its discipline is unchanged — guidance, not a deviation waiver); returns {id,
   status:'delivered', queued}. Only RUNNING async children are targetable — sync/queued/settled/unknown error clearly; if the child settles first, its report carries an 'undelivered' note.
 - action:'escalate' (飞刀): hand an implementation task to a STRONGER model from your consult models; it gets WRITE access and does the work itself, then returns a post-op report (what changed, why, verification). Escalate EARLY, when the task calls for stronger hands (complex refactors, intractable
-  bugs, intricate algorithms — or beyond your comfortable ability). Not available in engineering mode (implementation goes through eng-coder). Default-async at depth 0: ack {id, role:'escalate', status:'running'} returns immediately; the report arrives automatically with its mutations merged into
+  bugs, intricate algorithms — or beyond your comfortable ability). Not available in engineering mode (implementation goes through eng-coder).
+
+  Default-async at depth 0: ack {id, role:'escalate', status:'running'} returns immediately; the report arrives automatically with its mutations merged into
   your bookkeeping (pooled with the other role-domain spawns).
 - 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
+  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
+  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, designToken), 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.
-  Every row carries its designToken value (expired ones included — status marks them; a malformed record shows designToken=—). Pass designId to filter to a single slot (trimmed exact match; unknown = refused with the held id list; empty string = no filter). Take designId + designToken verbatim onto
+  Every row carries its designToken value (expired ones included — status marks them; a malformed record shows designToken=—).
+
+  Pass designId to filter to a single slot (trimmed exact match; unknown = refused with the held id list; empty string = no filter).
+
+  Take designId + designToken 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).
@@ -31,34 +41,61 @@ Available roles (exposed per mode; the role is REQUIRED for action:'spawn' — a
 - coder — full implementation; the parent's complete read/write/execute toolset plus verify and advisor self-review. Its report carries a delivery table, one row per requirement (Done / Simplified / Not done — no deferred column). Normal mode: may optionally carry `batchDoc` — binds this spawn's §5
   record-write channel (unbound ⇒ the main agent records §5 on its behalf); when provided the path must resolve to a readable file.
 - 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 — pass the exact value from that review, or copy it verbatim from the action:'design-slots' row (the text after designToken=): missing or mismatched = the spawn is refused, and an expired token is refused with expired named (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).
+  advisor(type='design') review — pass the exact value from that review, or copy it verbatim from the action:'design-slots' row (the text after designToken=): missing or mismatched = the spawn is refused,
+
+  and an expired token is refused with expired named (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, when it does not resolve to a readable file, or when that record already has an in-flight spawn).
+
+  One batch record serves one concurrent spawn: wait for the occupant to settle, or cancel it.
 - eng-designer — engineering mode only: the SOLE author of the design documents and of the batch record's design section (requirement docs stay with the main agent). 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).
+- tester — BOTH modes: the readings seat. It runs the verification commands the task book puts in `goal` and hands the readings back as they stand —
+  no verdict, no fix, no document of any kind.
+
+  Tool face = the read-only tools plus `execute` / `bash` (dependency installs, compiles and fixtures included), minus `verify` (a verdict tool).
+
+  Run only, never change is a role contract, not a sandbox — `bash` can write, so a tester that edits anything is treated by the parent as a defect.
+
+Task book (non-engineering roles: explore / plan / coder / tester): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format)
 
-Task book (normal-mode roles: explore / plan / coder): four core structured parameters — goal (goal & why), knownFacts (the facts you already verified), acceptance (machine-verifiable criteria), reportFormat (delivery-report format)
 — plus scope (scope & forbidden scope — what to read / what not to touch).
 All five are required: a missing, blank or non-string value is refused with the parameter named.
 A free-text task is an optional supplement, never the whole brief.
+
 Engineering roles (eng-coder / eng-designer) take their task book from the batch record: batchDoc (the record path) and round (initial|fix), plus files / dependsOn for scheduling; the child reads §2 of that record itself — no other task text is passed.
+
 An eng-coder spawn also carries designToken — the write credential (the exact value from the review, or copied verbatim from the action:'design-slots' row, the text after designToken=), and designId when several designs are open: missing or mismatched = the spawn is refused.
 
+A record carries one concurrent spawn at a time: a second spawn on a record still in flight is refused, naming the occupant — sequential hand-offs (design → implementation → fix round) pass, because the previous spawn has settled first.
+
 Pass one parameter per field — contents only (the runtime adds the labels):
 subagent(role="eng-coder", round="initial", batchDoc="<batch record>", designToken="…", files=[…])
 subagent(role="explore", goal="…", knownFacts="…", scope="…", acceptance="…", reportFormat="…")
 
-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).
+Mode filtering: normal mode exposes explore/plan/coder/tester (eng-coder and eng-designer are refused); engineering mode exposes explore/eng-designer/eng-coder/tester (plan and coder are refused — plan is a normal-mode role, coder is replaced by eng-coder; tester is dispatchable in both modes).
+
+The role enum is filtered per mode at assembly, and the spawn gate refuses out-of-mode roles mechanically.
 
-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
+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.
 
-Task scheduling: declare files (the file paths this task will modify) and dependsOn (ids from prior async returns whose outcome this task needs) to let the scheduler order your spawns. Overlapping-file tasks serialize and dependents start in order: a conflicting/dependent spawn queues
-(position/reason) and auto-starts when the conflict clears / the dependency settles (cancel to drop). A cancelled/failed dependency leaves it queued marked "dependency cancelled" until you decide (AUTO sessions auto-start). Unknown ids error; a consumed id counts as satisfied. Omit both for a plain
+Task scheduling: declare files (the file paths this task will modify) and dependsOn (ids from prior async returns whose outcome this task needs) to let the scheduler order your spawns.
+
+  Overlapping-file tasks serialize and dependents start in order: a conflicting/dependent spawn queues
+(position/reason) and auto-starts when the conflict clears / the dependency settles (cancel to drop).
+
+  A cancelled/failed dependency leaves it queued marked "dependency cancelled" until you decide (AUTO sessions auto-start). Unknown ids error; a consumed id counts as satisfied. Omit both for a plain
 immediate spawn (no scheduler involvement).
 
 Writing the prompt:
 - The child starts with zero context — brief it like a colleague who just walked in: goal, what you already know, the specifics.
 - Put exact paths and commands in — do not make it search for what you already know.
-- Do not delegate understanding: resolve the paths/line numbers the task hinges on first.
+- Do not delegate understanding: resolve the paths and the symbols the task hinges on first.
 - Once it runs, leave that scope to it — don't redo its searches in parallel or finish manually midway.

package/tool-docs/task.md

@@ -1,7 +1,9 @@
 Plan and track a task list for complex multi-step work.
 Each call replaces the entire list.
 Keep exactly one item in_progress at a time; mark items done as you complete them; never mark done if tests fail or work is partial.
+
 Statuses: pending | in_progress | done — synonyms (completed/finished/complete, todo/open/waiting, active/running/working, …) are accepted and normalized with a warning.
 IMPORTANT: title is required and must be a non-empty string — items with empty titles are silently dropped.
+
 For cross-session / project-level tracking, use `/ledger`.
 Returns the updated task list (or the new item's ID on add).

package/tool-docs/team_ledger.md

@@ -5,5 +5,5 @@
 - count：同 query 参数，出 total。
 - add：title 必填（≤200）∥ detail（≤4000）∥ owner（缺省 = 自己）——status 恒 待讨论。
 - update：id 必填；title / detail / owner / status 至少一件；status = 迁移表合法后继（待讨论→待设计 ∥ 待设计→在途 ∥ 在途→待核销 ∥ 待核销→已核销 ∥ 未归档→已废弃）；已归档（已核销 / 已废弃）⇒ 拒；仓不可改。
-- close：id + status（已核销 ∥ 已废弃）——已核销：勾销（待核销）/ 追认核销（待讨论 ∥ 待设计，须正文非空）；已废弃 = 撤回（任意未归档态）。
+- close：id + status（已核销 ∥ 已废弃）——已核销：勾销（只自 待核销；其余现态 400，出路 = 先 PATCH 推进到 待核销）；已废弃 = 撤回（任意未归档态）。
 - 登录态门：未登录 ⇒ 明示「未登录」且零请求；401（token 失效）⇒ 「登录已失效——请重新登录」；不可达 ⇒ 「服务器不可达」（零离线缓存，重试不落旧值）。

package/tool-docs/timer.md

@@ -1,13 +1,20 @@
 Set a timer before you start analyzing code.
 When the timer fires, a system reminder will be injected suggesting you try running code or adding debug logs.
 Use this to enforce a thinking budget: you get N seconds to reason, then the timer reminds you to act.
+
 Beyond a one-shot countdown, three schedule forms are available, one per call (`seconds`, `at`, `every` and `daily` are mutually exclusive — passing more than one is a validation error):
+
 `at` takes a local clock time such as "2026-10-13T09:00" and fires once at that moment — a time already past fires immediately.
 `every` takes a fixed interval in seconds (minimum 60): the first reminder comes N seconds after setting, then every N seconds, until cancelled.
+
 `daily` takes a local "HH:MM" and repeats every day at that time (a time already past today fires tomorrow), until cancelled.
 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: 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/tool-docs/verify.md

@@ -1 +1,13 @@
-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.
+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, the exact words you read at their path, 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/tool-docs/websearch.md

@@ -1,4 +1,6 @@
-Search the web (DeepSeek Search when a DeepSeek provider is configured; otherwise Tavily with a key, else Bing). Returns result titles, URLs, and snippets — DeepSeek results also carry a date · authority (0–4) · rerank (0–3) line and a long summary. Use for looking up current information, docs, error messages.
+Search the web (DeepSeek Search when a DeepSeek provider is configured; otherwise Tavily with a key, else Bing). Returns result titles, URLs, and snippets — DeepSeek results also carry a date · authority (0–4) · rerank (0–3) line and a long summary.
+
+Use for looking up current information, docs, error messages.
 
 Parameters:
 - query (required): Search query

package/tool-docs/write.md

@@ -9,3 +9,5 @@ Notes:
 - Returns `Wrote N chars to <path>` + git diff + syntax-check note.
 - This overwrites the entire file — use `edit` for targeted changes
 - The file is atomic: it either writes completely or fails
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused.

package/tools/bash.mjs

@@ -3,12 +3,16 @@ import {
   sanitizeOutput,
   truncate,
   makeDecoder,
-  BASH_TIMEOUT_MS,
+   BASH_TIMEOUT_MS,
+  LEDGER_PARAM_DESC,
+  PROJECT_PARAM_DESC,
 } from "./shared.mjs";
 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";
+// 过程档标记（TOOLS.md §6.28）：输出里行首路径 token 真解析到盘上的过程档行 ⇒ 行首前缀 + 末尾汇总行。
+import { markProcessDocLines } from "./process-doc-mark.mjs";
 import { resolveShellIdentity } from "../shell-identity.mjs";
 
 /** Maximum buffer size per stream (stdout / stderr) before truncation */
@@ -247,6 +251,9 @@ export const bashTool = {
       timeout: { type: "number", description: `Timeout in ms (default ${BASH_TIMEOUT_MS} for synchronous runs; background runs have no default — an explicit timeout still applies)` },
       async: { type: "boolean", description: "Run in the background (default false): returns an ack at once (bash#<id>, log path) and the result arrives as a digest when the process exits. Depth-0 only." },
       filter: { type: "string", description: "Optional: only return output lines matching this regex (case-insensitive; synchronous runs only)" },
+      ledger: { type: "string", description: LEDGER_PARAM_DESC },
+      // 项目声明面（决策 40）：`bash` 没有定位参数 ⇒ 判据点只能靠声明；纯声明，命令仍在会话 cwd 执行。
+      project: { type: "string", description: PROJECT_PARAM_DESC },
     },
     required: ["command"],
   },
@@ -288,7 +295,10 @@ export const bashTool = {
       shell: ctx.agent?.config?.shell ?? null,
     })
     const filtered = args.filter ? applyLineFilter(result, args.filter) : result
-    const body = guard ? `${guard.notice}\n\n${filtered}` : filtered
+    // §6.28：顺序写死 = **过滤 → 打标 → 汇总 → 外包装**（filter 才照旧匹配原始行，前缀不吃
+    // 过滤命中；`guard.notice` ∥ `hint` 包在标之外）。解析基准 = 子进程 cwd（同步径 = `ctx.cwd`）。
+    const marked = markProcessDocLines(filtered, ctx.cwd)
+    const body = guard ? `${guard.notice}\n\n${marked}` : marked
     return hint ? `${hint}\n${body}` : body
   },
 }