mingdao-harness 0.6.14 → 0.6.16

package/README.en.md

@@ -19,7 +19,7 @@ does not cover (this file is written so a reviewer can decide that, not to make
 than it is).
 
 - Node.js **>= 18.17** (`package.json` `engines`), no build step, no npm runtime dependencies.
-- Current version: **0.6.8** · License: **MIT**.
+- Current version: **0.6.14** · License: **MIT**.
 - Repo: <https://github.com/MingDaoTCM/MingDao-Harness> · Package: `mingdao-harness` on npm.
 
 ## Quickstart (3 steps)
@@ -66,11 +66,12 @@ enforced by the kernel is described as a declaration, not as a control.
 | **Sandbox** — `config.sandbox` | `"off"` (default), `"readonly"` (whole filesystem read-only, `/tmp` writable, network available), `"safe"` (read-only + no network via `unshare-net`; working dir and `/tmp` writable). Implemented with **bubblewrap** on **Linux only**. | If the platform is not Linux or `bwrap` is missing/incapable, it **downgrades to `off`** and says so in the tool result — it never silently pretends to be sandboxed. It wraps the `bash` tool only; the file tools are governed by the permission modes, not by this. |
 | **Credential separation** | API keys live in `<home>/credentials.json` (`<home>` defaults to `~/.mingdao`, overridable with `MINGDAO_HOME`), written atomically and forced to mode **600**. `config.json` is key-free, so it is shareable and committable. Resolution order: environment variable → local credential store → legacy `config.json` field. Manage with `mingdao key`. | The legacy `config.json` `"apiKey"` field is still **read** for backward compatibility — do not use it. Keys are stored as plaintext in your home directory (no OS keychain), so any process running as your user can read them. `mingdao key status` and logs only ever print a masked form. |
 | **Telemetry opt-out** | Only **packaged desktop builds** send anything, and only one event: after an update finishes downloading, a `POST` to `https://harness.mingdao.ai/updok` with `{"kind":"update","os":...,"ver":...}` — no user identifier, no session, no code. | It is **opt-out, not opt-in**: on by default in packaged builds. Disable with `MINGDAO_NO_TELEMETRY=1` or `"telemetry": false` in `config.json`; updates still download and install. The CLI and the WebUI send **no** telemetry at all. |
+| **Update-package signature** | The packaged desktop app verifies an **ed25519 detached signature** over the installer bytes against a public key pinned in the source (`desktop/update-verify.js`). A signature that is present but invalid is always rejected. | The release pipeline does not sign builds yet, so current builds verify as "no signature" and follow the default policy: **install, but state that the signature was not verified**. Set `MINGDAO_REQUIRE_UPDATE_SIGNATURE=1` to **reject** unsigned updates (fail-closed, recommended for high-assurance deployments). A feed controlled by an attacker can strip the signature — that is exactly the downgrade this switch closes off. |
 | **PID ownership** | Before `killTask` / `stopDaemon` signals a pid, it verifies the pid still belongs to the process we started (Linux reads `/proc/<pid>/cmdline`, macOS falls back to `ps -ww -o command=`). Three-valued: ours / definitely not ours / unknown. | **Windows has neither `/proc` nor `ps`**, and the project deliberately does not take a PowerShell/WMI dependency for this check, so ownership is reported as unknown and the caller falls back to best-effort "process is alive". Deploy on Linux or macOS if you need precise pid-ownership checks. |
 | **Egress gate** — `config.net` | `{ "allow": ["api.deepseek.com", "*.internal.corp", "10.0.0.0/8"], "mode": "warn", "allowLoopback": true }` — `warn` (default) logs and allows, `block` refuses. Decisions are made at a single HTTP exit and recorded per event (host, port, decision, matched rule); `mingdao net report` exports the record as evidence. Non-`fetch` paths (`node:https` sync, `safe-fetch` for skill/registry/model discovery) are wired into the same decision point. Loopback is exempt; private ranges are not. | **It does not cover child processes.** Your own `curl` inside `bash`, **MCP server processes**, `config.tools` and Pack-spawned subprocesses, and the Electron shell's update check all make their own requests that the gate never sees. It proves *"the kernel did not exfiltrate"*, **not** *"this machine never egressed"*. `net.jsonl` records hosts/ports/decisions, never request bodies or full URLs. If unconfigured, the gate is not installed at all. For process-level enforcement use an egress proxy or firewall. |
 | **SSRF protection** | One implementation (`src/ssrf-guard.js`): literal private / loopback / link-local / cloud-metadata hosts are refused (IPv4 plus all IPv6 forms, including IPv4-mapped, NAT64 and zone-ids); a hostname is resolved and **every** resolved address is checked; a hostname that fails to resolve is refused. The **validated IP is pinned to the connection layer** (via the `lookup` option of `node:http(s)`), so the check-time and connect-time resolutions cannot differ — this closes DNS rebinding. Redirects are re-checked per hop and cross-origin hops drop credential headers using a reverse allowlist. | The rule is fail-closed by design, which means it can over-block unusual-but-legitimate targets (odd IPv6 forms, `%`-scoped hosts); the fix is to use a literal, routable address or a proper hostname. It protects harness-initiated requests; it cannot constrain a subprocess' own networking (see the row above). |
 | **Pack trust** | A project-level `.mingdao/packs/**` is **not mounted** until you explicitly run `mingdao pack trust <project-dir>`. Trust is pinned to content: if the Pack's content changes afterwards, trust lapses automatically. `mingdao pack verify <dir>` is **static by default** and does not execute Pack code; only `--runtime` imports it. | `manifest.permissions` (`fs` / `net` / `env`) is a **declaration, not enforcement**. The kernel does not enforce it: `pack.mjs` is imported into the **host process** and runs with full Node privileges — it can read and write any file and reach the network — and Pack-contributed tools are **not** subject to `config.permission`. Packs you list explicitly in `config.packs` bypass the trust gate, because that is your own written authorization. Treat installing a Pack as equivalent to running its code. |
-| **Execution ledger** | Per-turn event streams under `<home>/ledger/`, each event chained to the previous one by a truncated SHA-256 digest starting from a fixed genesis value, plus a `run.end` seal sidecar. Details are redacted on write and again on export. Inspect with `mingdao ledger list\|show\|export\|verify` (there is also `replay`, which re-evaluates recorded calls against your *current* rules offline). | Hash chain + seal prove "unchanged and not truncated **since it was written**". There is **no trusted timestamp and no signature** (optional signing is not implemented), so it is **not** audit-grade non-repudiation — `verify` says so in its own output. |
+| **Execution ledger** | Per-turn event streams under `<home>/ledger/`, each event chained to the previous one by a truncated SHA-256 digest starting from a fixed genesis value, plus a `run.end` seal sidecar. The seal carries an **ed25519 source signature** (key at `<home>/ledger-key.json`, mode 600, generated on first seal). Details are redacted on write and again on export. Inspect with `mingdao ledger list\|show\|export\|verify` — `verify` reports chain/seal **and** provenance in four states (valid / unsigned / invalid / unverifiable) — plus `replay`, which re-evaluates recorded calls against your *current* rules offline; `ledger --sign-key` shows or rotates the key. | Hash chain + seal prove "unchanged and not truncated **since it was written**"; the signature proves "written by the holder of that key" — but the key lives on the same machine with the same permissions, so it does **not** stop a local attacker who can already rewrite the ledger. There is **no trusted timestamp**, and replacing the key makes old ledgers report "signed by another key". It is provenance, not audit-grade non-repudiation. |
 | **WebUI exposure** | Binds `127.0.0.1:3820` by default. When bound to a non-loopback address without a configured token, the server generates a random token for that run and prints a `?token=` URL. Tokens also accepted via `X-MingDao-Token` or `Authorization: Bearer`. Host header is checked against loopback/bind names (anti-DNS-rebinding), cross-site browser requests are rejected, and cloud-metadata endpoints are always refused. | On loopback with no token configured there is **no authentication** (local trust by design). With `host: 0.0.0.0` the Host-header check is relaxed and the **token becomes the only boundary**, so a token is mandatory in that mode. The token is deployment-level: everyone sharing it is the same user, and task/session lists are mutually visible. |
 
 ## Command index
@@ -87,7 +88,7 @@ Commands are grouped here for evaluation; `mingdao --help` and `src/help.js` are
 | `mingdao web [port]` | Start the WebUI (default `http://127.0.0.1:3820`); `--auth-token` (or `--auth-token=-` from stdin). |
 | `mingdao diagnose` | Build one redacted diagnostic bundle (logs / audit / config) for bug reports. |
 | `mingdao audit [n]` | Show the tool-call audit log (default last 20 entries). |
-| `mingdao ledger list\|show\|export\|verify\|replay` | Execution ledger: inspect, export, verify the hash chain, or replay against current rules. |
+| `mingdao ledger list\|show\|export\|verify\|replay` | Execution ledger: inspect, export, verify the hash chain and source signature, or replay against current rules. `ledger --sign-key [--generate\|--force]` shows or rotates the ed25519 signing key. |
 | `mingdao net report\|policy` | Egress record export and current `config.net` policy. |
 | `mingdao key [status\|set\|remove\|import] [provider]` | Manage the local credential store (never writes keys into `config.json`). |
 | `mingdao pack list\|verify\|info\|new\|trust\|untrust` | Discover, statically validate, scaffold, and trust domain Packs. |
@@ -111,7 +112,7 @@ Commands are grouped here for evaluation; `mingdao --help` and `src/help.js` are
 The full reference is **Chinese**; these are the entry points worth knowing:
 
 - [`docs/CONFIG.md`](docs/CONFIG.md) — every `config.json` field: permission rules, sandbox, `config.net`, hooks, MCP, sync, cost guard.
-- [`docs/CONFIG.en.md`](docs/CONFIG.en.md) — English configuration reference (verified against the code): permissions, sandbox & env filtering, egress gate and its limits, cost guard, WebUI exposure, audit/ledger, full field table.
+- [`docs/CONFIG.en.md`](docs/CONFIG.en.md) — English configuration reference (verified against the code): permissions, sandbox & env filtering, egress gate and its limits, cost guard, WebUI exposure, audit/ledger provenance, local-endpoint pre-flight/serialization, timeouts and the turn-level watchdog, full field table.
 - [`docs/PACK-API.md`](docs/PACK-API.md) — the Pack contract (manifest, contributions, constraint kinds, and which of them are **not** implemented).
 - [`docs/PROVIDERS.md`](docs/PROVIDERS.md) — built-in providers and writing a custom OpenAI-compatible provider.
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — module map and data flow.

package/SECURITY.md

@@ -11,7 +11,7 @@ Security fixes are provided for the **latest minor release only**.
 
 | Version | Supported |
 | --- | --- |
-| **0.6.x** (current: **0.6.8**) | Yes |
+| **0.6.x** (current: **0.6.14**) | Yes |
 | 0.5.x and older | No |
 
 Upgrade with `npm i -g mingdao-harness@latest` (npm installs), or `mingdao update` / `mingdao rollback`
@@ -48,7 +48,8 @@ Please do not open a public issue for an unfixed vulnerability. Credit is offere
 - `src/permissions.js` — the permission decision engine: `allow` / `deny` / `denyStrict` matching and
   the `readonly` / `ask` / `auto` modes.
 - `desktop/**` — the Electron shell: window navigation and `openExternal` handling, the contextBridge
-  preload surface, IPC handlers.
+  preload surface, IPC handlers, and update-package signature verification (a bypass of the pinned key or
+  of the fail-closed policy is in scope).
 
 Reports that affect anything else in `src/` are welcome too; the list above is where the trust
 boundaries live.
@@ -90,14 +91,18 @@ boundaries live.
 5. **Treat Packs as untrusted code.** Run `mingdao pack verify <dir>` (static; `--runtime` executes the
    Pack) and read `pack.mjs` before `mingdao pack trust`; never trust a freshly cloned repository you
    have not reviewed.
-6. **Enable the audit trail and the ledger.** Keep `config.audit` on, review `mingdao audit`
-   periodically, and run `mingdao ledger verify` on turns you care about. For unattended jobs, prefer
+6. **Enable the audit trail and the ledger, and keep the signing key.** Keep `config.audit` on,
+   review `mingdao audit` periodically, and run `mingdao ledger verify` on turns you care about; a new
+   ledger is signed automatically with `<home>/ledger-key.json` (mode 600). Back that file up: replacing
+   it turns every previously signed ledger into "signed by another key". For unattended jobs, prefer
    `readonly` or `denyStrict` over `auto`.
 7. **Sandbox shell execution where you can.** On Linux with `bubblewrap` installed, set
    `config.sandbox` to `readonly` or `safe` (no network). Elsewhere the sandbox downgrades to `off` and
    says so — compensate with OS-level isolation or a container.
 8. **Run the desktop build only from a source you trust** and verify the checksum published on the
-   Release page; current desktop builds are unsigned (see below).
+   Release page; current desktop builds are unsigned. If you require update provenance, set
+   `MINGDAO_REQUIRE_UPDATE_SIGNATURE=1` so an update package without a valid signature is **rejected**
+   (the default is to install but explicitly report that the signature was not verified).
 
 ## Known boundaries
 
@@ -114,15 +119,23 @@ price them in.
 2. **Packs have no isolation.** `pack.mjs` runs in the host process with full Node privileges, and
    `manifest.permissions` is not enforced by the kernel. Capability brokering or subprocess isolation
    for Packs requires an architectural change and is not implemented.
-3. **Electron code signing and update-package signature verification are not done.** Current builds
-   are unsigned (see [`docs/CODE-SIGNING.md`](docs/CODE-SIGNING.md), which describes the steps to sign);
-   the auto-updater does not verify a signature on the downloaded update package beyond the transport.
+3. **Electron code signing / notarization is still not done.** Current builds are unsigned (see
+   [`docs/CODE-SIGNING.md`](docs/CODE-SIGNING.md), which describes the steps to sign). Update-package
+   **source-signature verification is implemented** (`desktop/update-verify.js`: ed25519 over the
+   installer bytes, public key pinned in the source; a present-but-invalid signature is always rejected),
+   but the release pipeline does not sign builds yet. Consequently the default policy is
+   `warn-and-install` (install, and state that the signature was not verified); set
+   `MINGDAO_REQUIRE_UPDATE_SIGNATURE=1` to make unsigned updates fail closed.
 4. **IDE plugin token storage needs hardening.** The VS Code and JetBrains plugins drive the local
    WebUI over loopback; the broader item (secure token storage, and distinguishing HTTP 401 from
    "server unreachable") is registered as open work.
-5. **Ledger events are tamper-evident but not signed.** The hash chain plus the `run.end` seal detect
-   modification and truncation after the fact, but there is no trusted timestamp and optional signing
-   (`--sign-key`) is not implemented — so the ledger is not audit-grade non-repudiation, and
-   `mingdao ledger verify` says exactly that in its own output.
+5. **Ledger provenance has the same limits as the machine it runs on.** The hash chain plus the
+   `run.end` seal detect modification and truncation after the fact, and since v0.6.11 the seal also
+   carries an **ed25519 source signature** (auto-generated key at `<home>/ledger-key.json`, mode 600;
+   `mingdao ledger --sign-key` to inspect/rotate; `verify` reports valid / unsigned / invalid /
+   unverifiable, with "unverifiable" also failing). The boundary: the private key and the ledger share
+   the same machine and permissions, so this does not defend against a local attacker who can already
+   rewrite the ledger; there is no trusted timestamp; and replacing the key makes old ledgers report
+   "signed by another key". It is provenance, not audit-grade non-repudiation.
 
 We do not claim this project is vulnerability-free, and this document is not a marketing statement.

package/docs/CONFIG.md

@@ -373,6 +373,56 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 
 长期偏好仍走用户记忆（`AGENTS.md`，见上），不受此开关影响。
 
+## 模型名称以 API 为准（v0.6.19，§3.67）
+
+**仓库不维护具体版本号，只维护「家族能力 / 定价模式」。** 官方改名、升版本（例如
+`deepseek-v4-flash` → `deepseek-flash` → `DeepSeek-V4.1-Flash 1017` → 未来的 V4.2/V5）
+**不需要改代码**：模型名一律以 `GET /v1/models` 实时返回的官方名为准。
+
+### 家族模式表
+
+`src/models.js` 的 `MODEL_FAMILIES` 用正则匹配名字，能力（上下文窗口、单次输出上限、工具调用、
+视觉）与定价挂在**模式**上：
+
+| 家族 | 匹配（大小写 / 空格 / 连字符 / 版本号无关） | 典型官方名 |
+| --- | --- | --- |
+| `pro` | `deepseek` + 可选版本 + `pro` | `DeepSeek-V4.1-Pro 1017` |
+| `flash` | `deepseek` + 可选版本 + `flash` | `DeepSeek-V4.1-Flash 1017` |
+| `vision` | `deepseek` + 可选版本 + `flash` + `vision` | `DeepSeek-V4.1-Flash-Vision 1017` |
+
+- 精确 id 只作为**已知别名**存在（如旧名 `deepseek-v4-flash`），老配置与历史会话照常可用；
+  路由比较前会归一化到家族代表名，不会因为厂家改名而静默失效。
+- 比已核对规格更新的版本（例如 `DeepSeek-V4.2-Flash 1101`）**仍可选中**，列表会标
+  「能力未知（新版本）」并按家族规格保守估算上下文与价格；需要精确规格时用
+  `customModels.<模型名>.contextWindow` / `config.pricing.overrides` 覆盖。
+
+### 默认值如何解析
+
+默认模型（新建配置、WebUI 模型下拉、自动路由的 planner / executor）在**运行时**按下列顺序解析：
+
+1. 用户显式配置优先：`config.model`、`config.routing.planner`、`config.routing.executor`；
+2. 否则从**当前 API 名单**里按家族挑官方名：planner → `pro` 家族，executor → `flash` 家族，
+   多个版本并存时取最高版本；
+3. 名单里没有对应家族、或 API 不可达时，才退回**内置家族代表名**，并输出提示：
+   - 服务端日志：`[MingDao] ⚠ … 默认模型走兜底 …`
+   - WebUI / HTTP：`GET /api/models` 与 `GET /api/state` 的 `note` 字段，离线时
+     `offlineFallback: true`，文案为「离线兜底：模型名可能不是最新的」。
+
+离线时模型列表使用内置家族代表名（不是最新官方版本），并在每个条目上标
+「离线兜底」；连上 API 后刷新即恢复官方名。
+
+**自定义端点不主动探测。** `provider: "custom"`（以及未内置的服务商）不会收到
+`GET /models` 请求——很多自定义网关只实现 chat，空 body 的 `/models` 请求会让它们直接崩。
+这类端点的默认 planner / executor 用家族代表名兜底，需要指定时在 `config.routing.*`
+里写端点自己的模型名。
+
+### 旧名与自定义模型
+
+- 旧名（`deepseek-v4-flash`、`deepseek-flash`、`deepseek-v4-pro`、`deepseek-v4-flash-vision-exp`）
+  仍可作为 `--model` / `config.model` 的取值；能力与定价照旧按家族解析。
+- 完全不属于任何家族的线上新模型（例如非 DeepSeek 命名）仍会出现在列表里，可直接选中；
+  能力未知时按远程模型保守默认（上下文 128k）估算，可用 `customModels` 显式覆盖。
+
 ## 自定义模型（WebUI 添加后落盘的结构）
 
 ```json
@@ -531,6 +581,52 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 既有默认, 1800s)、无进展看门狗 = clamp(max(实测首帧×100, 参考prefill×20), 10min, 60min)；
 **你显式配置的 `timeout.*` / `noProgressTimeoutMs` 永远优先**（显式 > 自适应）。
 
+#### 本地模型：并发与内存（v0.6.15）
+
+真机证据（v0.6.14，8081 的 `mtplx-qwen38-27b-optimized-quality`）：长任务中途被引擎拒绝——
+`insufficient memory: the request exceeded available GPU memory (sustained critical memory pressure
+during prefill; aborted before the allocator wall). The engine shed its caches and stays up; this
+request failed.` 同一错误此前在 60091 的 35B 上也出现过 → **不是模型问题，是本机内存压力**。
+观测到该回合此前有子代理在跑（13 轮 / 17 次工具调用）→ **父回合 + 子代理同时向同一本地引擎
+发大 prefill**（各自要一份 KV cache）是主要来源。所以内核现在对**同一 `baseUrl`** 的本地端点
+在途请求做**串行化/限量**：
+
+- **默认 1 并发**：父回合、子代理（`task`）、**端点预检**（探针打的是同一个 `/chat/completions`）
+  共用同一条**进程级 Promise 队列**，谁先到谁先跑，后到的排队（不是忙等，释放即移交名额）。
+- **配置**（与 `timeout` 同级，写在 `config.json` 顶层）：
+
+  ```json
+  {
+    "localConcurrency": 1,
+    "localQueueTimeoutMs": 1800000
+  }
+  ```
+
+  | 字段 | 默认 | 含义 |
+  | --- | --- | --- |
+  | `localConcurrency` | `1` | 同一本地 `baseUrl` 的同时在途请求上限。`0` = **显式退出串行化**（不限并发）；正整数上限 16；非法/负数回落 1 |
+  | `localQueueTimeoutMs` | `1800000`（30 分钟） | 排队等待上限。超过即报**可见错误**（不重试、不死等），避免"看起来在跑、其实永远排不到" |
+
+- **云端端点不受影响**：`baseUrl` 不是回环/内网（如 `api.deepseek.com`）时直接放行——不排队、
+  不记日志、不增加任何延迟。`customModels.<名>.local: true` 可把经反代的本地端点纳入串行化。
+- **可见性**：入队时写一行 `本地端点串行化：等待 N 个在途请求（端点，并发上限 1）`
+  （WebUI 落 `~/.mingdao/logs/web-server.log`；CLI 写 stderr）；界面状态条/进度行显示
+  `本地端点已串行化（防内存压力）`，发送前的 `📏 本轮上下文` 预告在**已有在途请求**时会加一条强警告
+  `并发会加剧内存压力 … 建议减少子代理数量`。
+- **排队超时的报错**（`code=LOCAL_QUEUE_TIMEOUT`）：
+  `本地端点排队超时（等待 1800.0s，仍有 1 个在途请求，并发上限 1）：为避免内存压力已在本机端点串行化——可调大 config.localQueueTimeoutMs，或减少子代理/并行会话。`
+- **引擎活着但丢了缓存**：上游文案含 `engine shed its caches and stays up` / `allocator wall` 时，
+  错误分型会明确"**该引擎未崩溃**（自己丢弃缓存后继续运行）"、**不要重启引擎**，处置是
+  压上下文（`contextBudget` / `/compact`）、减少并发、等它自行恢复后重试。这与"引擎崩了/连接被拒"
+  （`ECONNREFUSED`、连接被断开）是**不同**的两种判定，后者才需要确认端口与进程。
+- **排查步骤**（还遇到内存拒绝时）：
+  1. 看 `web-server.log` 有没有 `本地端点串行化：等待 N 个在途请求`——有排队说明闸门在工作，
+     若仍被拒绝，说明单请求本身就超了引擎内存（压 `contextBudget`，或让 `customModels.<名>.contextWindow`
+     ≤ 引擎自述的 `n_ctx`，见上一节）；
+  2. 确认没有多个会话/多个本地模型同时跑长任务（每个模型各占一份显存与 KV cache）；
+  3. 临时把 `localConcurrency` 保持 `1`，并减少子代理数量（读只读子代理在本地模型下已不并行）；
+  4. **不要**因为 `engine shed its caches and stays up` 去重启引擎——它没有崩；重启只会重新加载模型。
+
 ### 用本地模型测 harness（测试者步骤清单）
 
 > 这一段是**操作清单**，不是原理说明。按顺序做，能在几分钟内区分"端点不行"和"harness 不行"。
@@ -653,6 +749,11 @@ mingdao ledger verify <runId> --key <文件>     # 用指定公钥验签（本
   顺手一次就会把签名密钥清掉、让全部历史账本变成"另一把密钥签发"。
 - **默认开启**：新账本在首次收尾时若本机还没有密钥会**自动生成**并签名（可选签名在合规上等于
   没有签名）。封条里带 `sig{alg,keyId,value}`，`run.end` 链内带 `sigKey`（公钥指纹）。
+- **`run.start.permissionSource`（v0.6.17 §3.64）**：记录本回合生效权限的**来源**——`explicit`
+  （用户/调用方显式选择，如 WebUI 权限档）/ `preset`（预设声明生效）/ `config`（`config.json`
+  的 `permission`）/ `cli`（后台/调度任务由 CLI 参数指定）/ `default`（以上都没有，落到内置缺省
+  `ask`；WebUI 的 `config` 分支在缺字段时也归 `config`）。`permission` 仍是生效值、`LEDGER_VERSION`
+  不变；旧账本没有该字段照样 `verify` 通过（`show` 只是少一行可选的「权限来源」）。
 - **`ledger verify` 的三种结论**（前两者退出码 0，第三者非 0）：
 
   | 结论 | 含义 | 退出码 |
@@ -671,3 +772,9 @@ mingdao ledger verify <runId> --key <文件>     # 用指定公钥验签（本
 （按模型分账、每日费用柱状图、缓存命中率、Batch 子项），文件落当前目录
 `mingdao-cost-report-<月>.md`。数据源为 cache-stats.jsonl（含缓存折扣与 Batch 半价的真实口径）。
 
+
+## 开发工具：变异验证的 fail-safe
+
+`node test/mutate/run.mjs` 启动时会先自检残留标记（能自愈的自愈，冲突/在飞则拒绝），
+并用 `test/mutate/.generated/mutate.lock` 做互斥；详见 `test/mutate/FAILSAFE.md`。
+手工自检：`node test/mutate/check.mjs`（`--allow-dirty` 可放行脏工作树）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.6.14",
+  "version": "0.6.16",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -18,15 +18,16 @@ import { redactSecrets } from './redact.js';
 import { checkCostGuard, costGuardConfig, todayCost, preflightBlockMessage, roundGuardAction } from './cost-guard.js';
 import { recordCacheStats, packDailyCost } from './cachestats.js';
 import { estimateCost, cacheSplit, isPeakHour } from './pricing.js';
-import { resolveProviderConfig, createProvider } from './providers/index.js';
+import { resolveProviderConfig, createProvider, localGateSnapshot, localConcurrencyLimit } from './providers/index.js';
 import { compileConstraints, checkPreTool, checkPostTool, checkOutput, blockedOutputText } from './constraints.js';
 import { createLedger, newRunId } from './ledger.js';
 import { registerEgressSink } from './net-guard.js';
 import { getActivePackContext } from './packs.js';
 // v0.6.11（审计 P1-1 拆分第三刀）：工具编排两端的判据单源在 tools-flow.js——
 // ① 本轮可见哪些工具（只读档 × 预设白名单 × 已用工具快照 × MCP 只读标注）；
-// ② 工具结果怎么回填（序列化 / 复用前缀 / 约束拒绝文案 / 按窗口截断）。
-import { READONLY_TIER_SET, visibleToolsFor, serializeToolResult, toolResultMessage } from './tools-flow.js';
+// ② 工具结果怎么回填（序列化 / 复用前缀 / 约束拒绝文案 / 按窗口截断）；
+// ③ 工具参数怎么解析（v0.6.17 第四刀：JSON + 容错 + 归一化 + 错误文案）。
+import { READONLY_TIER_SET, visibleToolsFor, serializeToolResult, toolResultMessage, parseToolArgs } from './tools-flow.js';
 
 const MAX_STEPS = 24;
 // 子代理步数上限：审计/精读类只读子任务需要读多个文件 + 交叉引用，12 步易在「读不全」时被截断
@@ -144,11 +145,16 @@ const fmtTok = (/** @type {any} */ n) => Number(n || 0).toLocaleString('en-US');
  *
  * v0.6.13（问题 1 修法）：**有预检实测就必须由它推导**，并在文案里如实标注
  * ①这是外推、②长上下文下外推会低估（附实测差值）；只有在**没有预检数据**时才退回保守文案。
+ *
+ * v0.6.15（§3.59 第 3 条）：本地端点**已有在途请求**（父回合/子代理/预检之一）时加一句强警告——
+ * 真机 8081 的内存拒绝就是"父子回合同时 prefill"撞出来的；串行化已经兜住资源，但用户仍应
+ * 知道"并发会加剧内存压力、应减少子代理"。
  * @param {{ promptTokens: number, contextWindow?: number, isLocal?: boolean,
- *           firstTokenMs?: number, budget?: number, probe?: any }} input
+ *           firstTokenMs?: number, budget?: number, probe?: any,
+ *           localBusy?: boolean, localActive?: number, localQueued?: number, localConcurrency?: number }} input
  * @returns {{ text: string, warn: boolean, promptTokens: number, ratio: number, estimateMs: number|null }}
  */
-export function prefillForecast({ promptTokens, contextWindow, isLocal, firstTokenMs, budget, probe = null }) {
+export function prefillForecast({ promptTokens, contextWindow, isLocal, firstTokenMs, budget, probe = null, localBusy = false, localActive = 0, localQueued = 0, localConcurrency = 1 }) {
   const p = Math.max(0, Math.round(Number(promptTokens) || 0));
   const win = Number(contextWindow) > 0 ? Number(contextWindow) : 0;
   const ratio = win > 0 ? p / win : 0;
@@ -187,10 +193,22 @@ export function prefillForecast({ promptTokens, contextWindow, isLocal, firstTok
       `建议缩小任务（新建会话、只给必要文件、先 /compact）或调大 config.timeout.firstTokenMs——` +
       `但注意调大它只会让"失败"更晚被发现，不会让 prefill 变快。`
     : '';
+  // v0.6.15（§3.59 第 3 条）：本地端点已有在途请求 → **强警告**（不是提示）。
+  // 真机证据：父回合 + 子代理同时向同一台 8081 引擎发大 prefill，引擎在 prefill 阶段报
+  // insufficient memory（"engine shed its caches and stays up"）；串行化解决资源冲突，
+  // 但用户仍必须知道"并发会加剧内存压力"，否则会继续开并行子代理/多会话。
+  const limit = Number(localConcurrency) >= 0 ? Math.floor(Number(localConcurrency)) : 1;
+  const active = Math.max(0, Math.floor(Number(localActive) || 0));
+  const queued = Math.max(0, Math.floor(Number(localQueued) || 0));
+  const concurrencyNote = Boolean(isLocal) && Boolean(localBusy)
+    ? `\n   ⚠ 本地端点当前已有 ${active} 个在途请求${queued > 0 ? `、${queued} 个在排队` : ''}（并发上限 ${limit}）：` +
+      `**并发会加剧内存压力**（父子回合同时 prefill 会被引擎以 insufficient memory 拒绝）；` +
+      `${limit <= 1 ? '已串行化，后来的请求会排队等待' : `已限制为 ${limit} 并发，仍可能叠加内存压力`}——建议减少子代理数量、避免多个长任务会话同时跑。`
+    : '';
   // v0.6.13（A 追加）：把**端点预检**结果并进这条预告——"这个端点行不行"与"这次要 prefill 多少"
   // 必须一起出现在发送前，而不是等出事后翻日志（引擎实际加载的模型名与配置名不一致也在这里说）。
   const probeLine = probe && probe.note ? `\n   端点预检：${probe.note}` : '';
-  return { text: `${head}\n   ${timing}${probeLine}${advice}`, warn, promptTokens: p, ratio, estimateMs: est ? est.ms : null };
+  return { text: `${head}\n   ${timing}${probeLine}${advice}${concurrencyNote}`, warn: warn || Boolean(concurrencyNote), promptTokens: p, ratio, estimateMs: est ? est.ms : null };
 }
 
 /**
@@ -276,6 +294,15 @@ export function describeUpstreamError(/** @type {any} */ err) {
     hint =
       '上游拒绝的是**它的 prompt 模板**（不是网络问题）：该端点的模板不接受当前 messages 形态（典型：按单轮 query 设计的 chatflow/模板，收到的是 OpenAI 多轮 messages）。' +
       '这类端点通常也**不返回 tool_calls**——请改用支持 function calling 的模型/端点，或让网关把 messages 映射成它要的单轮入参。';
+  } else if (/engine shed its caches and stays up|allocator wall/.test(t)) {
+    // v0.6.15（§3.59 第 2 条）：**引擎活着但丢了缓存**——与"引擎崩了/连接被拒"是两件事。
+    // 真机原文（8081）：`insufficient memory: … aborted before the allocator wall.
+    // The engine shed its caches and stays up; this request failed.` 引擎自己丢了 KV cache
+    // 并继续服务，**没有崩溃**；此时建议"重启引擎"是错的（重启只会把模型重新加载一遍）。
+    hint =
+      '本地引擎**内存/显存不足**，但它**未崩溃**（原文：engine shed its caches and stays up——引擎自己丢弃缓存后仍在运行）。' +
+      '**不要重启引擎**（重启不会增加显存，反而要重新加载模型）。处置：压缩上下文（减小 config.contextBudget 或 /compact）、' +
+      '减少并发子任务/并行会话（同一本地端点已按 config.localConcurrency 串行化），然后可直接重试——引擎通常会自行恢复。';
   } else if (/memory_refusal|insufficient memory|gib|内存不足|内存拒绝/.test(t)) {
     hint =
       '本地引擎**内存/显存不足**（在 prefill 前就拒绝了）。处置：压缩上下文（减小 config.contextBudget 或 /compact）、减少并发子任务，或重启模型服务释放内存后重试。';
@@ -302,9 +329,10 @@ export function describeUpstreamError(/** @type {any} */ err) {
  * @param {{ phase?: string, elapsedMs: number, modelRounds?: number, toolCalls?: number,
  *           toolExecuted?: number, contentChars?: number, ttftMs?: number|null,
  *           pendingTool?: { name: string, ms: number }|null, tokensPerSec?: number|null,
- *           subagent?: { label?: string, modelRounds?: number, toolCalls?: number, at?: number }|null }} p
+ *           subagent?: { label?: string, modelRounds?: number, toolCalls?: number, at?: number }|null,
+ *           localQueue?: { active?: number, queued?: number, limit?: number }|null }} p
  */
-export function formatTurnProgress({ phase, elapsedMs, modelRounds = 0, toolCalls = 0, toolExecuted = 0, contentChars = 0, ttftMs = null, pendingTool = null, tokensPerSec = null, subagent = null }) {
+export function formatTurnProgress({ phase, elapsedMs, modelRounds = 0, toolCalls = 0, toolExecuted = 0, contentChars = 0, ttftMs = null, pendingTool = null, tokensPerSec = null, subagent = null, localQueue = null }) {
   const s = Math.max(0, Math.round(Number(elapsedMs) / 1000));
   const parts = [
     `已跑 ${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s`,
@@ -316,6 +344,15 @@ export function formatTurnProgress({ phase, elapsedMs, modelRounds = 0, toolCall
   if (tokensPerSec != null) parts.push(`≈${Number(tokensPerSec).toFixed(1)} tok/s`);
   parts.push(`已收正文=${contentChars} 字`);
   if (pendingTool) parts.push(`正在等待工具 ${pendingTool.name}（已 ${Math.round(Number(pendingTool.ms) / 1000)}s）`);
+  // v0.6.15（§3.59）：本地端点因内存压力串行化时，进度行必须能看出来——
+  // 否则"在排队"与"引擎卡住"在事后日志里完全同形（真机取证最缺的就是这一行）。
+  if (localQueue) {
+    parts.push(
+      `本地端点已串行化（防内存压力）：等待 ${Math.max(0, Number(localQueue.active) || 0)} 个在途请求` +
+        (Number(localQueue.queued) > 0 ? `、${Number(localQueue.queued)} 个排队` : '') +
+        `，并发上限 ${Number(localQueue.limit) || 1}`
+    );
+  }
   // v0.6.13（问题 3）：等 `task` 子代理时必须能看出"这个子任务跑到哪一步"——
   // 否则"等子代理 620s"与"卡死 620s"在日志上完全同形（真机现场正是如此）。
   if (subagent) {
@@ -753,6 +790,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       session: sessionRef?.name ?? null,
       cwd: workingDir,
       permission: cfg.permission ?? permission?.mode ?? null,
+      // v0.6.17 §3.64：来源由入口（WebUI/CLI）算好随 cfg 传入；agent 只透传，不猜。
+      // 后台任务/REPL 内切换预设等未传来源的路径写 null（来源未知），绝不冒充 config。
+      permissionSource: cfg.permissionSource ?? null,
       preset: preset?.name ?? cfg.preset ?? null,
       // v0.6.7（报告二 P3-1）：activeCtx 的形状是 { mounted, warnings, promptSections, constraints, toolCount }，
       // **没有 `.packs` 键** —— 这里此前恒为 []，账本里"本次运行挂了哪些 Pack"永远记空。
@@ -859,6 +899,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       // 界面/日志据此显示"在等哪个子任务、它跑到第几轮 / 几次工具调用"
       subagent: null,
       forecast: null,
+      // v0.6.15（§3.59）：本地端点串行化快照（排队时由 provider 的 onQueueWait 填入）
+      localQueue: null,
+      localQueueNoticed: false,
       noProgressMs,
       lastProgressAt: Date.now(),
       progressReason: '回合开始',
@@ -1278,6 +1321,12 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         try {
           let promptTokens = 0;
           for (const m of sanitized) promptTokens += messageTokens(m, count);
+          // v0.6.15（§3.59 第 3 条）：本地端点是否已有在途/排队请求（父回合、子代理、预检共用同一队列）。
+          // 这里读的是**进程级闸门快照**（provider.config.baseUrl），不是猜——云端端点恒为 0。
+          let gate = { active: 0, queued: 0, limit: 1 };
+          try {
+            if (caps.isLocal) gate = localGateSnapshot(provider?.config?.baseUrl);
+          } catch {}
           const f = prefillForecast({
             promptTokens,
             contextWindow: caps.contextWindow,
@@ -1285,6 +1334,10 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             firstTokenMs: Number(cfg?.timeout?.firstTokenMs) > 0 ? Number(cfg.timeout.firstTokenMs) : effFirstTokenMs,
             budget,
             probe: cfg?.endpointProbe || null,
+            localBusy: Boolean(caps.isLocal && (gate.active > 0 || gate.queued > 0)),
+            localActive: gate.active,
+            localQueued: gate.queued,
+            localConcurrency: localConcurrencyLimit(cfg),
           });
           turnProgress.forecast = f;
           // 首次请求一定说；之后只在命中告警线时说（否则每步一条横幅会刷屏）
@@ -1309,6 +1362,31 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           // MiniMax P0：仅当 activeModel 声明支持 reasoning 才发送（否则 400 终止回合）；'off' 显式禁用例外
           reasoningEffort: modelPreset(activeModel)?.supportsReasoning || reasoningEffort === 'off' ? reasoningEffort : undefined,
           signal: ac.signal,
+          // v0.6.15（§3.59 第 1 条）：本地端点串行化必须**在界面上可见**——
+          // 排队时状态条/进度行写"排队等待本地端点（已串行化防内存压力）"，
+          // 拿到名额后恢复"发请求（等首帧）"（onDelta 之后会覆盖成"解码中"）。
+          onQueueWait(/** @type {any} */ ev) {
+            if (!ev) return;
+            if (ev.waiting) {
+              turnProgress.localQueue = { active: ev.active, queued: ev.queued, limit: ev.limit };
+              turnProgress.phase = `排队等待本地端点（已串行化防内存压力：${ev.active} 个在途）`;
+              if (!turnProgress.localQueueNoticed) {
+                turnProgress.localQueueNoticed = true;
+                try {
+                  io.print(
+                    style(
+                      `⏳ 本地端点串行化：等待 ${ev.active} 个在途请求（并发上限 ${ev.limit}）——` +
+                        `本地模型内存压力，父回合与子代理不再同时 prefill`,
+                      C.dim
+                    )
+                  );
+                } catch {}
+              }
+            } else {
+              turnProgress.localQueue = null;
+              if (String(turnProgress.phase || '').startsWith('排队等待本地端点')) turnProgress.phase = '发请求（等首帧）';
+            }
+          },
           onDelta(/** @type {any} */ d) {
             io.stopSpinner();
             // v0.6.13（A）：帧/字符计数 + 首帧时延（TTFT）——本地模型最关键的指标
@@ -1362,7 +1440,11 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         // MacBook 本地 507 memory_refusal 根因（v0.4.5）：服务端内存拒绝不是「空输出」——
         // 直接终结合合并透出降级提示，不计入空轮、不注入续写重试（内存未释放必再 507，空烧请求）。
         const e = /** @type {any} */ (err);
-        if (e?.status === 507 || /memory_refusal|内存不足|内存拒绝/i.test(String(e?.message || ''))) {
+        // v0.6.15（§3.59 第 2 条）：`engine shed its caches and stays up` / `allocator wall`
+        // 说明引擎**活着**（自己丢缓存后继续服务）——不走这条"507 旧文案"（那里建议重启引擎，
+        // 对活着但内存吃紧的引擎是错误处置）；交给下面 describeUpstreamError 的独立分型。
+        const engineShedCaches = /engine shed its caches and stays up|allocator wall/i.test(String(e?.message || ''));
+        if (!engineShedCaches && (e?.status === 507 || /memory_refusal|内存不足|内存拒绝/i.test(String(e?.message || '')))) {
           stripOrphanCalls();
           markOutcome('done');
           return {
@@ -1515,22 +1597,18 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
               ...extra,
             });
           let args = /** @type {any} */ (null);
-          try {
-            args = JSON.parse(tc.function?.arguments || '{}');
-          } catch {
+          // 参数解析/容错/归一化单源在 tools-flow.js 的 parseToolArgs()（v0.6.17，P1-1 第四刀）：
+          // 本函数只返回判据，下面三条副作用（渲染拒绝 / 审计 / 回填分块指引）仍按原顺序执行。
+          const parsedArgs = parseToolArgs(tc.function?.arguments);
+          if (!parsedArgs.ok) {
             // 参数 JSON 解析失败：回填错误给模型，不拿空参数去执行工具
-            io.renderToolDenied(name, {}, '参数解析失败（输出超限被截断？建议分块）');
-            if (auditOn) auditEntry({ denied: true, reason: '参数解析失败' });
+            io.renderToolDenied(name, {}, parsedArgs.deniedReason);
+            if (auditOn) auditEntry({ denied: true, reason: parsedArgs.auditReason });
             // 审计（长生成截断循环）：给出明确分块指引，避免模型反复用单个超大 write 撞输出上限
-            messages.push({
-              role: 'tool',
-              tool_call_id: tc.id,
-              content:
-                '工具参数 JSON 解析失败（大概率是输出超过模型单次上限被截断）。请把内容拆分成多个较小文件或多次调用逐步写入：单个 write 的参数总长控制在 6000 字符以内；先写核心骨架，再逐文件补充。',
-            });
+            messages.push({ role: 'tool', tool_call_id: tc.id, content: parsedArgs.message });
             return null;
           }
-          if (!args || typeof args !== 'object' || Array.isArray(args)) args = {};
+          args = parsedArgs.args;
 
           // PreToolUse 钩子
           const hook = await hooks.pre(name, args);

package/src/cli.js

@@ -403,7 +403,16 @@ async function main() {
     }
   }
   // agent 使用的配置 = cfg + 预设 overlay（presetTools/permission/参数按预设生效，cfg 本体保持干净）
-  const agentCfg = Object.keys(presetOverlay).length ? { ...cfg, ...presetOverlay } : cfg;
+  const agentCfgBase = Object.keys(presetOverlay).length ? { ...cfg, ...presetOverlay } : cfg;
+  // v0.6.17 §3.64：本进程的权限来源随 cfg 进账本（`run.start.permissionSource`）。
+  // 顺序与生效值一致：预设 overlay 里有 permission > config.json 的 permission > 内置缺省。
+  // 注意**不写回 cfg**（agentCfg 是副本）：repl 的 saveConfig(cfg) 绝不能把来源字段持久化。
+  const permissionSource = Object.prototype.hasOwnProperty.call(presetOverlay, 'permission')
+    ? 'preset'
+    : cfg.permission !== undefined && cfg.permission !== null
+      ? 'config'
+      : 'default';
+  const agentCfg = { ...agentCfgBase, permissionSource };
 
   const pc0 = resolveProviderConfig(cfg, modelName);
   // v0.6.0 C4：内网/本机端点（vLLM、Ollama、OneAPI 等）通常不校验密钥，很多也不发放密钥。