@misaka-net/misakanet-setup 0.5.4 → 0.5.5

package/bin/misakanet-setup.mjs

@@ -25,11 +25,19 @@
  * 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 { fileURLToPath } from 'node:url';
@@ -120,7 +128,71 @@ 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.5'
+
+// ── 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（重装/换机也能延续）'],
+  ['--no-register', '不注册匿名节点（不写 token，检索仍是 5 次/天/IP）'],
+  ['--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);
+}
+
+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 +220,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 +398,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, '');
@@ -456,13 +682,16 @@ 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();
+  // `--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 MISAKANET_CLIENT_ID：只接受 8–64 位的 [A-Za-z0-9._-]（这次会新生成一个）');
+    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-${crypto.randomUUID()}`;
+    : `setup-${randomUUID()}`;
   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,18 +699,24 @@ 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, 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，其它功能不受影响');
     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) {
     // 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;
 }
@@ -545,7 +780,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 +811,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`
@@ -845,10 +1080,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 已就绪（无改动）');
@@ -1034,12 +1268,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)) {
@@ -1127,6 +1363,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 +1496,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 +1570,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 +1601,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 {
@@ -1451,7 +1780,11 @@ if (mode !== 'report' && !SILENT) {
 if (mode === 'uninstall') {
   uninstall();
   say(render());
-  if (!SILENT) console.log('\n已恢复原状（每个改过的文件都有 .misakanet.bak 备份）。');
+  if (!SILENT) {
+    console.log('\n已移除本安装器写入的内容（规则块、MCP 注册、钩子、状态目录）。');
+    console.log(`备份保留在 <被改过的文件>.misakanet.bak（例如 ${join(HOME, '.claude', 'CLAUDE.md')}.misakanet.bak）`
+      + '，确认无误后可自行删除。');
+  }
   process.exit(0);
 }
 
@@ -1516,19 +1849,59 @@ 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 = '';
+try {
+  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) {
+      // 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
@@ -1542,5 +1915,17 @@ if (!SILENT) {
   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.5",
   "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;
+});