@misaka-net/misakanet-setup 0.5.6 → 0.7.0

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', 'mcode'];
 
 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.7.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*
@@ -172,7 +185,7 @@ const FLAGS = [
   ['--silent', '只压掉进度叙述，绝不压掉 ! 行与报告（MDM/GPO 用）'],
   ['--report', '打印一段可公开粘贴的脱敏状态报告（人读 YAML）'],
   ['--report-json', '同一份报告的 JSON 编码'],
-  ['--strict', '配合 --report：NOT READY 时退出码 1（默认仍退 0）'],
+  ['--strict', '配合 --report：NOT READY 时退出码 1，没能验证（探测超时/代理）时 2（默认仍退 0）'],
   ['--ci', '= --report --strict'],
   ['--verify', '自检：端点可达、钩子、MCP 注册、版本新旧'],
   ['--uninstall', '移除本安装器写入的内容（保留 .misakanet.bak 备份）'],
@@ -193,8 +206,9 @@ function printHelp() {
 
 ${FLAGS.map(([flag, desc]) => `  ${flag.padEnd(16)} ${desc}`).join('\n')}
 
-退出码（安装模式）：0 至少装上了一个助手 / 1 什么都没装上 / 2 自己跑不起来。
-健康检查用 --verify 或 --report --strict，不要看安装模式的退出码。`);
+退出码（三档，--verify 与 --report --strict 相同）：0 READY / 1 NOT READY（机器问题）/
+  2 没能验证（工具给不出机器判定：探测超时、代理不可信，或报告没生成）。
+安装模式：0 至少装上了一个助手 / 1 什么都没装上 / 2 自己跑不起来。`);
 }
 
 if (has('--help') || has('-h')) {
@@ -206,9 +220,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));
@@ -271,6 +282,16 @@ function sameJson(a, b) {
  *     read-only file (it only needs write permission on the *directory*), so the previous EACCES
  *     behaviour is kept explicitly rather than silently lost.
  */
+/**
+ * Every file this run actually wrote.
+ *
+ * The preview says which files are *in scope*; this says which ones were really touched. The
+ * difference is the whole point of the count a user actually reads: on an already-installed
+ * machine the preview listed 7 files and every one of them came back "无改动", while the header
+ * still said "将修改 7 个文件" — a number nobody could trust (measured 2026-10-23).
+ */
+const writtenFiles = new Set();
+
 function writeText(path, text, { mode } = {}) {
   if (DRY) return;
   mkdirSync(dirname(path), { recursive: true });
@@ -316,6 +337,172 @@ function writeText(path, text, { mode } = {}) {
     try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
     throw err;
   }
+  writtenFiles.add(path);
+}
+
+/**
+ * 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 面板复核',
+  },
+};
+
+/**
+ * Display names for every target, derived from the two lists that already define them.
+ *
+ * Why a table: the "no supported assistant was found" sentence used to spell out six names by
+ * hand (`Claude Code / Codex / Hermes / OpenClaw / Codewhale / Cursor`) while `AGENTS` had grown
+ * to ten — so a machine with none of the six was told about a smaller product than the one it was
+ * running, and Gemini/Copilot/OpenCode/Kiro users could not recognise themselves in it (#3778).
+ * The five MCP-only labels are read from `MCP_ONLY_TARGETS` rather than typed a second time, and
+ * `supportedAgentLabels()` falls back to the id if a future target is added without a label — an
+ * unlabelled target is then still named, instead of silently disappearing from the sentence.
+ */
+const AGENT_LABELS = {
+  claude: 'Claude Code',
+  codex: 'Codex',
+  hermes: 'Hermes',
+  openclaw: 'OpenClaw',
+  codewhale: 'Codewhale',
+  ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS).map(([id, spec]) => [id, spec.label])),
+  // Not an MCP-only target: it takes a rules block too (see `installMcode`), so its label cannot be
+  // read from that table.
+  mcode: 'MiniMax Code',
+};
+
+/**
+ * MiniMax Code (`mcode`) — a **plugin directory**, not a config file (issue #3777).
+ *
+ * Three facts decide this whole target, and none of them is guessable from the other clients:
+ *
+ *   * mcode does not read a user-level MCP config. `~/.minimax/config.yaml`'s `mcpServers` is
+ *     ignored (measured in #3777), so writing an entry there would look installed and register
+ *     nothing.
+ *   * It *does* read a **plugin directory** whose manifest is a Claude Code plugin manifest:
+ *     `~/.minimax/plugins/misakanet/.claude-plugin/plugin.json` (source `LOCAL_CLAUDE`) makes
+ *     `mcode plugin list` show `misakanet@local enabled`. Placing the directory is the install.
+ *   * `mcode plugin add misakanet@local` answers `LOCAL_PLUGIN_INSTALL_UNSUPPORTED` — that is its
+ *     refusal to *link* a local plugin, not evidence that the plugin is missing: the listing still
+ *     shows it enabled while the directory is in place. Nothing in this installer runs that command.
+ *
+ * The manifest cannot be copied from the repository's own `.claude-plugin/plugin.json`: the npm
+ * package's `files` list does not ship it (`bin/`, `hook/`, `voice/`, `README.md` only), so the
+ * expected shape is built here. Rules are ordinary `AGENTS.md`: `~/.minimax/AGENTS.md` is its
+ * global scope and applies to every session. There is no hook mechanism, so tier ③ does not exist
+ * for this target and the install says so instead of implying behaviour changed.
+ *
+ * What this target cannot fix: mcode budgets ~2000 ms for HTTP MCP discovery and Node's `fetch`
+ * ignores proxy variables unless `NODE_USE_ENV_PROXY=1`. On a proxied machine the result is
+ * "installed but 0 tools" — a runtime fact, documented in docs/integrations/mcode.md, not
+ * something an installer can write around.
+ */
+const MCODE_PLUGIN_REL = join('.minimax', 'plugins', 'misakanet', '.claude-plugin', 'plugin.json');
+const MCODE_RULES_REL = join('.minimax', 'AGENTS.md');
+const MCODE_DESCRIPTION = 'MisakaNet failure memory: search evidence-rated failure lessons before '
+  + 're-debugging, and turn new failures into shared knowledge.';
+
+const mcodePluginPath = (home) => join(home, MCODE_PLUGIN_REL);
+
+/** The manifest we write — the shape `mcode plugin list` reads. */
+function mcodePluginDoc(bearer) {
+  return {
+    name: 'misakanet',
+    version: VERSION,
+    description: MCODE_DESCRIPTION,
+    mcpServers: {
+      misakanet: { type: 'http', url: ENDPOINT, headers: mcpHeaders(bearer, 'mcode') },
+    },
+  };
+}
+
+/** The `misakanet` entry in that manifest, or null when the file is absent or not JSON. */
+function mcodePluginEntry() {
+  const doc = readJson(mcodePluginPath(HOME), null);
+  return doc && typeof doc === 'object' ? doc.mcpServers?.misakanet || null : null;
+}
+
+
+/** The supported assistants, named from `AGENTS` — never a hand-written second list. */
+function supportedAgentLabels() {
+  return AGENTS.map((agent) => AGENT_LABELS[agent] || agent).join(' / ');
 }
 
 /**
@@ -330,9 +517,124 @@ 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)]])),
+  // Two files, two tiers: the plugin manifest registers the endpoint (①) and the global AGENTS.md
+  // carries the rules block (②). Listing both here is what makes the preview, `--list-writes` and
+  // the permission pre-check agree with `installMcode`.
+  mcode: (home) => [join(home, MCODE_PLUGIN_REL), join(home, MCODE_RULES_REL)],
   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) {
+      // The endpoint record lives in the state directory, so it is tier ③ like everything else in
+      // there: `--mcp-only` must not create that directory at all (the e2e checks the directory
+      // itself, not just the files). The record is therefore written only when tier ③ is in scope.
+      add(join(stateDir(), STATE_ENDPOINT_FILE), 'create', 3, 'endpoint');
+      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 凭据',
+    endpoint: '端点记录',
+    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 [
+    // "将修改" was a promise the run could not keep: on an already-installed machine every file
+    // in this list came back "无改动" while the header still said "将修改 7 个文件" — and that is
+    // the number the reader looks at. The list is a scope, so it says so; the count of files that
+    // were really touched is printed after the install (see writtenFiles).
+    `将涉及 ${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,15 +715,76 @@ 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;
+}
+
+/**
+ * Our rules block in a file, with or without its markers.
+ *
+ * The markers can be lost — a hand-edit, a merge conflict — and then the block is still ours,
+ * sitting in the file as plain text. Two consequences, both measured on a real machine
+ * (2026-10-23): the installer looked for the markers, so it appended a *second* copy of a block
+ * that was already there (reporting "added", i.e. success); the uninstaller removed by marker,
+ * so it took only one of the two away and left the other for ever (also reporting success).
+ * Three rounds of install/uninstall left zero residue as long as the markers were intact, which
+ * is why this only ever showed up after the markers went missing.
+ *
+ * So both sides look for the same thing now: the marker pair, or the block's own text.
+ */
+function blockRegions(text, block) {
+  const regions = [];
+  // The marked region is exactly what the old installer matched — and it must stay that narrow:
+  // a region that also swallowed the newline in front of the block made every re-install rewrite
+  // the file (the e2e caught it: "the rules file was rewritten by a run that had nothing to
+  // change"). Taking that newline is the *uninstaller's* job, and only the uninstaller's.
+  const marked = new RegExp(`[ \\t]*<!--\\s*${START}\\s*-->[\\s\\S]*?<!--\\s*${END}\\s*-->\\n?`, 'g');
+  for (const m of text.matchAll(marked)) {
+    regions.push({ start: m.index, end: m.index + m[0].length, text: m[0], marked: true });
+  }
+  const body = block.trim();
+  let from = 0;
+  for (;;) {
+    const at = text.indexOf(body, from);
+    if (at < 0) break;
+    const inside = regions.some((r) => at >= r.start && at < r.end);
+    if (!inside) {
+      regions.push({ start: at, end: at + body.length, text: body, marked: false });
+    }
+    from = at + body.length;
+  }
+  return regions.sort((a, b) => a.start - b.start);
+}
+
 function injectBlock(path, block) {
   const existing = readText(path);
-  const pattern = new RegExp(`[ \\t]*<!--\\s*${START}\\s*-->[\\s\\S]*?<!--\\s*${END}\\s*-->\\n?`);
   const body = `<!-- ${START} -->\n${block.trim()}\n<!-- ${END} -->\n`;
-  if (pattern.test(existing)) {
-    const updated = existing.replace(pattern, () => body);
-    if (updated === existing) return 'unchanged';
+  const regions = blockRegions(existing, block);
+  if (regions.length) {
+    // Keep the first copy where it is, re-wrap it in its markers, and drop the others: a file
+    // that ended up with two copies of the rules gets one. This is the case that used to
+    // append a second copy every time the installer ran.
+    const first = regions[0];
+    let out = '';
+    let cursor = 0;
+    for (const r of regions) {
+      out += existing.slice(cursor, r.start);
+      if (r === first) out += body;
+      cursor = r.end;
+    }
+    out += existing.slice(cursor);
+    if (out === existing) return 'unchanged';
     backup(path);
-    writeText(path, updated);
+    writeText(path, out);
     return 'updated';
   }
   backup(path);
@@ -430,20 +793,36 @@ function injectBlock(path, block) {
   return 'added';
 }
 
-function stripBlock(path) {
+/**
+ * Take our rules block back out — marked or not.
+ *
+ * The unmarked case is the one that used to leave a permanent copy behind: the block was ours,
+ * but without its markers neither side recognised it, so the installer duplicated it and the
+ * uninstaller could not see it. `blockRegions()` finds both shapes, so removal matches what
+ * installation now recognises.
+ */
+function stripBlock(path, block = PROMPT_BLOCK) {
   const text = readText(path);
   if (!text) return false;
-  // `\n?` on both sides: install writes a blank line, then the block, so consuming only the
-  // block left the file one newline longer than it started (uninstall claimed "已恢复原状"
-  // while `diff` showed an extra empty line).
-  const pattern = new RegExp(`\\n?[ \\t]*<!--\\s*${START}\\s*-->[\\s\\S]*?<!--\\s*${END}\\s*-->\\n?`);
-  if (!pattern.test(text)) return false;
+  const regions = blockRegions(text, block);
+  if (!regions.length) return false;
   backup(path);
-  const stripped = text.replace(pattern, '');
-  if (!stripped.trim()) {
+  let out = '';
+  let cursor = 0;
+  for (const r of regions) {
+    // The install writes a blank line, then the block; consuming only the block left the file one
+    // newline longer than it started (uninstall claimed "已恢复原状" while `diff` showed an extra
+    // empty line). So the removal takes that newline with it.
+    let start = r.start;
+    if (start > 0 && text[start - 1] === '\n') start -= 1;
+    out += text.slice(cursor, start);
+    cursor = r.end;
+  }
+  out += text.slice(cursor);
+  if (!out.trim()) {
     if (!DRY) rmSync(path, { force: true });
   } else {
-    writeText(path, stripped);
+    writeText(path, out);
   }
   return true;
 }
@@ -483,12 +862,67 @@ 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();
   return CLIENT_ID_SHAPE.test(found) ? found : '';
 }
 
+/**
+ * An `X-MisakaNet-Client` value already written into a target's config.
+ *
+ * Three syntaxes, because three kinds of target carry this header: JSON (`"X-MisakaNet-Client": "…"`
+ * in `.claude.json`, `openclaw.json` and the `--mcp-only` configs), TOML (Codex writes it **inside**
+ * its one-line `http_headers = { … }` table, so it is not at the start of a line) and YAML (Hermes's
+ * `config.yaml`, where the key is followed by `:`). The leading `(?:^|[\s{,])` is what lets the TOML
+ * case match mid-line while still requiring a plausible delimiter before the key.
+ *
+ * The capture is limited to the id alphabet so a value that could close a quote or a mapping can
+ * never travel from this file into the next one; `CLIENT_ID_SHAPE` then rejects it on length too.
+ */
+const CLIENT_ID_IN_CONFIG = /(?:^|[\s{,])["']?X-MisakaNet-Client["']?\s*[:=]\s*["']?([A-Za-z0-9._-]+)/m;
+
+/**
+ * Adopt the client id a target's config already declares, so a re-run keeps writing the same header.
+ *
+ * What went wrong without it (#3772): the first run mints `setup-<uuid>`, writes it into every
+ * config and prints it — but deliberately does not persist it to `<stateDir>/client_id` (that is the
+ * "read a local file, send it in a request" shape #1688 removed). The second run therefore had no id
+ * to declare, `mcpHeaders()` dropped the header, every config compared unequal, and all of them were
+ * rewritten while the closing report said the same files had been installed again.
+ *
+ * The value is already in the file this run is about to rewrite, so inheriting it in place needs no
+ * new persistence and no file-to-network flow: it stays a file-to-file honouring of what this
+ * machine already told the service. The first target to adopt carries the id to the rest through
+ * `knownClientId`, which is what keeps every config on the machine pointing at one identity.
+ *
+ * Explicit intent and the state file win: `declaredClientId()` is checked first, the same precedence
+ * the register path applies. `clientIdHint` is set as well, because it only feeds the closing
+ * "这台机器的身份编号是 X" guidance — after this change the second run prints the identity instead
+ * of saying nothing, which is one of the consequences #3772 listed (the only remaining copy used to
+ * be buried inside a config file).
+ */
+function adoptExistingClientId(text) {
+  if (declaredClientId()) return;
+  const found = text.match(CLIENT_ID_IN_CONFIG)?.[1] || '';
+  if (!CLIENT_ID_SHAPE.test(found)) return;
+  knownClientId = found;
+  clientIdHint = found;
+}
+
 const CANONICAL_ENDPOINT = 'https://misakanet.org/mcp';
 
 /**
@@ -503,6 +937,119 @@ function probeEndpoint() {
   return (process.env.MISAKANET_ENDPOINT || CANONICAL_ENDPOINT).trim();
 }
 
+/**
+ * The endpoint this machine's MCP entries are supposed to point at.
+ *
+ * The record comes first: it is the fact about *this machine* — what the installer wrote here.
+ * The env var only says what the operator has in mind right now, and the two can differ without
+ * anything being wrong (a mirror installed once, then verified without the variable exported).
+ * Comparing against the env var alone turned a healthy machine into a NOT READY one — the same
+ * shape as the false alarm the CLI already refuses to raise about the endpoint probe.
+ */
+function expectedEndpoint() {
+  const recorded = readText(join(stateDir(), STATE_ENDPOINT_FILE)).trim();
+  if (recorded) return recorded;
+  const fromEnv = (process.env.MISAKANET_ENDPOINT || '').trim();
+  if (fromEnv) return fromEnv;
+  return CANONICAL_ENDPOINT;
+}
+
+/**
+ * One verdict for every MCP entry this installer writes.
+ *
+ * "The entry exists" used to be the whole check, so an entry pointing at
+ * `https://BROKEN.invalid/mcp` was reported as `✓ MCP 已注册（https://BROKEN.invalid/mcp）` — a
+ * green tick next to a URL nobody can reach, and the broken URL printed verbatim after it. The
+ * entry has to point at *our* endpoint, not merely have a field with the right name in it.
+ */
+function mcpEntryState(entry, urlField) {
+  if (!entry) return { state: 'missing' };
+  const url = entry[urlField];
+  if (!url) return { state: 'no-url-field' };
+  const expected = expectedEndpoint();
+  if (url !== expected) return { state: 'wrong-url', url, expected };
+  return { state: 'ok', url };
+}
+
+/**
+ * The `[mcp_servers.misakanet]` table in a Codex config, if it is there.
+ *
+ * The table header is the anchor, not our comment markers: the markers can be lost (a hand-edit,
+ * a merge conflict) and the entry is still the entry.
+ */
+function codexMisakanetTable(text) {
+  const lines = text.split('\n');
+  let inTable = false;
+  let url = '';
+  for (const line of lines) {
+    const t = line.trim();
+    if (t.startsWith('[')) {
+      if (inTable) break;            // the next table starts: ours ended
+      inTable = t === '[mcp_servers.misakanet]';
+      continue;
+    }
+    if (!inTable) continue;
+    const m = t.match(/^url\s*=\s*"([^"]*)"/);
+    if (m) url = m[1];
+  }
+  return inTable ? { url } : null;
+}
+
+/**
+ * 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`）';
+}
+
+/**
+ * How long one probe attempt may take.
+ *
+ * 6 s is the shipped value; `MISAKANET_PROBE_TIMEOUT_MS` exists so the test suite can prove the
+ * timeout *classification* in a few hundred milliseconds instead of six seconds per attempt. It is
+ * test plumbing, not a supported knob: a deployment that sets it is shortening the only honest
+ * signal it has, and the cap below keeps it from turning `--verify` into a hang.
+ */
+function probeTimeoutMs() {
+  const raw = Number(process.env.MISAKANET_PROBE_TIMEOUT_MS || '');
+  return Number.isFinite(raw) && raw > 0 ? Math.min(raw, 60000) : 6000;
+}
+
+/**
+ * The probe's retries and the pause between them.
+ *
+ * Fixed numbers, never random: the same machine with the same network must produce the same
+ * `endpoint-probe` value on two runs (#3778). A jittered backoff would make a timeout retry
+ * succeed on one run and fail on the next, which is how "flaky" gets filed against a health check.
+ */
+const PROBE_ATTEMPTS = 3;          // one attempt + at most two retries, per the issue
+const PROBE_RETRY_DELAY_MS = 300;
+
 /**
  * One unauthenticated MCP call.
  *
@@ -514,6 +1061,16 @@ function probeEndpoint() {
 // Records why the last request failed, so `--verify` can tell a timeout from a 404 from an
 // empty-but-successful answer instead of collapsing all three into "unreachable".
 let lastRequestError = '';
+// …and *which kind* of failure it was, which is what `endpoint-probe` reports: a timeout and a
+// refused connection deserve different verdicts (#3778). Reset per request, so a stale reason from
+// an earlier call (registration, a version lookup) can never be attributed to the probe.
+let lastRequestKind = '';
+// Whether HTTP answered at all. `200 {"hello":"world"}` parses fine and yields no `tools`, and the
+// old code called that "unreachable" — the endpoint did answer, it just does not speak MCP.
+let lastResponseOk = false;
+// The body it answered with, truncated: when the answer is not a handshake, the most useful thing
+// `--verify` can print is what actually came back (`{}` is not a diagnosis).
+let lastResponsePreview = '';
 
 async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
   const headers = {
@@ -525,6 +1082,11 @@ async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
   };
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
+  // Per request, not per process: the probe must not inherit the reason an earlier call failed.
+  lastRequestError = '';
+  lastRequestKind = '';
+  lastResponseOk = false;
+  lastResponsePreview = '';
   try {
     const response = await fetch(urlOverride || ENDPOINT, {
       method: 'POST',
@@ -532,7 +1094,18 @@ async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
       signal: controller.signal,
       body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
     });
+    // The exchange reached an HTTP peer. Whether that peer speaks MCP is decided by the body
+    // below, not by this line — but "it answered with something that is not a handshake" and
+    // "nothing answered" are different facts (see probeOutcome()).
+    lastResponseOk = true;
     const payload = await response.json();
+    lastResponsePreview = JSON.stringify(payload).slice(0, 160);
+    if (payload && payload.error) {
+      // A JSON-RPC error is an answer from an MCP-speaking server, but the *call* failed. Record
+      // its message so `--verify` can print the server's own words instead of "unreachable".
+      lastRequestError = String(payload.error.message || JSON.stringify(payload.error)).slice(0, 200);
+      lastRequestKind = 'json-rpc-error';
+    }
     const result = payload.result || {};
     // Three response shapes are in play: `structuredContent` (this worker's tools/call),
     // `content[0].text` (the MCP spec's text block), and plain fields (initialize, tools/list).
@@ -552,9 +1125,22 @@ async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
     // result indistinguishable to every caller — `--verify` then reported a working endpoint as
     // unreachable, which is the exact bug its own comment above describes. The shape of the return
     // value is unchanged (callers depend on it); the reason is now recorded for the report.
-    lastRequestError = (err && err.name === 'AbortError')
+    //
+    // The *kind* is recorded too, because it decides the verdict: `timeout` means "this machine
+    // could not answer", `unreachable` means "the connection really failed" (#3778). `ETIMEDOUT`
+    // is the socket-level spelling of the same thing, and undici wraps the real cause in
+    // `err.cause` (`fetch failed` alone names nothing: the interesting words are `bad port`,
+    // `connect ECONNREFUSED …`, `getaddrinfo EAI_AGAIN …`).
+    const cause = err && err.cause;
+    const code = String((cause && cause.code) || (err && err.code) || '');
+    const detail = String((cause && (cause.message || cause.code)) || (err && err.message) || err);
+    const timedOut = (err && (err.name === 'AbortError' || err.name === 'TimeoutError'))
+      || code === 'ETIMEDOUT'
+      || /timed? ?out|timeout|aborted/i.test(`${detail} ${(err && err.message) || ''}`);
+    lastRequestKind = timedOut ? 'timeout' : 'unreachable';
+    lastRequestError = timedOut
       ? `timeout after ${timeoutMs}ms`
-      : ((err && err.message) || String(err));
+      : (code && !detail.includes(code) ? `${detail}（${code}）` : detail);
     return {};
   } finally {
     clearTimeout(timer);
@@ -566,6 +1152,65 @@ function mcpCall(tool, toolArgs, timeoutMs = 6000, urlOverride = '') {
   return mcpRequest('tools/call', { name: tool, arguments: toolArgs }, timeoutMs, urlOverride);
 }
 
+/**
+ * The endpoint probe: up to `PROBE_ATTEMPTS` `tools/list` calls, retrying only on a timeout.
+ *
+ * Why retry at all: one stall on a slow link is not evidence about the endpoint, and a health
+ * check that flips on a single stall is not usable as a gate. Why *only* timeouts: a refused
+ * connection or a DNS failure is an answer, not a hiccup — retrying it just makes `--verify`
+ * slower. Why a fixed pause: see `PROBE_ATTEMPTS`.
+ */
+async function probeHandshake() {
+  const timeoutMs = probeTimeoutMs();
+  let payload = {};
+  let attempts = 0;
+  while (attempts < PROBE_ATTEMPTS) {
+    attempts += 1;
+    payload = await mcpRequest('tools/list', {}, timeoutMs, probeEndpoint());
+    if ((Array.isArray(payload?.tools) ? payload.tools : []).length) break;
+    if (lastRequestKind !== 'timeout') break;
+    if (attempts < PROBE_ATTEMPTS) {
+      await new Promise((resolve) => setTimeout(resolve, PROBE_RETRY_DELAY_MS));
+    }
+  }
+  return { payload, attempts, timeoutMs };
+}
+
+/**
+ * What the probe actually proved, as one of the values `endpoint-probe` reports.
+ *
+ * `ok`                  the handshake succeeded and the server listed tools
+ * `timeout`             no answer within the timeout, after retries — "could not verify", which is
+ *                       not the same claim as "the endpoint is down"
+ * `unreachable`         a real connection failure (ECONNREFUSED / ENOTFOUND / EAI_AGAIN / TLS …)
+ * `inconclusive-proxy`  a proxy is configured that this Node cannot use, and nothing better is
+ *                       known — the probe says nothing about the machine
+ * `non-mcp`             HTTP answered, but the exchange produced no MCP handshake (a non-MCP body,
+ *                       a wrong URL, a gateway, or an MCP error answer)
+ *
+ * The order is the contract, not an accident. `timeout` is checked before the proxy because a
+ * timeout is the better classification and must never be folded into the proxy story; the proxy is
+ * checked before `unreachable` because a refused *direct* connection does not prove the endpoint is
+ * down on a machine whose traffic is meant to go through a proxy this process cannot see. That
+ * precedence is what keeps the proxy case at "could not verify" (2) instead of sending the user to
+ * debug a network `curl` reaches fine (#3778).
+ */
+function probeOutcome(payload) {
+  const tools = Array.isArray(payload?.tools) ? payload.tools : [];
+  if (tools.length) return { state: 'ok', tools: tools.length };
+  // Before `lastResponseOk`: headers can arrive and the *body* can still hit the timeout (the
+  // same AbortController covers both), which leaves `lastResponseOk` true while the call is a
+  // timeout. Classifying that as `non-mcp` would name the wrong cause — measured on this repo's
+  // own endpoint, where a slow body occasionally produced exactly that pair.
+  if (lastRequestKind === 'timeout') return { state: 'timeout' };
+  if (lastResponseOk || payload?.error || payload?.protocolVersion || payload?.serverInfo) {
+    return { state: 'non-mcp' };
+  }
+  const proxy = proxyEnvironment();
+  if (proxy && !proxy.enabled) return { state: 'inconclusive-proxy', proxy };
+  return { state: 'unreachable' };
+}
+
 // Imperative first, and the trigger is line 1. Measured twice on real machines: the older
 // polite paragraph was followed by one agent and ignored by the next, while a short numbered
 // imperative list was followed immediately — a model that skips MCP tools entirely (reported
@@ -621,7 +1266,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 +1416,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 +1429,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 +1471,13 @@ 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))])),
+    // The manifest *is* the registry here, and the URL is part of the answer: a plugin pointing at
+    // a dead mirror is not "registered" for the question this function asks (`install-scope`).
+    mcode: () => (mcpEntryState(mcodePluginEntry(), 'url').state === 'ok'
+      ? readText(mcodePluginPath(HOME))
+      : ''),
   }[agent]?.() || '';
   return text.includes('misakanet') && text !== 'null';
 }
@@ -820,14 +1489,22 @@ function detect(agent) {
     hermes: ['.hermes'],
     openclaw: ['.openclaw'],
     codewhale: ['.codewhale'],
+    ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS).map(([id, spec]) => [id, spec.detect])),
+    // Both names are in circulation: `~/.minimax` is the current one, `~/.minimax-code` the older
+    // directory some installs still have (issue #3777). Either is evidence the CLI was here.
+    mcode: ['.minimax', '.minimax-code'],
   }[agent] || [];
   return paths.some((p) => existsSync(join(HOME, p)));
 }
 
 async function installClaude(hookPath, bearer) {
   const cfg = join(HOME, '.claude.json');
+  const existing = readText(cfg);
+  // Before building the entry: a re-run must declare the id this file already carries, or the
+  // comparison below sees a different entry and "deletes" the header (#3772).
+  adoptExistingClientId(existing);
   const data = readJson(cfg, null);
-  if (data === null && readText(cfg)) {
+  if (data === null && existing) {
     need(`Claude Code：${cfg} 不是合法 JSON → 请手动加入 mcpServers.misakanet`);
     return;
   }
@@ -992,6 +1669,8 @@ function hasTopLevelKey(text, key) {
 async function installCodex(hookPath, bearer) {
   const cfg = join(HOME, '.codex', 'config.toml');
   let text = readText(cfg);
+  // Inherit before `codexTable()` rebuilds the inline table from mcpHeaders() (#3772).
+  adoptExistingClientId(text);
   let changed = false;
 
   const topPattern = new RegExp(`^[ \\t]*#\\s*${TOP_START}\\s*$\\n?[\\s\\S]*?^[ \\t]*#\\s*${TOP_END}\\s*$\\n?`, 'm');
@@ -1041,6 +1720,16 @@ async function installCodex(hookPath, bearer) {
 }
 
 const STATE_VERSION_FILE = 'version';
+/**
+ * The endpoint this machine was pointed at, written at install time.
+ *
+ * `--verify` has to answer "does this machine point at *our* endpoint?", and on a self-hosted or
+ * mirrored install that endpoint is not the canonical one. Without a record of what was written,
+ * verifying without re-exporting `MISAKANET_ENDPOINT` would compare the mirror URL against the
+ * canonical one and report a mismatch that is not there — so the record is what makes the check
+ * honest instead of merely strict.
+ */
+const STATE_ENDPOINT_FILE = 'endpoint';
 
 const REGISTRY_LATEST = process.env.MISAKANET_REGISTRY_URL
   || 'https://registry.npmjs.org/@misaka-net%2fmisakanet-setup/latest';
@@ -1055,6 +1744,24 @@ const REGISTRY_LATEST = process.env.MISAKANET_REGISTRY_URL
  * `installed_at` is only refreshed when the version actually changes, so a re-run of the same
  * version does not reset the 14-day timer the user is relying on for peace and quiet.
  */
+/**
+ * Record the endpoint this install wrote, so `--verify` can tell "our endpoint" from "a URL".
+ */
+function stampEndpoint() {
+  const file = join(stateDir(), STATE_ENDPOINT_FILE);
+  if (readText(file).trim() === ENDPOINT) {
+    ok(`端点记录已存在（${ENDPOINT}）`);
+    return;
+  }
+  if (DRY) {
+    ok(`会写入端点记录 → ${file}（${ENDPOINT}）`);
+    return;
+  }
+  mkdirSync(stateDir(), { recursive: true });
+  writeText(file, `${ENDPOINT}\n`);
+  ok(`端点记录 → ${file}（${ENDPOINT}）`);
+}
+
 function stampVersion() {
   const file = join(stateDir(), STATE_VERSION_FILE);
   const existing = readJson(file, null);
@@ -1149,6 +1856,9 @@ function openclawWorkspaces() {
 async function installHermes(hookPath, bearer) {
   const cfg = join(HOME, '.hermes', 'config.yaml');
   const text = readText(cfg);
+  // The YAML block below is rebuilt from mcpHeaders() every run, so the id has to come from this
+  // file first or re-running would drop the header (#3772).
+  adoptExistingClientId(text);
   const rules = join(HOME, '.hermes', 'SOUL.md');
   if (!text) {
     need('Hermes：找不到 ~/.hermes/config.yaml → 先运行一次 hermes 再回来装');
@@ -1320,6 +2030,9 @@ async function installOpenclaw(bearer) {
   }
 
   const cfg = join(HOME, '.openclaw', 'openclaw.json');
+  const raw = readText(cfg);
+  // Same inheritance as the other JSON targets: the entry is rebuilt from mcpHeaders() (#3772).
+  adoptExistingClientId(raw);
   const data = readJson(cfg, null);
   if (data === null) {
     need(`OpenClaw：读不到或解析不了 ${cfg} → 先运行一次 openclaw 生成配置，`
@@ -1340,22 +2053,153 @@ 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 raw = readText(cfg);
+  // All five MCP-only targets share this path; adopt before spec.entry() builds mcpHeaders() (#3772).
+  adoptExistingClientId(raw);
+  const data = readJson(cfg, null);
+  if (data === null && raw) {
+    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}`);
+}
+
+/**
+ * MiniMax Code: write the plugin manifest, then the rules block in its global `AGENTS.md`.
+ *
+ * Two rules from the comment on `MCODE_PLUGIN_REL` drive the whole function:
+ *
+ *   * **the file may not be ours.** A plugin directory is a user-owned space, so an existing
+ *     manifest with a different `name` (or one that is not JSON) is *preserved* and reported as a
+ *     manual step — overwriting it would delete someone else's plugin to install ours.
+ *   * **`--mcp-only` is tier ①.** The manifest is the endpoint registration; `~/.minimax/AGENTS.md`
+ *     is a rules block (②), so it is skipped there — the same split every other target follows.
+ *
+ * Idempotent through `sameJson` (an editor that reorders keys is not a change) and through
+ * `adoptExistingClientId`, so a re-run without `--client-id` keeps the header the file already
+ * declares (#3772).
+ */
+async function installMcode(bearer) {
+  const plugin = mcodePluginPath(HOME);
+  const existing = readText(plugin);
+  // Before building the entry: a re-run must declare the id this manifest already carries.
+  if (existing) adoptExistingClientId(existing);
+  const wanted = mcodePluginDoc(bearer);
+
+  if (!existing) {
+    writeText(plugin, `${JSON.stringify(wanted, null, 2)}\n`);
+    ok(`MiniMax Code：写入插件清单 → ${plugin}`);
+  } else {
+    const current = readJson(plugin, null);
+    if (current === null) {
+      need(`MiniMax Code：${plugin} 不是合法 JSON → 已原样保留；请手动修正或删掉它，再重跑本命令`);
+      return;
+    }
+    if (current?.name !== 'misakanet') {
+      need(`MiniMax Code：${plugin} 已存在且不是本安装器写的（name=${JSON.stringify(current?.name ?? null)}）`
+        + ' → 已原样保留；要装 MisakaNet 请先把这个插件目录移走，再重跑本命令');
+      return;
+    }
+    if (sameJson(current, wanted)) {
+      ok('MiniMax Code：插件清单已是目标内容（无改动）');
+    } else {
+      backup(plugin);
+      writeText(plugin, `${JSON.stringify(wanted, null, 2)}\n`);
+      ok(`MiniMax Code：更新插件清单 → ${plugin}`);
+    }
+  }
+
+  const rules = join(HOME, MCODE_RULES_REL);
+  if (!MCP_ONLY) ok(`MiniMax Code：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+  else skip('MiniMax Code：规则块未写（--mcp-only：只放插件清单）');
+
+  // Said out loud for the same reason Cursor's and Gemini's layers are: an install that looks
+  // complete and has no behaviour layer is the failure this installer refuses to hide.
+  skip('MiniMax Code：没有 Claude Code 那种钩子（mcode 没有 hook 机制）'
+    + ' → 规则块在 ~/.minimax/AGENTS.md（每个会话生效），自动沉淀那一步做不到');
+  need('MiniMax Code：重启后跑 `mcode plugin list` 复核（应显示 misakanet@local enabled）；'
+    + '公司代理下还要设 NODE_USE_ENV_PROXY=1 —— 它的 HTTP MCP 发现预算约 2000ms，'
+    + '不设会表现为"装上了但 0 个工具"（`mcode plugin add` 报 LOCAL_PLUGIN_INSTALL_UNSUPPORTED '
+    + '不是失败，插件目录在位即为生效）');
+}
+
 // 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: 'ready' (a handshake), 'unverified' (timeout, or a
+  // proxy this Node cannot use — the tool could not answer) and 'not-ready' (unreachable, or HTTP
+  // answered without MCP — a real problem with the machine or the address). `unverified` is the
+  // one #3778 added: it is not READY, and it is not a machine verdict either.
+  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,
   // reported the rate-limit answer as "endpoint unreachable": the endpoint returns HTTP 200
   // with the error inside the JSON-RPC result, so a user who had used their quota was told their
   // network was broken (found 2026-09-15 by running the agent chain test on this machine).
-  const probe = await mcpRequest('tools/list', {}, 6000, probeEndpoint());
-  const tools = Array.isArray(probe?.tools) ? probe.tools : [];
-  lastProbe = { reachable: tools.length > 0, tools: tools.length };
-  if (tools.length) {
-    ok(`端点可达：${ENDPOINT}（MCP 握手成功，${tools.length} 个工具）`);
+  const { payload: probe, attempts, timeoutMs } = await probeHandshake();
+  const outcome = probeOutcome(probe);
+  const tools = outcome.state === 'ok' ? outcome.tools : 0;
+  lastProbe = { reachable: tools > 0, tools, note: outcome.state };
+  if (lastProbe.reachable) {
+    ok(`端点可达：${ENDPOINT}（MCP 握手成功，${tools} 个工具）`);
 
     // Surface the permission gap: an install that is otherwise perfect still fails the user's first
     // search if the host refuses the tool call, and that is invisible from the config files alone.
@@ -1364,18 +2208,65 @@ 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)) {
+  } else if (outcome.state === 'non-mcp') {
     allOk = false;
-    need(`端点可达但握手异常：${JSON.stringify(probe).slice(0, 120)}`);
+    usable = false;
+    probeState = 'not-ready';
+    // What came back, not `{}`: `200 {"hello":"world"}` is the shape that used to be reported as
+    // "unreachable" and send the reader after a network that was working the whole time.
+    need(`端点可达但响应不是 MCP（${lastResponsePreview || JSON.stringify(probe).slice(0, 160)}）`
+      + ' → 地址指错了，或中间有网关/门户在应答；读课程会静默失败'
+      + (lastRequestError ? `；最近一次失败原因：${lastRequestError}` : ''));
+  } else if (outcome.state === 'timeout') {
+    // Timeout is "could not verify", full stop. It is never folded into the proxy story (that is
+    // a different doubt) and never into "unreachable" (that is a claim we cannot make): the exit
+    // code for it is 2, and 2 is not a machine verdict (#3778).
+    allOk = false;
+    usable = false;
+    probeState = 'unverified';
+    need(`端点探测超时：${ENDPOINT}（${attempts} 次尝试，每次 ${timeoutMs}ms；`
+      + `最近一次失败原因：${lastRequestError || `timeout after ${timeoutMs}ms`}）`
+      + ' → 这不说明机器坏了，是工具没能拿到答案；先确认网络/代理'
+      + '（`curl -sS https://misakanet.org/mcp`），再重跑 --verify');
+  } else if (outcome.state === 'inconclusive-proxy') {
+    // Inconclusive rather than unreachable — and now a hard "could not verify" in every mode, not
+    // only under `--strict`: the old interactive path exited 0 while printing "the probe is
+    // untrustworthy", which is a READY a script cannot tell from a healthy machine (#3778).
+    allOk = false;
+    usable = false;
+    probeState = 'unverified';
+    need(`端点探测不可信（inconclusive-proxy —— 最近一次失败原因：`
+      + `${lastRequestError || '没有收到响应'}）：${proxyProbeAdvice(outcome.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 };
+  // Zero targets (#3778). This is the honest answer to "is the install complete": there was
+  // nothing to install into, so nothing was installed. The old code only ever called
+  // `installFailed()` inside the per-agent checks, so with no agent at all not one line ran and
+  // `install: complete` / `verify: READY` were reported for an untouched home — the exact
+  // self-contradiction the issue was filed for (`detected-agents: []` next to
+  // `install-complete: complete`). Judged on "no target in AGENTS is detected", not on one
+  // hard-coded directory: any of the supported assistants in `AGENTS` counts.
+  const detectedAgents = AGENTS.filter((agent) => detect(agent));
+  if (!detectedAgents.length) {
+    installFailed();
+    need('没有检测到任何受支持的助手 —— 因此什么都没装'
+      + `（支持：${supportedAgentLabels()}）→ 先打开一次你要用的那个助手，再回来运行本命令`);
+  }
   const tokenFile = join(stateDir(), 'token');
   let tokenPresent = '';
   try {
@@ -1386,43 +2277,72 @@ 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 {
+        const verdict = mcpEntryState(entry, 'url');
+        if (verdict.state === 'wrong-url') {
+          installFailed();
+          need(`Claude Code：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`);
+        } else if (verdict.state === 'no-url-field') {
+          installFailed();
+          need(`Claude Code：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`);
+        } else {
+          ok(`Claude Code：MCP 已注册（${verdict.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 +2351,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 +2378,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 +2401,144 @@ async function verify() {
       skip('Hermes：本进程只能确认"配置已写"，无法确认 Hermes 是否已加载 → 可用 hermes mcp list 复核');
     }
   }
+  // Codex and codewhale: reported only when the user has them, like every other target. They were
+  // the two gaps in the integrity check (measured 2026-10-23): `--verify` had no row for them at
+  // all, so a machine whose Codex entry pointed at `https://BROKEN.invalid/mcp` and whose rules
+  // block had lost its markers still reported READY with exit code 0 — while `--report`'s
+  // `detected-agents` listed codex and codewhale as present, and the gate let it through.
+  if (detect('codex')) {
+    const rules = join(HOME, '.codex', 'AGENTS.md');
+    if (!readText(rules).includes(`<!-- ${START} -->`)) {
+      installFailed();
+      need(canCreateHere(rules)
+        ? `Codex：规则块没装（${rules}）→ 重跑安装命令`
+        : `Codex：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
+    } else {
+      ok('Codex：规则块已装');
+    }
+    const cfg = join(HOME, '.codex', 'config.toml');
+    const toml = readText(cfg);
+    const table = codexMisakanetTable(toml);
+    const verdict = mcpEntryState(table, 'url');
+    if (verdict.state === 'missing') {
+      installFailed();
+      need(canCreateHere(cfg)
+        ? `Codex：MCP 未注册（${cfg}）→ 重跑安装命令`
+        : `Codex：MCP 未注册（${cfg}）→ ${unwritableAdvice()}`);
+    } else if (verdict.state === 'wrong-url') {
+      installFailed();
+      need(`Codex：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`);
+    } else if (verdict.state === 'no-url-field') {
+      installFailed();
+      need(`Codex：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`);
+    } else {
+      ok(`Codex：MCP 已注册（${verdict.url}）`);
+    }
+    // The top-level key is what makes Codex speak streamable-http at all: without it the entry
+    // above is present and still unusable.
+    if (!hasTopLevelKey(toml, 'experimental_use_rmcp_client')) {
+      installFailed();
+      need(`Codex：config.toml 里没有顶级键 experimental_use_rmcp_client（${cfg}）`
+        + '→ Codex 连不上 streamable-http，重跑安装命令即可补上');
+    }
+  }
+  if (detect('codewhale')) {
+    const cfg = join(HOME, '.codewhale', 'mcp.json');
+    const entry = (readJson(cfg, null) || {}).servers?.misakanet;
+    const verdict = mcpEntryState(entry, 'url');
+    if (verdict.state === 'missing') {
+      installFailed();
+      need(canCreateHere(cfg)
+        ? `codewhale：MCP 未注册（${cfg}）→ 重跑安装命令`
+        : `codewhale：MCP 未注册（${cfg}）→ ${unwritableAdvice()}`);
+    } else if (verdict.state === 'wrong-url') {
+      installFailed();
+      need(`codewhale：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`);
+    } else if (verdict.state === 'no-url-field') {
+      installFailed();
+      need(`codewhale：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`);
+    } else {
+      ok(`codewhale：MCP 已注册（${verdict.url}）`);
+    }
+    // Its rules blocks live in the projects it trusts, so that is where they are checked.
+    for (const project of codewhaleProjects()) {
+      const rules = join(project, 'AGENTS.md');
+      if (!readText(rules).includes(`<!-- ${START} -->`)) {
+        installFailed();
+        need(`codewhale：规则块没装（${rules}）→ 重跑安装命令`);
+      } else {
+        ok(`codewhale：规则块已装（${rules}）`);
+      }
+    }
+  }
+  // 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 {
+      const verdict = mcpEntryState(entry, spec.urlField);
+      if (verdict.state === 'no-url-field') {
+        installFailed();
+        need(`${spec.label}：MCP 条目在，但没有 ${spec.urlField} 字段（${cfg}）→ 重跑安装命令；`
+          + `这家用的是 ${spec.urlField}${spec.container === 'mcp' ? '（注意嵌套在 mcp 而不是 mcpServers 下）' : ''}`);
+      } else if (verdict.state === 'wrong-url') {
+        installFailed();
+        need(`${spec.label}：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`);
+      } else {
+        ok(`${spec.label}：MCP 已注册（${verdict.url}）`);
+        skip(`${spec.label}：只能确认"配置已写"，无法确认它是否已加载 → ${spec.verifyHint}`);
+      }
+    }
+  }
+  // MiniMax Code: a plugin directory + a rules file, so "installed" is two facts and both are
+  // checked. The manifest has to be valid JSON with our entry at the right URL; a file that a
+  // hand-edit turned into `{}` is exactly the state a re-run fixes. `mcode plugin add` refuses
+  // local plugins on purpose (LOCAL_PLUGIN_INSTALL_UNSUPPORTED), so its exit code is not evidence
+  // either way — the directory is, and that is what this reads.
+  if (detect('mcode')) {
+    const rules = join(HOME, MCODE_RULES_REL);
+    if (!readText(rules).includes(`<!-- ${START} -->`)) {
+      installFailed();
+      need(canCreateHere(rules)
+        ? `MiniMax Code：规则块没装（${rules}）→ 重跑安装命令`
+        : `MiniMax Code：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
+    } else {
+      ok('MiniMax Code：规则块已装');
+    }
+    const plugin = mcodePluginPath(HOME);
+    const doc = readJson(plugin, null);
+    if (doc === null) {
+      installFailed();
+      need(canCreateHere(plugin)
+        ? `MiniMax Code：插件清单缺失或不是合法 JSON（${plugin}）→ 重跑安装命令`
+        : `MiniMax Code：插件清单装不了（${plugin}）→ ${unwritableAdvice()}`);
+    } else {
+      const verdict = mcpEntryState(doc.mcpServers?.misakanet, 'url');
+      if (verdict.state === 'missing') {
+        installFailed();
+        need(`MiniMax Code：插件清单里没有 mcpServers.misakanet（${plugin}）→ 重跑安装命令`);
+      } else if (verdict.state === 'no-url-field') {
+        installFailed();
+        need(`MiniMax Code：插件清单里的条目没有 url 字段（${plugin}）→ 重跑安装命令`);
+      } else if (verdict.state === 'wrong-url') {
+        installFailed();
+        need(`MiniMax Code：插件清单指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${plugin}）`
+          + '→ 重跑安装命令');
+      } else {
+        ok(`MiniMax Code：插件清单已注册（${verdict.url}）`);
+        skip('MiniMax Code：只能确认"插件目录在位"，无法确认 mcode 是否已加载 → 跑 `mcode plugin list` 复核'
+          + '（`mcode plugin add` 报 LOCAL_PLUGIN_INSTALL_UNSUPPORTED 不是失败）');
+      }
+    }
+  }
   // 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 +2561,106 @@ async function verify() {
         + 'npx @misaka-net/misakanet-setup@latest');
     }
   }
-  return allOk;
+  return {
+    allOk,
+    usable,
+    probeState,
+    // `true` only for the probe answers that are not a verdict about the machine (timeout, and a
+    // proxy this Node cannot use). It is what turns the exit code from 1 into 2 (#3778).
+    unverified: probeState === 'unverified',
+    // A home with none of the supported targets: distinct from "detected, but our files are missing",
+    // and the only case where `install-scope` is forced to `none` in the report.
+    zeroTargets: !detectedAgents.length,
+    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 === 'unverified') {
+    // The third answer (#3778): neither READY nor a machine verdict. Saying "NOT READY" here is
+    // the false alarm the issue is about; saying "ready" is a lie a script cannot detect.
+    return '没能验证 —— 探测超时或代理不可信（不等于端点不可达，也不等于机器不健康）';
+  }
+  if (verdict.probeState === 'not-ready') {
+    // "unreachable" and "answered, but not MCP" are both not-ready and still different facts:
+    // the second one means the address or something in front of it is wrong, and telling the
+    // reader "端点不可达" about a host that just answered would send them to the wrong fix.
+    return lastProbe.note === 'non-mcp'
+      ? '不就绪 —— 端点有应答，但响应不是 MCP（地址指错，或中间有网关/门户）'
+      : '不就绪 —— 端点不可达或握手异常';
+  }
+  if (!verdict.usable) return '不就绪 —— 端点可达，但只读工具没放行，第一次检索会被拦下';
+  return '就绪 —— 端点可达，检索与读取可用';
+}
+
+function installText(verdict) {
+  if (verdict.zeroTargets) {
+    return '不完整 —— 没有检测到任何受支持的助手，因此什么都没装';
+  }
+  if (verdict.install === 'complete') return '完整 —— 我们偏好的文件都写好了';
+  return `不完整 —— ${verdict.openItems} 项需要手动处理（上面每条 ! 都给了成因和做法）`;
+}
+
+/**
+ * The three-code contract, in one place so `--verify` and `--report --strict` cannot disagree.
+ *
+ *   0  READY
+ *   1  NOT READY — a machine problem (zero targets, our files missing, the endpoint really
+ *      unreachable, or an address that does not speak MCP)
+ *   2  could not verify — the tool could not produce a machine verdict (a probe timeout, a proxy
+ *      this Node cannot use, or the report/CLI crashing outright)
+ *
+ * `2` outranks `1` only when *nothing else* is wrong: if the install segment is incomplete, that
+ * is a real machine verdict regardless of what the probe managed to do, and it stays `1`. That is
+ * why the check is `install === 'complete'` rather than `!allOk`.
+ */
+function exitCodeFor(verdict) {
+  if (verdict.allOk && verdict.openItems === 0) return 0;
+  return (verdict.unverified && verdict.install === 'complete') ? 2 : 1;
+}
+
+/**
+ * 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 +2717,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;
@@ -1587,7 +2755,7 @@ function restoreEmptiedFiles() {
 }
 
 function uninstall() {
-  for (const rel of ['.claude/CLAUDE.md', '.codex/AGENTS.md', '.hermes/SOUL.md']) {
+  for (const rel of ['.claude/CLAUDE.md', '.codex/AGENTS.md', '.hermes/SOUL.md', '.minimax/AGENTS.md']) {
     if (stripBlock(join(HOME, rel))) ok(`移除规则块 → ${rel}`);
   }
   // Both candidates: a block may have been written before the workspace was read from config.
@@ -1617,6 +2785,26 @@ 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}`);
+    }
+  }
+  // MiniMax Code's plugin directory is ours outright (the install creates it), so uninstall takes
+  // the whole subtree back. Only *our* directory: `~/.minimax/plugins/` is the user's namespace and
+  // stays even when it ends up empty — deleting it would remove a place their other plugins live.
+  const mcodeDir = join(HOME, '.minimax', 'plugins', 'misakanet');
+  if (existsSync(mcodeDir)) {
+    try {
+      if (!DRY) rmSync(mcodeDir, { recursive: true, force: true });
+      ok(`移除插件目录 → ${mcodeDir}`);
+    } catch { /* best effort */ }
+  }
   const voiceDir = join(stateDir(), 'voice');
   if (existsSync(voiceDir)) {
     try {
@@ -1657,14 +2845,25 @@ function uninstall() {
     for (const [s, e] of [[START, END], [TOP_START, TOP_END]]) {
       text = text.replace(new RegExp(`^[ \\t]*#\\s*${s}\\s*$\\n?[\\s\\S]*?^[ \\t]*#\\s*${e}\\s*$\\n?`, 'm'), '');
     }
-    if (text && text !== before) {
+    if (text !== before) {
+      // `text &&` used to guard this write, and that guard is the bug: when our blocks were the
+      // *only* thing in the file, removing them left an empty string, the guard said no, and the
+      // file was left exactly as it was — so the MCP entry survived the uninstall while the output
+      // said "已移除本安装器写入的内容（MCP 注册…）" (measured 2026-10-23). An empty file that is
+      // ours to remove goes away with the blocks; the rule the rules-block path already follows.
       backup(toml);
-      writeText(toml, text);
-      ok(`移除 MCP 表 → ${toml}`);
+      if (!text.trim()) {
+        if (!DRY) rmSync(toml, { force: true });
+        ok(`移除 MCP 表（文件里只剩我们的内容 → 一并删除）→ ${toml}`);
+      } else {
+        writeText(toml, text);
+        ok(`移除 MCP 表 → ${toml}`);
+      }
     }
   }
   if (readText(join(stateDir(), 'token')) || readText(join(stateDir(), 'hook.mjs'))
-    || readText(join(stateDir(), 'client_id')) || readText(join(stateDir(), STATE_VERSION_FILE))) {
+    || readText(join(stateDir(), 'client_id')) || readText(join(stateDir(), STATE_VERSION_FILE))
+    || readText(join(stateDir(), STATE_ENDPOINT_FILE))) {
     if (!DRY) rmSync(stateDir(), { recursive: true, force: true });
     ok(`删除状态目录 → ${stateDir()}`);
   }
@@ -1772,7 +2971,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,16 +2992,32 @@ 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],
+    // The classification of the probe, and the field that says whether the boolean above means
+    // anything (#3778). `ok` = handshake succeeded; `timeout` / `inconclusive-proxy` = the tool
+    // could not answer (exit 2 — network or proxy, not a verdict about this machine);
+    // `unreachable` / `non-mcp` = it did answer, and the answer is "this machine cannot read".
+    ['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'))
-      ? 'full'
-      : (AGENTS.some((agent) => detect(agent) && mcpEntryPresent(agent)) ? 'mcp-only' : 'none')],
+    // from "nothing installed" and must not be counted as one (#1753's T1-lite rows). Zero
+    // targets is always `none`, even if a stale state directory still holds a hook: with no agent
+    // to consume it, nothing is installed (#3778).
+    ['install-scope', agents.length === 0
+      ? 'none'
+      : (hookWired()
+        ? 'full'
+        : (agents.some((agent) => mcpEntryPresent(agent)) ? 'mcp-only' : 'none'))],
     ['voice', voiceStatus()],
     ['open-items', manual.length],
     // Redacted here, once, so neither encoder can print an unredacted message by accident.
@@ -1876,10 +3092,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 ─────────────────────────────────────────────────────────────
@@ -1943,7 +3159,12 @@ if (mode === 'report') {
   //                               follow the verdict** — that breaks every existing use, and the
   //                               gated form below already exists for CI.
   //   --report --strict (--ci)  → 0 READY · 1 NOT READY (including `open-items > 0`) ·
-  //                               2 the report could not be produced at all.
+  //                               2 could not verify (a probe timeout / a proxy this Node cannot
+  //                               use) or the report could not be produced at all.
+  //
+  // The two meanings of 2 are one sentence: "the tool could not answer". The report still prints
+  // first in the probe case — `endpoint-probe` says `timeout` / `inconclusive-proxy` — so CI has
+  // the evidence and the code together (#3778). `--verify` uses the same three codes.
   //
   // `--report-json` is the same mode, same contracts, same codes, other encoding: the JSON is
   // printed even when the machine is NOT READY — that is precisely the state an MDM is collecting
@@ -1970,22 +3191,38 @@ if (mode === 'report') {
     process.exit(2);
   }
   if (!STRICT) process.exit(0);
-  const ready = verdict.allOk && verdict.openItems === 0;
-  if (!ready) {
+  const code = exitCodeFor(verdict);
+  if (code === 2) {
+    // The report is already on stdout. This line says what the code means, because "2" here is
+    // not "unhealthy" and not "the tool crashed": it is "the probe could not answer".
+    console.error(`--strict：没能验证（endpoint-probe: ${lastProbe.note}）→ 退出码 2；`
+      + `上面的 ${REPORT_JSON ? 'JSON' : 'YAML'} 已经照常打印，这个码说的是网络/代理，不是机器坏了。`);
+  } else if (code === 1) {
     console.error(`--strict：NOT READY（verify: ${verdict.allOk ? 'READY' : 'NOT READY'}，`
       + `open-items: ${verdict.openItems}）→ 退出码 1；上面的 ${REPORT_JSON ? 'JSON' : 'YAML'} 就是证据。`);
   }
-  process.exit(ready ? 0 : 1);
+  process.exit(code);
 }
 
 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);
+  //
+  // Three conclusions for three answers (#3778): READY, NOT READY (a machine problem), and
+  // "could not verify" — which used to exit 0 while saying the probe was untrustworthy, so a
+  // script could not tell it from a healthy machine.
+  const code = exitCodeFor(verdict);
+  const conclusion = code === 0
+    ? `READY —— 打开一个新会话，问它「${ONBOARDING_QUERIES[0]}」这类带报错原文的片段`
+    : code === 2
+      ? '没能验证 —— 端点探测超时或代理不可信（看 endpoint-probe）；这不是"机器不健康"，'
+        + '先解决网络/代理再重跑 --verify'
+      : 'NOT READY —— 上面每条 ! 都给了成因和做法';
+  console.log(`\n结论：${conclusion}`);
+  process.exit(code);
 }
 
 const targets = (only.length ? only : AGENTS).filter((a) => {
@@ -2032,38 +3269,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}`);
   }
@@ -2072,19 +3283,49 @@ if (LIST_WRITES) {
     console.log('# --mcp-only：只申请 ①。规则块（②）与钩子（③）不会写入，'
       + '需要时由运营方另行批准后重跑不带 --mcp-only 的同一条命令。');
   } else {
-    console.log(`# 本次申请 ${shown.size} 级权限（${[...shown].sort().map((t) => tiers[t]).join(' · ')}）；`
-      + '只想批 ① 就加 --mcp-only。');
+    // With no target detected the manifest is empty, and the old line printed `0 级权限（）` — an
+    // empty parenthesis where the answer should be (#3778). Say "none" and why.
+    const asked = shown.size
+      ? `${shown.size} 级权限（${[...shown].sort().map((t) => tiers[t]).join(' · ')}）`
+      : '0 级权限（无 —— 没有检测到任何受支持的助手，这次不会写任何文件）';
+    console.log(`# 本次申请 ${asked}；只想批 ① 就加 --mcp-only。`);
   }
   console.log('# 这次没有写任何东西。撤销：npx @misaka-net/misakanet-setup --uninstall');
   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 的配置目录 → 请先打开一次你要用的那个助手，再回来运行本命令');
+    // The list comes from `AGENTS` (#3778): it used to name six assistants by hand while ten were
+    // supported, so a Gemini/Copilot/OpenCode/Kiro user was told about a smaller product than the
+    // one they had just run — and the `--verify` path said nothing at all.
+    need('没有检测到任何受支持的助手 —— 因此什么都没装'
+      + `（支持：${supportedAgentLabels()}）→ 先打开一次你要用的那个助手，再回来运行本命令`);
   } else {
-    const hookPath = MCP_ONLY ? null : await installHook();
-    if (!MCP_ONLY) stampVersion();
+    // 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();
+    // Tier ③ only: the record lives in the state directory, and `--mcp-only` must not create it.
+    // Without a record, `--verify` falls back to the env override and then to the canonical
+    // endpoint — which is the older behaviour, and the only place a mirrored install can be
+    // reported as broken (verify with the same MISAKANET_ENDPOINT it was installed with).
+    if (!MCP_ONLY) {
+      stampVersion();
+      stampEndpoint();
+    }
     const bearer = has('--no-register') ? '' : await ensureIdentity();
     for (const agent of targets) {
       // One target failing must not skip the rest: an uncaught throw used to abort the loop, so
@@ -2104,6 +3345,8 @@ 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 (agent === 'mcode') await installMcode(bearer);
+        else if (MCP_ONLY_TARGETS[agent]) await installMcpOnly(agent, bearer);
         installed += 1;
       } catch (err) {
         need(`${agent}：写入配置失败（${redact((err && err.message) || err)}）`
@@ -2122,6 +3365,15 @@ try {
 // the exact failures in it on a dirty one — which is the point (#1784). The machine-readable form
 // of the same run is `--report-json`, not this text.
 say(render());
+if (!SILENT && !DRY) {
+  // The number the reader actually wants: not "how many files are in scope" but "how many did
+  // this run really change". Printed even when it is 0, which is the honest answer on an
+  // already-installed machine and the one #3775 was filed about: the line used to appear only
+  // when something was written, so "already installed" and "the installer never got this far"
+  // looked identical. `--dry-run` keeps its own contract — it already says it would write
+  // nothing, so a "0 files written" line under it would only restate the mode.
+  console.log(`本次实际写入 ${writtenFiles.size} 个文件（上面的清单是"涉及哪些"，这一行是"真的动了哪些"）。`);
+}
 if (MCP_ONLY && !SILENT) {
   // The honest failure mode of tier ①, said where the user will read it: they are not installing a
   // behaviour. The rules block (②) and the first-turn announcement, which is injected by the hook