@misaka-net/misakanet-setup 0.5.4 → 0.5.6

package/README.md

@@ -16,7 +16,7 @@ knowledge base on its own instead of guessing.
 
 | # | Goal | Mechanism |
 |---|---|---|
-| 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json`, `~/.codex/config.toml` and `~/.openclaw/openclaw.json` (`mcp.servers.misakanet`), with the Bearer token so reads are not metered by the anonymous 5/day/IP limit. Hermes is the same thing in its own files: `mcp_servers.misakanet` in `~/.hermes/config.yaml` plus the token in `~/.hermes/.env` under `MCP_MISAKANET_API_KEY`. All four are config files written file-to-file — no subprocess is spawned, so **no token ever appears in a command line**. For Claude Code only, the five **read-only** tools are also added to `permissions.allow` — "can call it" otherwise still means a permission prompt on the very first search, so `0.5.3` pre-allows them (`--verify` reports it, `--report` prints `permissions:`); `write_lesson` is deliberately **not** pre-allowed, because a tool that writes should ask |
+| 1 | the agent **can** call it | MCP server `https://misakanet.org/mcp` (streamable HTTP) in `~/.claude.json`, `~/.codex/config.toml` and `~/.openclaw/openclaw.json` (`mcp.servers.misakanet`), with the Bearer token when registration succeeds — reads need no token (anonymous reads are unmetered since 2026-09-18); the token is what opens the **write** path. Every entry also carries the self-declared context hints `X-MisakaNet-Client` / `-Agent` / `-Os` / `-Version`, which the endpoint records on the read's analytics row and never treats as identity (`codewhale` is the one exception: its server entry has no custom-header field). Hermes is the same thing in its own files: `mcp_servers.misakanet` in `~/.hermes/config.yaml` plus the token in `~/.hermes/.env` under `MCP_MISAKANET_API_KEY`. All four are config files written file-to-file — no subprocess is spawned, so **no token ever appears in a command line**. For Claude Code only, the five **read-only** tools are also added to `permissions.allow` — "can call it" otherwise still means a permission prompt on the very first search, so `0.5.3` pre-allows them (`--verify` reports it, `--report` prints `permissions:`); `write_lesson` is deliberately **not** pre-allowed, because a tool that writes should ask |
 | 2 | the agent **knows when** | rules block appended to `~/.claude/CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.hermes/SOUL.md` / `~/.openclaw/workspace/AGENTS.md` (issue, retry, risky-operation triggers; desensitisation rules). Wording is **imperative first** ("必须先调 misakanet_search") rather than descriptive, because a field test showed a weaker model reads a descriptive block as background and never calls the tool |
 | 4 | *(opt-in)* you **hear** it | `--voice` adds a `PostToolUse` hook that plays the cue the server asked for (`lesson-found` / `failure-warning` / `connect-success` / `pair-success`). Off by default; mute with `MISAKANET_VOICE=0`; see `docs/integrations/mcp-voice-hooks.md` |
 | 3 | the checkpoint **fires** | a hook that counts user turns: turn 1 announces the install to the user, turn 20 (and every 10 after) injects the "distil and submit" reminder; a failed tool call injects a "search before you retry" reminder built from the error text. Claude Code only today — Codex's user-level hook shape is unconfirmed and OpenClaw's events are unverified, so those two work from the rules block, and `--verify` says so per target instead of implying otherwise |

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
@@ -25,13 +25,21 @@
  * 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, chmodSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, 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
 // another program (the plugin scanner's SHELL_INJECTION_PATTERN, alert #269, and argv secrets
 // are visible to every process on the box). Every target is configured by writing its own
 // config file; commands aimed at the user are printed, never executed.
+// `randomUUID` from `node:crypto`, not the global `crypto`: the global Web Crypto object only
+// became available without a flag in Node 19, so on Node 18 (which `engines` supports) any
+// registration crashed the whole run with `crypto is not defined` and exit code 2. Found
+// 2026-09-18 by the first Node 18 leg of misakanet-setup-ci.yml — the promise was in
+// 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));
@@ -70,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).
@@ -120,7 +147,87 @@ function readText(path) {
  * 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.
  */
-const VERSION = '0.5.4'
+const VERSION = '0.5.6'
+
+/**
+ * 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 CLIENT_ID_SHAPE = /^[A-Za-z0-9._-]{8,64}$/
+
+// ── argument surface ─────────────────────────────────────────────────
+// Until 2026-09-17 no flag was validated at all: `--help` fell through to a *real install*
+// (reproduced on a clean HOME — it rewrote the user's CLAUDE.md and settings.json), and an
+// unknown flag was silently ignored. `--help` is the first thing a cautious person types, so
+// "looking before you leap" was the action with the worst consequences.
+const FLAGS = [
+  ['--home <dir>', '把配置写到这个目录，而不是真实家目录（不是沙箱：--uninstall 也认这个目录）'],
+  ['--only <a,b>', `只处理列出的助手（${AGENTS.join(' / ')}）`],
+  ['--dry-run', '只说不做：打印会改哪些文件，不写任何东西'],
+  ['--silent', '只压掉进度叙述，绝不压掉 ! 行与报告（MDM/GPO 用）'],
+  ['--report', '打印一段可公开粘贴的脱敏状态报告（人读 YAML）'],
+  ['--report-json', '同一份报告的 JSON 编码'],
+  ['--strict', '配合 --report：NOT READY 时退出码 1（默认仍退 0）'],
+  ['--ci', '= --report --strict'],
+  ['--verify', '自检：端点可达、钩子、MCP 注册、版本新旧'],
+  ['--uninstall', '移除本安装器写入的内容（保留 .misakanet.bak 备份）'],
+  ['--upgrade', '与安装等价（覆盖安装即升级）'],
+  ['--client-id <id>', '固定本机身份：同一个 id 永远拿回同一个 node（重装/换机也能延续）'],
+  ['--mcp-only', '只注册 MCP 端点，不改 agent 行为（不写规则块、不装钩子）——权限分级用'],
+  ['--list-writes', '只打印会改哪些文件（文件 | 动作 | 撤销方式），不写任何东西'],
+  ['--no-register', '不注册匿名节点（不写 token；读不受影响，写入类工具不可用）'],
+  ['--voice', '打开语音/桌面通知（默认关）'],
+  ['--help, -h', '打印这份帮助并退出'],
+  ['--version', '打印版本并退出'],
+];
+const VALUE_FLAGS = ['--home', '--only', '--client-id'];
+
+function printHelp() {
+  console.log(`MisakaNet 安装程序 ${VERSION}
+用法：npx @misaka-net/misakanet-setup [选项]
+
+${FLAGS.map(([flag, desc]) => `  ${flag.padEnd(16)} ${desc}`).join('\n')}
+
+退出码（安装模式）：0 至少装上了一个助手 / 1 什么都没装上 / 2 自己跑不起来。
+健康检查用 --verify 或 --report --strict，不要看安装模式的退出码。`);
+}
+
+if (has('--help') || has('-h')) {
+  printHelp();
+  process.exit(0);
+}
+if (has('--version')) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+/** What we would write, and how to take it back — printed by --list-writes, and used by the report. */
+const WRITE_MANIFEST = [];
+
+const KNOWN = new Set(FLAGS.flatMap(([flag]) => flag.split(/[,\s]/).filter((f) => f.startsWith('-'))));
+{
+  const unknown = args.filter((a) => a.startsWith('-') && !KNOWN.has(a));
+  if (unknown.length) {
+    console.error(`无法识别的选项：${unknown.join(' ')}`
+      + `\n（本安装器不认识它，为避免误解你的意图，这里直接停下、什么都没写。--help 看全部选项。）`);
+    process.exit(2);
+  }
+  // A value flag whose value is missing or is itself a flag used to be accepted: `--home --voice`
+  // resolved HOME to `$(pwd)/--voice` and installed for real into a directory named `--voice`.
+  for (const flag of VALUE_FLAGS) {
+    const i = args.indexOf(flag);
+    if (i >= 0 && (!args[i + 1] || args[i + 1].startsWith('-'))) {
+      console.error(`${flag} 需要一个值（例如 ${flag} /tmp/home），现在后面跟的是 `
+        + `“${args[i + 1] ?? '空'}”——已停下，什么都没写。`);
+      process.exit(2);
+    }
+  }
+}
 
 function backup(path) {
   if (DRY || !readText(path)) return;
@@ -148,10 +255,161 @@ function sameJson(a, b) {
   return canonical(a) === canonical(b);
 }
 
-function writeText(path, text) {
+/**
+ * Write through a sibling temp file and rename it into place.
+ *
+ * A direct `writeFileSync` is not atomic: if the process dies (SIGINT, OOM, full disk) between
+ * truncating and finishing, the target is left half-written — and these targets are the user's
+ * `~/.claude.json`, `settings.json` and rule files, where "half-written" can mean an assistant that
+ * will not start. Proven, not assumed: after a direct write the file keeps its inode across a
+ * rewrite; after a `rename` it changes (pinned in workers/misakanet-setup.test.mjs).
+ *
+ * Two details that matter:
+ *   * `mode` is applied at creation, so a secret is never momentarily world-readable (the token and
+ *     the Hermes `.env` used to be written and then `chmod 600`-ed — a window on every run);
+ *   * an existing file that is not writable is still refused. `rename` would happily replace a
+ *     read-only file (it only needs write permission on the *directory*), so the previous EACCES
+ *     behaviour is kept explicitly rather than silently lost.
+ */
+function writeText(path, text, { mode } = {}) {
   if (DRY) return;
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, text);
+  if (existsSync(path)) {
+    try {
+      accessSync(path, constants.W_OK);
+    } catch {
+      const error = new Error(`EACCES: permission denied, open '${path}'`);
+      error.code = 'EACCES';
+      throw error;
+    }
+  }
+  const tmp = `${path}.misakanet-tmp`;
+  try {
+    // fsync, not just rename: `rename` guarantees the reader sees the old file or the new one, but
+    // it does not guarantee the *contents* reached the disk — a power loss after the rename can
+    // still leave an empty file. For an assistant config that is the difference between "the tool
+    // did not install" and "my assistant will not start". `writeFileSync` does not expose the
+    // descriptor, hence the explicit open/write/fsync/close.
+    const fd = openSync(tmp, 'w', mode ?? 0o666);
+    try {
+      writeSync(fd, text);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(tmp, path);
+  } catch (err) {
+    // Windows can refuse to replace an existing file with `rename` (EPERM when another process has
+    // the file open, EEXIST in some states). The old fallback was a direct `writeFileSync(path, …)`
+    // — which is the non-atomic write this function exists to avoid, and which truncates the user's
+    // config if the same lock is still held. Clearing the destination and retrying the rename keeps
+    // the replacement atomic, and when the file really is locked both attempts fail, so the caller
+    // reports "写入配置失败" instead of quietly writing half a config.
+    //
+    // (`writeFileSync` here also read as "write after a check on the same path" to CodeQL
+    // js/file-system-race — alert #272, the shape the fix above is about.)
+    if (err && (err.code === 'EPERM' || err.code === 'EEXIST')) {
+      rmSync(path, { force: true });
+      renameSync(tmp, path);
+      return;
+    }
+    try { rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    throw err;
+  }
+}
+
+/**
+ * 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
+ * this"). It mirrors what the per-agent install functions write; those keep their own try/catch as
+ * the safety net, because a mirror can fall out of date and the real error is still the truth.
+ */
+const AGENT_WRITE_PATHS = {
+  claude: (home) => [join(home, '.claude.json'), join(home, '.claude', 'settings.json'),
+                     join(home, '.claude', 'CLAUDE.md')],
+  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')],
+  openclaw: () => openclawWorkspaces().map((workspace) => join(workspace, 'AGENTS.md')),
+};
+
+/**
+ * Which of these paths this process may not write.
+ *
+ * Reported *before* anything is written, so a user without permission gets one clear list instead
+ * of a half-finished install. `--dry-run` uses the same list, which is what makes a dry run honest:
+ * it says "I would change this" and "I cannot change that" in the same breath.
+ */
+function unwritableTargets(paths) {
+  const blocked = [];
+  for (const path of paths) {
+    if (!canCreateHere(path)) blocked.push(path);
+  }
+  return blocked;
+}
+
+/**
+ * May this process create or overwrite `path`?
+ *
+ * Asked by *attempting* the access and reading the error, never by `existsSync(path)` first: a
+ * check-then-use pair is a race — the file can appear or disappear between the two calls, so the
+ * answer can describe a world that is already gone — and CodeQL reports exactly that shape as
+ * `js/file-system-race` (alerts #272/#273 on this file and its test, 2026-09-18). The attempt
+ * itself is also the *only* question with one answer: `access(W_OK)` on a file that does not exist
+ * yet says ENOENT, which is not "unwritable".
+ *
+ * When the file does not exist yet the question belongs to the nearest ancestor that does, because
+ * the install creates the missing parents (`mkdirSync(..., {recursive: true})`). The walk-up is
+ * what makes `--dry-run` honest on a first install: an earlier version asked about `dirname(path)`
+ * exactly once, so a home whose `~/.hermes` did not exist yet was reported "改不了" even though the
+ * installer was about to create that directory.
+ */
+function canCreateHere(path) {
+  for (let target = path; ;) {
+    try {
+      accessSync(target, constants.W_OK);
+      return true;
+    } catch (err) {
+      if (!err || err.code !== 'ENOENT') return false;   // EACCES/EROFS/EPERM/…
+      const parent = dirname(target);
+      if (parent === target) return false;               // walked up to the root: nothing exists
+      target = parent;
+    }
+  }
+}
+
+/**
+ * Is this settings.json hook entry one *this installer* wrote?
+ *
+ * Every command we install points into our own namespace directory
+ * (`<home>/.misakanet-agent/hook.mjs`, and `.../voice/voice-hook.mjs`), so that directory name
+ * is the identity marker. Matching the *filename* instead (`…includes('hook.mjs')`) treated a
+ * user's own `my-hook.mjs` as ours: `--uninstall` deleted the user's hook — reproduced
+ * 2026-09-17 — while `packages/misakanet-setup/README.md` promises "leaves your own hooks
+ * alone". The same loose test also made install skip adding our hook (believing it was
+ * already there) and made `--verify` report a foreign hook as ours.
+ *
+ * `checkpoint_reminder.mjs` is the legacy 0.4.x shape, from before the hook was copied into
+ * the state dir — our file name, not a generic one.
+ */
+function isOurHookEntry(entry) {
+  const commands = (entry?.hooks || [])
+    .map((h) => h?.command)
+    .filter((c) => typeof c === 'string');
+  // Namespace, not the absolute path: an entry written by an older install under a
+  // *different* HOME still points at `<something>/.misakanet-agent/hook.mjs`, and the 0.4.2
+  // upgrade path has to recognise exactly that (a fixture with /home/u covers it). Matching
+  // the directory name also survives Windows separators. `checkpoint_reminder.mjs` is the
+  // legacy shape from before the hook was copied into the state dir — our file name, not a
+  // generic one.
+  return commands.some(
+    (c) => c.includes('.misakanet-agent') || c.includes('checkpoint_reminder.mjs'),
+  );
+}
+
+/** Hook entries we wrote, across every event in a settings.json `hooks` object. */
+function ourHookEntries(hooks) {
+  return Object.values(hooks || {}).flat().filter(isOurHookEntry);
 }
 
 /** Insert or refresh a marker-delimited block. Uses a function replacement (no $-escapes). */
@@ -175,7 +433,10 @@ function injectBlock(path, block) {
 function stripBlock(path) {
   const text = readText(path);
   if (!text) return false;
-  const pattern = new RegExp(`[ \\t]*<!--\\s*${START}\\s*-->[\\s\\S]*?<!--\\s*${END}\\s*-->\\n?`);
+  // `\n?` on both sides: install writes a blank line, then the block, so consuming only the
+  // block left the file one newline longer than it started (uninstall claimed "已恢复原状"
+  // while `diff` showed an extra empty line).
+  const pattern = new RegExp(`\\n?[ \\t]*<!--\\s*${START}\\s*-->[\\s\\S]*?<!--\\s*${END}\\s*-->\\n?`);
   if (!pattern.test(text)) return false;
   backup(path);
   const stripped = text.replace(pattern, '');
@@ -189,6 +450,45 @@ 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.
+ */
+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';
 
 /**
@@ -435,6 +735,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 {
@@ -456,13 +766,11 @@ async function ensureIdentity() {
   // 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.
-  const exported = (process.env.MISAKANET_CLIENT_ID || '').trim();
-  if (exported && !/^[A-Za-z0-9._-]{8,64}$/.test(exported)) {
-    need('ignored MISAKANET_CLIENT_ID：只接受 8–64 位的 [A-Za-z0-9._-]（这次会新生成一个）');
-  }
-  const clientId = (exported && /^[A-Za-z0-9._-]{8,64}$/.test(exported))
-    ? exported
-    : `setup-${crypto.randomUUID()}`;
+  // `--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()}`;
+  knownClientId = clientId;
   const result = await mcpCall('misakanet_register', { agent_type: 'setup', client_id: clientId });
   // 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
@@ -470,23 +778,41 @@ async function ensureIdentity() {
   // 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)) {
-    need('注册没成功或返回的凭据形状不对（可能离线）→ 读课程不受影响；想要写入类工具时重跑本命令');
+    // Say what it costs, not what went wrong internally: "凭据形状不对" is jargon. Reading is not
+    // what is lost here (it needs no token and is not metered) — the write path is, and saying so
+    // plainly is the difference between a user retrying and a user concluding the tool is broken.
+    need('匿名注册没成功（多半是网络）→ 读课程不受影响，但写入类工具（write_lesson）现在用不了；'
+      + '网络恢复后重跑本命令就能拿到 token');
     return '';
   }
-  writeFileSync(file, token);
-  try {
-    chmodSync(file, 0o600);
-  } catch { /* windows */ }
+  // 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.
-    ok(`想在这个节点上继续累积（重装/换机后仍是同一个）：export MISAKANET_CLIENT_ID=${clientId}`);
+    // Kept out of the "done" list on purpose — it is something to *keep*, not something that
+    // happened, and a bare `export …` line reads as a chore to a non-technical user. It is shown
+    // with the closing guidance instead, in plain words.
+    clientIdHint = clientId;
   }
   return token;
 }
 
 // ── 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')),
+  }[agent]?.() || '';
+  return text.includes('misakanet') && text !== 'null';
+}
+
 function detect(agent) {
   const paths = {
     claude: ['.claude.json', '.claude'],
@@ -507,8 +833,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 {
@@ -519,8 +844,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;
@@ -545,7 +892,7 @@ async function installClaude(hookPath, bearer) {
 
   for (const [event, command] of Object.entries(wanted)) {
     const bucket = settings.hooks[event] || [];
-    if (JSON.stringify(bucket).includes('hook.mjs') || JSON.stringify(bucket).includes('checkpoint_reminder')) continue;
+    if (bucket.some(isOurHookEntry)) continue;
     bucket.push({ hooks: [{ type: 'command', command }] });
     settings.hooks[event] = bucket;
     changed = true;
@@ -576,13 +923,13 @@ async function installClaude(hookPath, bearer) {
       // matcher-less entry of ours as stale rather than "already installed", or re-running the
       // installer would leave a hook that stays silent forever (the exact failure this release
       // is about).
-      const stale = post.filter((e) => JSON.stringify(e).includes('voice-hook') && e.matcher !== '*');
+      const stale = post.filter((e) => isOurHookEntry(e) && e.matcher !== '*');
       if (stale.length) {
         post = post.filter((e) => !stale.includes(e));
         settings.hooks.PostToolUse = post;
         changed = true;
       }
-      if (!JSON.stringify(post).includes('voice-hook')) {
+      if (!post.some(isOurHookEntry)) {
         // `matcher: '*'` is load-bearing, not cosmetic: measured on 2026-09-16, a PostToolUse
         // entry **without** a matcher never fired in this host, while the same command with
         // `matcher: '*'` fired on every tool call. The hook itself filters by the `voice`
@@ -617,12 +964,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`;
 };
@@ -674,7 +1026,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
@@ -801,11 +1154,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
@@ -833,7 +1193,7 @@ async function installHermes(hookPath, bearer) {
   }
 
   if (!bearer) {
-    skip('Hermes：这次没有 token → 走匿名通道（5/天/IP），写入类工具不可用');
+    skip('Hermes：这次没有 token → 读仍然不限次数，写入类工具不可用');
     return;
   }
   const envPath = join(HOME, '.hermes', '.env');
@@ -845,10 +1205,9 @@ async function installHermes(hookPath, bearer) {
     : `${envText}${envText && !envText.endsWith('\n') ? '\n' : ''}${assignment}\n`;
   if (next !== envText) {
     backup(envPath);
-    writeText(envPath, next);
-    // The standalone token file is chmod 600 two hundred lines up; leaving the token in a
-    // world-readable .env (default umask is usually 0644) is the same leak through another door.
-    try { chmodSync(envPath, 0o600); } catch { /* windows */ }
+    // The standalone token file is 0600; leaving the token in a world-readable .env (default umask
+    // is usually 0644) is the same leak through another door, so the mode is set at creation.
+    writeText(envPath, next, { mode: 0o600 });
     ok(`Hermes：token 写入 ${envPath}（${envKey}，配置里只留 \${${envKey}} 模板）`);
   } else {
     ok('Hermes：token 已就绪（无改动）');
@@ -883,6 +1242,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'));
@@ -932,7 +1296,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"）→ '
@@ -949,7 +1315,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');
@@ -959,8 +1326,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)) {
@@ -1017,9 +1384,9 @@ async function verify() {
     tokenPresent = '';
   }
   if (tokenPresent) {
-    ok('写入通道：token 已就绪（解除每天 5 次读限额，write_lesson 可用）');
+    ok('写入通道：token 已就绪（write_lesson / preflight 可用）');
   } else {
-    skip('写入通道：无 token（只读也完全可用，但读有 5/天/IP 限额）');
+    skip('写入通道：无 token（读不限次数、只读完全可用，写入类工具不可用）');
   }
   const hookPath = join(stateDir(), 'hook.mjs');
   let hookPresent = false;
@@ -1034,12 +1401,14 @@ async function verify() {
   } else {
     const settingsPath = join(HOME, '.claude', 'settings.json');
     const settings = readJson(settingsPath, {}) || {};
-    const commands = Object.values(settings.hooks || {}).flat()
+    // 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' && c.includes('hook.mjs'));
+      .filter((c) => typeof c === 'string');
     if (!commands.length) {
       allOk = false;
-      need('Claude Code：钩子没装（settings.json 里没有指向 hook.mjs 的命令）');
+      need('Claude Code：钩子没装（settings.json 里没有本安装器写入的命令）');
     } else {
       const exe = commands[0].startsWith('"') ? commands[0].split('"')[1] : commands[0].split(' ')[0];
       if (!existsSync(exe)) {
@@ -1095,8 +1464,8 @@ async function verify() {
       need(`Hermes：MCP 未注册（${cfg}）→ 重跑安装命令，或执行 `
         + `hermes mcp add misakanet --url ${ENDPOINT} --auth header`);
     } 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 复核');
@@ -1127,6 +1496,96 @@ async function verify() {
   return allOk;
 }
 
+/**
+ * Hand the config back: drop containers that are empty now that our entries are gone, and delete
+ * files that held nothing but our own lines.
+ *
+ * `--uninstall` promises to remove exactly what this installer wrote, and removing only the
+ * *leaves* left the containers it had created behind. On a bare home (`{}` config, nothing else)
+ * that turned into: `~/.claude.json` came back as `{"mcpServers": {}}`, `~/.claude/settings.json`
+ * as `{"hooks": {}, "permissions": {"allow": []}}`, `~/.openclaw/openclaw.json` as
+ * `{"mcp": {"servers": {}}}`, `~/.codewhale/mcp.json` as `{"servers": {}}`, and
+ * `~/.hermes/config.yaml` gained a dangling `mcp_servers:` key. Found 2026-09-18 by the
+ * packaged-tarball e2e, which compares the whole tree before and after — four of five agents
+ * drifted, and only Codex (a line-based format) came back byte-exact.
+ *
+ * An empty object or array is semantically nothing in every format handled here, so pruning it
+ * restores the *meaning* of the user's file. The *formatting* of a JSON file is not restored (the
+ * install re-serialized it) — that is stated rather than pretended, and the e2e check asserts
+ * semantics plus "no trace of ours" for JSON, byte equality for the line-based formats.
+ */
+function pruneEmptyContainers(value) {
+  if (Array.isArray(value)) {
+    value.forEach(pruneEmptyContainers);
+  } else if (value && typeof value === 'object') {
+    for (const [key, child] of Object.entries(value)) {
+      pruneEmptyContainers(child);
+      if (child && typeof child === 'object' && Object.keys(child).length === 0) delete value[key];
+    }
+  }
+  return value;
+}
+
+/**
+ * The `mcp_servers:` line, when nothing is left under it.
+ *
+ * The install adds that key itself when the file has none (the last branch of `installHermes`), so
+ * removing only our block left the key dangling. Any indented key below it means the user has
+ * servers of their own, and then the line stays.
+ */
+function dropEmptyMcpServersKey(text) {
+  const lines = text.split('\n');
+  const kept = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    const isBareKey = /^mcp_servers:[ \t]*$/.test(lines[i]);
+    const hasChild = lines.slice(i + 1).some((line) => /^[ \t]+\S/.test(line));
+    if (isBareKey && !hasChild) continue;
+    kept.push(lines[i]);
+  }
+  return kept.join('\n');
+}
+
+/** The tail of `--uninstall`: give emptiness back, and take blank files away. */
+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')];
+  for (const file of jsonFiles) {
+    const data = readJson(file, null);
+    if (!data || typeof data !== 'object') continue;
+    const next = `${JSON.stringify(pruneEmptyContainers(data), null, 2)}\n`;
+    if (next === readText(file)) continue;
+    backup(file);
+    writeText(file, next);
+    ok(`移除空配置块 → ${file}`);
+  }
+
+  // Hermes' YAML: the key the install may have created.
+  const hermesCfg = join(HOME, '.hermes', 'config.yaml');
+  const hermesText = readText(hermesCfg);
+  if (hermesText) {
+    const tidied = dropEmptyMcpServersKey(hermesText);
+    if (tidied !== hermesText) {
+      backup(hermesCfg);
+      writeText(hermesCfg, tidied);
+      ok(`移除空的 mcp_servers 键 → ${hermesCfg}`);
+    }
+  }
+
+  // Files that only ever held our own lines: a blank rules file, an emptied `.env`. An empty file
+  // cannot carry user information, and `backup()` never copies an empty file, so removing it is the
+  // honest restore and leaves nothing dangling.
+  const textFiles = [join(HOME, '.claude', 'CLAUDE.md'), join(HOME, '.codex', 'AGENTS.md'),
+                     join(HOME, '.codex', 'config.toml'), join(HOME, '.hermes', 'SOUL.md'),
+                     hermesCfg, join(HOME, '.hermes', '.env')];
+  for (const file of textFiles) {
+    if (!existsSync(file) || readText(file).trim() !== '') continue;
+    rmSync(file, { force: true });
+    ok(`删除空文件 → ${redact(file)}`);
+  }
+}
+
 function uninstall() {
   for (const rel of ['.claude/CLAUDE.md', '.codex/AGENTS.md', '.hermes/SOUL.md']) {
     if (stripBlock(join(HOME, rel))) ok(`移除规则块 → ${rel}`);
@@ -1170,8 +1629,8 @@ function uninstall() {
   if (settings?.hooks) {
     let changed = false;
     for (const event of Object.keys(settings.hooks)) {
-      const kept = (settings.hooks[event] || []).filter((entry) =>
-        !JSON.stringify(entry).includes('hook.mjs') && !JSON.stringify(entry).includes('voice-hook'));
+      // Only entries we wrote: a user's own hook that happens to be named *-hook.mjs stays.
+      const kept = (settings.hooks[event] || []).filter((entry) => !isOurHookEntry(entry));
       // Drop our permission grants too, so uninstall leaves the file as it was.
       if (Array.isArray(settings.permissions?.allow)) {
         const pruned = settings.permissions.allow.filter((tool) => !CLAUDE_ALLOWED_TOOLS.includes(tool));
@@ -1244,6 +1703,9 @@ function uninstall() {
     writeText(ocCfg, `${JSON.stringify(ocData, null, 2)}\n`);
     ok(`移除 MCP 注册 → ${ocCfg}`);
   }
+
+  // Last, not first: the containers only become empty *after* the entries above are out.
+  restoreEmptiedFiles();
 }
 
 /**
@@ -1272,7 +1734,7 @@ function voiceStatus() {
     const settings = readJson(join(HOME, '.claude', 'settings.json'), null);
     const buckets = settings?.hooks?.PostToolUse;
     if (!Array.isArray(buckets)) return 'absent';
-    const ours = buckets.filter((entry) => JSON.stringify(entry).includes('voice-hook'));
+    const ours = buckets.filter(isOurHookEntry);
     if (!ours.length) return 'absent';
     return ours.some((entry) => entry.matcher === '*') ? 'on' : 'stale';
   } catch {
@@ -1335,6 +1797,11 @@ function reportValues(allOk) {
     ['token', token ? 'present' : 'absent'],
     ['permissions', permissions],
     ['hook', existsSync(join(stateDir(), 'hook.mjs')) ? 'present' : 'absent'],
+    // `mcp-only` = the endpoint is registered but the hooks are not, which is a different machine
+    // from "nothing installed" and must not be counted as one (#1753's T1-lite rows).
+    ['install-scope', existsSync(join(stateDir(), 'hook.mjs'))
+      ? 'full'
+      : (AGENTS.some((agent) => detect(agent) && mcpEntryPresent(agent)) ? 'mcp-only' : 'none')],
     ['voice', voiceStatus()],
     ['open-items', manual.length],
     // Redacted here, once, so neither encoder can print an unredacted message by accident.
@@ -1450,8 +1917,19 @@ if (mode !== 'report' && !SILENT) {
 
 if (mode === 'uninstall') {
   uninstall();
-  say(render());
-  if (!SILENT) console.log('\n已恢复原状（每个改过的文件都有 .misakanet.bak 备份）。');
+  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）`
+      + '，确认无误后可自行删除。');
+  }
   process.exit(0);
 }
 
@@ -1516,19 +1994,127 @@ const targets = (only.length ? only : AGENTS).filter((a) => {
   return true;
 });
 
-if (!targets.length) {
-  need('没检测到 Claude Code / Codex / Hermes 的配置目录 → 请先打开一次你要用的那个助手，再回来运行本命令');
-} else {
-  const hookPath = await installHook();
-  stampVersion();
-  const bearer = has('--no-register') ? '' : await ensureIdentity();
-  for (const agent of targets) {
-    if (agent === 'claude') await installClaude(hookPath, bearer);
-    else if (agent === 'codex') await installCodex(hookPath, bearer);
-    else if (agent === 'hermes') await installHermes(hookPath, bearer);
-    else if (agent === 'openclaw') await installOpenclaw(bearer);
-    else if (agent === 'codewhale') await installCodewhale(bearer);
+// Install mode used to end without any `process.exit`, so it returned **0 no matter what**:
+// "no agent detected", "registration failed", "a target could not be written" and a clean
+// install were indistinguishable, and `npx … && echo ok` asserted success for a run that
+// changed nothing (reproduced 2026-09-17 on a machine with no agent config at all).
+//
+// The contract now matches the other modes (0 fine / 1 ran but not ready / 2 could not run):
+//   * 0 - at least one target's config was written (advisory items may still be listed in `!`)
+//   * 1 - nothing was installed: no target detected, or every target failed
+//   * 2 - the installer itself could not do its job (I/O, permissions, a blown-up config)
+//
+// The exit code deliberately answers "did the install happen", not "is everything green":
+// a run that leaves the user with working read access but no write token is a *success* with a
+// listed item. Use `--verify` / `--report --strict` for the health question — that separation
+// is what makes this signal usable in a script.
+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.
+  // Compare base names, not separators: a `/settings.json$` regex silently classifies nothing on
+  // Windows (all three windows legs went red on the first CI run of this change), and a manifest
+  // that hides a tier is worse than no manifest.
+  const tierOf = (path) => {
+    const base = basename(path);
+    if (base === 'CLAUDE.md' || base === 'AGENTS.md' || base === 'SOUL.md') return 2;
+    if (path.includes('.misakanet-agent')) return 3;               // our own state dir
+    // `settings.json` carries both the read-only grants (①) and the hooks (③); the caller adds the
+    // second row only when the hooks are in scope.
+    if (base === 'settings.json' && path.includes('.claude')) return 1;
+    return 1;                                                     // an MCP entry in the agent's config
+  };
+  const rows = new Map();
+  const add = (path, action, tier) => {
+    const key = `${tier}|${path}`;
+    if (!rows.has(key)) rows.set(key, { path: redact(path), action, tier });
+  };
+  for (const agent of AGENTS) {
+    if (!detect(agent)) continue;
+    for (const path of (AGENT_WRITE_PATHS[agent] || (() => []))(HOME)) {
+      add(path, existsSync(path) ? 'append-or-update' : 'create', tierOf(path));
+      if (!MCP_ONLY && basename(path) === 'settings.json' && path.includes('.claude')) {
+        add(path, 'append-or-update（钩子）', 3);
+      }
+    }
+  }
+  add(join(stateDir(), 'token'), 'create (0600)', 1);
+  if (!MCP_ONLY) add(join(stateDir(), 'hook.mjs'), 'create', 3);
+
+  const tiers = { 1: '① 注册 MCP 端点', 2: '② 写规则块（改行为）', 3: '③ 装钩子（每轮自动执行）' };
+  const list = [...rows.values()].filter((row) => (MCP_ONLY ? row.tier === 1 : true))
+    .sort((a, b) => a.tier - b.tier || a.path.localeCompare(b.path));
+  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);
+}
+
+try {
+  if (!targets.length) {
+    need('没检测到 Claude Code / Codex / Hermes 的配置目录 → 请先打开一次你要用的那个助手，再回来运行本命令');
+  } else {
+    const hookPath = MCP_ONLY ? 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
+      // the remaining agents were never touched while the run still looked fine.
+      const blocked = unwritableTargets((AGENT_WRITE_PATHS[agent] || (() => []))(HOME));
+      if (blocked.length) {
+        // Reported before attempting, so the user gets "these files are read-only" instead of a raw
+        // EACCES from four call frames deep — and `--dry-run` says it too, which is the whole point
+        // of a dry run.
+        need(`${agent}：这些文件改不了（只读或权限不足）→ ${redact(blocked.join('、'))}`
+          + '；修好后重跑本命令，其它助手不受影响');
+        continue;
+      }
+      try {
+        if (agent === 'claude') await installClaude(hookPath, bearer);
+        else if (agent === 'codex') await installCodex(hookPath, bearer);
+        else if (agent === 'hermes') await installHermes(hookPath, bearer);
+        else if (agent === 'openclaw') await installOpenclaw(bearer);
+        else if (agent === 'codewhale') await installCodewhale(bearer);
+        installed += 1;
+      } catch (err) {
+        need(`${agent}：写入配置失败（${redact((err && err.message) || err)}）`
+          + '→ 修好这个文件或权限后重跑本命令，其它助手不受影响');
+      }
+    }
+  }
+} catch (err) {
+  say(render());
+  console.error(`安装没能跑完 —— 退出码 2（跑不起来，与「装不上」是两回事）：${redact((err && err.message) || err)}`);
+  process.exit(2);
 }
 
 // Under `--silent` this is the whole install-mode output: only the `!` lines survive render(), and
@@ -1536,11 +2122,30 @@ if (!targets.length) {
 // 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(`
 接下来：
   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`);
+  4) 想关掉：npx @misaka-net/misakanet-setup --uninstall`
+    + (clientIdHint
+      ? `
+  5) 记不记都行：这台机器的身份编号是 ${clientIdHint}
+     想让它以后重装/换机还算同一个身份，再跑安装时加：--client-id ${clientIdHint}`
+      : ''));
+}
+if (!installed) {
+  // Say it in one line on stderr as well: a script needs the reason next to the exit code, and
+  // "nothing was installed" is exactly the case that used to exit 0 in silence.
+  console.error('\n没有装上任何助手 —— 退出码 1。上面每条 ! 都给了下一步；装好助手再重跑即可。');
+  process.exit(1);
 }
+process.exit(0);

package/hook/checkpoint_reminder.mjs

@@ -21,6 +21,7 @@
  *   echo '{"session_id":"demo"}' | node checkpoint_reminder.mjs prompt
  */
 import { writeFileSync, mkdirSync, renameSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 
@@ -69,11 +70,20 @@ function parsePayload(raw) {
 }
 
 function sessionKey(payload) {
+  // An explicit key wins: the same value the strategy below would derive, but chosen by the user or
+  // by an agent that knows its own conversation boundaries.
+  const pinned = (process.env.MISAKANET_SESSION_KEY || '').trim();
+  if (pinned) return pinned.slice(0, 64);
   for (const key of ['session_id', 'sessionId', 'session', 'thread_id', 'conversation_id']) {
     const value = payload[key];
     if (typeof value === 'string' && value.trim()) return value.trim().slice(0, 64);
   }
-  return 'default';
+  // No session id at all used to fall back to the single name `default`, so every agent on the
+  // machine that does not report one shared *one* turn counter: agent A's twentieth turn fired the
+  // checkpoint in agent B's session and B never saw its own reminder (2026-09-18 review, 意见 9).
+  // Deriving the key from the working directory keeps one counter per project, which is the closest
+  // thing to "this conversation" that a hook can see without an id — and it is stable across turns.
+  return `default-${createHash('sha1').update(process.cwd()).digest('hex').slice(0, 8)}`;
 }
 
 function statePath(session) {
@@ -277,7 +287,11 @@ function promptMode(payload) {
     '1) 挑出本会话真正值得复用的「失败→根因→修复→验证」；门槛：可泛化、有可跑判据、且先 ' +
     'misakanet_search 确认语料里没有重复（有就引用其 id，不要另写一篇）。\n' +
     '2) 脱敏：密钥/token/凭据 → <REDACTED>；人名/邮箱/真实域名/绝对家目录 → 泛化成 ~/project、example.com；' +
-    '不要粘会话转录或整段工具输出。\n' +
+    // The "内部业务细节抽象成结构性描述" clause is the Python hook's wording, which is the one that
+    // carries it (added 2026-09-14, `2af7a41df`). The two hooks had drifted here and nothing
+    // compared them; `tests/test_agent_autostart_parity.py` now does, and this line was its first
+    // find. The stronger clause wins: it is a redaction rule, and the weaker copy was the Node one.
+    '不要粘会话转录或整段工具输出；内部业务细节抽象成结构性描述。\n' +
     '3) 提交（无需 token）：misakanet_submit_intake(kind="missing_lesson", problem="## Problem\\n…\\n\\n' +
     '## Root Cause\\n…\\n\\n## Solution\\n…\\n\\n## Verification\\n…")；若这条其实是「问题」而非经验，' +
     '用 kind="question"；若确实不够泛化/价值不高 → 不提交。\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misaka-net/misakanet-setup",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "One-command setup: teach your Claude Code / Codex / Hermes / OpenClaw / codewhale to search MisakaNet failure lessons before repeating a mistake, and to distil the session at a checkpoint.",
   "bin": {
     "misakanet-setup": "bin/misakanet-setup.mjs"

package/voice/voice-hook.mjs

@@ -444,10 +444,28 @@ try {
   main();
 } catch {
   /* a hook must never surface as a tool failure */
-} finally {
-  process.exit(0);
 }
 
-// Backstop: if a detached player leaves this process alive (some players keep a handle),
-// leave anyway. The sound is best-effort by design.
-setTimeout(() => process.exit(0), 3000).unref();
+// Exit on the next tick rather than through `process.exit(0)` *in* the finally above.
+//
+// The old shape was:
+//
+//     } finally { process.exit(0); }
+//     setTimeout(() => process.exit(0), 3000).unref();   // ← unreachable, every run
+//
+// `process.exit` ends the process before the backstop line is ever evaluated, so the safety net
+// for "a detached player kept a handle open" had never run — dead code that read like protection.
+// (Found by the 2026-09-18 setup review; verified by reading the tail of this file, which is also
+// why the package's `voice/voice-hook.mjs` copy is regenerated by `prepack`.)
+//
+// Why not just `process.exitCode = 0` with no exit call at all: the debug line above is written with
+// `writeFileSync(1, …)` precisely so it cannot be truncated, and this process must not stay alive
+// waiting on a spawned player — the agent is waiting for the hook to return. `setImmediate` keeps
+// stdout draining for one tick while still ending the process deterministically, and the timer is
+// the real backstop for a handle the spawn left behind.
+setImmediate(() => {
+  setTimeout(() => process.exit(0), 3000).unref();
+  // If the loop is otherwise empty, `unref`ed timers do not hold it open, so Node exits by itself
+  // within this tick — the timer only matters when something else is still keeping us alive.
+  process.exitCode = 0;
+});