mingdao-harness 0.6.6 → 0.6.9

package/README.en.md

@@ -0,0 +1,132 @@
+# MingDao Harness — English README
+
+> **Language policy.** The canonical documentation of this project is **Chinese**.
+> The Chinese [`README.md`](README.md) and everything under [`docs/`](docs/) are the reference.
+> This English README covers only the minimum needed to **evaluate and deploy** the project.
+> Where this file and the Chinese docs disagree, **the Chinese docs and the code win**.
+> (中文：规范文档为中文，本英文 README 只覆盖评估与部署所需的最低限度内容；两者不一致时以中文文档与代码为准。)
+
+---
+
+## What it is
+
+MingDao Harness (`mingdao`, short alias `mdh`) is a **zero-runtime-dependency** agent harness written
+in plain Node.js: a model loop plus tools plus a permission layer, driven from a terminal TUI, a local
+WebUI, an Electron desktop shell, or an IDE plugin. It ships with a declarative-plus-programmable
+"Pack" system for domain packages. It is **not** a sandbox and **not** a security boundary for
+untrusted code you choose to load — see the security model below, including the parts it deliberately
+does not cover (this file is written so a reviewer can decide that, not to make the project look safer
+than it is).
+
+- Node.js **>= 18.17** (`package.json` `engines`), no build step, no npm runtime dependencies.
+- Current version: **0.6.8** · License: **MIT**.
+- Repo: <https://github.com/MingDaoTCM/MingDao-Harness> · Package: `mingdao-harness` on npm.
+
+## Quickstart (3 steps)
+
+**1. Install.**
+
+```bash
+# Any platform, via npm (installs both `mingdao` and `mdh`)
+npm i -g mingdao-harness
+```
+
+Or take the **desktop build** from GitHub Releases (Electron; unsigned — see "Known boundaries" in
+[`SECURITY.md`](SECURITY.md)): <https://github.com/MingDaoTCM/MingDao-Harness/releases>
+
+**2. Configure a key.**
+
+```bash
+mingdao init          # wizard: provider -> API Key (hidden input) -> model -> permission -> sandbox
+```
+
+**3. Run.**
+
+```bash
+mingdao               # interactive TUI (REPL)
+mingdao web           # WebUI on http://127.0.0.1:3820 by default
+```
+
+One-shot / scripted use:
+
+```bash
+mingdao "explain this stack trace"
+mingdao --format json "summarize the diff"     # single-line structured output
+mingdao run "run the test suite and fix failures"   # background task
+```
+
+## Security model
+
+Every row states a **mechanism** and, in the same row, **its boundary**. A mechanism that is not
+enforced by the kernel is described as a declaration, not as a control.
+
+| Mechanism | What it does | Its boundary (read this) |
+| --- | --- | --- |
+| **Permission modes** — `config.permission` | `"ask"` (default), `"auto"`, `"readonly"`, or an object `{ "mode": "ask", "allow": [...], "deny": [...], "denyStrict": false }`. Rules match a tool name or `tool:argument-prefix*`. Read-only tools (`read`, `glob`, `grep`, `ls`, `skill`, `git`, `fetch`) auto-pass in every mode. | `deny` is **not** a hard block by default: a hit prompts "force allow this once?" and a `y` bypasses your own rule. Only `denyStrict: true` removes that override (and additionally refuses `sh -c` / `eval`-wrapped commands, because a deny rule cannot see the real command inside the argument). Under `auto` nothing else prompts, so `deny` is the only rule that can intervene — and it remains bypassable with a `y` until `denyStrict` is set. `allow` prefix rules for `bash` deliberately refuse to match any command containing shell metacharacters. |
+| **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. |
+| **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. |
+| **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
+
+Commands are grouped here for evaluation; `mingdao --help` and `src/help.js` are the source of truth.
+
+| Command | Purpose |
+| --- | --- |
+| `mingdao` | Interactive TUI (REPL). |
+| `mingdao "question"` | One-shot question; `--format json` for structured output. |
+| `mingdao init` | First-run wizard (provider → API Key → model → permission → sandbox). |
+| `mingdao run "<task>"` | Start a background task (managed via `mingdao tasks`). |
+| `mingdao tasks [watch\|kill <id>]` | List / live-refresh / stop background tasks. |
+| `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 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. |
+| `mingdao batch <file\|->` | Batch API (half price) over one question per line; `--model`, `--max-tokens`, `--max-cost`. |
+| `mingdao cost [report [YYYY-MM\|all]]` | Cost report / monthly export; `--by pack` for per-Pack attribution. |
+| `mingdao schedule add\|list\|remove\|pause\|resume\|chain` | Scheduled and chained tasks. |
+| `mingdao sync login\|status\|push\|pull\|logout` | Cross-device session sync client; also `passwd` (change password), `share` / `shares` / `accept` / `unshare` (session sharing) and `conflicts` / `conflict-resolve`. |
+| `mingdao sync-server [port]` | Self-hosted zero-dependency sync server. |
+| `mingdao skill search\|install\|uninstall\|update\|trust` | Skill library (built-in plus a remote registry). |
+| `mingdao sessions search <keyword>` | Full-text search over historical sessions. |
+| `mingdao workspace add\|list\|use\|path\|remove` | Register and switch project directories. |
+| `mingdao mcp preset list\|add <name>` | MCP ecosystem presets; `mcpServers` in `config.json` for arbitrary servers. |
+| `mingdao update [--check]` / `mingdao rollback` | Self-update (git installs) / roll back to the previous revision; `update --pricing` refreshes the price table. |
+| `mingdao desktop` | Launch the Electron desktop build. |
+| `mingdao autostart on\|off` | Start the server automatically at login. |
+| `mingdao --preset <name>` | Apply a declarative agent preset (tool allowlist / permission / model). In-session the equivalent is `/preset`. |
+| `mingdao --help` / `--version` | Help / version. |
+
+## Docs index
+
+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/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.
+- [`docs/DEVELOPER.md`](docs/DEVELOPER.md) — stable export surface and embedding the harness as a library.
+- [`docs/CODE-SIGNING.md`](docs/CODE-SIGNING.md) — desktop code-signing / notarization status and the steps to sign.
+- [`docs/internal/AUDIT-v0.6.1-第三方报告登记.md`](docs/internal/AUDIT-v0.6.1-第三方报告登记.md) — third-party audit register, including the sections that list **what is still unclosed**. (`docs/internal/` holds internal process records and is not shipped in the npm package.)
+- [`SECURITY.md`](SECURITY.md) — how to report a vulnerability, scope, hardening checklist, known boundaries.
+- [`docs/internal/`](docs/internal/) — plan/strategy/release/audit records (Chinese, not shipped in the npm package).
+
+**Language policy (restated).** Canonical docs are Chinese; this English README covers the minimum
+needed to evaluate and deploy; **when they disagree, the Chinese docs and the code win.**
+
+## Reporting security issues
+
+Please use GitHub Security Advisories (private) rather than a public issue — see [`SECURITY.md`](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -6,9 +6,12 @@
 
 轻量的「模型循环 + 工具 + 权限」内核，能力以 ESM 库导出、接口全部开放。架构见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
 
+> **语言政策**：本仓的**规范文档是中文**（`README.md` 与 `docs/`）；`README.en.md` 只覆盖"评估与部署所需的最小面"
+> （这是什么、3 步上手、安全模型与边界、命令索引）。两者冲突时，以**中文文档与代码**为准。
+
 ## 为什么选 MingDao
 
-- ⚡ **真正的零依赖**：纯 Node.js ≥ 18，无任何 npm 运行时依赖、无构建步骤——装完即用，不拖 node_modules
+- ⚡ **真正的零依赖**：内核与 CLI 纯 Node.js ≥ 18，**无任何 npm 运行时依赖**、无构建步骤——装完即用，不拖 node_modules（桌面版外壳另需 Electron / electron-updater，见下文"桌面版"）
 - 💰 **DeepSeek-V4 深度省钱**：1M 上下文预设（单次输出上限 384K）、**缓存命中计价**（命中价仅为未命中的 1/30）+ 命中率仪表盘、峰谷计价（高峰＝北京工作日 9:00–12:00、14:00–18:00，闲时半价自动识别）、自动路由（pro 规划 / flash 执行 + 分类缓存 + 会话粘滞）、精确 tokenizer（官方词表 BPE）、滞回自动压缩、**Batch API 半价批处理**（`mingdao batch`）、**避峰调度**（`--offpeak` 高峰顺延到最近闲时 12:00/18:00）、**费用护栏**（每日上限防超支）
 - 🖥 **双界面 + IDE 全家桶**：产品级 TUI（流式 Markdown、代码高亮、编辑 diff、Ctrl+C 中断、Tab 补全）与 `mingdao web` 一键 WebUI（PWA 可装桌面、多任务并行、全项设置面板）；VS Code 侧边栏与 JetBrains 工具窗深度集成
 - 🧠 **36 个技能开箱即用**：14 个内置常驻 + 22 个可安装技能库（线上 registry 逐文件 sha256 校验防供应链篡改，`mingdao skill install sql` 一键装，可自建企业内 registry）
@@ -18,7 +21,7 @@
 - 🖼 **多模态**：DeepSeek-V4-Flash-Vision-Exp 视觉模型内置，WebUI 直接上传图片；模型列表以官方 `/models` 线上名单为准，新模型发布自动出现
 - ♻ **长会话不丢上下文**：超预算自动压缩——早期段落由 executor 模型压成摘要注入（`/compact` 可手动），绝不静默失忆
 - 🔎 **历史会话秒搜**：增量索引全文检索（中文 bigram 分词，`mingdao sessions search` / WebUI 搜索框共用）；WebUI **会话级工作空间**——每个会话记住自己的项目目录，多任务并行互不串目录
-- 🌍 **真·跨平台**：Linux / macOS / Windows 全程实测，三平台 CI 矩阵（Ubuntu 18/20/22 + Windows + macOS）常驻守护，Windows 下 journal/测试全绿
+- 🌍 **真·跨平台**：Linux / macOS / Windows 全程实测，CI 矩阵常驻守护——Linux（Node 18/20/22）+ Windows（Node 20）+ macOS（Node 20）；覆盖率门禁只在 Linux/Node 20 腿执行（`--coverage` 需要 v8 覆盖率数据，其它腿跑普通测试）
 
 ## 快速开始（3 步）
 
@@ -232,7 +235,7 @@ mingdao cost --by pack          # 垂域费用分账
 
 ### 模型与 Key
 
-- 内置：DeepSeek（v4-pro / v4-flash / v4-flash-vision-exp）、OpenAI（GPT-5 系列）、Qwen（qwen3.7-max）、GLM（GLM-5）、Kimi（kimi-latest）
+- 内置：DeepSeek（`deepseek-v4-pro` / `deepseek-flash`〔旧名 `deepseek-v4-flash` 仍兼容，官方已改名〕/ `deepseek-v4-flash-vision-exp`）、OpenAI（GPT-5 系列）、Qwen（qwen3.7-max）、GLM（GLM-5）、Kimi（kimi-latest）
 - **动态模型列表**：下拉框只显示已设置 Key 的服务商，名单以官方 `/models` 接口线上拉取为准（缓存 1 小时，设置面板可手动「刷新模型」），新模型发布自动出现
 - 自定义 OpenAI 兼容端点：WebUI 设置面板直接添加/修改/删除（名称/标签/API 地址/Key，可标 `vision` 支持图片）
 - 其他协议：`~/.mingdao/providers/<name>.mjs` 写 `createProvider(cfg)`，见 [docs/PROVIDERS.md](docs/PROVIDERS.md)
@@ -289,12 +292,21 @@ mingdao cost --by pack          # 垂域费用分账
 ## 目录结构
 
 ```
-src/               CLI / Agent 循环 / 工具 / 权限 / 技能库 / MCP / 云同步 / WebUI（全部零依赖）
+src/               CLI / Agent 循环 / 工具 / 权限 / 技能库 / MCP / 云同步 / WebUI（内核与 CLI 全部零依赖）
+  src/web/         WebUI 服务端与前端（app.js / index.html / routes 各域）
+  src/commands/    CLI 子命令（init/run/web/key/pack/batch/ledger/schedule/sync/update…）
+  src/tools/       工具实现（read/write/edit/ls/glob/grep/bash/git/fetch/skill/task…）
 skills/            14 个内置常驻技能
 skills-lib/        22 个可安装技能库预设
 registry/          线上技能 registry 索引
-test/              smoke（离线）+ e2e（真实进程/HTTP）测试
-docs/              架构与扩展文档
+presets/           内置 Agent 预设（如 local-audit）
+packs/             内置示例 Pack（example-hello）
+assets/            内置分词器数据（tokenizer-data.json.gz，约 762 KB，`src/tokenizer.js` 使用）
+desktop/           Electron 桌面版外壳（含自动更新、原生目录选择器）
+ide/               VS Code / JetBrains 插件
+scripts/           发布与质量脚本（覆盖率、棘轮、发布校验、文档守卫…）
+test/              smoke（离线）/ e2e（真实进程与 HTTP）/ api-contracts / bench / mutate（变异验证）
+docs/              架构与扩展文档（`docs/internal/` 是内部过程文档，不随 npm 包分发）
 install.sh / install.bat / install.ps1   一键安装
 ```
 

package/SECURITY.md

@@ -0,0 +1,128 @@
+# Security Policy
+
+MingDao Harness (`mingdao`) is a zero-dependency agent harness that runs tools, executes shell
+commands, stores model API keys locally, can host a sync server, and loads third-party "Packs" into
+its own process. This document states what is supported, how to report a problem privately, what is in
+scope, and — importantly — **which security boundaries are known to be incomplete**.
+
+## Supported versions
+
+Security fixes are provided for the **latest minor release only**.
+
+| Version | Supported |
+| --- | --- |
+| **0.6.x** (current: **0.6.8**) | Yes |
+| 0.5.x and older | No |
+
+Upgrade with `npm i -g mingdao-harness@latest` (npm installs), or `mingdao update` / `mingdao rollback`
+for git installs. Fixes are not backported to older minors.
+
+## How to report
+
+**Preferred: GitHub Security Advisories (private).**
+<https://github.com/MingDaoTCM/MingDao-Harness/security/advisories/new>
+
+**Fallback email:** `netmi@foxmail.com` — use this if you cannot use GitHub, or if the report includes
+data you would rather not attach to a GitHub account.
+
+Please include: the affected version (`mingdao --version`), your platform, a minimal reproduction, the
+concrete impact, and whether the issue requires a malicious Pack, a malicious MCP server, or an
+already-authenticated local user.
+
+**Acknowledgement target: within 72 hours.** This is a goal we aim for, **not a contractual
+commitment** — this is a small project without an on-call rotation. If you do not hear back, please
+follow up on the same channel.
+
+Please do not open a public issue for an unfixed vulnerability. Credit is offered on request.
+
+## What's in scope
+
+- `src/web/**` — the local WebUI server: token handling, Host-header check, cross-site request
+  rejection, task/session API authorization.
+- `src/sync-server.js` — the self-hosted sync server: authentication, registration modes, path
+  handling, data isolation between accounts.
+- `src/packs.js` + `src/constraints.js` — Pack loading, the trust gate, manifest validation, and
+  constraint evaluation (a bypass of the trust gate is in scope).
+- `src/tools/**` — tool implementations: filesystem fence (`withinRoot`), shell execution and
+  sandboxing, the fetch tool's SSRF checks, credential/env exposure to subprocesses.
+- `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.
+
+Reports that affect anything else in `src/` are welcome too; the list above is where the trust
+boundaries live.
+
+## Out of scope
+
+- **A local, already-authorized user reading their own API key.** Keys are stored in plaintext at
+  `<home>/credentials.json` with mode 600 and are readable by anything running as that user. This is
+  the documented design (there is no OS keychain integration); it is not a vulnerability.
+- **Windows PID ownership is best-effort.** Before killing a task or a scheduler daemon, ownership of
+  the pid is verified on Linux (`/proc/<pid>/cmdline`) and macOS (`ps`). Windows has neither, and the
+  project deliberately does not add a PowerShell/WMI dependency, so the check reports "unknown" and the
+  caller falls back to "the process is alive". A pid-reuse mis-kill on Windows is a **known design
+  boundary**, documented in the security-model table of [`README.en.md`](README.en.md) — not a bug
+  report we can act on.
+- **Pack code running inside the host process.** `pack.mjs` is imported into the harness process with
+  full Node privileges, and `manifest.permissions` is a declaration that the kernel does **not**
+  enforce. Installing a Pack is equivalent to running its code; the mitigation is the explicit
+  `mingdao pack trust` gate plus your own review. See the Pack trust row of the
+  [`README.en.md`](README.en.md) security-model table. (This boundary is real, not acceptable — it is
+  listed again under "Known boundaries" below.)
+- **Upstream model providers and third-party endpoints.** Key leakage, prompt handling, abuse
+  detection, availability and content issues on a model vendor's side are theirs to fix.
+- **Anything that requires an attacker who already has code execution as your user**, unless it
+  escalates beyond what that access already grants.
+
+## Hardening checklist for deployers
+
+1. **Prefer `readonly` or `ask` over `auto`.** If you rely on `deny` rules, set `denyStrict: true` —
+   otherwise a `deny` hit merely prompts, and answering `y` bypasses the rule you wrote.
+2. **Keep the WebUI on loopback.** If you must expose it, configure `web.token` (or
+   `MINGDAO_WEB_TOKEN`) and terminate TLS in front of it. Never pass a token as a literal argument
+   (`--auth-token=<token>` lands in `argv`, `ps` and shell history); use `--auth-token=-` with the
+   token on stdin.
+3. **Use `config.net` with an explicit `allow` list and `mode: "block"`** so unexpected kernel egress
+   fails closed — and remember it does not constrain subprocesses (see Known boundaries).
+4. **Do not use `config.json` as a key store.** Keep keys in the credential store or environment
+   variables, keep `credentials.json` at mode 600, and keep `MINGDAO_HOME` on a path only you can read.
+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
+   `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).
+
+## Known boundaries
+
+These are **real, currently unclosed** items, registered in
+[`docs/internal/AUDIT-v0.6.1-第三方报告登记.md`](docs/internal/AUDIT-v0.6.1-第三方报告登记.md) (sections
+"未闭合（如实登记）" and "未纳入本批（如实登记）"). They are listed here rather than omitted so a reviewer can
+price them in.
+
+1. **The egress gate (`config.net`) does not cover child processes.** Bash subprocesses (your own
+   `curl`), MCP server processes, `config.tools` / Pack-spawned subprocesses, and the Electron shell's
+   update check make their own network requests that the gate never sees. It demonstrates "the kernel
+   did not exfiltrate", not "this machine never egressed". Process-level enforcement requires an egress
+   proxy or firewall.
+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.
+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.
+
+We do not claim this project is vulnerability-free, and this document is not a marketing statement.