@misaka-net/misakanet-setup 0.7.1 → 0.8.1

package/bin/misakanet-setup.mjs

@@ -25,7 +25,7 @@
  * Everything is idempotent, every rewritten file is backed up to *.misakanet.bak, and
  * --uninstall removes exactly what was added (same markers), leaving user config intact.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFileSync, rmSync,
+import { existsSync, mkdirSync, readFileSync, readdirSync, copyFileSync, rmSync,
          chmodSync, statSync, renameSync, accessSync, constants,
          openSync, writeSync, fsyncSync, closeSync } from 'node:fs';
 // No child_process import on purpose: this installer must never hand a file-derived value to
@@ -77,6 +77,24 @@ const valueOf = (flag, dflt) => {
   return i >= 0 && args[i + 1] ? args[i + 1] : dflt;
 };
 const only = valueOf('--only', '').split(',').map((s) => s.trim()).filter(Boolean);
+
+/**
+ * `--client <id>`: judge **one** client only (issue #3699).
+ *
+ * The checks in `verify()` are per client — each block reads one assistant's own files — but the
+ * verdict was per machine: on a machine with three assistants, one broken assistant condemned all
+ * three, and a healthy one was indistinguishable from a broken one (#3696). The question a
+ * multi-client machine actually asks is "how is *the one I use*", so this flag answers exactly
+ * that: the other clients are not checked, not printed, and not counted.
+ *
+ * Not to be confused with `--client-id`, which pins this machine's pseudonym and has nothing to do
+ * with the assistants.
+ */
+const CLIENT = valueOf('--client', '').trim().toLowerCase();
+
+/** Should this client's checks run? A `--client` filter narrows the whole run down to one. */
+const wantClient = (id) => !CLIENT || CLIENT === id;
+
 const DRY = has('--dry-run');
 /**
  * Permission tiers (2026-09-18).
@@ -116,12 +134,34 @@ const HOME = resolve(valueOf('--home', homedir()));
 const AGENTS = ['claude', 'codex', 'hermes', 'openclaw', 'codewhale',
                 'cursor', 'gemini', 'copilot', 'opencode', 'kiro', 'mcode'];
 
+/**
+ * The three line lists, and what every line knows about itself.
+ *
+ * A line knows the **client** it is about, and a failure knows its **kind** — what is wrong, which
+ * is what decides the fix (issue #3699). The checks in `verify()` are per client (each block reads
+ * one assistant's own files), but the output could only say "this machine is ready": a machine with
+ * three assistants was condemned because of the one the user never touches, and a healthy assistant
+ * was indistinguishable from a broken one (#3696, #3699).
+ *
+ * The kinds:
+ *   'blocked' — we cannot write there. A re-run writes exactly as much as the last one did, so
+ *               "re-run the install" is not the advice (measured 2026-10-22 on an OpenClaw machine
+ *               whose workspace was root-owned and read-only — see `unwritableAdvice`).
+ *   'absent'  — our footprint is not there at all. A re-run puts it there.
+ *   'broken'  — our footprint is there but wrong (wrong endpoint, missing field). A re-run fixes it.
+ *
+ * The client id is '' for a line that is about the machine rather than about one client: the
+ * endpoint probe, the token, the version stamp.
+ */
 const done = [];
 const manual = [];
 const skipped = [];
-const ok = (m) => done.push(m);
-const need = (m) => manual.push(m);
-const skip = (m) => skipped.push(m);
+const ok = (m, client = '') => done.push({ text: m, client });
+const need = (m, client = '', kind = '') => manual.push({ text: m, client, kind });
+const skip = (m, client = '') => skipped.push({ text: m, client });
+
+/** The display name of a client id — `AGENT_LABELS`, with the id as the fallback. */
+const clientLabel = (id) => AGENT_LABELS[id] || id;
 
 function readJson(path, fallback) {
   try {
@@ -157,7 +197,7 @@ function readText(path) {
  * 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.7.1'  // x-release-please-version
+const VERSION = '0.8.1'  // x-release-please-version
 
 /**
  * The shape of a client id, in one place.
@@ -181,6 +221,7 @@ const REFERRAL_SHAPE = /^[A-Za-z0-9]{4,16}$/
 const FLAGS = [
   ['--home <dir>', '把配置写到这个目录，而不是真实家目录（不是沙箱：--uninstall 也认这个目录）'],
   ['--only <a,b>', `只处理列出的助手（${AGENTS.join(' / ')}）`],
+  ['--client <id>', `只检查这一个客户端（${AGENTS.join(' / ')}）——只判它，不判整台机器`],
   ['--dry-run', '只说不做：打印会改哪些文件，不写任何东西'],
   ['--silent', '只压掉进度叙述，绝不压掉 ! 行与报告（MDM/GPO 用）'],
   ['--report', '打印一段可公开粘贴的脱敏状态报告（人读 YAML）'],
@@ -198,7 +239,7 @@ const FLAGS = [
   ['--help, -h', '打印这份帮助并退出'],
   ['--version', '打印版本并退出'],
 ];
-const VALUE_FLAGS = ['--home', '--only', '--client-id'];
+const VALUE_FLAGS = ['--home', '--only', '--client-id', '--client'];
 
 function printHelp() {
   console.log(`MisakaNet 安装程序 ${VERSION}
@@ -574,16 +615,27 @@ function buildWriteManifest(agents) {
   // 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');
+    // make the manifest — and the preview's file count — promise a file that stays absent. Even on
+    // a registering run it is only written *if the network lets the registration through*, so the
+    // row says so instead of presenting it as a file this run will certainly create (#3833).
+    if (!has('--no-register')) {
+      add(join(stateDir(), 'token'), 'create (0600，取决于注册是否成功)', 1, 'token');
+    }
     if (!MCP_ONLY) {
+      // `hook.mjs` is the *Claude Code* hook's body: `installHook()` runs only when `claude` is one
+      // of the targets. Listing it for mcode/codex/… promised a file those installs never write —
+      // in the same run that said "没有 Claude Code 那种钩子" (measured 2026-10-25, #3833).
+      if (agents.includes('claude')) add(join(stateDir(), 'hook.mjs'), 'create', 3, 'hookScript');
       // 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');
     }
+    // The pseudonym is persisted only on a run that has to mint one (#3832) — so the manifest
+    // names that file only then, keeping the "every path exists afterwards" rule. Tier ① like the
+    // token: `ensureIdentity()` writes both, and `--mcp-only` still registers.
+    if (willMintClientId()) add(join(stateDir(), CLIENT_ID_FILE), 'create', 1, 'clientId');
   }
   return [...rows.values()]
     .filter((row) => (MCP_ONLY ? row.tier === 1 : true))
@@ -616,10 +668,13 @@ function writePreview(rows) {
     grants: '只读工具放行',
     rules: '规则块（会改变 agent 的行为）',
     hook: '钩子',
-    token: 'MCP 凭据',
+    // The token is written only when the anonymous registration succeeds, so the preview says so
+    // rather than counting it as a file this run will certainly create (#3833).
+    token: 'MCP 凭据（取决于注册是否成功）',
     endpoint: '端点记录',
     hookScript: '钩子脚本',
     version: '版本戳',
+    clientId: '身份编号',
     state: '本机状态',
   };
   const width = Math.min(Math.max(...list.map((f) => f.path.length)) + 2, 32);
@@ -827,7 +882,11 @@ function stripBlock(path, block = PROMPT_BLOCK) {
   return true;
 }
 
-const stateDir = () => join(HOME, '.misakanet-agent');
+// The hook already reads MISAKANET_AGENT_DIR (checkpoint_reminder.mjs), so honouring it here is
+// what lets an install work on a machine whose HOME is not writable for the runtime user (#3701):
+// writes and --verify then agree on the same directory instead of failing to mkdir under HOME.
+// Kept unresolved on purpose — the hook does not resolve it either, so both ends read one path.
+const stateDir = () => process.env.MISAKANET_AGENT_DIR || join(HOME, '.misakanet-agent');
 
 /**
  * The headers every MCP entry we write carries.
@@ -923,6 +982,91 @@ function adoptExistingClientId(text) {
   clientIdHint = found;
 }
 
+/** The state file that pins this machine's pseudonym, so `--verify`-able identity survives a run. */
+const CLIENT_ID_FILE = 'client_id';
+
+/** The id `--client-id` / `MISAKANET_CLIENT_ID` asks for, shape-checked, or `''`. */
+function explicitClientId() {
+  const value = (valueOf('--client-id', '') || process.env.MISAKANET_CLIENT_ID || '').trim();
+  return CLIENT_ID_SHAPE.test(value) ? value : '';
+}
+
+/** The id `<stateDir>/client_id` pins, or `''` — shape-checked, because a file wrote it. */
+function storedClientId() {
+  const found = readText(join(stateDir(), CLIENT_ID_FILE)).trim();
+  return CLIENT_ID_SHAPE.test(found) ? found : '';
+}
+
+/**
+ * The pseudonym *any* config on this machine already declares, or `''`.
+ *
+ * "Which config" cannot be "the one this run is about to rewrite". A machine that installed one
+ * target and then installed a second wrote the second config with no `X-MisakaNet-Client` at all:
+ * `ensureIdentity()` returned early (the token existed), it never set `knownClientId`, and the
+ * per-target adopters only look at their own file (issue #3832, hole 1). Every surface this
+ * installer writes is a candidate, walked in `AGENTS` order so the answer is deterministic.
+ */
+function clientIdOnMachine() {
+  for (const agent of AGENTS) {
+    for (const path of (AGENT_WRITE_PATHS[agent] || (() => []))(HOME)) {
+      const found = readText(path).match(CLIENT_ID_IN_CONFIG)?.[1] || '';
+      if (CLIENT_ID_SHAPE.test(found)) return found;
+    }
+  }
+  return '';
+}
+
+/**
+ * Will this run have to mint the pseudonym, and therefore persist it?
+ *
+ * Asked by the write manifest so the preview names `<stateDir>/client_id` only when the run is
+ * really going to create it (#3832) — the same "every path must exist afterwards" rule the rest of
+ * the manifest follows. Mirrors `clientIdForThisRun()`: nothing explicit, nothing pinned, nothing
+ * to adopt → a mint (and a write).
+ */
+function willMintClientId() {
+  if (has('--no-register')) return false;
+  return !explicitClientId() && !storedClientId() && !clientIdOnMachine();
+}
+
+/** Remember the id and show it to the user: it is a number worth keeping for a reinstall. */
+function rememberClientId(id) {
+  knownClientId = id;
+  clientIdHint = id;
+  return id;
+}
+
+/**
+ * Resolve `X-MisakaNet-Client` for a run that is *not* given an explicit id (#3832).
+ *
+ * Three sources, in order of how much the machine means them:
+ *   1. `<stateDir>/client_id` — what a previous run pinned;
+ *   2. any config that already declares one — the file *is* the record (#3772's rule, widened from
+ *      "the file I am about to rewrite" to "the machine");
+ *   3. nothing — mint `setup-<uuid>` and **persist it**, so the next run has something to reuse.
+ *
+ * Persisting is the part #1688 deliberately removed, and the tradeoff is worth stating: #1688
+ * dropped it because "read a local file, put the value in an outbound request" is the shape CodeQL
+ * js/file-access-to-http (#268) flags, and the value is sent to a server. This file holds nothing
+ * secret — it is a pseudonym the installer itself minted, shape-checked on read (`CLIENT_ID_SHAPE`),
+ * and the server treats it as a hint, never as identity (AGENTS.md §3.3). Against that, *not*
+ * persisting it means every failed registration mints a new id, rewrites the user's agent config
+ * with it and leaves a backup behind — measurably wrong on the re-run path the installer tells the
+ * user to walk ("稍后重跑本命令就能拿到 token"). One pinned pseudonym beats five unregistered
+ * ones, so #3832 records the tradeoff here and keeps the file.
+ */
+function clientIdForThisRun() {
+  if (knownClientId) return knownClientId;
+  const stored = storedClientId();
+  if (stored) return rememberClientId(stored);
+  const adopted = clientIdOnMachine();
+  if (adopted) return rememberClientId(adopted);
+  const minted = `setup-${randomUUID()}`;
+  rememberClientId(minted);
+  writeText(join(stateDir(), CLIENT_ID_FILE), `${minted}\n`);
+  return minted;
+}
+
 const CANONICAL_ENDPOINT = 'https://misakanet.org/mcp';
 
 /**
@@ -954,6 +1098,35 @@ function expectedEndpoint() {
   return CANONICAL_ENDPOINT;
 }
 
+/**
+ * The endpoint URL in a Hermes config's `mcp_servers.misakanet` entry.
+ *
+ * Hermes' config is YAML and this installer has no YAML parser, so the URL is read the way it is
+ * written: the `url:` line of the `misakanet:` block. Both shapes put it there — the block this
+ * installer writes (marked with the comment pair) and the bare entry a user added through the
+ * Hermes CLI.
+ */
+function hermesMcpUrl(text) {
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const head = lines[i].match(/^([ \t]*)misakanet:/);
+    if (!head) continue;
+    const indent = head[1].length;
+    // The entry's own keys are indented deeper than the `misakanet:` line; the first line that is
+    // not ends the entry, and the next entry's `url:` must not be read as this one's.
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const line = lines[j];
+      if (!line.trim()) continue;
+      const lineIndent = line.match(/^[ \t]*/)[0].length;
+      if (lineIndent <= indent) break;
+      const url = line.match(/^[ \t]*url:[ \t]*(.+?)[ \t]*$/);
+      // The quotes are optional in YAML, and a user-added entry may well have them.
+      if (url) return url[1].replace(/^["']|["']$/g, '');
+    }
+  }
+  return '';
+}
+
 /**
  * One verdict for every MCP entry this installer writes.
  *
@@ -1072,6 +1245,40 @@ let lastResponseOk = false;
 // `--verify` can print is what actually came back (`{}` is not a diagnosis).
 let lastResponsePreview = '';
 
+// The server's retry horizon on the last response, in seconds, when it sent one: the `Retry-After`
+// response header (seconds or an HTTP-date), the standard shape `docs/index.html` already reads on
+// 429s. Per-request, so a horizon from an earlier call can never leak into a later failure's words.
+let lastRetryAfterSeconds = null;
+
+/** `Retry-After` → seconds. Both forms the header allows; anything else is "no horizon", not 0. */
+function retryAfterSeconds(headerValue) {
+  const raw = String(headerValue || '').trim();
+  if (!raw) return null;
+  if (/^\d+$/.test(raw)) return Number(raw);
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) return null;
+  return Math.max(0, Math.round((at - Date.now()) / 1000));
+}
+
+/**
+ * How long the server says to wait before re-running, when it says. The failure body's `retry_after`
+ * (seconds, HTTP `Retry-After` semantics) wins over the header, and neither is guessed: a server that
+ * stays silent gets no horizon sentence at all.
+ */
+function retryHorizonOf(result) {
+  const fromBody = result && (result.retry_after ?? result.retry_after_seconds);
+  const n = Number(fromBody);
+  if (Number.isFinite(n) && n > 0) return Math.round(n);
+  return lastRetryAfterSeconds;
+}
+
+/** "45 秒" / "15 分钟" / "2 小时" — the horizon in the words a person reads a clock in. */
+function humanWait(seconds) {
+  if (seconds < 60) return `${seconds} 秒`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)} 分钟`;
+  return `${Math.round(seconds / 3600)} 小时`;
+}
+
 async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
   const headers = {
     'Content-Type': 'application/json',
@@ -1087,6 +1294,7 @@ async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
   lastRequestKind = '';
   lastResponseOk = false;
   lastResponsePreview = '';
+  lastRetryAfterSeconds = null;
   try {
     const response = await fetch(urlOverride || ENDPOINT, {
       method: 'POST',
@@ -1098,6 +1306,9 @@ async function mcpRequest(method, params, timeoutMs = 6000, urlOverride = '') {
     // 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;
+    lastRetryAfterSeconds = retryAfterSeconds(
+      response.headers && typeof response.headers.get === 'function'
+        ? response.headers.get('Retry-After') : null);
     const payload = await response.json();
     lastResponsePreview = JSON.stringify(payload).slice(0, 160);
     if (payload && payload.error) {
@@ -1371,7 +1582,9 @@ async function installHook() {
   if (!DRY) {
     mkdirSync(stateDir(), { recursive: true });
     if (existing !== null) backup(hookPath);
-    writeFileSync(hookPath, bundled);
+    // `writeText`, not `writeFileSync`: the hook is a file this run wrote, so the closing count has
+    // to include it — and it must be replaced atomically like every other file here (#3833).
+    writeText(hookPath, bundled);
   }
   ok(isOurs
     ? `自动沉淀的钩子已更新（旧版备份为 ${hookPath}.misakanet.bak）→ ${hookPath}`
@@ -1399,22 +1612,23 @@ async function ensureIdentity() {
   }
   if (existing) {
     ok('已有匿名身份（token 已存在）');
+    // #3832 hole 1: this early return used to leave `knownClientId` empty, and the npm channel
+    // persisted nothing, so the *next* target's config was written with no `X-MisakaNet-Client` at
+    // all. Resolve the identity here too — nothing is registered this run, but the header still has
+    // to say who this machine is.
+    clientIdForThisRun();
     return existing;
   }
   if (DRY) {
     ok(`会注册匿名身份并把 token 写到 ${file}`);
     return '';
   }
-  // The client id is what makes a re-registration return the *same* node, so it has to come
-  // from somewhere the user owns rather than from a file this process found on disk: CodeQL
-  // js/file-access-to-http (#268) reads "read a local file, put it in an outbound request" as
-  // what it looks like, and it is right — the value may be ours, but the shape is the bug.
-  // An exported MISAKANET_CLIENT_ID is explicit intent (the same standard the hook applies to
-  // its token); otherwise this run mints one and prints it so the user can keep it.
-  // `--client-id` and `MISAKANET_CLIENT_ID` are the same explicit intent. The flag exists because
-  // the closing guidance told users to keep an identity and the only way to supply one was a shell
-  // export — an instruction a non-technical user cannot follow, and on Windows a different one.
-  const clientId = usable ? explicit : `setup-${randomUUID()}`;
+  // The client id is what makes a re-registration return the *same* node. It used to be minted
+  // fresh on every attempt that failed — held only in memory, so the re-run the installer asks for
+  // minted another, rewrote the user's config and left a backup (issue #3832, hole 2).
+  // `clientIdForThisRun()` pins the value in `<stateDir>/client_id`; its docstring records the
+  // #1688 vs CodeQL tradeoff that makes reading that file back acceptable.
+  const clientId = usable ? explicit : clientIdForThisRun();
   knownClientId = clientId;
   const referral = declaredReferral();
   const result = await mcpCall('misakanet_register', {
@@ -1442,8 +1656,15 @@ async function ensureIdentity() {
       : serverCode
         ? `服务端拒绝了这次注册（${serverCode}）`
         : `多半是网络（${lastRequestError || '没有收到响应'}）`;
+    // …and when the server says *how long* to wait, say that too instead of "稍后". The horizon is
+    // never guessed and never rounded into a promise: a server that sent none keeps the vague
+    // wording, because a made-up wait is the same lie as the network guess this replaced (issue
+    // #3511 — the retry-horizon half; the `code` half landed with #3512).
+    const horizon = retryHorizonOf(result);
     need(`匿名注册没成功：${cause} → 读课程不受影响，但写入类工具（write_lesson）现在用不了；`
-      + '稍后重跑本命令就能拿到 token'
+      + (horizon
+        ? `约 ${humanWait(horizon)}后重跑本命令就能拿到 token（服务端给出的重试窗口）`
+        : '稍后重跑本命令就能拿到 token')
       + (serverHint ? `（服务端提示：${serverHint}）` : ''));
     return '';
   }
@@ -1586,10 +1807,14 @@ async function installClaude(hookPath, bearer) {
       const destDir = join(stateDir(), 'voice');
       if (!DRY) {
         mkdirSync(destDir, { recursive: true });
+        // `copyFileSync` writes a file too, so these join `writtenFiles`: without it a `--voice`
+        // install under-reports its count the same way the version stamp did (#3833).
         copyFileSync(voice.player, join(destDir, 'voice-hook.mjs'));
+        writtenFiles.add(join(destDir, 'voice-hook.mjs'));
         const cues = existsSync(voice.cues) ? readdirSync(voice.cues).filter((f) => f.endsWith('.mp3')) : [];
         for (const cue of cues) {
           copyFileSync(join(voice.cues, cue), join(destDir, cue));
+          writtenFiles.add(join(destDir, cue));
         }
         if (!cues.length) {
           need('语音钩子：找到了播放器但没有找到音频文件 → 重装一次 npx 包即可（其它功能不受影响）');
@@ -1779,7 +2004,11 @@ function stampVersion() {
     installed_at: new Date().toISOString(),
   };
   mkdirSync(stateDir(), { recursive: true });
-  writeFileSync(file, `${JSON.stringify(stamp, null, 2)}\n`);
+  // `writeFileSync` here bypassed `writeText()`'s atomic replace *and* its `writtenFiles`
+  // bookkeeping, so every fresh install reported one file fewer than it had written (#3833) — and
+  // this was the one write path left without the truncation protection the rest of the installer
+  // went through.
+  writeText(file, `${JSON.stringify(stamp, null, 2)}\n`);
   ok(`版本戳 → ${file}（${VERSION}${existing?.version ? `，原 ${existing.version}` : ''}）`);
 }
 
@@ -2169,6 +2398,11 @@ function unwritableAdvice(manual = '') {
     : `只读或权限不足，重跑也写不进去 → ${fix}`;
 }
 
+// Claude Code is in use when its user-level config file exists — a stale `~/.claude/` directory is
+// not evidence (#3699). The install still detects on either (it can offer to set Claude up); the
+// verification and the report must not blame a machine that merely left the directory behind.
+const claudeCodeInUse = () => existsSync(join(HOME, '.claude.json'));
+
 async function verify() {
   let allOk = true;
   // The report answers two different questions, and one of them failing must not condemn the
@@ -2185,6 +2419,21 @@ async function verify() {
   // footprint, and it says nothing about the endpoint.
   let installOk = true;
   const installFailed = () => { installOk = false; allOk = false; };
+  /**
+   * A check whose answer is "we cannot write there" or "our footprint is not there".
+   *
+   * The two answers have different fixes, and the per-client summary has to name which one it is:
+   * a read-only target is **not** fixed by re-running the installer — 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; see `unwritableAdvice`). So the kind is decided **here**, where the
+   * writability is measured, and never by reading the wording of the message: a message that
+   * changes its phrasing must not silently change the verdict.
+   */
+  const needWrite = (client, path, absentMsg, blockedMsg) => {
+    installFailed();
+    if (canCreateHere(path)) need(absentMsg, client, 'absent');
+    else need(blockedMsg, client, 'blocked');
+  };
   // 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 };
@@ -2206,13 +2455,16 @@ async function verify() {
     try {
       const granted = readJson(join(HOME, '.claude', 'settings.json'), null)?.permissions?.allow || [];
       const missing = CLAUDE_ALLOWED_TOOLS.filter((tool) => !granted.includes(tool));
-      if (detect('claude') && missing.length) {
+      if (wantClient('claude') && claudeCodeInUse() && 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;
+        // It is a Claude Code fact all the same — the permission list is Claude Code's own
+        // config — so it is judged under Claude Code and not under the machine (#3699). The fix
+        // is the same re-run, which is what 'absent' means: the grant is not in the list yet.
         need(`Claude Code：只读 MCP 工具没有放行（${missing.length} 个）→ 第一次检索会被权限拦下；`
-          + '重跑安装命令即可放行');
+          + '重跑安装命令即可放行', 'claude', 'absent');
       }
     } catch { /* a settings file we cannot read is reported by the Claude checks below */ }
   } else if (outcome.state === 'non-mcp') {
@@ -2261,11 +2513,20 @@ async function verify() {
   // 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));
+  // `detected-agents` counts only the assistants in scope: with `--client <id>` the question is
+  // about that one, so another assistant's absence is not this machine's problem (#3699).
+  const detectedAgents = AGENTS.filter((agent) => wantClient(agent) && detect(agent));
   if (!detectedAgents.length) {
     installFailed();
-    need('没有检测到任何受支持的助手 —— 因此什么都没装'
-      + `（支持：${supportedAgentLabels()}）→ 先打开一次你要用的那个助手，再回来运行本命令`);
+    if (CLIENT) {
+      // The user named a client this machine does not have. That is an answer, not a silence:
+      // "OpenClaw：没装过（这台机器上没检测到它）" says what to do about it.
+      need(`${clientLabel(CLIENT)}：没装过（这台机器上没检测到它）`
+        + '→ 先打开一次那个助手，再回来运行本命令', CLIENT, 'absent');
+    } else {
+      need('没有检测到任何受支持的助手 —— 因此什么都没装'
+        + `（支持：${supportedAgentLabels()}）→ 先打开一次你要用的那个助手，再回来运行本命令`);
+    }
   }
   const tokenFile = join(stateDir(), 'token');
   let tokenPresent = '';
@@ -2289,7 +2550,7 @@ async function verify() {
   // 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')) {
+  if (wantClient('claude') && claudeCodeInUse()) {
     const hookPath = join(stateDir(), 'hook.mjs');
     let hookPresent = false;
     try {
@@ -2298,10 +2559,9 @@ async function verify() {
       hookPresent = false;
     }
     if (!hookPresent) {
-      installFailed();
-      need(canCreateHere(hookPath)
-        ? '自动沉淀钩子：缺失 → 重跑安装命令'
-        : `自动沉淀钩子：装不了（${hookPath}）→ ${unwritableAdvice()}`);
+      needWrite('claude', hookPath,
+        '自动沉淀钩子：缺失 → 重跑安装命令',
+        `自动沉淀钩子：装不了（${hookPath}）→ ${unwritableAdvice()}`);
     } else {
       const settingsPath = join(HOME, '.claude', 'settings.json');
       const settings = readJson(settingsPath, {}) || {};
@@ -2312,34 +2572,35 @@ async function verify() {
         .filter((c) => typeof c === 'string');
       if (!commands.length) {
         installFailed();
-        need('Claude Code：钩子没装（settings.json 里没有本安装器写入的命令）');
+        need('Claude Code：钩子没装（settings.json 里没有本安装器写入的命令）', 'claude', 'absent');
       } else {
         const exe = commands[0].startsWith('"') ? commands[0].split('"')[1] : commands[0].split(' ')[0];
         if (!existsSync(exe)) {
           installFailed();
-          need(`Claude Code：钩子里的解释器不存在（${exe}）→ 钩子永远不会触发，重跑安装命令即可修`);
+          need(`Claude Code：钩子里的解释器不存在（${exe}）→ 钩子永远不会触发，重跑安装命令即可修`,
+            'claude', 'broken');
         } else {
-          ok('Claude Code：钩子已装且解释器存在');
+          ok('Claude Code：钩子已装且解释器存在', 'claude');
         }
       }
       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()}`);
+        needWrite('claude', 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}）→ 重跑安装命令`);
+          need(`Claude Code：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`,
+            'claude', 'broken');
         } else if (verdict.state === 'no-url-field') {
           installFailed();
-          need(`Claude Code：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`);
+          need(`Claude Code：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`, 'claude', 'broken');
         } else {
-          ok(`Claude Code：MCP 已注册（${verdict.url}）`);
+          ok(`Claude Code：MCP 已注册（${verdict.url}）`, 'claude');
         }
       }
     }
@@ -2348,57 +2609,84 @@ async function verify() {
   // OpenClaw that it is "not ready" would be a lie about a target that was never selected.
   // The state is read from the same file `openclaw mcp list` reports from, which keeps this
   // check working where the CLI itself cannot start (its database may be unwritable).
-  if (detect('openclaw')) {
+  if (wantClient('openclaw') && detect('openclaw')) {
     const rules = join(openclawWorkspaces()[0], 'AGENTS.md');
     if (!readText(rules).includes(`<!-- ${START} -->`)) {
-      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()}`);
+      needWrite('openclaw', rules,
+        `OpenClaw：规则块没装（${rules}）→ 重跑安装命令`,
+        `OpenClaw：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
     } else {
-      ok('OpenClaw：规则块已装');
+      ok('OpenClaw：规则块已装', 'openclaw');
     }
     const cfg = join(HOME, '.openclaw', 'openclaw.json');
     const entry = (readJson(cfg, null) || {}).mcp?.servers?.misakanet;
     if (!entry) {
-      installFailed();
       const manual = `openclaw mcp add misakanet --url ${ENDPOINT} --transport streamable-http`;
-      need(canCreateHere(cfg)
-        ? `OpenClaw：MCP 未注册（${cfg}）→ 重跑安装命令，或手动执行 ${manual}`
-        : `OpenClaw：MCP 未注册（${cfg}）→ ${unwritableAdvice(manual)}`);
+      needWrite('openclaw', cfg,
+        `OpenClaw：MCP 未注册（${cfg}）→ 重跑安装命令，或手动执行 ${manual}`,
+        `OpenClaw：MCP 未注册（${cfg}）→ ${unwritableAdvice(manual)}`);
     } else {
-      ok(`OpenClaw：MCP 已注册（${entry.url || '?'}）`);
+      // The URL is checked here, and it was not: this block only ever asked "is there an entry",
+      // so an OpenClaw pointed at `https://BROKEN.invalid/mcp` was reported as "已注册" with the
+      // unreachable URL printed next to the tick. `mcpEntryState` exists for exactly this and was
+      // simply never applied here (it is applied to Claude, Codex, codewhale, the MCP-only
+      // targets and mcode). With a per-client verdict on screen, "就绪" next to an entry nobody
+      // can reach would be a false green (#1984).
+      const verdict = mcpEntryState(entry, 'url');
+      if (verdict.state === 'wrong-url') {
+        installFailed();
+        need(`OpenClaw：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`,
+          'openclaw', 'broken');
+      } else if (verdict.state === 'no-url-field') {
+        installFailed();
+        need(`OpenClaw：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`, 'openclaw', 'broken');
+      } else {
+        ok(`OpenClaw：MCP 已注册（${verdict.url}）`, 'openclaw');
+      }
     }
   }
   // Hermes: same rule — reported only when the user has it. Its config file *is* the registry,
   // so the state is readable without running anything. What cannot be confirmed from here is
   // whether Hermes has loaded that file, and the output says so rather than implying it.
-  if (readText(join(HOME, '.hermes', 'config.yaml'))) {
+  if (wantClient('hermes') && readText(join(HOME, '.hermes', 'config.yaml'))) {
     const rules = join(HOME, '.hermes', 'SOUL.md');
     if (!readText(rules).includes(`<!-- ${START} -->`)) {
-      installFailed();
-      need(canCreateHere(rules)
-        ? `Hermes：规则块没装（${rules}）→ 重跑安装命令`
-        : `Hermes：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
+      needWrite('hermes', rules,
+        `Hermes：规则块没装（${rules}）→ 重跑安装命令`,
+        `Hermes：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
     } else {
-      ok('Hermes：规则块已装');
+      ok('Hermes：规则块已装', 'hermes');
     }
     const cfg = join(HOME, '.hermes', 'config.yaml');
     const text = readText(cfg);
     if (!HERMES_MARKED.test(text) && !HERMES_BARE.test(text)) {
-      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}`);
+      needWrite('hermes', cfg,
+        `Hermes：MCP 未注册（${cfg}）→ 重跑安装命令，或执行 ${manual}`,
+        `Hermes：MCP 未注册（${cfg}）→ ${unwritableAdvice(manual)}`);
     } else {
-      ok(`Hermes：MCP 条目与 token 都在（${HERMES_ENV_KEY}）`);
-      skip('Hermes：本进程只能确认"配置已写"，无法确认 Hermes 是否已加载 → 可用 hermes mcp list 复核');
+      // The entry is there — but is it pointed at our endpoint? Same gap as OpenClaw had: the
+      // check asked "is there an entry" and never "does it point at the right place", so a Hermes
+      // on `https://BROKEN.invalid/mcp` was reported as registered (#1984: a green run is not
+      // evidence unless something in it can differ).
+      const url = hermesMcpUrl(text);
+      const expected = expectedEndpoint();
+      if (url && url !== expected) {
+        installFailed();
+        need(`Hermes：MCP 条目指向的端点不对（${url}，应为 ${expected}）（${cfg}）→ 重跑安装命令`,
+          'hermes', 'broken');
+      } else if (!url) {
+        installFailed();
+        need(`Hermes：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`, 'hermes', 'broken');
+      } else if (!new RegExp(`^${HERMES_ENV_KEY}=`, 'm').test(readText(join(HOME, '.hermes', '.env')))) {
+        ok('Hermes：MCP 条目已写入配置（无 token → 读不限次数，写入类工具不可用）', 'hermes');
+        skip(`Hermes：想让写入类工具可用（write_lesson），重跑安装命令即可写入 ${HERMES_ENV_KEY}`, 'hermes');
+      } else {
+        ok(`Hermes：MCP 条目与 token 都在（${HERMES_ENV_KEY}）`, 'hermes');
+        skip('Hermes：本进程只能确认"配置已写"，无法确认 Hermes 是否已加载 → 可用 hermes mcp list 复核', 'hermes');
+      }
     }
   }
   // Codex and codewhale: reported only when the user has them, like every other target. They were
@@ -2406,68 +2694,67 @@ async function verify() {
   // 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')) {
+  if (wantClient('codex') && detect('codex')) {
     const rules = join(HOME, '.codex', 'AGENTS.md');
     if (!readText(rules).includes(`<!-- ${START} -->`)) {
-      installFailed();
-      need(canCreateHere(rules)
-        ? `Codex：规则块没装（${rules}）→ 重跑安装命令`
-        : `Codex：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
+      needWrite('codex', rules,
+        `Codex：规则块没装（${rules}）→ 重跑安装命令`,
+        `Codex：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
     } else {
-      ok('Codex：规则块已装');
+      ok('Codex：规则块已装', '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()}`);
+      needWrite('codex', cfg,
+        `Codex：MCP 未注册（${cfg}）→ 重跑安装命令`,
+        `Codex：MCP 未注册（${cfg}）→ ${unwritableAdvice()}`);
     } else if (verdict.state === 'wrong-url') {
       installFailed();
-      need(`Codex：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`);
+      need(`Codex：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`,
+        'codex', 'broken');
     } else if (verdict.state === 'no-url-field') {
       installFailed();
-      need(`Codex：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`);
+      need(`Codex：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`, 'codex', 'broken');
     } else {
-      ok(`Codex：MCP 已注册（${verdict.url}）`);
+      ok(`Codex：MCP 已注册（${verdict.url}）`, 'codex');
     }
     // 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，重跑安装命令即可补上');
+        + '→ Codex 连不上 streamable-http，重跑安装命令即可补上', 'codex', 'broken');
     }
   }
-  if (detect('codewhale')) {
+  if (wantClient('codewhale') && 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()}`);
+      needWrite('codewhale', cfg,
+        `codewhale：MCP 未注册（${cfg}）→ 重跑安装命令`,
+        `codewhale：MCP 未注册（${cfg}）→ ${unwritableAdvice()}`);
     } else if (verdict.state === 'wrong-url') {
       installFailed();
-      need(`codewhale：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`);
+      need(`codewhale：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`,
+        'codewhale', 'broken');
     } else if (verdict.state === 'no-url-field') {
       installFailed();
-      need(`codewhale：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`);
+      need(`codewhale：MCP 条目在，但没有 url 字段（${cfg}）→ 重跑安装命令`, 'codewhale', 'broken');
     } else {
-      ok(`codewhale：MCP 已注册（${verdict.url}）`);
+      ok(`codewhale：MCP 已注册（${verdict.url}）`, 'codewhale');
     }
     // 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}）→ 重跑安装命令`);
+        need(`codewhale：规则块没装（${rules}）→ 重跑安装命令`, 'codewhale', 'absent');
       } else {
-        ok(`codewhale：规则块已装（${rules}）`);
+        ok(`codewhale：规则块已装（${rules}）`, 'codewhale');
       }
     }
   }
@@ -2475,26 +2762,27 @@ async function verify() {
   // 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;
+    if (!wantClient(agent) || !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()}`);
+      needWrite(agent, 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 下）' : ''}`);
+          + `这家用的是 ${spec.urlField}${spec.container === 'mcp' ? '（注意嵌套在 mcp 而不是 mcpServers 下）' : ''}`,
+          agent, 'broken');
       } else if (verdict.state === 'wrong-url') {
         installFailed();
-        need(`${spec.label}：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`);
+        need(`${spec.label}：MCP 条目指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${cfg}）→ 重跑安装命令`,
+          agent, 'broken');
       } else {
-        ok(`${spec.label}：MCP 已注册（${verdict.url}）`);
-        skip(`${spec.label}：只能确认"配置已写"，无法确认它是否已加载 → ${spec.verifyHint}`);
+        ok(`${spec.label}：MCP 已注册（${verdict.url}）`, agent);
+        skip(`${spec.label}：只能确认"配置已写"，无法确认它是否已加载 → ${spec.verifyHint}`, agent);
       }
     }
   }
@@ -2503,39 +2791,38 @@ async function verify() {
   // 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')) {
+  if (wantClient('mcode') && 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()}`);
+      needWrite('mcode', rules,
+        `MiniMax Code：规则块没装（${rules}）→ 重跑安装命令`,
+        `MiniMax Code：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
     } else {
-      ok('MiniMax Code：规则块已装');
+      ok('MiniMax Code：规则块已装', 'mcode');
     }
     const plugin = mcodePluginPath(HOME);
     const doc = readJson(plugin, null);
     if (doc === null) {
-      installFailed();
-      need(canCreateHere(plugin)
-        ? `MiniMax Code：插件清单缺失或不是合法 JSON（${plugin}）→ 重跑安装命令`
-        : `MiniMax Code：插件清单装不了（${plugin}）→ ${unwritableAdvice()}`);
+      needWrite('mcode', 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}）→ 重跑安装命令`);
+        need(`MiniMax Code：插件清单里没有 mcpServers.misakanet（${plugin}）→ 重跑安装命令`,
+          'mcode', 'absent');
       } else if (verdict.state === 'no-url-field') {
         installFailed();
-        need(`MiniMax Code：插件清单里的条目没有 url 字段（${plugin}）→ 重跑安装命令`);
+        need(`MiniMax Code：插件清单里的条目没有 url 字段（${plugin}）→ 重跑安装命令`, 'mcode', 'broken');
       } else if (verdict.state === 'wrong-url') {
         installFailed();
         need(`MiniMax Code：插件清单指向的端点不对（${verdict.url}，应为 ${verdict.expected}）（${plugin}）`
-          + '→ 重跑安装命令');
+          + '→ 重跑安装命令', 'mcode', 'broken');
       } else {
-        ok(`MiniMax Code：插件清单已注册（${verdict.url}）`);
+        ok(`MiniMax Code：插件清单已注册（${verdict.url}）`, 'mcode');
         skip('MiniMax Code：只能确认"插件目录在位"，无法确认 mcode 是否已加载 → 跑 `mcode plugin list` 复核'
-          + '（`mcode plugin add` 报 LOCAL_PLUGIN_INSTALL_UNSUPPORTED 不是失败）');
+          + '（`mcode plugin add` 报 LOCAL_PLUGIN_INSTALL_UNSUPPORTED 不是失败）', 'mcode');
       }
     }
   }
@@ -2575,6 +2862,10 @@ async function verify() {
     // 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,
+    // One verdict per client, so the conclusion can be read per assistant instead of per machine
+    // (issue #3699). The machine-level verdict below is derived from these, not the other way
+    // round: a client that was not checked cannot be the reason this machine is not ready.
+    clients: clientVerdicts(),
     segments: { start: segmentStart, end: segmentEnd },
   };
 }
@@ -2606,6 +2897,14 @@ function usabilityText(verdict) {
 }
 
 function installText(verdict) {
+  // The clients that are not ready, **by name** (issue #3699). "3 项需要手动处理" said how many;
+  // it never said which assistant the three belonged to, so on a multi-client machine the reader
+  // had to go and match the count against the lines above.
+  const notReady = (verdict.clients || []).filter((c) => c.verdict !== '就绪');
+  if (notReady.length) {
+    return `不完整 —— ${notReady.map((c) => `${c.label}：${c.verdict}`).join('；')}`
+      + '（上面每条 ! 都给了成因和做法）';
+  }
   if (verdict.zeroTargets) {
     return '不完整 —— 没有检测到任何受支持的助手，因此什么都没装';
   }
@@ -2631,32 +2930,118 @@ function exitCodeFor(verdict) {
   return (verdict.unverified && verdict.install === 'complete') ? 2 : 1;
 }
 
+/**
+ * One verdict per client, from the lines that client produced (issue #3699).
+ *
+ * The machine-level verdict was a single boolean over every check, but the checks are per client:
+ * a machine with three assistants was condemned because of the one the user never touches, and a
+ * healthy assistant was indistinguishable from a broken one (#3696, #3699). So the conclusion is
+ * per client — and each client gets one of four words, because the four fixes are four different
+ * things:
+ *
+ *   就绪    — everything we checked for this client passed; there is nothing to do.
+ *   装不了  — we cannot write there. Fix the permissions: 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 — see `unwritableAdvice`).
+ *   没装过  — our footprint is not there: the file, the entry, the permission grant. A re-run puts
+ *             it there.
+ *   装坏了  — our footprint is there but points at the wrong place: the wrong endpoint, a missing
+ *             field, a missing interpreter. A re-run fixes it.
+ *
+ * Issue #3699 names the first three. The fourth exists because "our entry is there and points at
+ * the wrong endpoint" is none of the three, and calling it 没装过 would be a lie about the
+ * machine.
+ *
+ * `blocked` wins over `broken` wins over `absent`: a client we cannot write to is not merely "not
+ * installed", and saying so would send the reader after the wrong fix.
+ */
+const CLIENT_VERDICT_WORDS = { blocked: '装不了', broken: '装坏了', absent: '没装过' };
+/** What to do about each verdict, in the order the fix differs. */
+const CLIENT_VERDICT_HINTS = {
+  就绪: '',
+  装不了: '（改权限后重跑安装命令）',
+  没装过: '（重跑安装命令）',
+  装坏了: '（重跑安装命令）',
+};
+
+function clientVerdicts() {
+  const buckets = new Map();
+  const bucket = (id) => {
+    if (!buckets.has(id)) {
+      buckets.set(id, { id, done: [], manual: [], skipped: [], kinds: new Set() });
+    }
+    return buckets.get(id);
+  };
+  for (const line of done) if (line.client) bucket(line.client).done.push(line);
+  for (const line of manual) {
+    if (!line.client) continue;
+    const b = bucket(line.client);
+    b.manual.push(line);
+    if (line.kind) b.kinds.add(line.kind);
+  }
+  for (const line of skipped) if (line.client) bucket(line.client).skipped.push(line);
+  // `AGENTS` is the order, so the output reads the same way on every machine.
+  return AGENTS.filter((id) => buckets.has(id)).map((id) => {
+    const b = buckets.get(id);
+    const verdict = !b.kinds.size ? '就绪'
+      : b.kinds.has('blocked') ? CLIENT_VERDICT_WORDS.blocked
+        : b.kinds.has('broken') ? CLIENT_VERDICT_WORDS.broken
+          : CLIENT_VERDICT_WORDS.absent;
+    return {
+      id,
+      label: clientLabel(id),
+      verdict,
+      hint: CLIENT_VERDICT_HINTS[verdict],
+      done: b.done,
+      manual: b.manual,
+      skipped: b.skipped,
+    };
+  });
+}
+
 /**
  * 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).
+ *
+ * The install section is grouped **per client** (issue #3699). The checks were per client all
+ * along — each block reads one assistant's own files — but the output could only say "this
+ * machine", so a machine with three assistants was condemned because of the one the user never
+ * touches, and a healthy assistant was indistinguishable from a broken one. Now each client gets
+ * one verdict line and its own details under it.
  */
 function renderVerify(verdict) {
   const { start, end } = verdict.segments;
   const tail = { done: done.length, manual: manual.length, skipped: skipped.length };
-  const section = (label, from, to) => {
+  // A line is either about the machine (the endpoint probe, the token, the version stamp) or
+  // about one client. The two never share a line, so the sections can be split by that.
+  const machineLines = (list, from, to) => list.slice(from, to).filter((l) => !l.client);
+  const section = (label, from, to, clients) => {
     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);
+    const finished = machineLines(done, from.done, to.done);
+    const open = machineLines(manual, from.manual, to.manual);
+    const ignored = machineLines(skipped, 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 (finished.length && !SILENT) out.push(...finished.map((l) => `  ✓ ${l.text}`));
+    if (open.length) out.push(...open.map((l) => `  ! ${l.text}`));
+    if (ignored.length && !SILENT) out.push(...ignored.map((l) => `  · ${l.text}`));
+    for (const client of clients || []) {
+      // The verdict line is the conclusion, not narration: it survives `--silent`, because a
+      // silent `--verify` that prints nothing about the client cannot be read at all.
+      out.push(`  ${client.label}：${client.verdict}${client.hint}`);
+      if (client.done.length && !SILENT) out.push(...client.done.map((l) => `    ✓ ${l.text}`));
+      if (client.manual.length) out.push(...client.manual.map((l) => `    ! ${l.text}`));
+      if (client.skipped.length && !SILENT) out.push(...client.skipped.map((l) => `    · ${l.text}`));
+    }
     if (!out.length) return out;
     return [`\n── ${label} ──`, ...out];
   };
   return [
-    ...section('端点/可用性', start, end),
-    ...section('安装完整性', end, tail),
+    ...section('端点/可用性', start, end, []),
+    ...section('安装完整性', end, tail, verdict.clients),
     '',
     `可用性：${usabilityText(verdict)}`,
     `安装完整性：${installText(verdict)}`,
@@ -2754,9 +3139,49 @@ function restoreEmptiedFiles() {
   }
 }
 
+/**
+ * Is `~/.minimax/plugins/misakanet/` ours to delete?
+ *
+ * The install side answers this by reading the manifest and refusing to touch a directory whose
+ * `name` is not `misakanet` (`installMcode`), reporting "已原样保留". Uninstall used to `rmSync`
+ * the subtree with no question at all, so on a machine where the install had just promised to keep
+ * the user's plugin, the next `--uninstall` deleted it (issue #3831, measured 2026-10-25) — the
+ * installer's own wording turned into a lie by the command it recommends for undoing.
+ *
+ * A manifest that is absent or unparseable is not proof of ownership either: a plugin directory is
+ * a user-owned space, and `misakanet` is a name another plugin can legitimately have. Being wrong
+ * here costs irreversible data, so only a manifest that says `name: "misakanet"` answers "yes".
+ */
+function mcodePluginDirectoryOwnership() {
+  const plugin = mcodePluginPath(HOME);
+  const text = readText(plugin);
+  if (!text) {
+    return { ours: false, why: '里没有 .claude-plugin/plugin.json（无法确认归属）' };
+  }
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch {
+    return { ours: false, why: '的清单不是合法 JSON（无法确认归属）' };
+  }
+  if (doc?.name !== 'misakanet') {
+    return {
+      ours: false,
+      why: `的清单不是本安装器写的（name=${JSON.stringify(doc?.name ?? null)}）`,
+    };
+  }
+  return { ours: true, why: '' };
+}
+
 function uninstall() {
+  let hermesRulesRemoved = false;
   for (const rel of ['.claude/CLAUDE.md', '.codex/AGENTS.md', '.hermes/SOUL.md', '.minimax/AGENTS.md']) {
-    if (stripBlock(join(HOME, rel))) ok(`移除规则块 → ${rel}`);
+    if (stripBlock(join(HOME, rel))) {
+      ok(`移除规则块 → ${rel}`);
+      // Recorded here because the block is already gone by the time the Hermes summary is built —
+      // "已移除" must describe what this run did, not what a file says now (#3834).
+      if (rel === '.hermes/SOUL.md') hermesRulesRemoved = true;
+    }
   }
   // Both candidates: a block may have been written before the workspace was read from config.
   for (const workspace of openclawWorkspaces()) {
@@ -2796,14 +3221,29 @@ function uninstall() {
     }
   }
   // 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.
+  // the whole subtree back. Only *our* directory, and only once its manifest says it is ours: see
+  // `mcodePluginDirectoryOwnership` for what asking the same question as the install costs (#3831).
+  // `~/.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 ownership = mcodePluginDirectoryOwnership();
+    if (!ownership.ours) {
+      // Deliberately a `need`, never an `ok`: the directory is still there, and only a human can
+      // decide whether it is theirs to remove. Putting it under "已完成" was the second half of the
+      // bug — the run claimed a removal it had skipped.
+      need(`MiniMax Code：${mcodeDir} ${ownership.why} → 已保留（不删）；`
+        + '确认它是你的插件后手动删掉这个目录，本安装器不碰它');
+    } else {
+      try {
+        if (!DRY) rmSync(mcodeDir, { recursive: true, force: true });
+        ok(`移除插件目录 → ${mcodeDir}`);
+      } catch (err) {
+        // A failed delete used to be swallowed by an empty `catch`, so the run said nothing while
+        // the directory survived. Now it is a manual step, which is what it is.
+        need(`MiniMax Code：删不掉 ${mcodeDir}（${redact((err && err.message) || err)}）→ 手动删除它`);
+      }
+    }
   }
   const voiceDir = join(stateDir(), 'voice');
   if (existsSync(voiceDir)) {
@@ -2890,8 +3330,18 @@ function uninstall() {
       ok(`移除 token 行 → ${hermesEnv}（${HERMES_ENV_KEY}）`);
     }
   }
-  need('Hermes 的钩子不归本安装器管 → 需要时看 hermes hooks doctor；'
-    + `规则块已在 ~/.hermes/SOUL.md 移除`);
+  // Hermes' advice, only on a machine that has Hermes. It was unconditional, so a machine that had
+  // never installed Hermes was told "规则块已在 ~/.hermes/SOUL.md 移除" and sent to a
+  // `hermes hooks doctor` that does not exist there (#3834, measured 2026-10-25). The `!` list is
+  // the user's only action list — an item that does not apply dilutes it.
+  if (existsSync(join(HOME, '.hermes'))) {
+    // And say what actually happened to the rules block: "已移除" only when this run removed one,
+    // "本来就没装" when the file was there without our markers.
+    need('Hermes 的钩子不归本安装器管 → 需要时看 hermes hooks doctor；'
+      + (hermesRulesRemoved
+        ? '规则块已在 ~/.hermes/SOUL.md 移除'
+        : '规则块本来就没装（~/.hermes/SOUL.md 里没有本安装器的标记块）'));
+  }
 
   // OpenClaw's MCP entry is one we wrote ourselves, so we can take it back ourselves.
   const ocCfg = join(HOME, '.openclaw', 'openclaw.json');
@@ -2978,7 +3428,7 @@ function reportValues(verdict) {
   const permissions = (() => {
     // `n/a` when Claude Code is not a target on this machine: an absent settings file is not a
     // gap, and reporting one would send a Codex-only user chasing a fix they do not need.
-    if (!detect('claude')) return 'n/a';
+    if (!claudeCodeInUse()) return 'n/a';
     const granted = readJson(join(HOME, '.claude', 'settings.json'), null)?.permissions?.allow || [];
     const missing = CLAUDE_ALLOWED_TOOLS.filter((tool) => !granted.includes(tool));
     return missing.length ? 'incomplete' : 'ok';
@@ -3021,7 +3471,7 @@ function reportValues(verdict) {
     ['voice', voiceStatus()],
     ['open-items', manual.length],
     // Redacted here, once, so neither encoder can print an unredacted message by accident.
-    ['open-items-detail', manual.map((m) => redact(m))],
+    ['open-items-detail', manual.map((m) => redact(m.text))],
     ...HUMAN_REPORT_FIELDS.map(([key, value, note]) => [key, value, note]),
   ];
 }
@@ -3104,9 +3554,9 @@ function render() {
   // `--silent` drops the narration, never the errors: `done` is progress, `manual` is what a human
   // (or a GPO log reader) has to act on, and a run that failed silently would be worse than a loud
   // one. See SILENT at the top for the full contract.
-  if (done.length && !SILENT) out.push(`\n已完成（${done.length}）:`, ...done.map((l) => `  ✓ ${l}`));
-  if (manual.length) out.push(`\n需要你手动一步（${manual.length}）:`, ...manual.map((l) => `  ! ${l}`));
-  if (skipped.length && !SILENT) out.push(`\n跳过（${skipped.length}）:`, ...skipped.map((l) => `  · ${l}`));
+  if (done.length && !SILENT) out.push(`\n已完成（${done.length}）:`, ...done.map((l) => `  ✓ ${l.text}`));
+  if (manual.length) out.push(`\n需要你手动一步（${manual.length}）:`, ...manual.map((l) => `  ! ${l.text}`));
+  if (skipped.length && !SILENT) out.push(`\n跳过（${skipped.length}）:`, ...skipped.map((l) => `  · ${l.text}`));
   return out.join('\n');
 }
 
@@ -3123,6 +3573,22 @@ const STRICT = has('--strict') || has('--ci');
 const mode = has('--uninstall') ? 'uninstall'
   : ((has('--report') || REPORT_JSON || (has('--ci') && !has('--verify'))) ? 'report'
   : (has('--verify') ? 'verify' : 'install'));
+// `--client` is a question about *judging*, so it belongs to `--verify` and nowhere else: in
+// install mode `--only` already says which assistants to write to, and in report mode the report
+// has its own shape. A flag that silently does nothing is worse than one that refuses: `--client`
+// next to `--client-id` is exactly the kind of pair a user mixes up, so it says what it means.
+// Exit 2 is this tool's "could not answer" code (same as a probe timeout, #3778) — the machine
+// is not broken, the request was.
+if (CLIENT && mode !== 'verify') {
+  console.error(`--client 只对 --verify 有意义（它决定"只判哪一个客户端"）；`
+    + `当前模式是 ${mode}，请用 --only <助手> 指定要处理的助手。`);
+  process.exit(2);
+}
+if (CLIENT && !AGENTS.includes(CLIENT)) {
+  console.error(`未知的客户端：${CLIENT}`);
+  console.error(`支持的客户端：${supportedAgentLabels()}`);
+  process.exit(2);
+}
 if (mode !== 'report' && !SILENT) {
   // The banner names the home directory, which is exactly the kind of thing that gets pasted
   // along with a report — so `--report` prints only the report. `--silent` drops it for the other
@@ -3377,6 +3843,25 @@ if (!SILENT && !DRY) {
   // 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 (installed > 0) {
+    // The tail is what a user reads, and until now it held only next steps: a real Windows run on
+    // 2026-10-29 ended on "5) 想关掉…" and the identity line, so the sole evidence that anything had
+    // worked was the absence of errors. Verified here rather than assumed: the version is this build's,
+    // and whether it is the published one is asked of the registry — the same two primitives `--verify`
+    // uses, so the closing line and the self-check cannot disagree about what "latest" means.
+    const latest = await latestPublishedVersion();
+    const delta = latest ? compareVersions(VERSION, latest) : null;
+    let versionNote = '；查不到 npm 上的最新版本（离线或 registry 不可达）';
+    if (delta === 0) versionNote = '（已是最新）';
+    else if (delta !== null && delta < 0) {
+      versionNote = `；npm 上已有 ${latest} → 重跑 npx @misaka-net/misakanet-setup@latest 可更新`;
+    } else if (delta !== null) {
+      versionNote = `；比 npm 上的 ${latest} 新（本地构建或预发布）`;
+    }
+    console.log(`\n✓ 安装成功 —— misakanet-setup ${VERSION}${versionNote}`
+      + `\n  已配置 ${installed} 个助手；撤销：npx @misaka-net/misakanet-setup --uninstall`);
+  }
 }
 if (MCP_ONLY && !SILENT) {
   // The honest failure mode of tier ①, said where the user will read it: they are not installing a
@@ -3388,13 +3873,14 @@ if (MCP_ONLY && !SILENT) {
 if (!SILENT) {
   console.log(`
 接下来：
-  1) **把这个助手窗口关掉再打开一次**（新功能要重开会话才生效）
-  2) 随便挑一句带报错原文的片段问它（例如「${ONBOARDING_QUERIES[0]}」「${ONBOARDING_QUERIES[1]}」「${ONBOARDING_QUERIES[2]}」）——它应该先去查经验库
-  3) 想确认状态：npx @misaka-net/misakanet-setup --verify
-  4) 想关掉：npx @misaka-net/misakanet-setup --uninstall`
+  1) 启动时加载 MCP 配置的客户端（Claude Code / Codex 等）重开一次会话；dsh 下一条消息就生效，mcporter 这类按次调用的通道不需要重启
+  2) 确认工具装上了：跑客户端的 MCP 列表命令（如 mcporter list misakanet，或 Claude Code 的 /mcp）——应看到 8 个工具
+  3) 随便挑一句带报错原文的片段问它（例如「${ONBOARDING_QUERIES[0]}」「${ONBOARDING_QUERIES[1]}」「${ONBOARDING_QUERIES[2]}」）——它应该先去查经验库
+  4) 想确认状态：npx @misaka-net/misakanet-setup --verify
+  5) 想关掉：npx @misaka-net/misakanet-setup --uninstall`
     + (clientIdHint
       ? `
-  5) 记不记都行：这台机器的身份编号是 ${clientIdHint}
+  6) 记不记都行：这台机器的身份编号是 ${clientIdHint}
      想让它以后重装/换机还算同一个身份，再跑安装时加：--client-id ${clientIdHint}`
       : ''));
 }