@misaka-net/misakanet-setup 0.5.6 → 0.6.0

package/README.md

@@ -1,8 +1,15 @@
 # @misaka-net/misakanet-setup
 
-One command to teach your **Claude Code**, **Codex**, **Hermes**, **OpenClaw** or **codewhale** to
-check MisakaNet's failure lessons before repeating a mistake — and to distil the session's reusable
-lessons at a checkpoint.
+One command to teach your **Claude Code**, **Codex**, **Hermes**, **OpenClaw**, **codewhale**,
+**Cursor**, **Gemini CLI**, **Copilot CLI**, **OpenCode** or **Kiro** to
+check MisakaNet's failure lessons before repeating a mistake — and to write up the reusable lessons
+this session produced, at a checkpoint.
+
+**What it writes:** an MCP endpoint into each agent config, rules blocks for the clients that take
+one, and a local hook for Claude Code. **What leaves this machine:** at most one anonymous request
+while the installer runs; afterwards, only what the agent itself sends — with one opt-in exception:
+`MISAKANET_HOOK_FETCH=1` (off by default) makes the hook itself send the failed call's error text
+(or the command, when the tool gave no error text) as a search query.
 
 ```bash
 npx @misaka-net/misakanet-setup
@@ -16,19 +23,54 @@ knowledge base on its own instead of guessing.
 
 | # | Goal | Mechanism |
 |---|---|---|
-| 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json`, `~/.codex/config.toml` and `~/.openclaw/openclaw.json` (`mcp.servers.misakanet`), with the Bearer token when registration succeeds — reads need no token (anonymous reads are unmetered since 2026-09-18); the token is what opens the **write** path. Every entry also carries the self-declared context hints `X-MisakaNet-Client` / `-Agent` / `-Os` / `-Version`, which the endpoint records on the read's analytics row and never treats as identity (`codewhale` is the one exception: its server entry has no custom-header field). Hermes is the same thing in its own files: `mcp_servers.misakanet` in `~/.hermes/config.yaml` plus the token in `~/.hermes/.env` under `MCP_MISAKANET_API_KEY`. All four are config files written file-to-file — no subprocess is spawned, so **no token ever appears in a command line**. For Claude Code only, the five **read-only** tools are also added to `permissions.allow` — "can call it" otherwise still means a permission prompt on the very first search, so `0.5.3` pre-allows them (`--verify` reports it, `--report` prints `permissions:`); `write_lesson` is deliberately **not** pre-allowed, because a tool that writes should ask |
-| 2 | the agent **knows when** | rules block appended to `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.hermes/SOUL.md` / `~/.openclaw/workspace/AGENTS.md` (issue, retry, risky-operation triggers; desensitisation rules). Wording is **imperative first** ("必须先调 misakanet_search") rather than descriptive, because a field test showed a weaker model reads a descriptive block as background and never calls the tool |
+| 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json`, `~/.codex/config.toml` and `~/.openclaw/openclaw.json` (`mcp.servers.misakanet`), with the Bearer token when registration succeeds — reads need no token (anonymous reads are unmetered since 2026-09-18); the token is what opens the **write** path. Every entry also carries the self-declared context hints `X-MisakaNet-Client` / `-Agent` / `-Os` / `-Version`, which the endpoint records on the read's analytics row and never treats as identity (`codewhale` is the one exception: its server entry has no custom-header field). Hermes is the same thing in its own files: `mcp_servers.misakanet` in `~/.hermes/config.yaml` plus the token in `~/.hermes/.env` under `MCP_MISAKANET_API_KEY`. Five clients take the same idea in one file each, and **each file uses its own key path and URL field** — they are not interchangeable, and a copied entry with the wrong key fails silently (no error, the server simply never appears):
+
+| client | file | container | URL field |
+|---|---|---|---|
+| Cursor | `~/.cursor/mcp.json` | `mcpServers` | `url` |
+| Gemini CLI | `~/.gemini/settings.json` | `mcpServers` | **`httpUrl`** (its `url` means SSE) |
+| Copilot CLI | `~/.copilot/mcp-config.json` | `mcpServers` | `url`, with `type: "http"` |
+| OpenCode | `~/.config/opencode/opencode.json` | **`mcp`** | `url`, with `type: "remote"` |
+| Kiro | `~/.kiro/settings/mcp.json` | `mcpServers` | `url` |
+
+All of them are config files written file-to-file — no subprocess is spawned, so **no token ever appears in a command line**. For Claude Code only, the five **read-only** tools are also added to `permissions.allow` — "can call it" otherwise still means a permission prompt on the very first search, so `0.5.3` pre-allows them (`--verify` reports it, `--report` prints `permissions:`); `write_lesson` is deliberately **not** pre-allowed, because a tool that writes should ask |
+| 2 | the agent **knows when** | rules block appended to `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.hermes/SOUL.md` / `~/.openclaw/workspace/AGENTS.md`. **The five JSON-file clients are the exception: they get none**, because their rules are project-scoped (`.cursor/rules/*.mdc`, `GEMINI.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `.kiro/steering/*.md`) and the installer cannot know where your projects live — the install output says so, with the project-side action for each client, instead of implying behaviour changed (issue, retry, risky-operation triggers; desensitisation rules). Wording is **imperative first** ("必须先调 misakanet_search") rather than descriptive, because a field test showed a weaker model reads a descriptive block as background and never calls the tool |
 | 4 | *(opt-in)* you **hear** it | `--voice` adds a `PostToolUse` hook that plays the cue the server asked for (`lesson-found` / `failure-warning` / `connect-success` / `pair-success`). Off by default; mute with `MISAKANET_VOICE=0`; see `docs/integrations/mcp-voice-hooks.md` |
-| 3 | the checkpoint **fires** | a hook that counts user turns: turn 1 announces the install to the user, turn 20 (and every 10 after) injects the "distil and submit" reminder; a failed tool call injects a "search before you retry" reminder built from the error text. Claude Code only today — Codex's user-level hook shape is unconfirmed and OpenClaw's events are unverified, so those two work from the rules block, and `--verify` says so per target instead of implying otherwise |
+| 3 | the checkpoint **fires** | a hook that counts user turns: turn 1 announces the install to the user, turn 20 (and every 10 after) injects the "write up the reusable lessons and submit them" reminder — the agent does that writing and that submitting, by hand, and the hook itself sends nothing by default; a failed tool call injects a "search before you retry" reminder built from the error text, and only with `MISAKANET_HOOK_FETCH=1` (off by default) does the hook itself send that error text as a search query. Claude Code only today — Codex's user-level hook shape is unconfirmed and OpenClaw's events are unverified, so those two work from the rules block, and `--verify` says so per target instead of implying otherwise |
 
 Without (3) a rule saying "summarise every 20 turns" never fires — agents do not keep
 counters. Without (1)/(2) the hook has nothing to call.
 
+### dsh is not a file target — it is a plugin
+
+dsh takes its MCP servers from a **plugin bundle**, not from a JSON file. Its instruction files are a
+chain: **`$DSH_HOME/AGENTS.md`** (user-global, default `~/.dsh/AGENTS.md`, applies to every session)
+first, then the project's `AGENTS.md`/`CLAUDE.md` from the project root down to the working directory
+(`@deepseek-ai/dsh-agent-instructions`, byte-budgeted at 65,536 by default). It has no Claude-Code-style
+hooks. So the two commands are:
+
+```bash
+dsh plugin --profile web add misakanet   # ① the tools (mcp__misakanet__*)
+# ② put the rules block in ~/.dsh/AGENTS.md (global) or the project's AGENTS.md
+```
+
+Measured 2026-10-17: writing `~/.dsh/AGENTS.md` is picked up as `user-global` instructions on the next
+message, with no restart.
+
+Measured 2026-10-17: installing the current `misakanet` takes ~1s into `~/.dsh/profiles/web`; the plugin's
+`index.js` mounts the MCP client and `lib/client.js` is the web panel — **neither injects a rule**,
+which is why ② is a separate, manual step. Full guide: `docs/integrations/dsh.md`.
+
 ## Flags
 
 ```bash
 npx @misaka-net/misakanet-setup --dry-run     # show what would change, write nothing
 npx @misaka-net/misakanet-setup --verify      # READY / NOT READY, installed version, and the fix for each gap
+                                             # two sections, two questions: 端点/可用性 (can you use it — the
+                                             #  endpoint answers) and 安装完整性 (are the files we prefer
+                                             #  written); one failing does not condemn the other, and a file
+                                             #  we cannot write says 装不了 with its cause — not 没装 with
+                                             #  the one fix that cannot work ("re-run the installer")
 npx @misaka-net/misakanet-setup --only claude # one agent only
 npx @misaka-net/misakanet-setup --no-register # read-only, no anonymous token
 npx @misaka-net/misakanet-setup --upgrade     # same as installing the latest (the command is idempotent)
@@ -98,6 +140,10 @@ GPO / Intune / Jamf / Ansible snippets, and the section an IT security review ac
 `--no-register` avoids registration entirely):
 [`docs/maintainer/enterprise-deployment.md`](https://github.com/Ikalus1988/MisakaNet/blob/main/docs/maintainer/enterprise-deployment.md).
 
+A reviewer-facing landing page — the same boundary questions, plus an explicit list of what does
+**not** exist yet (no compliance certifications, no organisation-level audit export, no self-hosted
+form of the hosted endpoint): <https://misakanet.org/enterprise/>.
+
 The short version for a deployment script — two commands, both silent:
 
 ```bash
@@ -153,9 +199,30 @@ npx @misaka-net/misakanet-setup@latest
 ## Offline / restricted networks
 
 The hook ships inside the npm tarball, so installing needs no download beyond npm itself.
-Registration is best-effort: without it you keep the anonymous read path (5 reads/day/IP)
+Registration is best-effort: without it you keep the anonymous read path (unmetered since 2026-09-18; only a per-address burst window applies)
 and the installer says so in plain words.
 
+**Behind a corporate proxy, read the probe line before believing it.** `--verify` probes the
+endpoint with Node's `fetch`, and Node ignores `HTTP_PROXY` / `HTTPS_PROXY` unless the runtime is
+told to use them — `NODE_USE_ENV_PROXY=1` or `--use-env-proxy`, with `fetch` support in Node
+≥ 22.21.0 / 24.0.0 ([Node docs](https://nodejs.org/learn/http/enterprise-network-configuration)).
+On a proxy machine the probe can therefore fail while your agent reaches the endpoint fine. The
+report now says which of the two it is:
+
+```bash
+NODE_USE_ENV_PROXY=1 npx @misaka-net/misakanet-setup --verify   # let Node use the proxy
+curl -sS https://misakanet.org/mcp -H 'Accept: application/json' \
+  -H 'MCP-Protocol-Version: 2025-06-18' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+`endpoint-probe: inconclusive-proxy` in `--report` means exactly this: a proxy is configured, this
+process could not use it, so the `endpoint-reachable` boolean above it says nothing. `--strict` /
+`--ci` still fail in that case — a gate that cannot tell must not pass silently. If your proxy also
+intercepts TLS, add `NODE_USE_SYSTEM_CA=1`.
+
+The Python installer (`integrations/agent-autostart/install_misakanet_agent.py`) needs none of this:
+it uses `urllib`, which honours the proxy environment variables by default.
+
 ## Requires
 
 Node 18+ (the same runtime your assistant already uses). No dependencies, no Python.

package/bin/misakanet-setup.mjs

@@ -113,7 +113,8 @@ const SILENT = has('--silent');
 /** `--report-json`: the same report as JSON, and nothing else on stdout (#1784). */
 const REPORT_JSON = has('--report-json');
 const HOME = resolve(valueOf('--home', homedir()));
-const AGENTS = ['claude', 'codex', 'hermes', 'openclaw', 'codewhale'];
+const AGENTS = ['claude', 'codex', 'hermes', 'openclaw', 'codewhale',
+                'cursor', 'gemini', 'copilot', 'opencode', 'kiro'];
 
 const done = [];
 const manual = [];
@@ -146,8 +147,17 @@ function readText(path) {
  * (the value goes into the User-Agent header): js/file-access-to-http #268. The drift it was
  * meant to prevent is now caught in CI instead, by a test that binds this literal to the
  * manifest — a failing test is a better place for that than a request header.
+ *
+ * **Who moves it:** the release tooling, not a person. The `x-release-please-version` marker on
+ * this line is what release-please's generic updater looks for, and the file is listed in the
+ * setup package's `extra-files`, so the release pull request bumps this literal together with
+ * the manifest. That marker is not decoration: release-please replaces a version **only on a
+ * line that carries the marker** — an unmarked line is copied verbatim, so a release would ship
+ * a stale `--version` and a stale `X-MisakaNet-Version` header while every gate stayed green
+ * except the two that name the version (measured 2026-10-22: the 0.6.0 release pull request
+ * failed 9 e2e legs on exactly that).
  */
-const VERSION = '0.5.6'
+const VERSION = '0.6.0'  // x-release-please-version
 
 /**
  * The shape of a client id, in one place.
@@ -159,6 +169,9 @@ const VERSION = '0.5.6'
  * this cannot contain a quote, a newline or a `:`, so it cannot break any of the three.
  */
 const CLIENT_ID_SHAPE = /^[A-Za-z0-9._-]{8,64}$/
+// The server's rule for a referral code (`misakanet_register` → `referral_code`), kept identical on
+// both sides: a value the client is willing to send and the server is willing to count.
+const REFERRAL_SHAPE = /^[A-Za-z0-9]{4,16}$/
 
 // ── argument surface ─────────────────────────────────────────────────
 // Until 2026-09-17 no flag was validated at all: `--help` fell through to a *real install*
@@ -206,9 +219,6 @@ if (has('--version')) {
   process.exit(0);
 }
 
-/** What we would write, and how to take it back — printed by --list-writes, and used by the report. */
-const WRITE_MANIFEST = [];
-
 const KNOWN = new Set(FLAGS.flatMap(([flag]) => flag.split(/[,\s]/).filter((f) => f.startsWith('-'))));
 {
   const unknown = args.filter((a) => a.startsWith('-') && !KNOWN.has(a));
@@ -318,6 +328,91 @@ function writeText(path, text, { mode } = {}) {
   }
 }
 
+/**
+ * The targets whose whole install is one MCP entry in one JSON file.
+ *
+ * Each entry shape is the one that target's own documentation shows, and they are **not**
+ * interchangeable: Gemini CLI's remote field is `httpUrl` (its `url` means SSE), OpenCode nests under
+ * `mcp` rather than `mcpServers` and wants `type: "remote"`, Copilot CLI wants `type: "http"`, and
+ * Cursor and Kiro use a bare `url`. A copied entry with the wrong key fails **silently** — no error,
+ * the server simply never appears — which is why each shape is pinned by tests instead of assumed.
+ *
+ * None of these five has a rules block or a hook *this installer can write*: their rules live in
+ * project-scoped files (`.cursor/rules/*.mdc`, `GEMINI.md`, `AGENTS.md`, `.github/copilot-instructions.md`,
+ * `.kiro/steering/*.md`) and we do not know where a user's projects are. So tier ① is the whole
+ * install for them, `--mcp-only` is an identity, and the output says "MCP only" out loud instead of
+ * implying behaviour changed. That is also why `--report` says `install-scope: mcp-only` on a machine
+ * whose only target is one of these.
+ */
+const MCP_ONLY_TARGETS = {
+  cursor: {
+    label: 'Cursor',
+    detect: ['.cursor'],
+    config: (home) => join(home, '.cursor', 'mcp.json'),
+    container: 'mcpServers',
+    urlField: 'url',
+    entry: (bearer) => ({ url: ENDPOINT, headers: mcpHeaders(bearer, 'cursor') }),
+    rules: '.cursor/rules/*.mdc 是项目级的，安装器不知道你的项目在哪',
+    ruleHint: '想让 Cursor 主动去查，把 .cursor/rules/misakanet-failure-memory.mdc 放进项目',
+    manual: '重启 Cursor 后在 Settings → MCP 里确认能看见 misakanet（本安装器只写用户级 '
+      + '~/.cursor/mcp.json，项目级 .cursor/mcp.json 归你自己管）',
+    verifyHint: '在 Settings → MCP 里复核',
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    detect: ['.gemini'],
+    config: (home) => join(home, '.gemini', 'settings.json'),
+    container: 'mcpServers',
+    // `httpUrl` is the HTTP-streaming endpoint; `url` would mean SSE. Documented property list:
+    // geminicli.com/docs/tools/mcp-server ("headers: Custom HTTP headers when using url or httpUrl").
+    urlField: 'httpUrl',
+    entry: (bearer) => ({ httpUrl: ENDPOINT, headers: mcpHeaders(bearer, 'gemini') }),
+    rules: '它读 GEMINI.md（全局 ~/.gemini/GEMINI.md 与项目树），而安装器不写别人的规则文件',
+    ruleHint: '想让 Gemini CLI 主动去查，把规则块加进项目的 GEMINI.md',
+    manual: '重启会话后用 `/mcp` 复核 misakanet 是否列出',
+    verifyHint: '用 /mcp 复核',
+  },
+  copilot: {
+    label: 'Copilot CLI',
+    detect: ['.copilot'],
+    config: (home) => join(home, '.copilot', 'mcp-config.json'),
+    container: 'mcpServers',
+    urlField: 'url',
+    entry: (bearer) => ({ type: 'http', url: ENDPOINT, headers: mcpHeaders(bearer, 'copilot') }),
+    rules: '它读 .github/copilot-instructions.md 与 AGENTS.md（项目级），安装器不写项目文件',
+    ruleHint: '想让 Copilot CLI 主动去查，把规则写进项目的 .github/copilot-instructions.md',
+    manual: '跑 `copilot mcp list` 复核（VS Code 里的 Copilot 是另一份配置，键名是 `servers`）',
+    verifyHint: '用 `copilot mcp list` 复核',
+  },
+  opencode: {
+    label: 'OpenCode',
+    detect: ['.config/opencode'],
+    config: (home) => join(home, '.config', 'opencode', 'opencode.json'),
+    container: 'mcp',
+    urlField: 'url',
+    entry: (bearer) => ({ type: 'remote', url: ENDPOINT, enabled: true,
+                          headers: mcpHeaders(bearer, 'opencode') }),
+    rules: '它读 AGENTS.md（项目根与 ~/.config/opencode/AGENTS.md），安装器不写别人的规则文件',
+    ruleHint: '想让 OpenCode 主动去查，把规则块加进项目的 AGENTS.md',
+    manual: '重启 OpenCode 后看它的 MCP 列表；若你设了 XDG_CONFIG_HOME，它读的是 '
+      + '$XDG_CONFIG_HOME/opencode/opencode.json，把同样的条目贴过去即可',
+    verifyHint: '看 OpenCode 的 MCP 列表复核',
+    parseNote: 'opencode.jsonc 允许注释，若你用的正是它，本安装器解析不了',
+  },
+  kiro: {
+    label: 'Kiro',
+    detect: ['.kiro'],
+    config: (home) => join(home, '.kiro', 'settings', 'mcp.json'),
+    container: 'mcpServers',
+    urlField: 'url',
+    entry: (bearer) => ({ url: ENDPOINT, headers: mcpHeaders(bearer, 'kiro') }),
+    rules: '它读 .kiro/steering/*.md（steering 文件），安装器不写别人的规则文件',
+    ruleHint: '想让 Kiro 主动去查，把规则加进 .kiro/steering/',
+    manual: '重启 Kiro 后用它的 MCP 面板复核 misakanet（Kiro 还支持 disabled / autoApprove 字段）',
+    verifyHint: '用 Kiro 的 MCP 面板复核',
+  },
+};
+
 /**
  * The files each assistant's install writes, so a permission problem can be reported *before*
  * anything is touched (and so `--dry-run` can say "I cannot change that" as well as "I would change
@@ -330,9 +425,111 @@ const AGENT_WRITE_PATHS = {
   codex: (home) => [join(home, '.codex', 'config.toml'), join(home, '.codex', 'AGENTS.md')],
   hermes: (home) => [join(home, '.hermes', 'config.yaml'), join(home, '.hermes', 'SOUL.md')],
   codewhale: (home) => [join(home, '.codewhale', 'mcp.json')],
+  // Every MCP-only target writes exactly one file, so the table above is the single source of truth
+  // for the write manifest, the detection paths and the report's scope line.
+  ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS)
+    .map(([id, spec]) => [id, (home) => [spec.config(home)]])),
   openclaw: () => openclawWorkspaces().map((workspace) => join(workspace, 'AGENTS.md')),
 };
 
+/**
+ * The write manifest: every file this run would touch, with the kind of write and the tier it
+ * belongs to.
+ *
+ * One builder, two readers: `--list-writes` prints it for an operator who has to approve it, and
+ * the install preview prints it for the user who is about to say yes (#3690). They cannot drift,
+ * because there is only one list — a preview that disagrees with the manifest is worse than no
+ * preview at all.
+ *
+ * The tiers are the permission tiers from the top of this file: ① registers an MCP endpoint,
+ * ② writes a rules block (that changes how the agent behaves), ③ installs hooks and state (that
+ * run on every turn). Under `--mcp-only` only ① is in scope, so the other two are not listed —
+ * the same rule the install itself follows.
+ */
+function buildWriteManifest(agents) {
+  // Compare base names, not separators: a `/settings.json$` regex silently classifies nothing on
+  // Windows (all three windows legs went red on the first CI run of this change), and a manifest
+  // that hides a tier is worse than no manifest.
+  const classify = (path) => {
+    const base = basename(path);
+    if (base === 'CLAUDE.md' || base === 'AGENTS.md' || base === 'SOUL.md') return { tier: 2, kind: 'rules' };
+    if (path.includes('.misakanet-agent')) return { tier: 3, kind: 'state' };
+    // `settings.json` carries both the read-only grants (①) and the hooks (③); the hook row is
+    // added separately below, and only when the hooks are in scope.
+    if (base === 'settings.json' && path.includes('.claude')) return { tier: 1, kind: 'grants' };
+    return { tier: 1, kind: 'mcp' };
+  };
+  const rows = new Map();
+  const add = (path, action, tier, kind) => {
+    const key = `${tier}|${path}`;
+    if (!rows.has(key)) rows.set(key, { path: redact(path), action, tier, kind });
+  };
+  for (const agent of agents) {
+    if (!detect(agent)) continue;
+    for (const path of (AGENT_WRITE_PATHS[agent] || (() => []))(HOME)) {
+      const { tier, kind } = classify(path);
+      add(path, existsSync(path) ? 'append-or-update' : 'create', tier, kind);
+      if (!MCP_ONLY && basename(path) === 'settings.json' && path.includes('.claude')) {
+        add(path, 'append-or-update（钩子）', 3, 'hook');
+      }
+    }
+  }
+  // The state dir is ours, but it is still written to disk — and only when there is something to
+  // install: with no target detected the run writes nothing at all.
+  if (agents.length) {
+    // `--no-register` registers no anonymous node, so no token is written; listing it anyway would
+    // make the manifest — and the preview's file count — promise a file that stays absent.
+    if (!has('--no-register')) add(join(stateDir(), 'token'), 'create (0600)', 1, 'token');
+    if (!MCP_ONLY) {
+      add(join(stateDir(), 'hook.mjs'), 'create', 3, 'hookScript');
+      add(join(stateDir(), STATE_VERSION_FILE), 'create', 3, 'version');
+    }
+  }
+  return [...rows.values()]
+    .filter((row) => (MCP_ONLY ? row.tier === 1 : true))
+    .sort((a, b) => a.tier - b.tier || a.path.localeCompare(b.path));
+}
+
+/**
+ * The preview: what this run is about to write, said *before* it writes it (#3690).
+ *
+ * A user who never opens a checkout has no way to know that an installer also edits the agent's
+ * rules file — and that file is the one that changes how the agent behaves. So the summary names
+ * the files, the kind of change, and the three ways out: look first (`--list-writes`), ask for the
+ * endpoint only (`--mcp-only`), or take it back (`--uninstall`).
+ *
+ * One line per file, one line of ways out, and every path redacted to `~` — the person reading
+ * this may never see a checkout, so nothing here may assume one.
+ */
+function writePreview(rows) {
+  const files = new Map();
+  for (const row of rows) {
+    const file = files.get(row.path) || { path: row.path, tier: row.tier, kinds: [] };
+    file.tier = Math.min(file.tier, row.tier);
+    file.kinds.push(row.kind);
+    files.set(row.path, file);
+  }
+  const list = [...files.values()].sort((a, b) => a.tier - b.tier || a.path.localeCompare(b.path));
+  if (!list.length) return '';
+  const labels = {
+    mcp: 'MCP 端点',
+    grants: '只读工具放行',
+    rules: '规则块（会改变 agent 的行为）',
+    hook: '钩子',
+    token: 'MCP 凭据',
+    hookScript: '钩子脚本',
+    version: '版本戳',
+    state: '本机状态',
+  };
+  const width = Math.min(Math.max(...list.map((f) => f.path.length)) + 2, 32);
+  const pad = (text) => (text.length >= width ? `${text} ` : text.padEnd(width));
+  return [
+    `将修改 ${list.length} 个文件${DRY ? '（--dry-run：只是预览，不写任何东西）' : ''}：`,
+    ...list.map((f) => `  ${pad(f.path)}+ ${f.kinds.map((k) => labels[k]).join(' + ')}`),
+    '先看：--list-writes   不改行为：--mcp-only   撤销：--uninstall',
+  ].join('\n');
+}
+
 /**
  * Which of these paths this process may not write.
  *
@@ -413,6 +610,19 @@ function ourHookEntries(hooks) {
 }
 
 /** Insert or refresh a marker-delimited block. Uses a function replacement (no $-escapes). */
+/**
+ * Is tier ③ (the behaviour layer) actually *wired*, or merely present on disk?
+ *
+ * `hook.mjs` living in our own state directory proves nothing about the user's agents: the hook only
+ * runs where a config file points at it, and today that is Claude Code alone. `--report` used to
+ * answer `install-scope: full` from the file's existence, so a Cursor-only machine claimed the
+ * behaviour layer was installed. It is `full` only when Claude Code's settings carry our entries.
+ */
+function hookWired() {
+  const settings = readJson(join(HOME, '.claude', 'settings.json'), null);
+  return ourHookEntries(settings?.hooks).length > 0;
+}
+
 function injectBlock(path, block) {
   const existing = readText(path);
   const pattern = new RegExp(`[ \\t]*<!--\\s*${START}\\s*-->[\\s\\S]*?<!--\\s*${END}\\s*-->\\n?`);
@@ -483,6 +693,19 @@ function mcpHeaders(bearer, agent) {
  * syntaxes, so it is checked against `CLIENT_ID_SHAPE` first. A `client_id` that is not id-shaped is
  * not a hint worth writing; it is noise that could close a quote or a mapping.
  */
+/**
+ * The referral code of the node that invited this one, or `''`.
+ *
+ * `python3 scripts/referral.py --apply=CODE` writes it to `<stateDir>/referral_code` — the same
+ * directory `client_id` and `token` live in, so every client on the machine can read it. Shape-checked
+ * for the same reason `client_id` is: it is a value from a file on its way into an API request, and the
+ * server will ignore anything that is not code-shaped, which would be a silent no-op (#1996).
+ */
+function declaredReferral() {
+  const found = readText(join(stateDir(), 'referral_code')).trim();
+  return REFERRAL_SHAPE.test(found) ? found : '';
+}
+
 function declaredClientId() {
   if (knownClientId) return knownClientId;
   const found = readText(join(stateDir(), 'client_id')).trim();
@@ -503,6 +726,38 @@ function probeEndpoint() {
   return (process.env.MISAKANET_ENDPOINT || CANONICAL_ENDPOINT).trim();
 }
 
+/**
+ * The proxy environment, and whether *this* Node will actually use it.
+ *
+ * Node's `fetch` ignores `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` unless the runtime is told to
+ * honour them — `NODE_USE_ENV_PROXY=1` or `--use-env-proxy`, with fetch support in v22.21.0 /
+ * v24.0.0+ (nodejs.org/learn/http/enterprise-network-configuration). So in an enterprise-proxy
+ * environment a failed probe is **not** evidence that the endpoint is down: `curl` and the user's
+ * agent may both be reaching it through a proxy this process never saw. Reporting that as
+ * "端点不可达（网络受限？）" sends a user whose install works off to debug a network that is fine —
+ * and the audience for this installer includes exactly the people whose proxies cause this.
+ *
+ * Returns `null` when no proxy is configured (the ordinary path), otherwise the variables in play
+ * and whether the runtime was told to use them.
+ */
+function proxyEnvironment() {
+  const vars = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy']
+    .filter((name) => (process.env[name] || '').trim());
+  if (!vars.length) return null;
+  const enabled = Boolean((process.env.NODE_USE_ENV_PROXY || '').trim())
+    || process.execArgv.some((arg) => arg.includes('use-env-proxy'))
+    || (process.env.NODE_OPTIONS || '').includes('use-env-proxy');
+  return { vars, enabled, noProxy: (process.env.NO_PROXY || process.env.no_proxy || '').trim() };
+}
+
+/** The one line that turns an inconclusive probe into a next action. */
+function proxyProbeAdvice(proxy) {
+  return `本机配了代理（${proxy.vars.join('、')}），而 Node 的 fetch 默认不读这些变量 → 探测结果不可信，`
+    + '不代表端点不可达。确认方式：先 `curl -sS https://misakanet.org/mcp` 手测，'
+    + '或让 Node 走代理重跑：`NODE_USE_ENV_PROXY=1 npx @misaka-net/misakanet-setup --verify`'
+    + '（fetch 需要 Node ≥ 22.21.0 / 24.0.0；公司代理做 TLS 拦截时再加 `NODE_USE_SYSTEM_CA=1`）';
+}
+
 /**
  * One unauthenticated MCP call.
  *
@@ -621,7 +876,7 @@ const PROMPT_BLOCK = `调用规则（按顺序照做）：
 5) 查不到就 misakanet_submit_intake(kind="question")。
 6) 约 20 轮后、或刚解决一个非平凡问题时：把本次「失败→根因→修复→验证」里可泛化、有判据、且搜过没有重复的部分，
    脱敏后 misakanet_submit_intake(kind="missing_lesson") 提交；不够价值就不提交。
-脱敏：密钥/凭据→<REDACTED>，人名/邮箱/真实域名/绝对家目录→泛化。全程不要打断用户任务。`;
+脱敏：已由代码自动完成——本地钩子发出的查询在离开本机前、服务端入库前，都会把密钥/绝对路径/邮箱换成占位符；你不必手动改写，但仍不要粘整段会话转录或与故障无关的业务机密。全程不要打断用户任务。`;
 
 // ── the hook file: shipped in the package, downloaded only if missing ─
 /**
@@ -771,7 +1026,10 @@ async function ensureIdentity() {
   // export — an instruction a non-technical user cannot follow, and on Windows a different one.
   const clientId = usable ? explicit : `setup-${randomUUID()}`;
   knownClientId = clientId;
-  const result = await mcpCall('misakanet_register', { agent_type: 'setup', client_id: clientId });
+  const referral = declaredReferral();
+  const result = await mcpCall('misakanet_register', {
+    agent_type: 'setup', client_id: clientId, ...(referral ? { referral_code: referral } : {}),
+  });
   // Validate before persisting: a response body is not something to write to disk unchecked
   // (CodeQL js/http-to-file-access #262/#264 is about exactly that flow). The endpoint is
   // ours, but "trust the shape" is the correct habit and it makes the value failing to match
@@ -781,8 +1039,22 @@ async function ensureIdentity() {
     // Say what it costs, not what went wrong internally: "凭据形状不对" is jargon. Reading is not
     // what is lost here (it needs no token and is not metered) — the write path is, and saying so
     // plainly is the difference between a user retrying and a user concluding the tool is broken.
-    need('匿名注册没成功（多半是网络）→ 读课程不受影响，但写入类工具（write_lesson）现在用不了；'
-      + '网络恢复后重跑本命令就能拿到 token');
+    //
+    // And say *whose* problem it is. This branch used to say "多半是网络" unconditionally, which on
+    // 2026-10-18 was measurably wrong: the server answered
+    // `{"code":"storage_unavailable","storage":{"token":true},"hint":"Retry shortly."}` because D1's
+    // daily quota was spent, and the user was sent to inspect a network that was working. The
+    // server already names the cause and the wait; the fix is to read it instead of guessing.
+    const serverCode = typeof result?.code === 'string' ? result.code : '';
+    const serverHint = typeof result?.hint === 'string' ? result.hint.trim() : '';
+    const cause = serverCode === 'storage_unavailable'
+      ? '服务端暂时存不了 token（**不是你的网络**）'
+      : serverCode
+        ? `服务端拒绝了这次注册（${serverCode}）`
+        : `多半是网络（${lastRequestError || '没有收到响应'}）`;
+    need(`匿名注册没成功：${cause} → 读课程不受影响，但写入类工具（write_lesson）现在用不了；`
+      + '稍后重跑本命令就能拿到 token'
+      + (serverHint ? `（服务端提示：${serverHint}）` : ''));
     return '';
   }
   // Created with mode 0600 rather than written and then chmodded: the old order left a window in
@@ -809,6 +1081,8 @@ function mcpEntryPresent(agent) {
     hermes: () => readText(join(HOME, '.hermes', 'config.yaml')),
     openclaw: () => readText(join(HOME, '.openclaw', 'openclaw.json')),
     codewhale: () => readText(join(HOME, '.codewhale', 'mcp.json')),
+    ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS)
+      .map(([id, spec]) => [id, () => readText(spec.config(HOME))])),
   }[agent]?.() || '';
   return text.includes('misakanet') && text !== 'null';
 }
@@ -820,6 +1094,7 @@ function detect(agent) {
     hermes: ['.hermes'],
     openclaw: ['.openclaw'],
     codewhale: ['.codewhale'],
+    ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS).map(([id, spec]) => [id, spec.detect])),
   }[agent] || [];
   return paths.some((p) => existsSync(join(HOME, p)));
 }
@@ -1340,11 +1615,77 @@ async function installOpenclaw(bearer) {
   ok(`OpenClaw：注册 MCP（streamable-http）→ ${cfg}`);
 }
 
+/**
+ * Install one MCP-only target: read its JSON, merge our entry under the vendor's own key path, write.
+ *
+ * File-to-file, never a subprocess, so no token ever reaches a command line. An existing file is
+ * preserved (other servers, other keys) and backed up first; a file we cannot parse stops at a manual
+ * step that names exactly what to paste, because guessing at a half-written config is how a user
+ * loses the servers they already had.
+ */
+async function installMcpOnly(agent, bearer) {
+  const spec = MCP_ONLY_TARGETS[agent];
+  const cfg = spec.config(HOME);
+  const data = readJson(cfg, null);
+  if (data === null && readText(cfg)) {
+    need(`${spec.label}：${cfg} 不是合法 JSON${spec.parseNote ? `（${spec.parseNote}）` : ''}`
+      + ` → 请手动加入 ${spec.container}.misakanet（形状见 https://misakanet.org/mcp 的客户端文档）`);
+    return;
+  }
+  const doc = data || {};
+  doc[spec.container] = doc[spec.container] || {};
+  const entry = spec.entry(bearer);
+  if (sameJson(doc[spec.container].misakanet, entry)) {
+    ok(`${spec.label}：MCP 已注册（无改动）`);
+  } else {
+    doc[spec.container].misakanet = entry;
+    backup(cfg);
+    writeText(cfg, `${JSON.stringify(doc, null, 2)}\n`);
+    ok(`${spec.label}：注册 MCP → ${cfg}`);
+  }
+  skip(`${spec.label}：没有规则块与钩子（${spec.rules}）→ ${spec.ruleHint}`);
+  need(`${spec.label}：${spec.manual}`);
+}
+
 // The last endpoint probe, recorded so `--report` can print it without probing twice.
-let lastProbe = { reachable: false, tools: 0 };
+let lastProbe = { reachable: false, tools: 0, note: '' };
+
+/**
+ * The advice for a file we could not write.
+ *
+ * It has to be an advice that can work — and "re-run the install command" is not one: the file is
+ * read-only or the permissions do not allow it, so a re-run writes exactly as much as the last one
+ * did. Measured 2026-10-22 on an OpenClaw machine whose workspace was root-owned and read-only:
+ * `--verify` said "规则块没装 → 重跑安装命令", and the trialer went after the network, the
+ * permissions and the gateway while the installer had already named the real blocker.
+ *
+ * The question is asked the way the installer asks it before writing (`canCreateHere`): by
+ * attempting the access, never by `existsSync` first.
+ */
+function unwritableAdvice(manual = '') {
+  const fix = '改权限（或换到可写的目录）后再重跑';
+  return manual
+    ? `只读或权限不足，重跑也写不进去 → ${manual}（或${fix}）`
+    : `只读或权限不足，重跑也写不进去 → ${fix}`;
+}
 
 async function verify() {
   let allOk = true;
+  // The report answers two different questions, and one of them failing must not condemn the
+  // other (issue #3696): "can you use it" (the endpoint answers) and "are the files we prefer
+  // written" (our own footprint). A machine whose endpoint answers and whose workspace is
+  // read-only is **usable** — and the old verdict called it NOT READY.
+  let usable = true;
+  // The probe has three answers, not two: a probe that could not run is not a probe that failed.
+  // "unknown" is reported as unknown, and only `--strict` refuses to pass on it.
+  let probeState = 'ready';
+  // The install segment is judged on its own: a file we cannot write is a fact about our
+  // footprint, and it says nothing about the endpoint.
+  let installOk = true;
+  const installFailed = () => { installOk = false; allOk = false; };
+  // Where each segment starts, in the three line lists. The output prints the two segments as
+  // two sections, and this boundary is the only thing that has to be right about them.
+  const segmentStart = { done: done.length, manual: manual.length, skipped: skipped.length };
   // Handshake, not a search. `tools/list` proves the endpoint speaks MCP and answers, and it
   // consumes no anonymous read quota — so `--verify` can be run as often as the user likes. The
   // search used to be the probe, which spent one of the five free reads per run and, worse,
@@ -1364,18 +1705,46 @@ async function verify() {
       const missing = CLAUDE_ALLOWED_TOOLS.filter((tool) => !granted.includes(tool));
       if (detect('claude') && missing.length) {
         allOk = false;
+        // Not an install fact: the endpoint answers, and the search still fails. It belongs to
+        // the usability segment, so it belongs there in the output too.
+        usable = false;
         need(`Claude Code：只读 MCP 工具没有放行（${missing.length} 个）→ 第一次检索会被权限拦下；`
           + '重跑安装命令即可放行');
       }
     } catch { /* a settings file we cannot read is reported by the Claude checks below */ }
   } else if (probe && (probe.error || probe.protocolVersion || probe.serverInfo)) {
     allOk = false;
+    usable = false;
+    probeState = 'not-ready';
     need(`端点可达但握手异常：${JSON.stringify(probe).slice(0, 120)}`);
   } else {
-    allOk = false;
-    need(`端点不可达：${ENDPOINT}（网络受限？读课程会静默失败）`
-      + (lastRequestError ? ` —— 最近一次失败原因：${lastRequestError}` : ''));
+    const proxy = proxyEnvironment();
+    if (proxy && !proxy.enabled) {
+      // Inconclusive rather than unreachable. Interactive runs warn (a visible `!` that does not
+      // flip the verdict), because the install itself is fine and the user's agent may well be
+      // reaching the endpoint through that proxy. `--strict` / `--ci` keep a hard verdict: a gate
+      // that cannot tell must not pass silently, and CI machines are the ones actually configured
+      // to make the probe trustworthy.
+      lastProbe = { reachable: false, tools: 0, note: 'inconclusive-proxy' };
+      probeState = 'unknown';
+      if (STRICT) {
+        allOk = false;
+        usable = false;
+        need(`端点探测不可信，且 --strict 不接受"说不清"：${proxyProbeAdvice(proxy)}`);
+      } else {
+        need(`端点探测不可信（不是"不可达"）：${proxyProbeAdvice(proxy)}`);
+      }
+    } else {
+      allOk = false;
+      usable = false;
+      probeState = 'not-ready';
+      need(`端点不可达：${ENDPOINT}（网络受限？读课程会静默失败）`
+        + (lastRequestError ? ` —— 最近一次失败原因：${lastRequestError}` : ''));
+    }
   }
+  // The endpoint segment ends here. Everything below is about our own footprint: the files we
+  // write, the entries we register, the token we keep.
+  const segmentEnd = { done: done.length, manual: manual.length, skipped: skipped.length };
   const tokenFile = join(stateDir(), 'token');
   let tokenPresent = '';
   try {
@@ -1386,43 +1755,61 @@ async function verify() {
   if (tokenPresent) {
     ok('写入通道：token 已就绪（write_lesson / preflight 可用）');
   } else {
-    skip('写入通道：无 token（读不限次数、只读完全可用，写入类工具不可用）');
-  }
-  const hookPath = join(stateDir(), 'hook.mjs');
-  let hookPresent = false;
-  try {
-    hookPresent = readFileSync(hookPath, 'utf8').length > 0;
-  } catch {
-    hookPresent = false;
-  }
-  if (!hookPresent) {
-    allOk = false;
-    need('自动沉淀钩子：缺失 → 重跑安装命令');
-  } else {
-    const settingsPath = join(HOME, '.claude', 'settings.json');
-    const settings = readJson(settingsPath, {}) || {};
-    // Only our own entries: a foreign hook that merely mentions "hook.mjs" is not evidence
-    // that this machine is installed (and its interpreter may not even be ours).
-    const commands = ourHookEntries(settings.hooks)
-      .flatMap((entry) => (entry.hooks || []).map((h) => h.command))
-      .filter((c) => typeof c === 'string');
-    if (!commands.length) {
-      allOk = false;
-      need('Claude Code：钩子没装（settings.json 里没有本安装器写入的命令）');
+    // Which token this is looking for, said out loud: it reads **our own** state directory, so a
+    // machine that got its token through another channel (mcporter, a gateway) shows "no token"
+    // here even though writes work. The trialer read that as "nothing is set up".
+    skip('写入通道：无 token（这一项只检查本安装器状态目录里的 token；如果 token 来自别的通道，'
+      + '读路径完全不受影响——读不限次数、只读完全可用，写入类工具不可用）');
+  }
+  // The hook is Claude Code's alone: it is the one target whose config carries it (Codex's
+  // user-level hook shape is unconfirmed, OpenClaw's events are unverified), so a machine without
+  // Claude Code must not be told its hook is missing. Until 2026-09-20 it was: a Codex-only or
+  // Cursor-only install reported NOT READY with two Claude Code complaints about a target that was
+  // never selected — the same lie the OpenClaw and Hermes checks below already refuse to tell
+  // (found while adding Cursor, which is mcp-only by construction).
+  if (detect('claude')) {
+    const hookPath = join(stateDir(), 'hook.mjs');
+    let hookPresent = false;
+    try {
+      hookPresent = readFileSync(hookPath, 'utf8').length > 0;
+    } catch {
+      hookPresent = false;
+    }
+    if (!hookPresent) {
+      installFailed();
+      need(canCreateHere(hookPath)
+        ? '自动沉淀钩子：缺失 → 重跑安装命令'
+        : `自动沉淀钩子：装不了（${hookPath}）→ ${unwritableAdvice()}`);
     } else {
-      const exe = commands[0].startsWith('"') ? commands[0].split('"')[1] : commands[0].split(' ')[0];
-      if (!existsSync(exe)) {
-        allOk = false;
-        need(`Claude Code：钩子里的解释器不存在（${exe}）→ 钩子永远不会触发，重跑安装命令即可修`);
+      const settingsPath = join(HOME, '.claude', 'settings.json');
+      const settings = readJson(settingsPath, {}) || {};
+      // Only our own entries: a foreign hook that merely mentions "hook.mjs" is not evidence
+      // that this machine is installed (and its interpreter may not even be ours).
+      const commands = ourHookEntries(settings.hooks)
+        .flatMap((entry) => (entry.hooks || []).map((h) => h.command))
+        .filter((c) => typeof c === 'string');
+      if (!commands.length) {
+        installFailed();
+        need('Claude Code：钩子没装（settings.json 里没有本安装器写入的命令）');
       } else {
-        ok('Claude Code：钩子已装且解释器存在');
+        const exe = commands[0].startsWith('"') ? commands[0].split('"')[1] : commands[0].split(' ')[0];
+        if (!existsSync(exe)) {
+          installFailed();
+          need(`Claude Code：钩子里的解释器不存在（${exe}）→ 钩子永远不会触发，重跑安装命令即可修`);
+        } else {
+          ok('Claude Code：钩子已装且解释器存在');
+        }
       }
+      const cfg = join(HOME, '.claude.json');
+      const data = readJson(cfg, {}) || {};
+      const entry = data.mcpServers?.misakanet;
+      if (!entry) {
+        installFailed();
+        need(canCreateHere(cfg)
+          ? `Claude Code：MCP 未注册（${cfg}）`
+          : `Claude Code：MCP 未注册（${cfg}）→ ${unwritableAdvice()}`);
+      } else ok(`Claude Code：MCP 已注册（${entry.url}）`);
     }
-    const cfg = join(HOME, '.claude.json');
-    const data = readJson(cfg, {}) || {};
-    const entry = data.mcpServers?.misakanet;
-    if (!entry) { allOk = false; need(`Claude Code：MCP 未注册（${cfg}）`); }
-    else ok(`Claude Code：MCP 已注册（${entry.url}）`);
   }
   // OpenClaw is only reported when the user actually has it: telling a machine without
   // OpenClaw that it is "not ready" would be a lie about a target that was never selected.
@@ -1431,17 +1818,23 @@ async function verify() {
   if (detect('openclaw')) {
     const rules = join(openclawWorkspaces()[0], 'AGENTS.md');
     if (!readText(rules).includes(`<!-- ${START} -->`)) {
-      allOk = false;
-      need(`OpenClaw：规则块没装（${rules}）→ 重跑安装命令`);
+      installFailed();
+      // "没装" and "装不了" are different facts with different fixes, and the difference is the
+      // whole point (issue #3696): a read-only workspace is not something a re-run installs.
+      need(canCreateHere(rules)
+        ? `OpenClaw：规则块没装（${rules}）→ 重跑安装命令`
+        : `OpenClaw：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
     } else {
       ok('OpenClaw：规则块已装');
     }
     const cfg = join(HOME, '.openclaw', 'openclaw.json');
     const entry = (readJson(cfg, null) || {}).mcp?.servers?.misakanet;
     if (!entry) {
-      allOk = false;
-      need(`OpenClaw：MCP 未注册（${cfg}）→ 重跑安装命令，或手动执行 `
-        + `openclaw mcp add misakanet --url ${ENDPOINT} --transport streamable-http`);
+      installFailed();
+      const manual = `openclaw mcp add misakanet --url ${ENDPOINT} --transport streamable-http`;
+      need(canCreateHere(cfg)
+        ? `OpenClaw：MCP 未注册（${cfg}）→ 重跑安装命令，或手动执行 ${manual}`
+        : `OpenClaw：MCP 未注册（${cfg}）→ ${unwritableAdvice(manual)}`);
     } else {
       ok(`OpenClaw：MCP 已注册（${entry.url || '?'}）`);
     }
@@ -1452,17 +1845,21 @@ async function verify() {
   if (readText(join(HOME, '.hermes', 'config.yaml'))) {
     const rules = join(HOME, '.hermes', 'SOUL.md');
     if (!readText(rules).includes(`<!-- ${START} -->`)) {
-      allOk = false;
-      need(`Hermes：规则块没装（${rules}）→ 重跑安装命令`);
+      installFailed();
+      need(canCreateHere(rules)
+        ? `Hermes：规则块没装（${rules}）→ 重跑安装命令`
+        : `Hermes：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
     } else {
       ok('Hermes：规则块已装');
     }
     const cfg = join(HOME, '.hermes', 'config.yaml');
     const text = readText(cfg);
     if (!HERMES_MARKED.test(text) && !HERMES_BARE.test(text)) {
-      allOk = false;
-      need(`Hermes：MCP 未注册（${cfg}）→ 重跑安装命令，或执行 `
-        + `hermes mcp add misakanet --url ${ENDPOINT} --auth header`);
+      installFailed();
+      const manual = `hermes mcp add misakanet --url ${ENDPOINT} --auth header`;
+      need(canCreateHere(cfg)
+        ? `Hermes：MCP 未注册（${cfg}）→ 重跑安装命令，或执行 ${manual}`
+        : `Hermes：MCP 未注册（${cfg}）→ ${unwritableAdvice(manual)}`);
     } else if (!new RegExp(`^${HERMES_ENV_KEY}=`, 'm').test(readText(join(HOME, '.hermes', '.env')))) {
       ok('Hermes：MCP 条目已写入配置（无 token → 读不限次数，写入类工具不可用）');
       skip(`Hermes：想让写入类工具可用（write_lesson），重跑安装命令即可写入 ${HERMES_ENV_KEY}`);
@@ -1471,6 +1868,27 @@ async function verify() {
       skip('Hermes：本进程只能确认"配置已写"，无法确认 Hermes 是否已加载 → 可用 hermes mcp list 复核');
     }
   }
+  // The MCP-only targets are reported only when the user actually has them, like OpenClaw and
+  // Hermes. Their state is one JSON file, so it is readable without starting anything — but whether
+  // the client has *loaded* that file cannot be confirmed from here, and the line says so.
+  for (const [agent, spec] of Object.entries(MCP_ONLY_TARGETS)) {
+    if (!detect(agent)) continue;
+    const cfg = spec.config(HOME);
+    const entry = (readJson(cfg, null) || {})[spec.container]?.misakanet;
+    if (!entry) {
+      installFailed();
+      need(canCreateHere(cfg)
+        ? `${spec.label}：MCP 未注册（${cfg}）→ 重跑安装命令，然后${spec.verifyHint}`
+        : `${spec.label}：MCP 未注册（${cfg}）→ ${unwritableAdvice()}`);
+    } else if (!entry[spec.urlField]) {
+      installFailed();
+      need(`${spec.label}：MCP 条目在，但没有 ${spec.urlField} 字段（${cfg}）→ 重跑安装命令；`
+        + `这家用的是 ${spec.urlField}${spec.container === 'mcp' ? '（注意嵌套在 mcp 而不是 mcpServers 下）' : ''}`);
+    } else {
+      ok(`${spec.label}：MCP 已注册（${entry[spec.urlField]}）`);
+      skip(`${spec.label}：只能确认"配置已写"，无法确认它是否已加载 → ${spec.verifyHint}`);
+    }
+  }
   // Version: what is installed, and whether the registry has moved on. Read-only here — the
   // hook owns the periodic nudge (it cannot be a network call in this process's hot path), and
   // `--verify` is an explicit user action, so one lookup is both cheap and expected.
@@ -1493,7 +1911,72 @@ async function verify() {
         + 'npx @misaka-net/misakanet-setup@latest');
     }
   }
-  return allOk;
+  return {
+    allOk,
+    usable,
+    probeState,
+    install: installOk ? 'complete' : 'incomplete',
+    // The install segment's open items, counted on their own: the report's `open-items` is every
+    // manual item, this is the ones that belong to our footprint.
+    openItems: manual.length - segmentEnd.manual,
+    segments: { start: segmentStart, end: segmentEnd },
+  };
+}
+
+/**
+ * The two verdicts, in words.
+ *
+ * They are two answers to two questions, and the point of #3696 is that they are printed as two:
+ * a machine whose endpoint answers perfectly and whose workspace is read-only is **usable**, and
+ * the old single verdict said NOT READY about it — the one word that sends the user to debug the
+ * wrong thing.
+ */
+function usabilityText(verdict) {
+  if (verdict.probeState === 'not-ready') return '不就绪 —— 端点不可达或握手异常';
+  if (verdict.probeState === 'unknown') {
+    return STRICT
+      ? '不就绪 —— 探测不可信，--strict 不接受"说不清"'
+      : '说不清 —— 探测不可信（不等于不可达）';
+  }
+  if (!verdict.usable) return '不就绪 —— 端点可达，但只读工具没放行，第一次检索会被拦下';
+  return '就绪 —— 端点可达，检索与读取可用';
+}
+
+function installText(verdict) {
+  if (verdict.install === 'complete') return '完整 —— 我们偏好的文件都写好了';
+  return `不完整 —— ${verdict.openItems} 项需要手动处理（上面每条 ! 都给了成因和做法）`;
+}
+
+/**
+ * The verify output: two sections, because the two questions have two answers.
+ *
+ * The old output was one list, and one list cannot say "the endpoint answered, the files did not
+ * get written" — it can only say NOT READY, which is the sentence the OpenClaw trialer read as
+ * "MisakaNet does not work here" (issue #3696).
+ */
+function renderVerify(verdict) {
+  const { start, end } = verdict.segments;
+  const tail = { done: done.length, manual: manual.length, skipped: skipped.length };
+  const section = (label, from, to) => {
+    const out = [];
+    const finished = done.slice(from.done, to.done);
+    const open = manual.slice(from.manual, to.manual);
+    const ignored = skipped.slice(from.skipped, to.skipped);
+    // `--silent` drops the narration, never the errors (the same contract `render()` keeps): the
+    // `!` lines are what a human has to act on, the `✓` and `·` lines are progress.
+    if (finished.length && !SILENT) out.push(...finished.map((l) => `  ✓ ${l}`));
+    if (open.length) out.push(...open.map((l) => `  ! ${l}`));
+    if (ignored.length && !SILENT) out.push(...ignored.map((l) => `  · ${l}`));
+    if (!out.length) return out;
+    return [`\n── ${label} ──`, ...out];
+  };
+  return [
+    ...section('端点/可用性', start, end),
+    ...section('安装完整性', end, tail),
+    '',
+    `可用性：${usabilityText(verdict)}`,
+    `安装完整性：${installText(verdict)}`,
+  ].join('\n');
 }
 
 /**
@@ -1550,7 +2033,8 @@ function restoreEmptiedFiles() {
   // JSON configs: prune containers that our own removal emptied. The file itself is never deleted —
   // it may have existed before us (an empty `~/.claude.json` is a legitimate user state).
   const jsonFiles = [join(HOME, '.claude.json'), join(HOME, '.claude', 'settings.json'),
-                     join(HOME, '.openclaw', 'openclaw.json'), join(HOME, '.codewhale', 'mcp.json')];
+                     join(HOME, '.openclaw', 'openclaw.json'), join(HOME, '.codewhale', 'mcp.json'),
+                     ...Object.values(MCP_ONLY_TARGETS).map((spec) => spec.config(HOME))];
   for (const file of jsonFiles) {
     const data = readJson(file, null);
     if (!data || typeof data !== 'object') continue;
@@ -1617,6 +2101,16 @@ function uninstall() {
     writeText(cfg, `${JSON.stringify(data, null, 2)}\n`);
     ok(`移除 MCP 注册 → ${cfg}`);
   }
+  for (const spec of Object.values(MCP_ONLY_TARGETS)) {
+    const cfg = spec.config(HOME);
+    const data = readJson(cfg, null);
+    if (data?.[spec.container]?.misakanet) {
+      delete data[spec.container].misakanet;
+      backup(cfg);
+      writeText(cfg, `${JSON.stringify(data, null, 2)}\n`);
+      ok(`移除 MCP 注册 → ${cfg}`);
+    }
+  }
   const voiceDir = join(stateDir(), 'voice');
   if (existsSync(voiceDir)) {
     try {
@@ -1772,7 +2266,8 @@ function distroName() {
  * scalars (`true`, `[claude, codex]`, `""`); the JSON keeps their real types (boolean, array,
  * string), which is the whole point of a machine-readable form.
  */
-function reportValues(allOk) {
+function reportValues(verdict) {
+  const allOk = verdict.allOk;
   const agents = AGENTS.filter((agent) => detect(agent));
   const token = existsSync(join(stateDir(), 'token'));
   const permissions = (() => {
@@ -1792,14 +2287,25 @@ function reportValues(allOk) {
     ['node', process.version],
     ['detected-agents', agents],
     ['verify', allOk ? 'READY' : 'NOT READY'],
+    // The verdict has two halves, and a machine that collects this report needs to be able to
+    // tell them apart: `verify: NOT READY` because our files could not be written is a
+    // different machine from `verify: NOT READY` because the endpoint does not answer
+    // (issue #3696). `endpoint-reachable` and `endpoint-probe` below already say the endpoint's
+    // half; this is ours.
+    ['install-complete', verdict.install],
+    ['endpoint-usable', verdict.usable ? 'yes' : 'no'],
     ['endpoint-reachable', lastProbe.reachable],
     ['endpoint-tools', lastProbe.tools],
+    // `ok` = the probe ran and its answer is meaningful; `inconclusive-proxy` = the machine has a
+    // proxy this process cannot use, so the boolean above says nothing. Without this field the YAML
+    // a user pastes into a public issue cannot tell a real outage from a false negative.
+    ['endpoint-probe', lastProbe.note || 'ok'],
     ['token', token ? 'present' : 'absent'],
     ['permissions', permissions],
     ['hook', existsSync(join(stateDir(), 'hook.mjs')) ? 'present' : 'absent'],
     // `mcp-only` = the endpoint is registered but the hooks are not, which is a different machine
     // from "nothing installed" and must not be counted as one (#1753's T1-lite rows).
-    ['install-scope', existsSync(join(stateDir(), 'hook.mjs'))
+    ['install-scope', hookWired()
       ? 'full'
       : (AGENTS.some((agent) => detect(agent) && mcpEntryPresent(agent)) ? 'mcp-only' : 'none')],
     ['voice', voiceStatus()],
@@ -1876,10 +2382,10 @@ function reportJson(values) {
  * encoding never changes the verdict.
  */
 async function report(asJson) {
-  const allOk = await verify();
-  const values = reportValues(allOk);
+  const verdict = await verify();
+  const values = reportValues(verdict);
   console.log(asJson ? reportJson(values) : reportYaml(values));
-  return { allOk, openItems: manual.length };
+  return { ...verdict, openItems: manual.length };
 }
 
 // ── main ─────────────────────────────────────────────────────────────
@@ -1979,13 +2485,13 @@ if (mode === 'report') {
 }
 
 if (mode === 'verify') {
-  const allOk = await verify();
-  say(render());
+  const verdict = await verify();
+  say(renderVerify(verdict));
   // Kept under `--silent`: this line is the verdict, not progress. (It is also the only thing a
   // silent `--verify` prints when the machine is healthy, which is what makes it usable in a
   // deployment log.)
-  console.log(`\n结论：${allOk ? `READY —— 打开一个新会话，问它「${ONBOARDING_QUERIES[0]}」这类带报错原文的片段` : 'NOT READY —— 上面每条 ! 都给了修复动作'}`);
-  process.exit(allOk ? 0 : 1);
+  console.log(`\n结论：${verdict.allOk ? `READY —— 打开一个新会话，问它「${ONBOARDING_QUERIES[0]}」这类带报错原文的片段` : 'NOT READY —— 上面每条 ! 都给了成因和做法'}`);
+  process.exit(verdict.allOk ? 0 : 1);
 }
 
 const targets = (only.length ? only : AGENTS).filter((a) => {
@@ -2032,38 +2538,12 @@ if (LIST_WRITES) {
   // Every row carries its **tier**, which is the point: an operator approving "add an MCP server"
   // (①) is not approving "change how the agent behaves" (② rules block, ③ automatic hooks). Files
   // already exist → we append or update keys; missing → we create them.
-  // Compare base names, not separators: a `/settings.json$` regex silently classifies nothing on
-  // Windows (all three windows legs went red on the first CI run of this change), and a manifest
-  // that hides a tier is worse than no manifest.
-  const tierOf = (path) => {
-    const base = basename(path);
-    if (base === 'CLAUDE.md' || base === 'AGENTS.md' || base === 'SOUL.md') return 2;
-    if (path.includes('.misakanet-agent')) return 3;               // our own state dir
-    // `settings.json` carries both the read-only grants (①) and the hooks (③); the caller adds the
-    // second row only when the hooks are in scope.
-    if (base === 'settings.json' && path.includes('.claude')) return 1;
-    return 1;                                                     // an MCP entry in the agent's config
-  };
-  const rows = new Map();
-  const add = (path, action, tier) => {
-    const key = `${tier}|${path}`;
-    if (!rows.has(key)) rows.set(key, { path: redact(path), action, tier });
-  };
-  for (const agent of AGENTS) {
-    if (!detect(agent)) continue;
-    for (const path of (AGENT_WRITE_PATHS[agent] || (() => []))(HOME)) {
-      add(path, existsSync(path) ? 'append-or-update' : 'create', tierOf(path));
-      if (!MCP_ONLY && basename(path) === 'settings.json' && path.includes('.claude')) {
-        add(path, 'append-or-update（钩子）', 3);
-      }
-    }
-  }
-  add(join(stateDir(), 'token'), 'create (0600)', 1);
-  if (!MCP_ONLY) add(join(stateDir(), 'hook.mjs'), 'create', 3);
-
+  //
+  // The rows come from the shared manifest builder, the same list the install preview prints: one
+  // source of truth, so the manifest an operator approves and the preview a user reads cannot
+  // disagree about what this command would write.
   const tiers = { 1: '① 注册 MCP 端点', 2: '② 写规则块（改行为）', 3: '③ 装钩子（每轮自动执行）' };
-  const list = [...rows.values()].filter((row) => (MCP_ONLY ? row.tier === 1 : true))
-    .sort((a, b) => a.tier - b.tier || a.path.localeCompare(b.path));
+  const list = buildWriteManifest(targets);
   for (const row of list) {
     console.log(`tier${row.tier}\t${tiers[row.tier]}\t${row.path}\t${row.action}`);
   }
@@ -2079,11 +2559,27 @@ if (LIST_WRITES) {
   process.exit(0);
 }
 
+// The preview (#3690): the first thing a user sees about what this run is about to write, printed
+// **before** the first write — so a user who did not expect these files still sees them while
+// there is nothing to undo yet.
+//
+// `--silent` keeps its contract: a clean silent run is an empty log, and this summary is progress
+// narration, not an error line. `--list-writes` has already exited above with the machine-readable
+// version of the same list.
+if (!SILENT && targets.length) {
+  const preview = writePreview(buildWriteManifest(targets));
+  if (preview) console.log(preview);
+}
+
 try {
   if (!targets.length) {
-    need('没检测到 Claude Code / Codex / Hermes 的配置目录 → 请先打开一次你要用的那个助手，再回来运行本命令');
+    need('没检测到任何受支持助手的配置目录（Claude Code / Codex / Hermes / OpenClaw / Codewhale / '
+      + 'Cursor）→ 请先打开一次你要用的那个助手，再回来运行本命令');
   } else {
-    const hookPath = MCP_ONLY ? null : await installHook();
+    // Only install the hook when a target can actually consume it. Writing it for a Cursor-only or
+    // Codex-only machine produced a file nothing would ever run, and made `--report` claim
+    // `install-scope: full` for an install that registered an endpoint and nothing else.
+    const hookPath = (MCP_ONLY || !targets.includes('claude')) ? null : await installHook();
     if (!MCP_ONLY) stampVersion();
     const bearer = has('--no-register') ? '' : await ensureIdentity();
     for (const agent of targets) {
@@ -2104,6 +2600,7 @@ try {
         else if (agent === 'hermes') await installHermes(hookPath, bearer);
         else if (agent === 'openclaw') await installOpenclaw(bearer);
         else if (agent === 'codewhale') await installCodewhale(bearer);
+        else if (MCP_ONLY_TARGETS[agent]) await installMcpOnly(agent, bearer);
         installed += 1;
       } catch (err) {
         need(`${agent}：写入配置失败（${redact((err && err.message) || err)}）`

package/hook/checkpoint_reminder.mjs

@@ -226,6 +226,94 @@ function failureText(payload) {
   return '';
 }
 
+/**
+ * Deterministic redaction — the query must not carry the machine's secrets out of it.
+ *
+ * Issue #3692: the rules block used to *ask* the agent to redact, and an instruction is
+ * only a request. When the model did not comply, the internal table name, the home
+ * directory path or the token left the machine inside a search query. This table is the
+ * mechanical version of that rule: it runs on the error text before the fragment is
+ * printed into the agent's context, and again before anything is sent over the network.
+ * Redacting only at the network call would not be enough — the un-redacted text would
+ * still be in the agent's context, and the agent's own `misakanet_search` call would
+ * carry it.
+ *
+ * The ids are the server's (`workers/lib/redact-patterns.json`), so both ends name the
+ * same classes and the client never invents a rule the server does not know. Real
+ * domains and personal names are deliberately NOT redacted: the corpus is indexed by error
+ * text, and over-redaction would cost search quality for a leak that is not in scope.
+ *
+ * One path segment: anything but a space, a separator or punctuation that would end the
+ * segment (so a trailing comma or bracket in prose stays outside the match).
+ */
+const SEG = "[^\\s/\\\\'\"<>,;:!?()\\[\\]{}]";
+// A path only counts as a *filesystem* path when it starts at a known root, or when its
+// last segment carries a file extension. Without that, every API route in the corpus
+// ("/api/v1/users", "/oauth/token") would be swallowed — and the corpus is indexed by
+// error text, so a swallowed route destroys the lesson it belongs to. The roots are
+// case-sensitive, except "Users" and "Volumes", which are written in capitals by
+// convention but arrive in every casing.
+const FS_ROOTS = "(?:home|root|var|opt|etc|usr|tmp|mnt|srv|data|private|workspace|app|code|project"
+  + "|[Uu][Ss][Ee][Rr][Ss]|[Vv][Oo][Ll][Uu][Mm][Ee][Ss])";
+const FILE_EXT = "[A-Za-z][A-Za-z0-9_\\-]*";
+
+const REDACT_RULES = [
+  // A Unix absolute path: either it starts at a known filesystem root, or its last
+  // segment has a file extension ("/opt/app/config.yaml"). The look-behind keeps it out
+  // of a URL ("https://host/a/b" — the slash follows a word character) and out of a
+  // relative path; "file://" is matched as a whole, because its inner path is a path.
+  { id: 'abs_path', pattern: `(?<![A-Za-z0-9_:/~.\\-])(?:file://)?/(?:${FS_ROOTS}(?:/${SEG}+)+|(?:${SEG}+/)*${SEG}*\\.${FILE_EXT})`, flags: 'g', replacement: '<PATH>' },
+  // A Windows path, with either separator. The look-behind keeps the "s://" of a URL out.
+  { id: 'windows_path', pattern: `(?<![A-Za-z0-9_])[A-Za-z]:[\\\\/](?:${SEG}+[\\\\/])*${SEG}*`, flags: 'g', replacement: '<PATH>' },
+  // The secret rules are the server's shapes with two additions its copy does not need: a
+  // word boundary (so "task_identifier" is not read as the key "sk_identifier") and a floor
+  // of six characters on the bearer value (so the phrase "Bearer token" in prose survives).
+  // A real credential is longer than that; a real key is not glued to the end of a word.
+  { id: 'bearer_token', pattern: '(?<![A-Za-z0-9])(?:Bearer|Authorization)\\s+[A-Za-z0-9\\-._~+/]{6,}=*', flags: 'gi', replacement: '[REDACTED:bearer_token]' },
+  { id: 'github_token', pattern: '(?<![A-Za-z0-9])(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9]{10,}', flags: 'g', replacement: '[REDACTED:github_token]' },
+  { id: 'api_key', pattern: '(?<![A-Za-z0-9])(?:sk|pk|rk|ak)[_-][A-Za-z0-9]{10,}', flags: 'g', replacement: '[REDACTED:api_key]' },
+  // The top-level domain has to be alphabetic: "foo@1.2.3" is an npm version spec, and
+  // eating it would destroy the version the reporter was talking about.
+  { id: 'email', pattern: '[A-Za-z0-9._%+\\-]+@[A-Za-z0-9\\-]+(?:\\.[A-Za-z0-9\\-]*)*\\.[A-Za-z]{2,}', flags: 'g', replacement: '<REDACTED:email>' },
+];
+
+const COMPILED_REDACT_RULES = REDACT_RULES.map((rule) => ({
+  ...rule,
+  regex: new RegExp(rule.pattern, rule.flags),
+}));
+
+/**
+ * Replace every secret the table knows about. Never throws: a broken rule must not become
+ * a failed hook (the hook's contract is that it cannot break a session).
+ */
+function redact(text) {
+  let out = String(text);
+  for (const rule of COMPILED_REDACT_RULES) {
+    try {
+      out = out.replace(rule.regex, rule.replacement);
+    } catch (err) {
+      debug(`redaction rule ${rule.id} failed: ${err}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Cut the query to a length, without cutting a placeholder in half: a truncated
+ * `<REDACTED:email` is noise the agent would carry into its own call.
+ *
+ * Counted in code points, not UTF-16 units, so this and the Python twin cut in the same
+ * place — the parity test compares their stdout byte for byte.
+ */
+function clip(text, limit) {
+  const chars = Array.from(text);
+  if (chars.length <= limit) return text;
+  let cut = chars.slice(0, limit).join('');
+  const open = cut.lastIndexOf('<');
+  if (open !== -1 && cut.indexOf('>', open) === -1) cut = cut.slice(0, open);
+  return cut;
+}
+
 function target() {
   const configured = (process.env.MISAKANET_ENDPOINT || CANONICAL_ENDPOINT).trim();
   const envToken = (process.env.MISAKANET_TOKEN || '').trim();
@@ -251,7 +339,9 @@ async function search(query) {
       signal: controller.signal,
       body: JSON.stringify({
         jsonrpc: '2.0', id: 1, method: 'tools/call',
-        params: { name: 'misakanet_search', arguments: { query: query.slice(0, 300), top: 1, detail: 'summary' } },
+        // Redacted again on the way out: the fragment is already redacted, but this is the
+        // only place where the text actually leaves the machine, so it gets its own gate.
+        params: { name: 'misakanet_search', arguments: { query: redact(query).slice(0, 300), top: 1, detail: 'summary' } },
       }),
     });
     clearTimeout(timer);
@@ -302,7 +392,9 @@ function promptMode(payload) {
 async function failureMode(payload) {
   const text = failureText(payload);
   if (!text) return;
-  const fragment = text.split(/\s+/).join(' ').slice(0, 120);
+  // Redact first, cut second: the query the agent is told to search with must not carry a
+  // path, an address or a token, and the agent may copy it into its own later call.
+  const fragment = clip(redact(text).split(/\s+/).join(' '), 120);
   const lines = [
     '[MisakaNet] 刚刚有一次工具调用失败。在**重试或换修法之前**先查一次（第二次盲试就是『重复犯错』）：',
     `  misakanet_search(query=${JSON.stringify(fragment)})   # 查不到就用 kind="question" 提 intake，别猜`,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@misaka-net/misakanet-setup",
-  "version": "0.5.6",
-  "description": "One-command setup: teach your Claude Code / Codex / Hermes / OpenClaw / codewhale to search MisakaNet failure lessons before repeating a mistake, and to distil the session at a checkpoint.",
+  "version": "0.6.0",
+  "description": "MisakaNet failure lessons for your agents: writes an MCP endpoint into each agent config, rules blocks where the client takes one, and a Claude Code hook. At most one anonymous request leaves this machine at install; then only the agent's calls — unless MISAKANET_HOOK_FETCH=1 (off by default) the hook sends the failed call's error text or command.",
   "bin": {
     "misakanet-setup": "bin/misakanet-setup.mjs"
   },