@misaka-net/misakanet-setup 0.5.5 → 0.6.0

package/bin/misakanet-setup.mjs

@@ -16,8 +16,8 @@
  * undone by the other.
  *
  * Three things, all required, or the install is theatre:
- *   1. the agent CAN call it        → MCP server entry (with the token, so reads are not
- *                                     metered by the anonymous 5/day limit)
+ *   1. the agent CAN call it        → MCP server entry (with the token when we have one, plus the
+ *                                     self-declared context hints; reads are unlimited either way)
  *   2. the agent KNOWS when to call → rules block in its own rules file
  *   3. the checkpoint FIRES         → a hook, because "summarise every 20 turns" is dead
  *                                     text: agents do not keep counters
@@ -39,7 +39,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, copyFi
 // package.json since 0.4 and had never been executed on the version it names.
 import { randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
-import { delimiter, join, dirname, resolve } from 'node:path';
+import { basename, delimiter, join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -78,6 +78,25 @@ const valueOf = (flag, dflt) => {
 };
 const only = valueOf('--only', '').split(',').map((s) => s.trim()).filter(Boolean);
 const DRY = has('--dry-run');
+/**
+ * Permission tiers (2026-09-18).
+ *
+ * The installer does three different kinds of thing, and they do not need the same permission:
+ *
+ *   ① register an MCP endpoint        — the user's own agent config; the same privilege as adding
+ *                                       any MCP server;
+ *   ② write a rules block             — changes the agent's behaviour ("search before retrying"),
+ *                                       and for Hermes that means editing `~/.hermes/SOUL.md`, its
+ *                                       *identity* file;
+ *   ③ install hooks + state           — acts automatically on every turn.
+ *
+ * Asking for all three in one command is why a machine with an approval process can only answer
+ * "no" (issue #1753, 2026-09-18): an operator willing to approve ① has no way to say it. `--mcp-only`
+ * is that way to say it — ① only, and the run says so in its own report instead of looking partial.
+ */
+const MCP_ONLY = has('--mcp-only');
+const LIST_WRITES = has('--list-writes');
+
 /**
  * `--silent` (issue #1784): the enterprise/MDM form. A GPO or Intune script pipes this program's
  * stdout into a log file, where the ✓/· narration is noise (and names local paths).
@@ -94,7 +113,8 @@ const SILENT = has('--silent');
 /** `--report-json`: the same report as JSON, and nothing else on stdout (#1784). */
 const REPORT_JSON = has('--report-json');
 const HOME = resolve(valueOf('--home', homedir()));
-const AGENTS = ['claude', 'codex', 'hermes', 'openclaw', 'codewhale'];
+const AGENTS = ['claude', 'codex', 'hermes', 'openclaw', 'codewhale',
+                'cursor', 'gemini', 'copilot', 'opencode', 'kiro'];
 
 const done = [];
 const manual = [];
@@ -127,8 +147,31 @@ 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.6.0'  // x-release-please-version
+
+/**
+ * The shape of a client id, in one place.
+ *
+ * It gates two different things: what the endpoint accepts as `client_id` on registration, and — since
+ * 2026-09-19 — what may be written into an assistant's config as `X-MisakaNet-Client`. The second use
+ * is why the shape matters here and not only at the endpoint: that value can come from a file we found
+ * on disk, and it is interpolated into a TOML inline table, a YAML mapping and JSON. A string matching
+ * this cannot contain a quote, a newline or a `:`, so it cannot break any of the three.
  */
-const VERSION = '0.5.5'
+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*
@@ -148,7 +191,9 @@ const FLAGS = [
   ['--uninstall', '移除本安装器写入的内容（保留 .misakanet.bak 备份）'],
   ['--upgrade', '与安装等价（覆盖安装即升级）'],
   ['--client-id <id>', '固定本机身份：同一个 id 永远拿回同一个 node（重装/换机也能延续）'],
-  ['--no-register', '不注册匿名节点（不写 token，检索仍是 5 次/天/IP）'],
+  ['--mcp-only', '只注册 MCP 端点，不改 agent 行为（不写规则块、不装钩子）——权限分级用'],
+  ['--list-writes', '只打印会改哪些文件（文件 | 动作 | 撤销方式），不写任何东西'],
+  ['--no-register', '不注册匿名节点（不写 token；读不受影响，写入类工具不可用）'],
   ['--voice', '打开语音/桌面通知（默认关）'],
   ['--help, -h', '打印这份帮助并退出'],
   ['--version', '打印版本并退出'],
@@ -283,6 +328,91 @@ function writeText(path, text, { mode } = {}) {
   }
 }
 
+/**
+ * The targets whose whole install is one MCP entry in one JSON file.
+ *
+ * Each entry shape is the one that target's own documentation shows, and they are **not**
+ * interchangeable: Gemini CLI's remote field is `httpUrl` (its `url` means SSE), OpenCode nests under
+ * `mcp` rather than `mcpServers` and wants `type: "remote"`, Copilot CLI wants `type: "http"`, and
+ * Cursor and Kiro use a bare `url`. A copied entry with the wrong key fails **silently** — no error,
+ * the server simply never appears — which is why each shape is pinned by tests instead of assumed.
+ *
+ * None of these five has a rules block or a hook *this installer can write*: their rules live in
+ * project-scoped files (`.cursor/rules/*.mdc`, `GEMINI.md`, `AGENTS.md`, `.github/copilot-instructions.md`,
+ * `.kiro/steering/*.md`) and we do not know where a user's projects are. So tier ① is the whole
+ * install for them, `--mcp-only` is an identity, and the output says "MCP only" out loud instead of
+ * implying behaviour changed. That is also why `--report` says `install-scope: mcp-only` on a machine
+ * whose only target is one of these.
+ */
+const MCP_ONLY_TARGETS = {
+  cursor: {
+    label: 'Cursor',
+    detect: ['.cursor'],
+    config: (home) => join(home, '.cursor', 'mcp.json'),
+    container: 'mcpServers',
+    urlField: 'url',
+    entry: (bearer) => ({ url: ENDPOINT, headers: mcpHeaders(bearer, 'cursor') }),
+    rules: '.cursor/rules/*.mdc 是项目级的，安装器不知道你的项目在哪',
+    ruleHint: '想让 Cursor 主动去查，把 .cursor/rules/misakanet-failure-memory.mdc 放进项目',
+    manual: '重启 Cursor 后在 Settings → MCP 里确认能看见 misakanet（本安装器只写用户级 '
+      + '~/.cursor/mcp.json，项目级 .cursor/mcp.json 归你自己管）',
+    verifyHint: '在 Settings → MCP 里复核',
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    detect: ['.gemini'],
+    config: (home) => join(home, '.gemini', 'settings.json'),
+    container: 'mcpServers',
+    // `httpUrl` is the HTTP-streaming endpoint; `url` would mean SSE. Documented property list:
+    // geminicli.com/docs/tools/mcp-server ("headers: Custom HTTP headers when using url or httpUrl").
+    urlField: 'httpUrl',
+    entry: (bearer) => ({ httpUrl: ENDPOINT, headers: mcpHeaders(bearer, 'gemini') }),
+    rules: '它读 GEMINI.md（全局 ~/.gemini/GEMINI.md 与项目树），而安装器不写别人的规则文件',
+    ruleHint: '想让 Gemini CLI 主动去查，把规则块加进项目的 GEMINI.md',
+    manual: '重启会话后用 `/mcp` 复核 misakanet 是否列出',
+    verifyHint: '用 /mcp 复核',
+  },
+  copilot: {
+    label: 'Copilot CLI',
+    detect: ['.copilot'],
+    config: (home) => join(home, '.copilot', 'mcp-config.json'),
+    container: 'mcpServers',
+    urlField: 'url',
+    entry: (bearer) => ({ type: 'http', url: ENDPOINT, headers: mcpHeaders(bearer, 'copilot') }),
+    rules: '它读 .github/copilot-instructions.md 与 AGENTS.md（项目级），安装器不写项目文件',
+    ruleHint: '想让 Copilot CLI 主动去查，把规则写进项目的 .github/copilot-instructions.md',
+    manual: '跑 `copilot mcp list` 复核（VS Code 里的 Copilot 是另一份配置，键名是 `servers`）',
+    verifyHint: '用 `copilot mcp list` 复核',
+  },
+  opencode: {
+    label: 'OpenCode',
+    detect: ['.config/opencode'],
+    config: (home) => join(home, '.config', 'opencode', 'opencode.json'),
+    container: 'mcp',
+    urlField: 'url',
+    entry: (bearer) => ({ type: 'remote', url: ENDPOINT, enabled: true,
+                          headers: mcpHeaders(bearer, 'opencode') }),
+    rules: '它读 AGENTS.md（项目根与 ~/.config/opencode/AGENTS.md），安装器不写别人的规则文件',
+    ruleHint: '想让 OpenCode 主动去查，把规则块加进项目的 AGENTS.md',
+    manual: '重启 OpenCode 后看它的 MCP 列表；若你设了 XDG_CONFIG_HOME，它读的是 '
+      + '$XDG_CONFIG_HOME/opencode/opencode.json，把同样的条目贴过去即可',
+    verifyHint: '看 OpenCode 的 MCP 列表复核',
+    parseNote: 'opencode.jsonc 允许注释，若你用的正是它，本安装器解析不了',
+  },
+  kiro: {
+    label: 'Kiro',
+    detect: ['.kiro'],
+    config: (home) => join(home, '.kiro', 'settings', 'mcp.json'),
+    container: 'mcpServers',
+    urlField: 'url',
+    entry: (bearer) => ({ url: ENDPOINT, headers: mcpHeaders(bearer, 'kiro') }),
+    rules: '它读 .kiro/steering/*.md（steering 文件），安装器不写别人的规则文件',
+    ruleHint: '想让 Kiro 主动去查，把规则加进 .kiro/steering/',
+    manual: '重启 Kiro 后用它的 MCP 面板复核 misakanet（Kiro 还支持 disabled / autoApprove 字段）',
+    verifyHint: '用 Kiro 的 MCP 面板复核',
+  },
+};
+
 /**
  * The files each assistant's install writes, so a permission problem can be reported *before*
  * anything is touched (and so `--dry-run` can say "I cannot change that" as well as "I would change
@@ -295,9 +425,111 @@ const AGENT_WRITE_PATHS = {
   codex: (home) => [join(home, '.codex', 'config.toml'), join(home, '.codex', 'AGENTS.md')],
   hermes: (home) => [join(home, '.hermes', 'config.yaml'), join(home, '.hermes', 'SOUL.md')],
   codewhale: (home) => [join(home, '.codewhale', 'mcp.json')],
+  // Every MCP-only target writes exactly one file, so the table above is the single source of truth
+  // for the write manifest, the detection paths and the report's scope line.
+  ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS)
+    .map(([id, spec]) => [id, (home) => [spec.config(home)]])),
   openclaw: () => openclawWorkspaces().map((workspace) => join(workspace, 'AGENTS.md')),
 };
 
+/**
+ * The write manifest: every file this run would touch, with the kind of write and the tier it
+ * belongs to.
+ *
+ * One builder, two readers: `--list-writes` prints it for an operator who has to approve it, and
+ * the install preview prints it for the user who is about to say yes (#3690). They cannot drift,
+ * because there is only one list — a preview that disagrees with the manifest is worse than no
+ * preview at all.
+ *
+ * The tiers are the permission tiers from the top of this file: ① registers an MCP endpoint,
+ * ② writes a rules block (that changes how the agent behaves), ③ installs hooks and state (that
+ * run on every turn). Under `--mcp-only` only ① is in scope, so the other two are not listed —
+ * the same rule the install itself follows.
+ */
+function buildWriteManifest(agents) {
+  // Compare base names, not separators: a `/settings.json$` regex silently classifies nothing on
+  // Windows (all three windows legs went red on the first CI run of this change), and a manifest
+  // that hides a tier is worse than no manifest.
+  const classify = (path) => {
+    const base = basename(path);
+    if (base === 'CLAUDE.md' || base === 'AGENTS.md' || base === 'SOUL.md') return { tier: 2, kind: 'rules' };
+    if (path.includes('.misakanet-agent')) return { tier: 3, kind: 'state' };
+    // `settings.json` carries both the read-only grants (①) and the hooks (③); the hook row is
+    // added separately below, and only when the hooks are in scope.
+    if (base === 'settings.json' && path.includes('.claude')) return { tier: 1, kind: 'grants' };
+    return { tier: 1, kind: 'mcp' };
+  };
+  const rows = new Map();
+  const add = (path, action, tier, kind) => {
+    const key = `${tier}|${path}`;
+    if (!rows.has(key)) rows.set(key, { path: redact(path), action, tier, kind });
+  };
+  for (const agent of agents) {
+    if (!detect(agent)) continue;
+    for (const path of (AGENT_WRITE_PATHS[agent] || (() => []))(HOME)) {
+      const { tier, kind } = classify(path);
+      add(path, existsSync(path) ? 'append-or-update' : 'create', tier, kind);
+      if (!MCP_ONLY && basename(path) === 'settings.json' && path.includes('.claude')) {
+        add(path, 'append-or-update（钩子）', 3, 'hook');
+      }
+    }
+  }
+  // The state dir is ours, but it is still written to disk — and only when there is something to
+  // install: with no target detected the run writes nothing at all.
+  if (agents.length) {
+    // `--no-register` registers no anonymous node, so no token is written; listing it anyway would
+    // make the manifest — and the preview's file count — promise a file that stays absent.
+    if (!has('--no-register')) add(join(stateDir(), 'token'), 'create (0600)', 1, 'token');
+    if (!MCP_ONLY) {
+      add(join(stateDir(), 'hook.mjs'), 'create', 3, 'hookScript');
+      add(join(stateDir(), STATE_VERSION_FILE), 'create', 3, 'version');
+    }
+  }
+  return [...rows.values()]
+    .filter((row) => (MCP_ONLY ? row.tier === 1 : true))
+    .sort((a, b) => a.tier - b.tier || a.path.localeCompare(b.path));
+}
+
+/**
+ * The preview: what this run is about to write, said *before* it writes it (#3690).
+ *
+ * A user who never opens a checkout has no way to know that an installer also edits the agent's
+ * rules file — and that file is the one that changes how the agent behaves. So the summary names
+ * the files, the kind of change, and the three ways out: look first (`--list-writes`), ask for the
+ * endpoint only (`--mcp-only`), or take it back (`--uninstall`).
+ *
+ * One line per file, one line of ways out, and every path redacted to `~` — the person reading
+ * this may never see a checkout, so nothing here may assume one.
+ */
+function writePreview(rows) {
+  const files = new Map();
+  for (const row of rows) {
+    const file = files.get(row.path) || { path: row.path, tier: row.tier, kinds: [] };
+    file.tier = Math.min(file.tier, row.tier);
+    file.kinds.push(row.kind);
+    files.set(row.path, file);
+  }
+  const list = [...files.values()].sort((a, b) => a.tier - b.tier || a.path.localeCompare(b.path));
+  if (!list.length) return '';
+  const labels = {
+    mcp: 'MCP 端点',
+    grants: '只读工具放行',
+    rules: '规则块（会改变 agent 的行为）',
+    hook: '钩子',
+    token: 'MCP 凭据',
+    hookScript: '钩子脚本',
+    version: '版本戳',
+    state: '本机状态',
+  };
+  const width = Math.min(Math.max(...list.map((f) => f.path.length)) + 2, 32);
+  const pad = (text) => (text.length >= width ? `${text} ` : text.padEnd(width));
+  return [
+    `将修改 ${list.length} 个文件${DRY ? '（--dry-run：只是预览，不写任何东西）' : ''}：`,
+    ...list.map((f) => `  ${pad(f.path)}+ ${f.kinds.map((k) => labels[k]).join(' + ')}`),
+    '先看：--list-writes   不改行为：--mcp-only   撤销：--uninstall',
+  ].join('\n');
+}
+
 /**
  * Which of these paths this process may not write.
  *
@@ -378,6 +610,19 @@ function ourHookEntries(hooks) {
 }
 
 /** Insert or refresh a marker-delimited block. Uses a function replacement (no $-escapes). */
+/**
+ * Is tier ③ (the behaviour layer) actually *wired*, or merely present on disk?
+ *
+ * `hook.mjs` living in our own state directory proves nothing about the user's agents: the hook only
+ * runs where a config file points at it, and today that is Claude Code alone. `--report` used to
+ * answer `install-scope: full` from the file's existence, so a Cursor-only machine claimed the
+ * behaviour layer was installed. It is `full` only when Claude Code's settings carry our entries.
+ */
+function hookWired() {
+  const settings = readJson(join(HOME, '.claude', 'settings.json'), null);
+  return ourHookEntries(settings?.hooks).length > 0;
+}
+
 function injectBlock(path, block) {
   const existing = readText(path);
   const pattern = new RegExp(`[ \\t]*<!--\\s*${START}\\s*-->[\\s\\S]*?<!--\\s*${END}\\s*-->\\n?`);
@@ -415,6 +660,58 @@ function stripBlock(path) {
 
 const stateDir = () => join(HOME, '.misakanet-agent');
 
+/**
+ * The headers every MCP entry we write carries.
+ *
+ * Two kinds, and the difference matters: `Authorization` is a credential (only when we have a token),
+ * while the other four are **self-declared hints** the service records on its analytics row — the
+ * stable pseudonym `X-MisakaNet-Client` (so a caller's history stays together without an account), the
+ * assistant name, the platform, and the installer version that wrote this. The endpoint treats them as
+ * hints and never as identity, which is what makes it acceptable to write them automatically
+ * (see AGENTS.md §3.3).
+ *
+ * Written only for agents whose config format supports custom headers; `--mcp-only` gets them too,
+ * because "the tool is callable" is exactly what tier ① means.
+ */
+function mcpHeaders(bearer, agent) {
+  const headers = {};
+  if (bearer) headers.Authorization = `Bearer ${bearer}`;
+  const clientId = declaredClientId();
+  if (clientId) headers['X-MisakaNet-Client'] = clientId;
+  headers['X-MisakaNet-Agent'] = agent;
+  headers['X-MisakaNet-Os'] = `${process.platform}/${process.arch}`.slice(0, 40);
+  headers['X-MisakaNet-Version'] = VERSION;
+  return headers;
+}
+
+/**
+ * The pseudonym to declare, or `''` when this machine has not said.
+ *
+ * Explicit intent beats a file we merely found, the same rule the register path applies. The file is
+ * `integrations/agent-autostart`'s (it keeps one there for the Python channel), so picking it up is
+ * continuity worth having — but it is data from outside this process on its way into three config
+ * 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 : '';
+}
+
 const CANONICAL_ENDPOINT = 'https://misakanet.org/mcp';
 
 /**
@@ -429,6 +726,38 @@ function probeEndpoint() {
   return (process.env.MISAKANET_ENDPOINT || CANONICAL_ENDPOINT).trim();
 }
 
+/**
+ * The proxy environment, and whether *this* Node will actually use it.
+ *
+ * Node's `fetch` ignores `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` unless the runtime is told to
+ * honour them — `NODE_USE_ENV_PROXY=1` or `--use-env-proxy`, with fetch support in v22.21.0 /
+ * v24.0.0+ (nodejs.org/learn/http/enterprise-network-configuration). So in an enterprise-proxy
+ * environment a failed probe is **not** evidence that the endpoint is down: `curl` and the user's
+ * agent may both be reaching it through a proxy this process never saw. Reporting that as
+ * "端点不可达（网络受限？）" sends a user whose install works off to debug a network that is fine —
+ * and the audience for this installer includes exactly the people whose proxies cause this.
+ *
+ * Returns `null` when no proxy is configured (the ordinary path), otherwise the variables in play
+ * and whether the runtime was told to use them.
+ */
+function proxyEnvironment() {
+  const vars = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy']
+    .filter((name) => (process.env[name] || '').trim());
+  if (!vars.length) return null;
+  const enabled = Boolean((process.env.NODE_USE_ENV_PROXY || '').trim())
+    || process.execArgv.some((arg) => arg.includes('use-env-proxy'))
+    || (process.env.NODE_OPTIONS || '').includes('use-env-proxy');
+  return { vars, enabled, noProxy: (process.env.NO_PROXY || process.env.no_proxy || '').trim() };
+}
+
+/** The one line that turns an inconclusive probe into a next action. */
+function proxyProbeAdvice(proxy) {
+  return `本机配了代理（${proxy.vars.join('、')}），而 Node 的 fetch 默认不读这些变量 → 探测结果不可信，`
+    + '不代表端点不可达。确认方式：先 `curl -sS https://misakanet.org/mcp` 手测，'
+    + '或让 Node 走代理重跑：`NODE_USE_ENV_PROXY=1 npx @misaka-net/misakanet-setup --verify`'
+    + '（fetch 需要 Node ≥ 22.21.0 / 24.0.0；公司代理做 TLS 拦截时再加 `NODE_USE_SYSTEM_CA=1`）';
+}
+
 /**
  * One unauthenticated MCP call.
  *
@@ -547,7 +876,7 @@ const PROMPT_BLOCK = `调用规则（按顺序照做）：
 5) 查不到就 misakanet_submit_intake(kind="question")。
 6) 约 20 轮后、或刚解决一个非平凡问题时：把本次「失败→根因→修复→验证」里可泛化、有判据、且搜过没有重复的部分，
    脱敏后 misakanet_submit_intake(kind="missing_lesson") 提交；不够价值就不提交。
-脱敏：密钥/凭据→<REDACTED>，人名/邮箱/真实域名/绝对家目录→泛化。全程不要打断用户任务。`;
+脱敏：已由代码自动完成——本地钩子发出的查询在离开本机前、服务端入库前，都会把密钥/绝对路径/邮箱换成占位符；你不必手动改写，但仍不要粘整段会话转录或与故障无关的业务机密。全程不要打断用户任务。`;
 
 // ── the hook file: shipped in the package, downloaded only if missing ─
 /**
@@ -661,6 +990,16 @@ async function installHook() {
 }
 
 async function ensureIdentity() {
+  // The explicit intent is read first, because it decides the `X-MisakaNet-Client` hint on every run
+  // — including one that registers nothing (the token is already there) — so it cannot sit below the
+  // early returns. `--client-id` and `MISAKANET_CLIENT_ID` are the same intent.
+  const explicit = (valueOf('--client-id', '') || process.env.MISAKANET_CLIENT_ID || '').trim();
+  const usable = CLIENT_ID_SHAPE.test(explicit);
+  if (explicit && !usable) {
+    need('ignored --client-id / MISAKANET_CLIENT_ID：只接受 8–64 位的 [A-Za-z0-9._-]（这次会新生成一个）');
+  }
+  if (usable) knownClientId = explicit;
+
   const file = join(stateDir(), 'token');
   let existing = '';
   try {
@@ -685,32 +1024,44 @@ async function ensureIdentity() {
   // `--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 exported = (valueOf('--client-id', '') || process.env.MISAKANET_CLIENT_ID || '').trim();
-  if (exported && !/^[A-Za-z0-9._-]{8,64}$/.test(exported)) {
-    need('ignored --client-id / MISAKANET_CLIENT_ID：只接受 8–64 位的 [A-Za-z0-9._-]（这次会新生成一个）');
-  }
-  const clientId = (exported && /^[A-Za-z0-9._-]{8,64}$/.test(exported))
-    ? exported
-    : `setup-${randomUUID()}`;
-  const result = await mcpCall('misakanet_register', { agent_type: 'setup', client_id: clientId });
+  const clientId = usable ? explicit : `setup-${randomUUID()}`;
+  knownClientId = 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
   // a visible, debuggable outcome instead of a silent 401 later.
   const token = typeof result?.token === 'string' ? result.token.trim() : '';
   if (!/^mcp_[A-Za-z0-9_-]{20,}$/.test(token)) {
-    // Say what it costs, not what went wrong internally: "凭据形状不对" is jargon, and
-    // "读课程不受影响" was misleading — without a token the read path is capped at the anonymous
-    // quota. Someone who does not know that will hit a wall five queries later and blame the tool.
-    need('匿名注册没成功（多半是网络）→ 现在检索限额是每天 5 次/IP，写入类工具也用不了；'
-      + '网络恢复后重跑本命令就能拿到 token，其它功能不受影响');
+    // 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.
+    //
+    // 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
   // which the token sat in a world-readable file on every single run.
   writeText(file, token, { mode: 0o600 });
   ok(`匿名身份：${String(result.node_id || '?').slice(0, 32)}（token 存 ${file}，权限 600）`);
-  if (!exported) {
+  if (!usable) {
     // Printed, not stored: this process must not turn a file it found into request data
     // (CodeQL js/file-access-to-http #268), and the value is the user's to keep anyway.
     // Kept out of the "done" list on purpose — it is something to *keep*, not something that
@@ -722,6 +1073,20 @@ async function ensureIdentity() {
 }
 
 // ── per-agent install ────────────────────────────────────────────────
+/** Is our MCP entry already in this agent's config? (read-only; used by the report's scope line) */
+function mcpEntryPresent(agent) {
+  const text = {
+    claude: () => JSON.stringify(readJson(join(HOME, '.claude.json'), {})?.mcpServers?.misakanet || null),
+    codex: () => readText(join(HOME, '.codex', 'config.toml')),
+    hermes: () => readText(join(HOME, '.hermes', 'config.yaml')),
+    openclaw: () => readText(join(HOME, '.openclaw', 'openclaw.json')),
+    codewhale: () => readText(join(HOME, '.codewhale', 'mcp.json')),
+    ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS)
+      .map(([id, spec]) => [id, () => readText(spec.config(HOME))])),
+  }[agent]?.() || '';
+  return text.includes('misakanet') && text !== 'null';
+}
+
 function detect(agent) {
   const paths = {
     claude: ['.claude.json', '.claude'],
@@ -729,6 +1094,7 @@ function detect(agent) {
     hermes: ['.hermes'],
     openclaw: ['.openclaw'],
     codewhale: ['.codewhale'],
+    ...Object.fromEntries(Object.entries(MCP_ONLY_TARGETS).map(([id, spec]) => [id, spec.detect])),
   }[agent] || [];
   return paths.some((p) => existsSync(join(HOME, p)));
 }
@@ -742,8 +1108,7 @@ async function installClaude(hookPath, bearer) {
   }
   const doc = data || {};
   doc.mcpServers = doc.mcpServers || {};
-  const entry = { type: 'http', url: ENDPOINT };
-  if (bearer) entry.headers = { Authorization: `Bearer ${bearer}` };
+  const entry = { type: 'http', url: ENDPOINT, headers: mcpHeaders(bearer, 'claude-code') };
   if (sameJson(doc.mcpServers.misakanet, entry)) {
     ok('Claude Code：MCP 已注册（无改动）');
   } else {
@@ -754,8 +1119,30 @@ async function installClaude(hookPath, bearer) {
   }
 
   const rules = join(HOME, '.claude', 'CLAUDE.md');
-  ok(`Claude Code：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
-
+  if (!MCP_ONLY) ok(`Claude Code：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+  else skip('Claude Code：规则块未写（--mcp-only：只注册端点）');
+
+  if (MCP_ONLY) {
+    // Tier ① = "the tool can be called", and that includes the read-only grants: the comment below
+    // says it plainly — without them the first search is *denied*, so an operator who approved
+    // "add an MCP server" would be shipping a tool their users cannot use. The grants are therefore
+    // tier ①. What tier ③ adds is the hooks, and those are not written here.
+    const settingsPath = join(HOME, '.claude', 'settings.json');
+    const settings = readJson(settingsPath, {}) || {};
+    const allow = ((settings.permissions = settings.permissions || {}).allow =
+      Array.isArray(settings.permissions.allow) ? settings.permissions.allow : []);
+    let changed = false;
+    for (const tool of CLAUDE_ALLOWED_TOOLS) {
+      if (!allow.includes(tool)) { allow.push(tool); changed = true; }
+    }
+    if (changed) {
+      backup(settingsPath);
+      writeText(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    }
+    ok(`Claude Code：只读工具已放行（${CLAUDE_ALLOWED_TOOLS.length} 个${changed ? '' : '，无改动'}）`);
+    skip('Claude Code：自动沉淀钩子未装（--mcp-only：只注册端点与工具放行）');
+    return;
+  }
   if (!hookPath) {
     need('Claude Code：跳过了"自动沉淀"钩子（钩子文件没取到）');
     return;
@@ -852,12 +1239,17 @@ async function installClaude(hookPath, bearer) {
 
 const codexTable = (bearer) => {
   const lines = ['[mcp_servers.misakanet]', 'type = "streamable-http"', `url = "${ENDPOINT}"`];
-  if (bearer) {
-    // http_headers, not bearer_token_env_var: the env var needs the user to export it, and
-    // this user will not.
-    lines.push(`http_headers = { Authorization = "Bearer ${bearer}" }`);
-  } else {
-    lines.push('# 没有 token：读走匿名通道（5/天/IP）');
+  // http_headers, not bearer_token_env_var: the env var needs the user to export it, and this user
+  // will not. All the headers go into the ONE inline table — a second `http_headers` line is a
+  // duplicate key, and TOML refuses the whole file for it. (Bare TOML keys may contain `-`, which is
+  // why the hint names need no quoting.)
+  const headers = Object.entries(mcpHeaders(bearer, 'codex'))
+    .map(([key, value]) => `${key} = "${value}"`).join(', ');
+  lines.push(`http_headers = { ${headers} }`);
+  if (!bearer) {
+    // Only worth saying when it is true. Since 2026-09-18 anonymous reads are not metered — what a
+    // token buys is the write path, not more reads.
+    lines.push('# 没有 token：读不限次数，写入类工具（write_lesson）不可用');
   }
   return `${lines.join('\n')}\n`;
 };
@@ -909,7 +1301,8 @@ async function installCodex(hookPath, bearer) {
   }
 
   const rules = join(HOME, '.codex', 'AGENTS.md');
-  ok(`Codex：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+  if (!MCP_ONLY) ok(`Codex：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+  else skip('Codex：规则块未写（--mcp-only：只注册端点）');
   // Verified on codex-cli 0.154.0 (2026-09-15), so this is no longer a "could not
   // confirm" note: `codex mcp list` shows misakanet enabled with the Bearer token,
   // `codex doctor` reports config.toml parse ok + 1 streamable_http server + 0
@@ -1036,11 +1429,18 @@ async function installHermes(hookPath, bearer) {
     need('Hermes：找不到 ~/.hermes/config.yaml → 先运行一次 hermes 再回来装');
     return;
   }
-  ok(`Hermes：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+  if (!MCP_ONLY) ok(`Hermes：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+  else skip('Hermes：规则块未写（--mcp-only：只注册端点；SOUL.md 是它的人格文件）');
 
   const envKey = HERMES_ENV_KEY;
   const lines = [`  misakanet:  ${YAML_START}`, `    url: ${ENDPOINT}`];
-  if (bearer) lines.push('    headers:', `      Authorization: Bearer \${${envKey}}`);
+  lines.push('    headers:');
+  if (bearer) lines.push(`      Authorization: Bearer \${${envKey}}`);
+  // Hermes reads its headers from YAML, so these are literals rather than env templates: they are
+  // hints, not secrets (a token would have to go through `.env` like the Authorization line above).
+  for (const [key, value] of Object.entries(mcpHeaders('', 'hermes'))) {
+    lines.push(`      ${key}: ${value}`);
+  }
   lines.push(`  ${YAML_END}`);
   // No trailing newline: the three call sites below each own the one they need, and the
   // "insert after mcp_servers:" case must NOT add one (the line it replaces already ends with
@@ -1068,7 +1468,7 @@ async function installHermes(hookPath, bearer) {
   }
 
   if (!bearer) {
-    skip('Hermes：这次没有 token → 走匿名通道（5/天/IP），写入类工具不可用');
+    skip('Hermes：这次没有 token → 读仍然不限次数，写入类工具不可用');
     return;
   }
   const envPath = join(HOME, '.hermes', '.env');
@@ -1117,6 +1517,11 @@ async function installHermes(hookPath, bearer) {
  * The token is the one thing codewhale will not take inline: `bearer_token_env_var` names
  * an environment variable, so "install once" for this agent ends with the user exporting
  * `MISAKANET_TOKEN` once. That is stated rather than silently half-installed.
+ *
+ * This is also the one agent that gets no `X-MisakaNet-*` hints: its server entry has a fixed
+ * field set (`command`/`args`/`env`/`url`/timeouts/`bearer_token_env_var`) with no custom-header
+ * field, and inventing one would risk the file being rejected outright. Hints are optional by
+ * design — a call without them is still a normal anonymous read.
  */
 function codewhaleProjects() {
   const text = readText(join(HOME, '.codewhale', 'config.toml'));
@@ -1166,7 +1571,9 @@ async function installCodewhale(bearer) {
   const projects = codewhaleProjects();
   for (const project of projects) {
     if (!existsSync(project)) continue;
-    ok(`codewhale：规则块 ${injectBlock(join(project, 'AGENTS.md'), PROMPT_BLOCK)} → ${join(project, 'AGENTS.md')}`);
+    if (!MCP_ONLY) {
+      ok(`codewhale：规则块 ${injectBlock(join(project, 'AGENTS.md'), PROMPT_BLOCK)} → ${join(project, 'AGENTS.md')}`);
+    } else skip('codewhale：规则块未写（--mcp-only）');
   }
   if (!projects.length) {
     need('codewhale：没有受信任的项目目录（config.toml 里没有 trust_level = "trusted"）→ '
@@ -1183,7 +1590,8 @@ async function installOpenclaw(bearer) {
   if (!existsSync(workspace)) {
     need(`OpenClaw：找不到 workspace（${workspace}）→ 先运行一次 openclaw 生成它`);
   } else {
-    ok(`OpenClaw：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+    if (!MCP_ONLY) ok(`OpenClaw：规则块 ${injectBlock(rules, PROMPT_BLOCK)} → ${rules}`);
+    else skip('OpenClaw：规则块未写（--mcp-only）');
   }
 
   const cfg = join(HOME, '.openclaw', 'openclaw.json');
@@ -1193,8 +1601,8 @@ async function installOpenclaw(bearer) {
       + `或手动执行 \`${manual}\``);
     return;
   }
-  const entry = { url: ENDPOINT, transport: 'streamable-http' };
-  if (bearer) entry.headers = { Authorization: `Bearer ${bearer}` };
+  const entry = { url: ENDPOINT, transport: 'streamable-http',
+                  headers: mcpHeaders(bearer, 'openclaw') };
   data.mcp = data.mcp || {};
   data.mcp.servers = data.mcp.servers || {};
   if (sameJson(data.mcp.servers.misakanet, entry)) {
@@ -1207,11 +1615,77 @@ async function installOpenclaw(bearer) {
   ok(`OpenClaw：注册 MCP（streamable-http）→ ${cfg}`);
 }
 
+/**
+ * Install one MCP-only target: read its JSON, merge our entry under the vendor's own key path, write.
+ *
+ * File-to-file, never a subprocess, so no token ever reaches a command line. An existing file is
+ * preserved (other servers, other keys) and backed up first; a file we cannot parse stops at a manual
+ * step that names exactly what to paste, because guessing at a half-written config is how a user
+ * loses the servers they already had.
+ */
+async function installMcpOnly(agent, bearer) {
+  const spec = MCP_ONLY_TARGETS[agent];
+  const cfg = spec.config(HOME);
+  const data = readJson(cfg, null);
+  if (data === null && readText(cfg)) {
+    need(`${spec.label}：${cfg} 不是合法 JSON${spec.parseNote ? `（${spec.parseNote}）` : ''}`
+      + ` → 请手动加入 ${spec.container}.misakanet（形状见 https://misakanet.org/mcp 的客户端文档）`);
+    return;
+  }
+  const doc = data || {};
+  doc[spec.container] = doc[spec.container] || {};
+  const entry = spec.entry(bearer);
+  if (sameJson(doc[spec.container].misakanet, entry)) {
+    ok(`${spec.label}：MCP 已注册（无改动）`);
+  } else {
+    doc[spec.container].misakanet = entry;
+    backup(cfg);
+    writeText(cfg, `${JSON.stringify(doc, null, 2)}\n`);
+    ok(`${spec.label}：注册 MCP → ${cfg}`);
+  }
+  skip(`${spec.label}：没有规则块与钩子（${spec.rules}）→ ${spec.ruleHint}`);
+  need(`${spec.label}：${spec.manual}`);
+}
+
 // The last endpoint probe, recorded so `--report` can print it without probing twice.
-let lastProbe = { reachable: false, tools: 0 };
+let lastProbe = { reachable: false, tools: 0, note: '' };
+
+/**
+ * The advice for a file we could not write.
+ *
+ * It has to be an advice that can work — and "re-run the install command" is not one: the file is
+ * read-only or the permissions do not allow it, so a re-run writes exactly as much as the last one
+ * did. Measured 2026-10-22 on an OpenClaw machine whose workspace was root-owned and read-only:
+ * `--verify` said "规则块没装 → 重跑安装命令", and the trialer went after the network, the
+ * permissions and the gateway while the installer had already named the real blocker.
+ *
+ * The question is asked the way the installer asks it before writing (`canCreateHere`): by
+ * attempting the access, never by `existsSync` first.
+ */
+function unwritableAdvice(manual = '') {
+  const fix = '改权限（或换到可写的目录）后再重跑';
+  return manual
+    ? `只读或权限不足，重跑也写不进去 → ${manual}（或${fix}）`
+    : `只读或权限不足，重跑也写不进去 → ${fix}`;
+}
 
 async function verify() {
   let allOk = true;
+  // The report answers two different questions, and one of them failing must not condemn the
+  // other (issue #3696): "can you use it" (the endpoint answers) and "are the files we prefer
+  // written" (our own footprint). A machine whose endpoint answers and whose workspace is
+  // read-only is **usable** — and the old verdict called it NOT READY.
+  let usable = true;
+  // The probe has three answers, not two: a probe that could not run is not a probe that failed.
+  // "unknown" is reported as unknown, and only `--strict` refuses to pass on it.
+  let probeState = 'ready';
+  // The install segment is judged on its own: a file we cannot write is a fact about our
+  // footprint, and it says nothing about the endpoint.
+  let installOk = true;
+  const installFailed = () => { installOk = false; allOk = false; };
+  // Where each segment starts, in the three line lists. The output prints the two segments as
+  // two sections, and this boundary is the only thing that has to be right about them.
+  const segmentStart = { done: done.length, manual: manual.length, skipped: skipped.length };
   // Handshake, not a search. `tools/list` proves the endpoint speaks MCP and answers, and it
   // consumes no anonymous read quota — so `--verify` can be run as often as the user likes. The
   // search used to be the probe, which spent one of the five free reads per run and, worse,
@@ -1231,18 +1705,46 @@ async function verify() {
       const missing = CLAUDE_ALLOWED_TOOLS.filter((tool) => !granted.includes(tool));
       if (detect('claude') && missing.length) {
         allOk = false;
+        // Not an install fact: the endpoint answers, and the search still fails. It belongs to
+        // the usability segment, so it belongs there in the output too.
+        usable = false;
         need(`Claude Code：只读 MCP 工具没有放行（${missing.length} 个）→ 第一次检索会被权限拦下；`
           + '重跑安装命令即可放行');
       }
     } catch { /* a settings file we cannot read is reported by the Claude checks below */ }
   } else if (probe && (probe.error || probe.protocolVersion || probe.serverInfo)) {
     allOk = false;
+    usable = false;
+    probeState = 'not-ready';
     need(`端点可达但握手异常：${JSON.stringify(probe).slice(0, 120)}`);
   } else {
-    allOk = false;
-    need(`端点不可达：${ENDPOINT}（网络受限？读课程会静默失败）`
-      + (lastRequestError ? ` —— 最近一次失败原因：${lastRequestError}` : ''));
+    const proxy = proxyEnvironment();
+    if (proxy && !proxy.enabled) {
+      // Inconclusive rather than unreachable. Interactive runs warn (a visible `!` that does not
+      // flip the verdict), because the install itself is fine and the user's agent may well be
+      // reaching the endpoint through that proxy. `--strict` / `--ci` keep a hard verdict: a gate
+      // that cannot tell must not pass silently, and CI machines are the ones actually configured
+      // to make the probe trustworthy.
+      lastProbe = { reachable: false, tools: 0, note: 'inconclusive-proxy' };
+      probeState = 'unknown';
+      if (STRICT) {
+        allOk = false;
+        usable = false;
+        need(`端点探测不可信，且 --strict 不接受"说不清"：${proxyProbeAdvice(proxy)}`);
+      } else {
+        need(`端点探测不可信（不是"不可达"）：${proxyProbeAdvice(proxy)}`);
+      }
+    } else {
+      allOk = false;
+      usable = false;
+      probeState = 'not-ready';
+      need(`端点不可达：${ENDPOINT}（网络受限？读课程会静默失败）`
+        + (lastRequestError ? ` —— 最近一次失败原因：${lastRequestError}` : ''));
+    }
   }
+  // The endpoint segment ends here. Everything below is about our own footprint: the files we
+  // write, the entries we register, the token we keep.
+  const segmentEnd = { done: done.length, manual: manual.length, skipped: skipped.length };
   const tokenFile = join(stateDir(), 'token');
   let tokenPresent = '';
   try {
@@ -1251,45 +1753,63 @@ async function verify() {
     tokenPresent = '';
   }
   if (tokenPresent) {
-    ok('写入通道：token 已就绪（解除每天 5 次读限额，write_lesson 可用）');
-  } else {
-    skip('写入通道：无 token（只读也完全可用，但读有 5/天/IP 限额）');
-  }
-  const hookPath = join(stateDir(), 'hook.mjs');
-  let hookPresent = false;
-  try {
-    hookPresent = readFileSync(hookPath, 'utf8').length > 0;
-  } catch {
-    hookPresent = false;
-  }
-  if (!hookPresent) {
-    allOk = false;
-    need('自动沉淀钩子：缺失 → 重跑安装命令');
+    ok('写入通道：token 已就绪（write_lesson / preflight 可用）');
   } else {
-    const settingsPath = join(HOME, '.claude', 'settings.json');
-    const settings = readJson(settingsPath, {}) || {};
-    // Only our own entries: a foreign hook that merely mentions "hook.mjs" is not evidence
-    // that this machine is installed (and its interpreter may not even be ours).
-    const commands = ourHookEntries(settings.hooks)
-      .flatMap((entry) => (entry.hooks || []).map((h) => h.command))
-      .filter((c) => typeof c === 'string');
-    if (!commands.length) {
-      allOk = false;
-      need('Claude Code：钩子没装（settings.json 里没有本安装器写入的命令）');
+    // Which token this is looking for, said out loud: it reads **our own** state directory, so a
+    // machine that got its token through another channel (mcporter, a gateway) shows "no token"
+    // here even though writes work. The trialer read that as "nothing is set up".
+    skip('写入通道：无 token（这一项只检查本安装器状态目录里的 token；如果 token 来自别的通道，'
+      + '读路径完全不受影响——读不限次数、只读完全可用，写入类工具不可用）');
+  }
+  // The hook is Claude Code's alone: it is the one target whose config carries it (Codex's
+  // user-level hook shape is unconfirmed, OpenClaw's events are unverified), so a machine without
+  // Claude Code must not be told its hook is missing. Until 2026-09-20 it was: a Codex-only or
+  // Cursor-only install reported NOT READY with two Claude Code complaints about a target that was
+  // never selected — the same lie the OpenClaw and Hermes checks below already refuse to tell
+  // (found while adding Cursor, which is mcp-only by construction).
+  if (detect('claude')) {
+    const hookPath = join(stateDir(), 'hook.mjs');
+    let hookPresent = false;
+    try {
+      hookPresent = readFileSync(hookPath, 'utf8').length > 0;
+    } catch {
+      hookPresent = false;
+    }
+    if (!hookPresent) {
+      installFailed();
+      need(canCreateHere(hookPath)
+        ? '自动沉淀钩子：缺失 → 重跑安装命令'
+        : `自动沉淀钩子：装不了（${hookPath}）→ ${unwritableAdvice()}`);
     } else {
-      const exe = commands[0].startsWith('"') ? commands[0].split('"')[1] : commands[0].split(' ')[0];
-      if (!existsSync(exe)) {
-        allOk = false;
-        need(`Claude Code：钩子里的解释器不存在（${exe}）→ 钩子永远不会触发，重跑安装命令即可修`);
+      const settingsPath = join(HOME, '.claude', 'settings.json');
+      const settings = readJson(settingsPath, {}) || {};
+      // Only our own entries: a foreign hook that merely mentions "hook.mjs" is not evidence
+      // that this machine is installed (and its interpreter may not even be ours).
+      const commands = ourHookEntries(settings.hooks)
+        .flatMap((entry) => (entry.hooks || []).map((h) => h.command))
+        .filter((c) => typeof c === 'string');
+      if (!commands.length) {
+        installFailed();
+        need('Claude Code：钩子没装（settings.json 里没有本安装器写入的命令）');
       } else {
-        ok('Claude Code：钩子已装且解释器存在');
+        const exe = commands[0].startsWith('"') ? commands[0].split('"')[1] : commands[0].split(' ')[0];
+        if (!existsSync(exe)) {
+          installFailed();
+          need(`Claude Code：钩子里的解释器不存在（${exe}）→ 钩子永远不会触发，重跑安装命令即可修`);
+        } else {
+          ok('Claude Code：钩子已装且解释器存在');
+        }
       }
+      const cfg = join(HOME, '.claude.json');
+      const data = readJson(cfg, {}) || {};
+      const entry = data.mcpServers?.misakanet;
+      if (!entry) {
+        installFailed();
+        need(canCreateHere(cfg)
+          ? `Claude Code：MCP 未注册（${cfg}）`
+          : `Claude Code：MCP 未注册（${cfg}）→ ${unwritableAdvice()}`);
+      } else ok(`Claude Code：MCP 已注册（${entry.url}）`);
     }
-    const cfg = join(HOME, '.claude.json');
-    const data = readJson(cfg, {}) || {};
-    const entry = data.mcpServers?.misakanet;
-    if (!entry) { allOk = false; need(`Claude Code：MCP 未注册（${cfg}）`); }
-    else ok(`Claude Code：MCP 已注册（${entry.url}）`);
   }
   // OpenClaw is only reported when the user actually has it: telling a machine without
   // OpenClaw that it is "not ready" would be a lie about a target that was never selected.
@@ -1298,17 +1818,23 @@ async function verify() {
   if (detect('openclaw')) {
     const rules = join(openclawWorkspaces()[0], 'AGENTS.md');
     if (!readText(rules).includes(`<!-- ${START} -->`)) {
-      allOk = false;
-      need(`OpenClaw：规则块没装（${rules}）→ 重跑安装命令`);
+      installFailed();
+      // "没装" and "装不了" are different facts with different fixes, and the difference is the
+      // whole point (issue #3696): a read-only workspace is not something a re-run installs.
+      need(canCreateHere(rules)
+        ? `OpenClaw：规则块没装（${rules}）→ 重跑安装命令`
+        : `OpenClaw：规则块装不了（${rules}）→ ${unwritableAdvice()}`);
     } else {
       ok('OpenClaw：规则块已装');
     }
     const cfg = join(HOME, '.openclaw', 'openclaw.json');
     const entry = (readJson(cfg, null) || {}).mcp?.servers?.misakanet;
     if (!entry) {
-      allOk = false;
-      need(`OpenClaw：MCP 未注册（${cfg}）→ 重跑安装命令，或手动执行 `
-        + `openclaw mcp add misakanet --url ${ENDPOINT} --transport streamable-http`);
+      installFailed();
+      const manual = `openclaw mcp add misakanet --url ${ENDPOINT} --transport streamable-http`;
+      need(canCreateHere(cfg)
+        ? `OpenClaw：MCP 未注册（${cfg}）→ 重跑安装命令，或手动执行 ${manual}`
+        : `OpenClaw：MCP 未注册（${cfg}）→ ${unwritableAdvice(manual)}`);
     } else {
       ok(`OpenClaw：MCP 已注册（${entry.url || '?'}）`);
     }
@@ -1319,25 +1845,50 @@ 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 → 匿名 5 次/天/IP）');
-      skip(`Hermes：想让检索不计匿名额度，重跑安装命令即可写入 ${HERMES_ENV_KEY}`);
+      ok('Hermes：MCP 条目已写入配置（无 token → 读不限次数，写入类工具不可用）');
+      skip(`Hermes：想让写入类工具可用（write_lesson），重跑安装命令即可写入 ${HERMES_ENV_KEY}`);
     } else {
       ok(`Hermes：MCP 条目与 token 都在（${HERMES_ENV_KEY}）`);
       skip('Hermes：本进程只能确认"配置已写"，无法确认 Hermes 是否已加载 → 可用 hermes mcp list 复核');
     }
   }
+  // The MCP-only targets are reported only when the user actually has them, like OpenClaw and
+  // Hermes. Their state is one JSON file, so it is readable without starting anything — but whether
+  // the client has *loaded* that file cannot be confirmed from here, and the line says so.
+  for (const [agent, spec] of Object.entries(MCP_ONLY_TARGETS)) {
+    if (!detect(agent)) continue;
+    const cfg = spec.config(HOME);
+    const entry = (readJson(cfg, null) || {})[spec.container]?.misakanet;
+    if (!entry) {
+      installFailed();
+      need(canCreateHere(cfg)
+        ? `${spec.label}：MCP 未注册（${cfg}）→ 重跑安装命令，然后${spec.verifyHint}`
+        : `${spec.label}：MCP 未注册（${cfg}）→ ${unwritableAdvice()}`);
+    } else if (!entry[spec.urlField]) {
+      installFailed();
+      need(`${spec.label}：MCP 条目在，但没有 ${spec.urlField} 字段（${cfg}）→ 重跑安装命令；`
+        + `这家用的是 ${spec.urlField}${spec.container === 'mcp' ? '（注意嵌套在 mcp 而不是 mcpServers 下）' : ''}`);
+    } else {
+      ok(`${spec.label}：MCP 已注册（${entry[spec.urlField]}）`);
+      skip(`${spec.label}：只能确认"配置已写"，无法确认它是否已加载 → ${spec.verifyHint}`);
+    }
+  }
   // Version: what is installed, and whether the registry has moved on. Read-only here — the
   // hook owns the periodic nudge (it cannot be a network call in this process's hot path), and
   // `--verify` is an explicit user action, so one lookup is both cheap and expected.
@@ -1360,7 +1911,72 @@ async function verify() {
         + 'npx @misaka-net/misakanet-setup@latest');
     }
   }
-  return allOk;
+  return {
+    allOk,
+    usable,
+    probeState,
+    install: installOk ? 'complete' : 'incomplete',
+    // The install segment's open items, counted on their own: the report's `open-items` is every
+    // manual item, this is the ones that belong to our footprint.
+    openItems: manual.length - segmentEnd.manual,
+    segments: { start: segmentStart, end: segmentEnd },
+  };
+}
+
+/**
+ * The two verdicts, in words.
+ *
+ * They are two answers to two questions, and the point of #3696 is that they are printed as two:
+ * a machine whose endpoint answers perfectly and whose workspace is read-only is **usable**, and
+ * the old single verdict said NOT READY about it — the one word that sends the user to debug the
+ * wrong thing.
+ */
+function usabilityText(verdict) {
+  if (verdict.probeState === 'not-ready') return '不就绪 —— 端点不可达或握手异常';
+  if (verdict.probeState === 'unknown') {
+    return STRICT
+      ? '不就绪 —— 探测不可信，--strict 不接受"说不清"'
+      : '说不清 —— 探测不可信（不等于不可达）';
+  }
+  if (!verdict.usable) return '不就绪 —— 端点可达，但只读工具没放行，第一次检索会被拦下';
+  return '就绪 —— 端点可达，检索与读取可用';
+}
+
+function installText(verdict) {
+  if (verdict.install === 'complete') return '完整 —— 我们偏好的文件都写好了';
+  return `不完整 —— ${verdict.openItems} 项需要手动处理（上面每条 ! 都给了成因和做法）`;
+}
+
+/**
+ * The verify output: two sections, because the two questions have two answers.
+ *
+ * The old output was one list, and one list cannot say "the endpoint answered, the files did not
+ * get written" — it can only say NOT READY, which is the sentence the OpenClaw trialer read as
+ * "MisakaNet does not work here" (issue #3696).
+ */
+function renderVerify(verdict) {
+  const { start, end } = verdict.segments;
+  const tail = { done: done.length, manual: manual.length, skipped: skipped.length };
+  const section = (label, from, to) => {
+    const out = [];
+    const finished = done.slice(from.done, to.done);
+    const open = manual.slice(from.manual, to.manual);
+    const ignored = skipped.slice(from.skipped, to.skipped);
+    // `--silent` drops the narration, never the errors (the same contract `render()` keeps): the
+    // `!` lines are what a human has to act on, the `✓` and `·` lines are progress.
+    if (finished.length && !SILENT) out.push(...finished.map((l) => `  ✓ ${l}`));
+    if (open.length) out.push(...open.map((l) => `  ! ${l}`));
+    if (ignored.length && !SILENT) out.push(...ignored.map((l) => `  · ${l}`));
+    if (!out.length) return out;
+    return [`\n── ${label} ──`, ...out];
+  };
+  return [
+    ...section('端点/可用性', start, end),
+    ...section('安装完整性', end, tail),
+    '',
+    `可用性：${usabilityText(verdict)}`,
+    `安装完整性：${installText(verdict)}`,
+  ].join('\n');
 }
 
 /**
@@ -1417,7 +2033,8 @@ function restoreEmptiedFiles() {
   // JSON configs: prune containers that our own removal emptied. The file itself is never deleted —
   // it may have existed before us (an empty `~/.claude.json` is a legitimate user state).
   const jsonFiles = [join(HOME, '.claude.json'), join(HOME, '.claude', 'settings.json'),
-                     join(HOME, '.openclaw', 'openclaw.json'), join(HOME, '.codewhale', 'mcp.json')];
+                     join(HOME, '.openclaw', 'openclaw.json'), join(HOME, '.codewhale', 'mcp.json'),
+                     ...Object.values(MCP_ONLY_TARGETS).map((spec) => spec.config(HOME))];
   for (const file of jsonFiles) {
     const data = readJson(file, null);
     if (!data || typeof data !== 'object') continue;
@@ -1484,6 +2101,16 @@ function uninstall() {
     writeText(cfg, `${JSON.stringify(data, null, 2)}\n`);
     ok(`移除 MCP 注册 → ${cfg}`);
   }
+  for (const spec of Object.values(MCP_ONLY_TARGETS)) {
+    const cfg = spec.config(HOME);
+    const data = readJson(cfg, null);
+    if (data?.[spec.container]?.misakanet) {
+      delete data[spec.container].misakanet;
+      backup(cfg);
+      writeText(cfg, `${JSON.stringify(data, null, 2)}\n`);
+      ok(`移除 MCP 注册 → ${cfg}`);
+    }
+  }
   const voiceDir = join(stateDir(), 'voice');
   if (existsSync(voiceDir)) {
     try {
@@ -1639,7 +2266,8 @@ function distroName() {
  * scalars (`true`, `[claude, codex]`, `""`); the JSON keeps their real types (boolean, array,
  * string), which is the whole point of a machine-readable form.
  */
-function reportValues(allOk) {
+function reportValues(verdict) {
+  const allOk = verdict.allOk;
   const agents = AGENTS.filter((agent) => detect(agent));
   const token = existsSync(join(stateDir(), 'token'));
   const permissions = (() => {
@@ -1659,11 +2287,27 @@ function reportValues(allOk) {
     ['node', process.version],
     ['detected-agents', agents],
     ['verify', allOk ? 'READY' : 'NOT READY'],
+    // The verdict has two halves, and a machine that collects this report needs to be able to
+    // tell them apart: `verify: NOT READY` because our files could not be written is a
+    // different machine from `verify: NOT READY` because the endpoint does not answer
+    // (issue #3696). `endpoint-reachable` and `endpoint-probe` below already say the endpoint's
+    // half; this is ours.
+    ['install-complete', verdict.install],
+    ['endpoint-usable', verdict.usable ? 'yes' : 'no'],
     ['endpoint-reachable', lastProbe.reachable],
     ['endpoint-tools', lastProbe.tools],
+    // `ok` = the probe ran and its answer is meaningful; `inconclusive-proxy` = the machine has a
+    // proxy this process cannot use, so the boolean above says nothing. Without this field the YAML
+    // a user pastes into a public issue cannot tell a real outage from a false negative.
+    ['endpoint-probe', lastProbe.note || 'ok'],
     ['token', token ? 'present' : 'absent'],
     ['permissions', permissions],
     ['hook', existsSync(join(stateDir(), 'hook.mjs')) ? 'present' : 'absent'],
+    // `mcp-only` = the endpoint is registered but the hooks are not, which is a different machine
+    // from "nothing installed" and must not be counted as one (#1753's T1-lite rows).
+    ['install-scope', hookWired()
+      ? 'full'
+      : (AGENTS.some((agent) => detect(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.
@@ -1738,10 +2382,10 @@ function reportJson(values) {
  * encoding never changes the verdict.
  */
 async function report(asJson) {
-  const allOk = await verify();
-  const values = reportValues(allOk);
+  const verdict = await verify();
+  const values = reportValues(verdict);
   console.log(asJson ? reportJson(values) : reportYaml(values));
-  return { allOk, openItems: manual.length };
+  return { ...verdict, openItems: manual.length };
 }
 
 // ── main ─────────────────────────────────────────────────────────────
@@ -1779,7 +2423,14 @@ if (mode !== 'report' && !SILENT) {
 
 if (mode === 'uninstall') {
   uninstall();
-  say(render());
+  if (MCP_ONLY) {
+  // The honest failure mode of tier ①: the tool is callable, but nothing tells the agent (or the
+  // user) to call it — the rules block and the first-turn announcement live in tiers ②/③. Printed
+  // as a "manual step" so it survives --silent (a deployment log keeps the `!` lines).
+  need('只注册了端点：你的 agent 不会自己想到去查 —— 需要你自己说「先查 MisakaNet」，'
+    + '或者请运营方批准 ②③ 后重跑同一条命令（去掉 --mcp-only）');
+}
+say(render());
   if (!SILENT) {
     console.log('\n已移除本安装器写入的内容（规则块、MCP 注册、钩子、状态目录）。');
     console.log(`备份保留在 <被改过的文件>.misakanet.bak（例如 ${join(HOME, '.claude', 'CLAUDE.md')}.misakanet.bak）`
@@ -1834,13 +2485,13 @@ if (mode === 'report') {
 }
 
 if (mode === 'verify') {
-  const allOk = await verify();
-  say(render());
+  const verdict = await verify();
+  say(renderVerify(verdict));
   // Kept under `--silent`: this line is the verdict, not progress. (It is also the only thing a
   // silent `--verify` prints when the machine is healthy, which is what makes it usable in a
   // deployment log.)
-  console.log(`\n结论：${allOk ? `READY —— 打开一个新会话，问它「${ONBOARDING_QUERIES[0]}」这类带报错原文的片段` : 'NOT READY —— 上面每条 ! 都给了修复动作'}`);
-  process.exit(allOk ? 0 : 1);
+  console.log(`\n结论：${verdict.allOk ? `READY —— 打开一个新会话，问它「${ONBOARDING_QUERIES[0]}」这类带报错原文的片段` : 'NOT READY —— 上面每条 ! 都给了成因和做法'}`);
+  process.exit(verdict.allOk ? 0 : 1);
 }
 
 const targets = (only.length ? only : AGENTS).filter((a) => {
@@ -1866,12 +2517,70 @@ const targets = (only.length ? only : AGENTS).filter((a) => {
 let installed = 0;
 // Set when a stable client id was minted: shown to the user at the end (see ensureIdentity).
 let clientIdHint = '';
+/**
+ * The pseudonym this run knows the machine by — an explicit `--client-id` / `MISAKANET_CLIENT_ID`, or
+ * the one this run minted. This is what `X-MisakaNet-Client` carries.
+ *
+ * Deliberately separate from `clientIdHint`, which exists only for the closing "keep this number"
+ * guidance: a user who supplied an id must not be told to keep it, but their config still has to say
+ * who they are — otherwise the hint would be missing for exactly the users who took the trouble to
+ * have an identity at all.
+ */
+let knownClientId = '';
+/**
+ * `--list-writes`: the manifest an operator needs to approve, or to undo by hand.
+ *
+ * `--dry-run` already says which files it would touch; this adds the two things an approval process
+ * asks for — *what* each write does (new file / append a marked block / add a config key) and *how to
+ * take it back* — and it is machine-readable so a ticket can carry it.
+ */
+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.
+  //
+  // 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 = buildWriteManifest(targets);
+  for (const row of list) {
+    console.log(`tier${row.tier}\t${tiers[row.tier]}\t${row.path}\t${row.action}`);
+  }
+  const shown = new Set(list.map((row) => row.tier));
+  if (MCP_ONLY) {
+    console.log('# --mcp-only：只申请 ①。规则块（②）与钩子（③）不会写入，'
+      + '需要时由运营方另行批准后重跑不带 --mcp-only 的同一条命令。');
+  } else {
+    console.log(`# 本次申请 ${shown.size} 级权限（${[...shown].sort().map((t) => tiers[t]).join(' · ')}）；`
+      + '只想批 ① 就加 --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 的配置目录 → 请先打开一次你要用的那个助手，再回来运行本命令');
+    need('没检测到任何受支持助手的配置目录（Claude Code / Codex / Hermes / OpenClaw / Codewhale / '
+      + 'Cursor）→ 请先打开一次你要用的那个助手，再回来运行本命令');
   } else {
-    const hookPath = await installHook();
-    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();
+    if (!MCP_ONLY) stampVersion();
     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
@@ -1891,6 +2600,7 @@ try {
         else if (agent === 'hermes') await installHermes(hookPath, bearer);
         else if (agent === 'openclaw') await installOpenclaw(bearer);
         else if (agent === 'codewhale') await installCodewhale(bearer);
+        else if (MCP_ONLY_TARGETS[agent]) await installMcpOnly(agent, bearer);
         installed += 1;
       } catch (err) {
         need(`${agent}：写入配置失败（${redact((err && err.message) || err)}）`
@@ -1909,6 +2619,13 @@ 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 (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
+  // (③), are exactly what makes an agent look things up on its own.
+  console.log('\n⚠️ --mcp-only：只注册了端点与只读工具放行 —— **你的 agent 不会自己想到去查**。'
+    + '\n   需要你自己说「先查 MisakaNet」，或请运营方批准 ②③ 后重跑同一条命令（去掉 --mcp-only）。');
+}
 if (!SILENT) {
   console.log(`
 接下来：