agentmash 0.3.0

package/agentmash.mjs

@@ -0,0 +1,1798 @@
+#!/usr/bin/env node
+// AgentMash CLI — Node built-ins only. (The package it ships in is not
+// dependency-free: `agentmash mcp` runs the real MCP server, which needs
+// @modelcontextprotocol/sdk. Everything this file installs into a repo is.)
+//
+//   npx agentmash init      create a room and wire this repo up
+//   npx agentmash join ID   point this repo at an existing room
+//   npx agentmash doctor    explain exactly what is and isn't working
+//   npx agentmash status    who is working on what, right now
+//   npx agentmash git-hook  install or remove the post-commit client
+//   npx agentmash uninstall remove the hooks from this repo
+//   npx agentmash mcp       serve the MCP tools on stdio (what .mcp.json runs)
+
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SERVER = (process.env.AGENTMASH_SERVER || 'https://agentmash.dev').replace(/\/+$/, '');
+const HOOK_FILES = [
+  'lib.mjs',
+  'pre_tool_use.mjs',
+  'post_tool_use.mjs',
+  'user_prompt_submit.mjs',
+  'session_end.mjs',
+  'stop.mjs',
+];
+// Not a hook, but it installs like one: dependency-free, copied into the repo,
+// committed, and picked up by a teammate's `git pull`.
+const MCP_LAUNCHER = 'mcp_launcher.mjs';
+const INSTALLED_FILES = [...HOOK_FILES, MCP_LAUNCHER];
+const MCP_SERVER_NAME = 'agentmash';
+// Non-Claude-Code clients of the same protocol, copied in beside the hooks so
+// they travel with the repo too. [source path under clients/, installed name]
+const CLIENT_FILES = [['git/post_commit.mjs', 'git_post_commit.mjs']];
+const REQUEST_TIMEOUT_MS = 10_000;
+
+const c = {
+  bold: (s) => `${s}`,
+  dim: (s) => `${s}`,
+  green: (s) => `${s}`,
+  red: (s) => `${s}`,
+  yellow: (s) => `${s}`,
+  cyan: (s) => `${s}`,
+};
+const ok = (s) => console.log(`  ${c.green('✓')} ${s}`);
+const bad = (s) => console.log(`  ${c.red('✗')} ${s}`);
+const warn = (s) => console.log(`  ${c.yellow('!')} ${s}`);
+const info = (s) => console.log(`  ${c.dim('·')} ${s}`);
+
+function die(message) {
+  console.error(`\n${c.red('error')} ${message}\n`);
+  process.exit(1);
+}
+
+// ── locations ──────────────────────────────────────────────────────────────
+
+function findRepoRoot(start = process.cwd()) {
+  let dir = start;
+  for (let i = 0; i < 40; i++) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Hook sources: the repo checkout in dev, or the copy bundled with the
+ * published package. The checkout comes first because `sync-hooks.mjs` leaves a
+ * vendored copy in cli/hooks/ that goes stale the moment anyone edits hooks/,
+ * and installing yesterday's hooks is worse than not finding them.
+ */
+function hookSourceDir() {
+  for (const candidate of [path.join(HERE, '..', 'hooks'), path.join(HERE, 'hooks')]) {
+    if (INSTALLED_FILES.every((f) => fs.existsSync(path.join(candidate, f)))) return candidate;
+  }
+  die('could not locate the hook scripts to install (broken package?)');
+}
+
+function clientSourceDir() {
+  for (const candidate of [path.join(HERE, 'clients'), path.join(HERE, '..', 'clients')]) {
+    if (CLIENT_FILES.every(([src]) => fs.existsSync(path.join(candidate, src)))) return candidate;
+  }
+  return null;
+}
+
+const meshDir = (repo) => path.join(repo, '.claude', 'agentmash');
+const configPath = (repo) => path.join(meshDir(repo), 'config.json');
+const settingsPath = (repo) => path.join(repo, '.claude', 'settings.json');
+const mcpJsonPath = (repo) => path.join(repo, '.mcp.json');
+
+function readConfig(repo) {
+  try {
+    return JSON.parse(fs.readFileSync(configPath(repo), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ── http ───────────────────────────────────────────────────────────────────
+
+/**
+ * Node races the addresses a hostname resolves to and gives each attempt 250 ms
+ * by default. A TCP connect to a server a continent away takes longer than that,
+ * so every attempt is abandoned, fetch rejects with ETIMEDOUT in ~300 ms, and the
+ * caller sees a dead server that curl reaches fine. Give each attempt half the
+ * request's own budget instead: a slow-but-working first address gets to finish,
+ * and a blackholed one still leaves the other half for the next family.
+ */
+function widenConnectAttempts(timeoutMs) {
+  try {
+    net.setDefaultAutoSelectFamilyAttemptTimeout(Math.max(250, Math.floor(timeoutMs / 2)));
+  } catch {
+    // Node older than 18.18 has no such knob, and no such 250 ms default to undo
+  }
+}
+
+async function api(method, url, { room, token, poll, body } = {}) {
+  const started = Date.now();
+  try {
+    widenConnectAttempts(REQUEST_TIMEOUT_MS);
+    const res = await fetch(url, {
+      method,
+      // Short-lived CLI: don't leave keep-alive sockets open for exit to race.
+      // Credentials go in headers, never in the URL — query strings end up in
+      // access logs, shell history and browser referrers.
+      headers: {
+        ...(body === undefined ? {} : { 'content-type': 'application/json' }),
+        'x-agentmash-room': room || '',
+        ...(token ? { 'x-agentmash-token': token } : {}),
+        ...(poll ? { 'x-agentmash-poll': poll } : {}),
+        connection: 'close',
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      /* non-JSON response */
+    }
+    return { ok: res.ok, status: res.status, json, text, ms: Date.now() - started };
+  } catch (err) {
+    return { ok: false, status: 0, json: null, text: String(err?.message || err), ms: Date.now() - started };
+  }
+}
+
+/**
+ * Ask the server about the room this repo points at, with the key in a header.
+ * `GET /rooms/:id` puts a working credential in the URL, so it lands verbatim
+ * in the server's log, in every proxy in between, and in shell history — and
+ * `doctor` runs it constantly. Servers older than /rooms/self answer that path
+ * from their `:id` route with a 404 that carries no `code`, which is the signal
+ * to fall back so a new CLI still works against an old server.
+ */
+async function lookupRoom(url, room, token) {
+  const res = await api('GET', `${url}/rooms/self`, { room, token });
+  if (res.status === 404 && !res.json?.code) return api('GET', `${url}/rooms/${room}`, { room, token });
+  return res;
+}
+
+// ── per-machine credentials ────────────────────────────────────────────────
+// Developer tokens are personal: they live in the user's home directory, mode
+// 0600, and never in the repo. Keyed by server + the room's non-secret ref, so
+// rotating the room key leaves them intact.
+
+function credentialsPath() {
+  const home = process.env.AGENTMASH_HOME || os.homedir();
+  return path.join(home, '.agentmash', 'credentials.json');
+}
+
+function readCredentials() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(credentialsPath(), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : { version: 1, tokens: {} };
+  } catch {
+    return { version: 1, tokens: {} };
+  }
+}
+
+function credentialKey(url, roomRef) {
+  return `${url.replace(/\/+$/, '')}|${roomRef}`;
+}
+
+function readToken(url, roomRef) {
+  if (!roomRef) return '';
+  const entry = readCredentials().tokens?.[credentialKey(url, roomRef)];
+  return typeof entry?.token === 'string' ? entry.token : '';
+}
+
+function writeToken(url, roomRef, entry) {
+  const file = credentialsPath();
+  const store = readCredentials();
+  store.version = 1;
+  store.tokens = store.tokens ?? {};
+  store.tokens[credentialKey(url, roomRef)] = entry;
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    /* best effort on platforms without POSIX modes */
+  }
+}
+
+/** The room this repo is wired to, plus whatever credentials we hold for it. */
+function connection(repo) {
+  const config = readConfig(repo);
+  const url = (process.env.AGENTMASH_URL || config?.url || '').replace(/\/+$/, '');
+  const room = process.env.AGENTMASH_ROOM || config?.room || '';
+  const roomRef = process.env.AGENTMASH_ROOM_REF || config?.room_ref || '';
+  return { config, url, room, roomRef, token: process.env.AGENTMASH_TOKEN || readToken(url, roomRef) };
+}
+
+// ── install ────────────────────────────────────────────────────────────────
+
+const HOOK_DIR_TOKEN = '${CLAUDE_PROJECT_DIR}/.claude/agentmash';
+const hookCommand = (script, extra = {}) => ({
+  type: 'command',
+  command: 'node',
+  args: [`${HOOK_DIR_TOKEN}/${script}`],
+  timeout: 5,
+  ...extra,
+});
+
+// Reporting hooks run with async: true — Claude Code doesn't wait for them, so
+// a distant server costs the agent nothing. Only the advisory check is
+// synchronous, because its whole purpose is to speak before an edit happens.
+const HOOK_ENTRIES = {
+  UserPromptSubmit: { hooks: [hookCommand('user_prompt_submit.mjs', { async: true })] },
+  PreToolUse: { matcher: 'Write|Edit|MultiEdit', hooks: [hookCommand('pre_tool_use.mjs')] },
+  PostToolUse: { matcher: 'Write|Edit|MultiEdit', hooks: [hookCommand('post_tool_use.mjs', { async: true })] },
+  // SessionEnd hooks share a short budget, and the process is going away, so
+  // this one stays synchronous with a little more room than the default.
+  SessionEnd: { hooks: [hookCommand('session_end.mjs', { timeout: 4 })] },
+  // Synchronous on purpose: its whole job is to speak before the turn ends.
+  Stop: { hooks: [hookCommand('stop.mjs')] },
+};
+
+// Claude Code reads project-scoped MCP servers from .mcp.json at the repo root
+// and expands ${VAR} and ${VAR:-default} in `command`, `args`, `env`, `url` and
+// `headers`. CLAUDE_PROJECT_DIR is set in the *spawned server's* environment,
+// not in Claude Code's own, so at expansion time it is unset — and an unset
+// variable with no default is left in the path verbatim, registering a server
+// that never starts. The docs name `${CLAUDE_PROJECT_DIR:-.}` as the form to
+// use for exactly this reason; `.` is the directory Claude Code launches
+// project servers in. `doctor` spawns this same expansion rather than the
+// launcher's resolved path, so a wrong belief here fails out loud.
+const MCP_SERVER_ENTRY = {
+  command: 'node',
+  args: ['${CLAUDE_PROJECT_DIR:-.}/.claude/agentmash/' + MCP_LAUNCHER],
+};
+
+/** Merge our server into whatever .mcp.json the repo already has. Null when nothing changes. */
+function mergeMcpJson(existing) {
+  let config = {};
+  if (existing && existing.trim()) {
+    try {
+      config = JSON.parse(existing);
+    } catch {
+      throw new Error('is not valid JSON');
+    }
+    if (config === null || typeof config !== 'object' || Array.isArray(config)) {
+      throw new Error('must contain a JSON object at the top level');
+    }
+  }
+  config.mcpServers = config.mcpServers ?? {};
+  const current = config.mcpServers[MCP_SERVER_NAME];
+  if (JSON.stringify(current) === JSON.stringify(MCP_SERVER_ENTRY)) return null;
+  config.mcpServers[MCP_SERVER_NAME] = MCP_SERVER_ENTRY;
+  return JSON.stringify(config, null, 2) + '\n';
+}
+
+function copyHooks(repo) {
+  const source = hookSourceDir();
+  fs.mkdirSync(meshDir(repo), { recursive: true });
+  for (const file of INSTALLED_FILES) {
+    fs.copyFileSync(path.join(source, file), path.join(meshDir(repo), file));
+  }
+  const clients = clientSourceDir();
+  if (!clients) return;
+  for (const [src, dest] of CLIENT_FILES) {
+    fs.copyFileSync(path.join(clients, src), path.join(meshDir(repo), dest));
+  }
+}
+
+// ── git client ─────────────────────────────────────────────────────────────
+// The post-commit hook is the only way a room ever sees a teammate who edits by
+// hand, or in an editor with no extension point. It lives in .git/hooks, which
+// is NOT committed — so unlike the Claude Code hooks it does not arrive with a
+// `git pull`, and every developer installs it on their own machine.
+
+const GIT_HOOK_MARKER = 'agentmash-git-hook';
+
+/**
+ * Never blocks, never fails, never speaks. It backgrounds the worker and returns
+ * immediately, which is the git equivalent of the reporting hooks' `async: true`
+ * — the developer's `git commit` finishes at exactly the speed it did before.
+ */
+const GIT_HOOK_SCRIPT = `#!/bin/sh
+# ${GIT_HOOK_MARKER} — installed by \`agentmash git-hook install\`.
+#
+# Reports which files this commit touched to your team's AgentMash room, in the
+# background. It cannot slow down or fail your commit: it starts a detached
+# process and exits 0 immediately.
+#
+# Any post-commit hook that was already here was moved to post-commit.local and
+# still runs first, unchanged. Removing this file (or \`agentmash git-hook
+# uninstall\`) restores it.
+
+hook_dir=$(dirname "$0")
+if [ -x "$hook_dir/post-commit.local" ]; then
+  "$hook_dir/post-commit.local" "$@" </dev/null
+fi
+
+root=$(git rev-parse --show-toplevel 2>/dev/null) || root=""
+[ -n "$root" ] || root="$PWD"
+worker="$root/.claude/agentmash/git_post_commit.mjs"
+
+# Hooks run under a non-login shell that never reads your profile, so a node
+# installed by nvm/volta/fnm is not on PATH — that is every commit made from a
+# GUI client. Look where those put it before giving up. Globs and [ -x ] are
+# shell builtins: no subprocess, no measurable cost.
+node_bin=""
+if command -v node >/dev/null 2>&1; then
+  node_bin=node
+else
+  for candidate in "$HOME"/.volta/bin/node /opt/homebrew/bin/node /usr/local/bin/node \
+                   "$HOME"/.nvm/versions/node/*/bin/node; do
+    if [ -x "$candidate" ]; then node_bin="$candidate"; break; fi
+  done
+fi
+
+if [ -f "$worker" ] && [ -n "$node_bin" ]; then
+  "$node_bin" "$worker" "$root" </dev/null >/dev/null 2>&1 &
+fi
+
+exit 0
+`;
+
+const contains = (parent, child) => child === parent || child.startsWith(parent + path.sep);
+
+/**
+ * Where git will actually look for hooks, and what kind of place that is.
+ *
+ * core.hooksPath must be honoured — git runs hooks from there and nowhere else,
+ * so writing to .git/hooks when it is set produces a hook that is never run.
+ * But *where* it points changes what installing means: a `.githooks/` or
+ * `.husky/_` directory is inside the working tree, and a file written there is
+ * a tracked file modified plus an untracked sibling created — see installGitHook.
+ * Linked worktrees are the other case: their hooks live in the common git dir.
+ */
+function resolveHooksDir(repo) {
+  const ask = (args) => {
+    try {
+      return execFileSync('git', args, { cwd: repo, timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString()
+        .trim();
+    } catch {
+      return '';
+    }
+  };
+  const gitDir = path.resolve(repo, ask(['rev-parse', '--git-common-dir']) || '.git');
+  const workTree = path.resolve(ask(['rev-parse', '--show-toplevel']) || repo);
+  const configured = ask(['config', '--get', 'core.hooksPath']);
+  if (!configured) {
+    return { dir: path.join(gitDir, 'hooks'), configured: null, insideWorkTree: false, outsideRepo: false };
+  }
+  // git resolves a relative core.hooksPath against the top of the working tree.
+  const dir = path.resolve(workTree, configured);
+  const inGitDir = contains(gitDir, dir);
+  return {
+    dir,
+    configured,
+    insideWorkTree: !inGitDir && contains(workTree, dir),
+    outsideRepo: !inGitDir && !contains(workTree, dir),
+  };
+}
+
+const gitHooksDir = (repo) => resolveHooksDir(repo).dir;
+const gitHookPath = (repo) => path.join(gitHooksDir(repo), 'post-commit');
+const chainedHookPath = (repo) => path.join(gitHooksDir(repo), 'post-commit.local');
+
+/**
+ * What is at a path, *without* following symlinks — the whole point.
+ * fs.existsSync() answers false for a dangling symlink, and writing to that
+ * path then creates the file at the link's target, wherever that is.
+ */
+function pathKind(file) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file, { throwIfNoEntry: false });
+  } catch {
+    return 'unreadable'; // no permission on the directory, EIO, a path with a non-directory in it
+  }
+  if (!stat) return 'missing';
+  if (stat.isSymbolicLink()) return 'symlink';
+  if (stat.isDirectory()) return 'directory';
+  if (stat.isFile()) return 'file';
+  return 'something else'; // fifo, socket, device
+}
+
+// O_NOFOLLOW closes the gap between the lstat above and the open below: if the
+// path became a symlink in between, the open fails instead of following it.
+// Windows has neither the flag nor the symlink-in-.git/hooks case; 0 there.
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+
+/** Write the shim to a path we have just established is a plain file (or nothing). */
+function writeHookFile(file, { replacing }) {
+  const { O_WRONLY, O_CREAT, O_TRUNC, O_EXCL } = fs.constants;
+  const flags = replacing ? O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW : O_WRONLY | O_CREAT | O_EXCL;
+  const fd = fs.openSync(file, flags, 0o755);
+  try {
+    fs.writeFileSync(fd, GIT_HOOK_SCRIPT);
+    // O_CREAT's mode is masked by umask, and git ignores a non-executable hook.
+    fs.fchmodSync(fd, 0o755);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function isOurGitHook(file) {
+  if (pathKind(file) !== 'file') return false;
+  try {
+    return fs.readFileSync(file, 'utf8').includes(GIT_HOOK_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns { ok, message }. Never throws: a checkout where the hooks directory
+ * cannot be written still gets a working install of everything else.
+ *
+ * Two refusals matter more than the install:
+ *
+ * 1. Anything at post-commit that is not a plain file we may replace. A dangling
+ *    symlink is the sharp case — `existsSync` says false, the write then lands
+ *    at the link's target, and the chmod makes it executable. That is an
+ *    arbitrary executable file anywhere on the filesystem, from a command we ask
+ *    every developer on a team to run.
+ * 2. A hooks directory inside the working tree (core.hooksPath = .githooks,
+ *    .husky/_, lefthook). Writing there modifies a tracked file, and the next
+ *    `git add -A` commits AgentMash to everybody. The whole argument for
+ *    installing by default is that .git/hooks is never committed; where that is
+ *    not true, the argument is not either, so we stop and ask.
+ */
+function installGitHook(repo, { forceHooksPath = false } = {}) {
+  const hooks = resolveHooksDir(repo);
+  const file = path.join(hooks.dir, 'post-commit');
+  const chained = path.join(hooks.dir, 'post-commit.local');
+  const shown = path.relative(repo, hooks.dir) || hooks.dir;
+
+  if (hooks.insideWorkTree && !forceHooksPath) {
+    return {
+      ok: false,
+      message:
+        `this repo runs hooks from ${shown}/ (core.hooksPath), which is inside the working tree —\n` +
+        `    installing there would modify a tracked file and commit AgentMash to your whole team.\n` +
+        `    Re-run with --force-hooks-path if that is what you want.`,
+    };
+  }
+
+  try {
+    fs.mkdirSync(hooks.dir, { recursive: true });
+
+    const kind = pathKind(file);
+    if (kind === 'symlink') {
+      return {
+        ok: false,
+        message:
+          `${file} is a symlink — leaving it alone.\n` +
+          `    Writing through it would create an executable file wherever it points.`,
+      };
+    }
+    if (kind === 'unreadable') return { ok: false, message: `cannot inspect ${file} — leaving it alone` };
+    if (kind !== 'missing' && kind !== 'file') {
+      return { ok: false, message: `${file} is not a regular file (${kind}) — leaving it alone` };
+    }
+
+    if (kind === 'file' && !isOurGitHook(file)) {
+      // Somebody's existing hook. Step aside politely: move it to
+      // post-commit.local, which our script runs first, so their behaviour is
+      // byte-for-byte what it was.
+      const chainedKind = pathKind(chained);
+      if (chainedKind !== 'missing') {
+        return { ok: false, message: `post-commit.local already exists (${chainedKind}) — leaving ${file} alone` };
+      }
+      // rename, never chmod: making a non-executable hook executable would
+      // start running something git was ignoring
+      fs.renameSync(file, chained);
+      writeHookFile(file, { replacing: false });
+      return { ok: true, message: 'git post-commit hook installed alongside the one already there' };
+    }
+
+    writeHookFile(file, { replacing: kind === 'file' });
+    const where = hooks.outsideRepo
+      ? ` in ${hooks.dir} (core.hooksPath — shared with every repository that uses it)`
+      : hooks.insideWorkTree
+        ? ` in ${shown}/ (core.hooksPath, inside the working tree — do not commit it)`
+        : '';
+    return {
+      ok: true,
+      message: (kind === 'file' ? 'git post-commit hook updated' : 'git post-commit hook installed') + where,
+    };
+  } catch (err) {
+    return { ok: false, message: `could not write ${file} — ${err.message}` };
+  }
+}
+
+/**
+ * Whether the installed shim will actually do anything. The shim needs two
+ * things: the worker beside it, and a `node` that a non-login `/bin/sh` can
+ * find. The second is the one that surprises people — `git commit` from
+ * SourceTree, VS Code or JetBrains runs with a PATH that never saw nvm.
+ */
+function workerCanRun(repo) {
+  if (!fs.existsSync(path.join(meshDir(repo), 'git_post_commit.mjs'))) {
+    return { ok: false, message: 'the hook is installed but the worker is not — run: agentmash git-hook install' };
+  }
+  let found = '';
+  try {
+    found = execFileSync('/bin/sh', ['-c', 'command -v node'], { timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim();
+  } catch {
+    // no node on PATH at all, or no /bin/sh (Windows) — say nothing rather than
+    // guess; the shim itself is inert-and-silent in that case by design
+    return { ok: true };
+  }
+  if (/[/\\](\.nvm|\.volta|\.fnm|\.asdf|fnm_multishells|\.nodenv)[/\\]/.test(found)) {
+    return {
+      ok: false,
+      message:
+        `node comes from a version manager (${found}), which a GUI git client's PATH will not have.\n` +
+        `    The hook looks in the usual version-manager locations too, but commits made outside a\n` +
+        `    terminal are the case to check if your commits never show up.`,
+    };
+  }
+  return { ok: true };
+}
+
+function uninstallGitHook(repo) {
+  const file = gitHookPath(repo);
+  const chained = chainedHookPath(repo);
+  try {
+    const kind = pathKind(file);
+    if (kind === 'missing') return { ok: true, message: 'no git post-commit hook to remove' };
+    // A symlink is never ours even if what it points at contains our marker:
+    // somebody else made that link, and removing it is their decision.
+    if (kind === 'symlink') return { ok: false, message: `${file} is a symlink, not ours — leaving it alone` };
+    if (!isOurGitHook(file)) return { ok: false, message: `${file} is not ours — leaving it alone` };
+    fs.rmSync(file, { force: true });
+    if (pathKind(chained) === 'file') {
+      fs.renameSync(chained, file);
+      return { ok: true, message: 'git post-commit hook removed, the one it replaced is back in place' };
+    }
+    return { ok: true, message: 'git post-commit hook removed' };
+  } catch (err) {
+    return { ok: false, message: `could not remove ${file} — ${err.message}` };
+  }
+}
+
+/**
+ * Check we'll be able to write the files we merge into before doing anything
+ * remote — otherwise a broken settings file leaves an orphan room on the server.
+ */
+function assertSettingsUsable(repo) {
+  for (const file of [settingsPath(repo), mcpJsonPath(repo)]) {
+    if (!fs.existsSync(file)) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      die(`${file} is not valid JSON — fix or move it, then re-run.`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      die(`${file} must contain a JSON object at the top level.`);
+    }
+  }
+}
+
+/** Merge our entries into settings.json without disturbing anything already there. */
+function mergeSettings(repo) {
+  const file = settingsPath(repo);
+  let settings = {};
+  if (fs.existsSync(file)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      die(`${file} is not valid JSON — fix or move it, then re-run.`);
+    }
+    if (settings === null || typeof settings !== 'object' || Array.isArray(settings)) {
+      die(`${file} must contain a JSON object at the top level.`);
+    }
+  }
+  settings.hooks = settings.hooks ?? {};
+  let added = 0;
+  for (const [event, group] of Object.entries(HOOK_ENTRIES)) {
+    const groups = (settings.hooks[event] = settings.hooks[event] ?? []);
+    if (JSON.stringify(groups).includes('.claude/agentmash/')) continue;
+    groups.push(group);
+    added += 1;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return added;
+}
+
+/** Register the MCP server in .mcp.json, keeping any servers the team added. */
+function mergeMcpFile(repo) {
+  const file = mcpJsonPath(repo);
+  let existing = null;
+  if (fs.existsSync(file)) existing = fs.readFileSync(file, 'utf8');
+  // A server already called "agentmash" that is not ours gets overwritten by
+  // the merge. Narrow, but silently replacing someone's server is not ours to
+  // do quietly, so say what was there.
+  let replaced = null;
+  try {
+    const before = existing && existing.trim() ? JSON.parse(existing) : {};
+    const current = before?.mcpServers?.[MCP_SERVER_NAME];
+    if (current && JSON.stringify(current) !== JSON.stringify(MCP_SERVER_ENTRY)) replaced = current;
+  } catch {
+    /* mergeMcpJson reports an unparseable file */
+  }
+  let merged;
+  try {
+    merged = mergeMcpJson(existing);
+  } catch (err) {
+    die(`${file} ${err.message} — fix or move it, then re-run.`);
+  }
+  if (merged === null) return { changed: false, replaced: null };
+  fs.writeFileSync(file, merged);
+  return { changed: true, replaced };
+}
+
+function writeConfig(repo, config) {
+  fs.mkdirSync(meshDir(repo), { recursive: true });
+  fs.writeFileSync(configPath(repo), JSON.stringify(config, null, 2) + '\n');
+}
+
+function wire(repo, config, { gitHook = true, forceHooksPath = false } = {}) {
+  copyHooks(repo);
+  const added = mergeSettings(repo);
+  const mcp = mergeMcpFile(repo);
+  writeConfig(repo, config);
+  // Installed by default, and argued for in docs/ADAPTERS.md: it is local-only
+  // (nothing is committed, so it cannot surprise a teammate), it cannot affect a
+  // commit, and `uninstall` puts everything back. An opt-in flag nobody
+  // discovers would leave exactly the people this is for invisible.
+  return {
+    added,
+    mcp: mcp.changed,
+    replaced: mcp.replaced,
+    git: gitHook ? installGitHook(repo, { forceHooksPath }) : null,
+  };
+}
+
+function printJoined(repo, config, { added, mcp, replaced, git }) {
+  const dashboard = `${config.url}/r/${config.room}`;
+  console.log(`\n${c.bold('AgentMash is wired up.')}\n`);
+  ok(`hooks installed  ${c.dim(path.relative(repo, meshDir(repo)))}`);
+  ok(added > 0 ? `settings.json updated (${added} hook events)` : 'settings.json already had the hooks');
+  ok(mcp ? 'MCP server registered  .mcp.json' : 'MCP server already registered in .mcp.json');
+  if (replaced) {
+    warn(
+      '.mcp.json already had a server called "agentmash" and it has been replaced:\n' +
+        `      ${c.dim(JSON.stringify(replaced))}\n` +
+        '      Put it back under another name if you still need it.'
+    );
+  }
+  if (git?.ok) ok(git.message);
+  else if (git) warn(git.message);
+  ok(`room  ${c.cyan(config.room)}`);
+  console.log(`\n  ${c.bold('Dashboard')}  ${c.cyan(dashboard)}\n`);
+  console.log(`  ${c.bold('To bring in your team — commit and push:')}`);
+  console.log(c.dim('    git add .claude .mcp.json && git commit -m "add agentmash" && git push\n'));
+  console.log('  Teammates just pull. The hooks and room travel with the repo,');
+  console.log('  so their next Claude Code session joins automatically.\n');
+  console.log(`  ${c.bold('Each teammate approves the MCP server once.')}`);
+  console.log('  Claude Code asks before it runs a server a repo brought with it, and');
+  console.log('  AgentMash does not answer that on anyone else\'s behalf. The hooks work');
+  console.log(`  either way; ${c.bold('npx agentmash doctor')} says what a machine is missing.\n`);
+  console.log('  The git post-commit client is local to this checkout — .git/hooks is not');
+  console.log(`  committed — so each teammate runs ${c.bold('npx agentmash git-hook install')} once.\n`);
+  console.log(c.dim('  (Already have Claude Code open? It picks up new hooks on its own,\n') +
+    c.dim('   but restarting the session is the sure thing.)\n'));
+}
+
+/**
+ * Open a link in the person's browser, when there is a person: stdout is a
+ * terminal, this is not CI, and they did not say --no-open. The platform's
+ * own opener, detached, so a browser that takes its time never holds the
+ * command open. Returns whether anything was launched.
+ */
+function openInBrowser(url, args = {}) {
+  if (args.noOpen || !process.stdout.isTTY || process.env.CI) return false;
+  const [cmd, cmdArgs] =
+    process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url.replace(/&/g, '^&')]]
+      : process.platform === 'darwin'
+        ? ['open', [url]]
+        : ['xdg-open', [url]];
+  try {
+    const child = spawn(cmd, cmdArgs, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Two lines, for someone who typed `npx agentmash` in a repo that is not wired up. */
+function nudge() {
+  console.log(`\n  This repo is not connected yet.  ${c.bold('npx agentmash init')} wires it up in one command.`);
+  console.log(`  Want to see it first?  ${c.bold('npx agentmash demo')} opens a made-up team.  ${c.dim('(--help for everything else)')}\n`);
+}
+
+// ── commands ───────────────────────────────────────────────────────────────
+
+async function cmdInit(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot();
+  if (!repo) die('not inside a git repository — run this in your team\'s repo, or pass --repo <path>');
+  assertSettingsUsable(repo);
+  const server = (args.server || DEFAULT_SERVER).replace(/\/+$/, '');
+
+  const existing = readConfig(repo);
+  if (existing?.room && !args.force) {
+    console.log(`\n${c.yellow('This repo is already connected.')}`);
+    info(`room ${c.cyan(existing.room)} on ${existing.url}`);
+    info(`dashboard ${c.cyan(`${existing.url}/r/${existing.room}`)}`);
+    console.log(`\n  Re-run with ${c.bold('--force')} to create a new room, or use ${c.bold('agentmash join <id>')}.\n`);
+    return;
+  }
+
+  const label = args.label || path.basename(repo);
+  console.log(`\ncreating a room on ${c.dim(server)} …`);
+  const res = await api('POST', `${server}/rooms`, { body: { label } });
+  if (!res.ok) {
+    if (res.status === 0) {
+      die(
+        `could not reach ${server}\n        ${c.dim(res.text)}\n\n` +
+          `        Is the server deployed? Point somewhere else with --server <url>,\n` +
+          `        or run one locally: npm run dev:server (then --server http://localhost:8787)`
+      );
+    }
+    die(`server refused to create a room (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+  }
+
+  const config = { url: res.json.server_url || server, room: res.json.room, label };
+  // Older servers don't have refs; the field is simply absent then.
+  if (res.json.room_ref) config.room_ref = res.json.room_ref;
+  const budget = await measuredBudget(config.url);
+  if (budget) config.timeout_ms = budget;
+  const result = wire(repo, config, { gitHook: !args.noGitHook, forceHooksPath: args.forceHooksPath });
+  printJoined(repo, config, result);
+  if (budget) {
+    info(`this server is ${budget}ms away, so the advisory budget was set to match`);
+  }
+  if (openInBrowser(`${config.url}/r/${config.room}`, args)) info('opened the dashboard in your browser (--no-open to skip)\n');
+}
+
+async function cmdDemo(args) {
+  const server = (args.server || DEFAULT_SERVER).replace(/\/+$/, '');
+  const url = `${server}/demo`;
+  console.log(`\n  ${c.bold('Demo')}  ${c.cyan(url)}\n`);
+  console.log('  A made-up team of four on a made-up repo, so you can see the room move');
+  console.log(`  before there is anyone in yours. Nothing you do there leaves the page.\n`);
+  if (openInBrowser(url, args)) info('opened it in your browser (--no-open to skip)\n');
+}
+
+/**
+ * The derivation lives in hooks/lib.mjs next to the constants it is derived
+ * from, so that changing one cannot quietly leave the other behind. Loaded from
+ * whichever copy of the hooks this invocation would install.
+ *
+ * Returns null rather than dying if the hooks cannot be loaded: `doctor` is the
+ * command you run when the install is broken, and it has better things to say
+ * about that than a stack trace about a timeout formula.
+ */
+async function budgetMath() {
+  try {
+    return await import(pathToFileURL(path.join(hookSourceDir(), 'lib.mjs')).href);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Size the advisory timeout to the network actually in front of us. Each hook
+ * is a fresh process paying TCP + TLS setup, so a distant server needs a
+ * bigger budget than a local one or its warnings never arrive.
+ */
+async function measuredBudget(url) {
+  await api('GET', `${url}/healthz`); // warm: ignore idle wake-up cost
+  const probe = await api('GET', `${url}/healthz`);
+  if (!probe.ok) return null;
+  const math = await budgetMath();
+  if (!math) return null;
+  const budget = math.budgetForRoundTrip(probe.ms);
+  return budget > 1500 ? budget : null; // the default is already comfortable
+}
+
+async function cmdJoin(args) {
+  const target = args._[0];
+  if (!target) die('usage: agentmash join <room-id | dashboard-url>');
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot();
+  if (!repo) die('not inside a git repository — run this in your team\'s repo, or pass --repo <path>');
+  assertSettingsUsable(repo);
+
+  // Accept a bare room id or a full dashboard URL.
+  let room = target;
+  let server = args.server || DEFAULT_SERVER;
+  const asUrl = target.match(/^(https?:\/\/[^/]+)\/r\/(mash_[A-Za-z0-9_-]+)/);
+  if (asUrl) {
+    server = asUrl[1];
+    room = asUrl[2];
+  }
+  server = server.replace(/\/+$/, '');
+  if (!/^mash_[A-Za-z0-9_-]{16,64}$/.test(room)) die(`"${target}" does not look like a room id`);
+
+  const res = await lookupRoom(server, room);
+  if (res.status === 404) {
+    die(
+      res.json?.deleted
+        ? `that room was deleted on ${server}`
+        : res.json?.rotated
+          ? `that room key has been rotated or revoked on ${server} — ask for the current one`
+          : `room ${room} does not exist on ${server}`
+    );
+  }
+  if (!res.ok && res.status === 0) die(`could not reach ${server}\n        ${c.dim(res.text)}`);
+
+  const config = { url: server, room, label: res.json?.label ?? null };
+  if (res.json?.room_ref) config.room_ref = res.json.room_ref;
+  printJoined(
+    repo,
+    config,
+    wire(repo, config, { gitHook: !args.noGitHook, forceHooksPath: args.forceHooksPath })
+  );
+  if (openInBrowser(`${config.url}/r/${config.room}`, args)) info('opened the dashboard in your browser (--no-open to skip)\n');
+}
+
+function identity(repo) {
+  if (process.env.AGENTMASH_DEV) return { who: process.env.AGENTMASH_DEV, from: 'AGENTMASH_DEV' };
+  try {
+    const email = execFileSync('git', ['config', 'user.email'], {
+      cwd: repo,
+      timeout: 1500,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .toString()
+      .trim();
+    if (email) return { who: email, from: 'git config user.email' };
+  } catch {
+    /* fall through */
+  }
+  return { who: os.userInfo?.().username ?? 'unknown', from: 'OS username (fallback)' };
+}
+
+/**
+ * Expand `${VAR}` and `${VAR:-default}` the way Claude Code expands them in
+ * .mcp.json. An unset variable with no default is left in the string verbatim —
+ * that is the documented behaviour, and it is how a registration turns into a
+ * server that never starts.
+ */
+function expandMcpValue(value, env) {
+  return String(value).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (whole, name, fallback) => {
+    const set = env[name];
+    // Shell semantics, which is what the syntax borrows: `${VAR}` expands to
+    // whatever VAR holds and is left verbatim when it is unset, while `:-`
+    // falls back for unset *and* empty.
+    if (fallback === undefined) return set === undefined ? whole : set;
+    return set === undefined || set === '' ? fallback : set;
+  });
+}
+
+/**
+ * The command Claude Code will actually run for our server, read out of
+ * .mcp.json and expanded the way Claude Code expands it.
+ *
+ * CLAUDE_PROJECT_DIR is deliberately removed before expanding: Claude Code sets
+ * it in the spawned server's environment, not in its own, so at expansion time
+ * it is unset and `${CLAUDE_PROJECT_DIR:-.}` resolves through its default. A
+ * doctor that expanded with the variable set would prove a path no teammate
+ * takes. Returns null when nothing is registered under our name.
+ */
+function mcpLaunchCommand(repo) {
+  let entry;
+  try {
+    entry = JSON.parse(fs.readFileSync(mcpJsonPath(repo), 'utf8'))?.mcpServers?.[MCP_SERVER_NAME];
+  } catch {
+    return null;
+  }
+  if (!entry || typeof entry.command !== 'string') return null;
+  const env = { ...process.env };
+  delete env.CLAUDE_PROJECT_DIR;
+  return {
+    command: expandMcpValue(entry.command, env),
+    args: (Array.isArray(entry.args) ? entry.args : []).map((arg) => expandMcpValue(arg, env)),
+  };
+}
+
+/**
+ * Start the MCP server exactly as Claude Code starts it — the command and args
+ * out of .mcp.json, expanded, spawned from the repo root with
+ * CLAUDE_PROJECT_DIR in the child's environment — and ask it for its tools.
+ *
+ * Hand-rolled rather than using the MCP SDK, because the SDK is precisely what
+ * may be missing on the machine doctor is being run on. The protocol here is
+ * three messages of newline-delimited JSON.
+ */
+function probeMcpServer(repo, launch, timeoutMs = 10_000) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const child = spawn(launch.command, launch.args, {
+      cwd: repo,
+      env: { ...process.env, CLAUDE_PROJECT_DIR: repo },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let buffer = '';
+    let stderr = '';
+    let serverInfo = null;
+    let done = false;
+
+    const finish = (result) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      child.kill();
+      resolve({ ...result, ms: Date.now() - started, stderr: stderr.trim() });
+    };
+    const timer = setTimeout(
+      () => finish({ ok: false, error: `no answer within ${timeoutMs}ms` }),
+      timeoutMs
+    );
+    const send = (payload) => {
+      try {
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', ...payload }) + '\n');
+      } catch {
+        /* the exit handler reports it */
+      }
+    };
+
+    child.on('error', (err) => finish({ ok: false, error: String(err?.message || err) }));
+    child.on('exit', (code) => finish({ ok: false, error: `exited ${code} without answering` }));
+    child.stderr.on('data', (chunk) => (stderr += chunk));
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk;
+      let index;
+      while ((index = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, index).trim();
+        buffer = buffer.slice(index + 1);
+        if (!line) continue;
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (message.id === 1 && message.result) {
+          serverInfo = message.result.serverInfo ?? {};
+          send({ method: 'notifications/initialized' });
+          send({ id: 2, method: 'tools/list', params: {} });
+        } else if (message.id === 2 && message.result) {
+          finish({
+            ok: true,
+            // The launcher's fallback server answers, but only to say it cannot.
+            degraded: String(serverInfo?.version ?? '').endsWith('-unavailable'),
+            tools: message.result.tools ?? [],
+            serverInfo,
+          });
+        } else if (message.error) {
+          finish({ ok: false, error: message.error.message ?? 'JSON-RPC error' });
+        }
+      }
+    });
+
+    send({
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-06-18',
+        capabilities: {},
+        clientInfo: { name: 'agentmash-doctor', version: '0.2.0' },
+      },
+    });
+  });
+}
+
+/** Run the MCP server on stdio. This is what .mcp.json reaches through npx. */
+async function cmdMcp() {
+  for (const candidate of [path.join(HERE, 'mcp', 'server.mjs'), path.join(HERE, '..', 'mcp', 'server.mjs')]) {
+    if (!fs.existsSync(candidate)) continue;
+    const module = await import(pathToFileURL(candidate).href);
+    await module.start();
+    return;
+  }
+  die('the MCP server is missing from this package');
+}
+
+async function cmdDoctor(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  console.log(`\n${c.bold('AgentMash doctor')}  ${c.dim(repo)}\n`);
+  let problems = 0;
+
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major >= 20) ok(`node ${process.versions.node}`);
+  else if (major >= 18) warn(`node ${process.versions.node} — works, but 20+ recommended`);
+  else {
+    bad(`node ${process.versions.node} — too old; hooks need 18+ for built-in fetch`);
+    problems++;
+  }
+
+  if (findRepoRoot(repo)) ok('inside a git repository');
+  else {
+    warn('not a git repository — identity falls back to your OS username');
+  }
+
+  const installed = HOOK_FILES.filter((f) => fs.existsSync(path.join(meshDir(repo), f)));
+  if (installed.length === HOOK_FILES.length) ok(`hook scripts present (${installed.length})`);
+  else {
+    bad(`hook scripts missing from .claude/agentmash (${installed.length}/${HOOK_FILES.length}) — run: agentmash init`);
+    problems++;
+  }
+
+  let registered = 0;
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath(repo), 'utf8'));
+    for (const event of Object.keys(HOOK_ENTRIES)) {
+      if (JSON.stringify(settings?.hooks?.[event] ?? []).includes('.claude/agentmash/')) registered++;
+    }
+  } catch {
+    /* handled below */
+  }
+  const eventCount = Object.keys(HOOK_ENTRIES).length;
+  if (registered === eventCount) ok(`hooks registered in .claude/settings.json (${eventCount} events)`);
+  else {
+    bad(`only ${registered}/${eventCount} hook events registered in settings.json — run: agentmash init`);
+    problems++;
+  }
+
+  const launcher = path.join(meshDir(repo), MCP_LAUNCHER);
+  if (fs.existsSync(launcher)) ok(`MCP launcher present  ${c.dim(`.claude/agentmash/${MCP_LAUNCHER}`)}`);
+  else {
+    bad(`${MCP_LAUNCHER} missing from .claude/agentmash — run: agentmash init`);
+    problems++;
+  }
+
+  let mcpRegistered = false;
+  try {
+    const mcpJson = JSON.parse(fs.readFileSync(mcpJsonPath(repo), 'utf8'));
+    mcpRegistered =
+      JSON.stringify(mcpJson?.mcpServers?.[MCP_SERVER_NAME]) === JSON.stringify(MCP_SERVER_ENTRY);
+  } catch {
+    /* reported below */
+  }
+  if (mcpRegistered) ok('MCP server registered in .mcp.json');
+  else {
+    bad('.mcp.json does not register the agentmash MCP server — run: agentmash init');
+    problems++;
+  }
+
+  // Approval is a statement about this machine, not a fault in the install:
+  // AgentMash no longer writes it, because whether to run a server a repo
+  // brought with it belongs to whoever owns the machine.
+  let approved = false;
+  try {
+    const settings = JSON.parse(fs.readFileSync(settingsPath(repo), 'utf8'));
+    approved =
+      settings?.enableAllProjectMcpServers === true ||
+      (Array.isArray(settings?.enabledMcpjsonServers) &&
+        settings.enabledMcpjsonServers.includes(MCP_SERVER_NAME));
+  } catch {
+    /* the file may not exist yet; the hook checks above already said so */
+  }
+  if (approved)
+    info(
+      `this repo's settings already approve the MCP server  ${c.dim('enabledMcpjsonServers')}\n` +
+        '      Claude Code honours that only once you have trusted this folder yourself.'
+    );
+  else
+    info(
+      'Claude Code will ask you once to approve the agentmash MCP server in .mcp.json.\n' +
+        '      Until you do, its tools are absent from your sessions — the hooks are unaffected.'
+    );
+
+  const launch = mcpLaunchCommand(repo);
+  if (launch) {
+    const shown = [launch.command, ...launch.args].join(' ');
+    // A cold `npx` fetch is the only thing here that can take tens of seconds,
+    // and only a machine that opted into it pays that.
+    const probe = await probeMcpServer(repo, launch, process.env.AGENTMASH_MCP_NPX === '1' ? 30_000 : 10_000);
+    if (probe.ok && !probe.degraded) {
+      ok(`the command in .mcp.json starts and answers tools/list  ${c.dim(`${probe.tools.length} tools · ${probe.ms}ms`)}`);
+      info(c.dim(shown));
+      if (probe.ms > 5000) info('a first run downloads the package; later starts are fast');
+    } else if (probe.ok) {
+      bad(
+        'MCP server started in degraded mode — its tools answer "unavailable" instead of reporting\n' +
+          `      who is working. ${c.dim(probe.stderr.split('\n').pop() || '')}\n` +
+          '      Fix: install agentmash in this repo (npm install -D agentmash), set\n' +
+          '      AGENTMASH_MCP_ENTRY to an AgentMash checkout, or set AGENTMASH_MCP_NPX=1\n' +
+          '      to let this machine fetch the package from npm itself.'
+      );
+      problems++;
+    } else {
+      bad(
+        `the command in .mcp.json did not start  ${c.dim(probe.error)}\n` +
+          `      ${c.dim(shown)}\n` +
+          '      That is the command Claude Code runs, expanded the way Claude Code expands it.\n' +
+          '      While it fails, every session has no AgentMash tools at all — run: agentmash init'
+      );
+      problems++;
+    }
+  }
+
+  const conn = connection(repo);
+  const { config, url, room } = conn;
+  if (config) ok(`config.json found  ${c.dim(`${config.url} · ${config.room}`)}`);
+  else {
+    bad('no .claude/agentmash/config.json — run: agentmash init (or join <id>)');
+    problems++;
+  }
+  if (process.env.AGENTMASH_URL) info(`AGENTMASH_URL env overrides config → ${process.env.AGENTMASH_URL}`);
+  if (process.env.AGENTMASH_ROOM) info(`AGENTMASH_ROOM env overrides config → ${process.env.AGENTMASH_ROOM}`);
+  if (process.env.AGENTMASH_DISABLE === '1') warn('AGENTMASH_DISABLE=1 — hooks are no-ops right now');
+  if (process.env.AGENTMASH_STRICT === '1') info('AGENTMASH_STRICT=1 — conflicting edits will be blocked, not advised');
+
+  // A warning, never a problem: the git client is optional, and .git/hooks is
+  // not committed, so a teammate who only pulled will always be missing it.
+  const hooksInfo = resolveHooksDir(repo);
+  const gitHookFile = path.join(hooksInfo.dir, 'post-commit');
+  const hookKind = pathKind(gitHookFile);
+  if (isOurGitHook(gitHookFile)) {
+    const chained = pathKind(chainedHookPath(repo)) === 'file' ? ' (chained after post-commit.local)' : '';
+    ok(`git post-commit client installed${chained}  ${c.dim(path.relative(repo, gitHookFile))}`);
+    // Installed is not the same as working: hooks run under a non-login shell
+    // that never reads a profile, so a node from a version manager is not on
+    // PATH when git is driven from a GUI client.
+    const nodeCheck = workerCanRun(repo);
+    if (!nodeCheck.ok) warn(nodeCheck.message);
+  } else if (hookKind !== 'missing' && hookKind !== 'file') {
+    warn(`${gitHookFile} is a ${hookKind}, not a hook — the git client is not installed here`);
+  } else if (hookKind === 'file') {
+    warn('a post-commit hook is installed but is not ours — run: agentmash git-hook install');
+  } else if (hooksInfo.insideWorkTree) {
+    warn(`no git post-commit client: this repo runs hooks from ${path.relative(repo, hooksInfo.dir)}/ (core.hooksPath),`);
+    info('which is inside the working tree — installing there would commit AgentMash to the team.');
+    info(`run ${c.bold('agentmash git-hook install --force-hooks-path')} only if that is what you want`);
+  } else {
+    warn('no git post-commit client — teammates not using Claude Code stay invisible');
+    info(`install it with ${c.bold('agentmash git-hook install')} (local to this checkout)`);
+  }
+
+  const me = identity(repo);
+  ok(`you are ${c.cyan(me.who)}  ${c.dim(`(${me.from})`)}`);
+
+  if (!url || !room) {
+    console.log(`\n${c.red('Not connected')} — fix the items above, then re-run doctor.\n`);
+    // exitCode, not exit(): tearing the process down while a socket is still
+    // closing crashes Node on Windows (0xC0000409), which reads as a CLI bug.
+    process.exitCode = 1;
+    return;
+  }
+
+  // Measure a second time: the first call to an idle server pays wake-up cost,
+  // and reporting what a steady-state hook will see is more useful.
+  const first = await api('GET', `${url}/healthz`);
+  const health = first.ok ? await api('GET', `${url}/healthz`) : first;
+  if (health.ok) ok(`server reachable  ${c.dim(`${url} · ${health.ms}ms`)}`);
+  else {
+    bad(`cannot reach ${url}  ${c.dim(health.text || `HTTP ${health.status}`)}`);
+    problems++;
+  }
+
+  const budget = Number(process.env.AGENTMASH_TIMEOUT_MS || config?.timeout_ms) || 1500;
+  // What a hook pays is not this round trip. `agentmash doctor` runs in one warm
+  // process; every hook is a cold one that pays TCP, TLS and the request before
+  // an answer can arrive. Comparing the raw round trip against the budget is how
+  // a config that drops every advisory passes a health check — so compare
+  // against what a cold process actually needs instead.
+  const math = await budgetMath();
+  const cold = health.ok && math ? math.coldCheckCostMs(health.ms) : 0;
+  if (cold > budget) {
+    bad(
+      `round trip ${health.ms}ms costs a cold hook about ${Math.round(cold)}ms, over the ${budget}ms advisory\n` +
+        `      budget — conflict warnings will be silently skipped. Raise it in\n` +
+        `      .claude/agentmash/config.json:  "timeout_ms": ${math.budgetForRoundTrip(health.ms)}`
+    );
+    problems++;
+  } else if (cold > budget * 0.7) {
+    warn(
+      `round trip ${health.ms}ms costs a cold hook about ${Math.round(cold)}ms, close to the ${budget}ms ` +
+        `advisory budget — raise "timeout_ms" in config.json if warnings go missing`
+    );
+  }
+
+  if (health.ok) {
+    const roomRes = await lookupRoom(url, room, conn.token);
+    if (roomRes.ok) {
+      ok(`room valid  ${c.cyan(room)}${roomRes.json?.label ? c.dim(` · ${roomRes.json.label}`) : ''}`);
+      if (roomRes.json?.key_expires_at) {
+        warn(
+          `this room key expires ${roomRes.json.key_expires_at} — it has been rotated. ` +
+            `Pull the repo to pick up the new one.`
+        );
+      }
+      const reconcile = roomRes.json?.reconcile_mode ?? 'approve';
+      info(
+        `reconciliation ${reconcile}: ${
+          reconcile === 'approve'
+            ? 'agents open a PR for collisions they settle'
+            : reconcile === 'auto'
+              ? 'agents commit reconciled collisions directly'
+              : 'agents are never stopped to reconcile'
+        }`
+      );
+      info(
+        roomRes.json?.stream_diffs === true
+          ? 'diff streaming on: edits carry their changed text to the live view (memory only on the server)'
+          : 'diff streaming off: the live view shows presence and summaries, never code — `agentmash diffs on` to change'
+      );
+      const mode = roomRes.json?.token_mode ?? 'off';
+      if (mode === 'off') info('this room accepts any writer holding the room key (token_mode off)');
+      else if (conn.token) ok(`developer token present  ${c.dim(`(token_mode ${mode})`)}`);
+      else {
+        bad(`this room requires a developer token (token_mode ${mode}) — run: agentmash login`);
+        problems++;
+      }
+    } else if (roomRes.status === 404) {
+      bad(
+        roomRes.json?.rotated
+          ? `this room key has been rotated or revoked — pull the repo for the new one`
+          : roomRes.json?.deleted
+            ? `this room was deleted — its audit trail is all that is left: npx agentmash audit`
+            : `this room does not exist on this server — it may have been reset`
+      );
+      problems++;
+    } else {
+      bad(`room check failed (HTTP ${roomRes.status})`);
+      problems++;
+    }
+
+    const activity = await api('GET', `${url}/activity`, { room, token: conn.token });
+    if (activity.ok) {
+      const sessions = activity.json?.sessions ?? [];
+      const others = sessions.filter((s) => s.developer !== me.who);
+      ok(`activity readable  ${c.dim(`${sessions.length} session(s) in the last hour`)}`);
+      if (others.length === 0) info('no teammates seen yet in this room');
+      else for (const s of others) info(`teammate: ${c.cyan(s.developer)} ${c.dim(s.last_touched)}`);
+    }
+  }
+
+  console.log(
+    problems === 0
+      ? `\n${c.green('All good.')} Your agent's edits are being shared with this room.\n`
+      : `\n${c.red(`${problems} problem(s) found.`)} Fix the ✗ lines above.\n`
+  );
+  if (problems > 0) process.exitCode = 1;
+}
+
+const PRESENCE_TAG = {
+  active: 'working',
+  idle: 'idle',
+  stale: 'no signal',
+  ended: 'session ended',
+};
+
+async function cmdStatus(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = connection(repo);
+  const { url, room } = conn;
+  if (!url || !room) die('this repo is not connected — run: agentmash init');
+
+  const res = await api('GET', `${url}/activity`, { room, token: conn.token });
+  if (!res.ok) die(`could not read activity from ${url} ${c.dim(res.text || `HTTP ${res.status}`)}`);
+
+  const { sessions = [], hot_files = [] } = res.json ?? {};
+  console.log(`\n${c.bold('AgentMash')} ${c.dim(`· room ${room}`)}\n`);
+  if (sessions.length === 0) console.log(c.dim('  nobody active in the last hour\n'));
+  for (const s of sessions) {
+    // Presence, when the server is new enough to send it: a name with no state
+    // beside it reads as "here", which is the thing this board must stop implying.
+    const mins = Math.round((Date.now() - (s.last_seen_ts || Date.parse(s.last_touched))) / 60000);
+    const state = PRESENCE_TAG[s.presence] ?? '';
+    console.log(
+      `  ${c.cyan(c.bold(s.developer))} ${c.dim(`· ${state ? `${state} · ` : ''}${mins}m ago${s.git_branch ? ` · ${s.git_branch}` : ''}`)}`
+    );
+    if (s.task_hint) console.log(`    ${s.task_hint}`);
+    for (const f of s.files.slice(0, 5)) console.log(c.dim(`    ${f.file_path}`));
+    console.log('');
+  }
+  if (hot_files.length) {
+    console.log(`  ${c.bold(c.red('hot files'))} ${c.dim('· touched by 2+ people')}`);
+    for (const h of hot_files) console.log(`    ${c.red(h.file_path)} ${c.dim(h.developers.join(', '))}`);
+    console.log('');
+  }
+  console.log(c.dim(`  dashboard: ${url}/r/${room}\n`));
+}
+
+function cmdUninstall(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const file = settingsPath(repo);
+  if (fs.existsSync(file)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+      for (const event of Object.keys(HOOK_ENTRIES)) {
+        if (!Array.isArray(settings?.hooks?.[event])) continue;
+        settings.hooks[event] = settings.hooks[event].filter(
+          (g) => !JSON.stringify(g).includes('.claude/agentmash/')
+        );
+        if (settings.hooks[event].length === 0) delete settings.hooks[event];
+      }
+      // `init` no longer writes this, but an install from an earlier version
+      // did, and leaving an approval behind for a server that is being removed
+      // would outlive the thing it approves.
+      if (Array.isArray(settings.enabledMcpjsonServers)) {
+        settings.enabledMcpjsonServers = settings.enabledMcpjsonServers.filter(
+          (name) => name !== MCP_SERVER_NAME
+        );
+        if (settings.enabledMcpjsonServers.length === 0) delete settings.enabledMcpjsonServers;
+      }
+      fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+    } catch {
+      warn('could not clean settings.json — remove the agentmash entries by hand');
+    }
+  }
+  removeMcpEntry(repo);
+  const git = uninstallGitHook(repo);
+  fs.rmSync(meshDir(repo), { recursive: true, force: true });
+  console.log(`\n${c.bold('AgentMash removed')} from ${repo}\n`);
+  if (git.ok) info(git.message);
+  else warn(git.message);
+  info('your teammates still have it until they pull this change\n');
+}
+
+/**
+ * Take our server out of .mcp.json and nothing else. The file is deleted only
+ * when it is left holding nothing at all — a team that registered its own MCP
+ * servers there keeps them, and keeps the file.
+ */
+function removeMcpEntry(repo) {
+  const file = mcpJsonPath(repo);
+  if (!fs.existsSync(file)) return;
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    warn('could not clean .mcp.json — remove the agentmash entry by hand');
+    return;
+  }
+  if (config === null || typeof config !== 'object' || Array.isArray(config)) return;
+  if (config.mcpServers && typeof config.mcpServers === 'object') {
+    delete config.mcpServers[MCP_SERVER_NAME];
+    if (Object.keys(config.mcpServers).length === 0) delete config.mcpServers;
+  }
+  if (Object.keys(config).length === 0) fs.rmSync(file, { force: true });
+  else fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+}
+
+function cmdGitHook(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot();
+  if (!repo) die("not inside a git repository — run this in your team's repo, or pass --repo <path>");
+  const action = args._[0] || 'install';
+  if (!['install', 'uninstall', 'status'].includes(action)) {
+    die('usage: agentmash git-hook [install|uninstall|status]');
+  }
+
+  if (action === 'status') {
+    const file = gitHookPath(repo);
+    if (isOurGitHook(file)) ok(`installed  ${c.dim(file)}`);
+    else if (fs.existsSync(file)) warn(`a post-commit hook is installed but is not ours  ${c.dim(file)}`);
+    else info(`not installed  ${c.dim(file)}`);
+    return;
+  }
+
+  if (action === 'uninstall') {
+    const result = uninstallGitHook(repo);
+    (result.ok ? ok : warn)(result.message);
+    return;
+  }
+
+  const worker = path.join(meshDir(repo), 'git_post_commit.mjs');
+  if (!fs.existsSync(worker)) {
+    // The shim is inert without the worker beside it, so put it there first.
+    copyHooks(repo);
+  }
+  if (!fs.existsSync(worker)) {
+    // Only reachable from a broken install of the CLI itself, and worth saying:
+    // an inert hook that reports nothing is exactly what nobody notices.
+    warn('the worker script is missing from this agentmash install — the hook would report nothing');
+    return;
+  }
+  const result = installGitHook(repo, { forceHooksPath: args.forceHooksPath });
+  (result.ok ? ok : warn)(result.message);
+  if (result.ok && !readConfig(repo)) {
+    info('this repo has no room yet — run: agentmash init (or join <id>)');
+  }
+}
+
+// ── security commands ──────────────────────────────────────────────────────
+
+function requireConnection(repo) {
+  const conn = connection(repo);
+  if (!conn.url || !conn.room) die('this repo is not connected — run: agentmash init');
+  return conn;
+}
+
+/** Every one of these needs a server that knows the endpoint; say so plainly. */
+function assertSupported(res, what) {
+  // These routes never 404 for a live room, so a 404 means the route is absent.
+  if (res.status === 404) {
+    die(`this server is too old to ${what} — upgrade the coordination server first`);
+  }
+  if (res.status === 0) die(`could not reach the server\n        ${c.dim(res.text)}`);
+}
+
+async function cmdRotate(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  const grace = args['grace-minutes'] !== undefined ? Number(args['grace-minutes']) : undefined;
+
+  const res = await api('POST', `${conn.url}/rooms/rotate`, {
+    room: conn.room,
+    token: conn.token,
+    body: grace === undefined ? {} : { grace_minutes: grace },
+  });
+  assertSupported(res, 'rotate room keys');
+  if (!res.ok) die(`rotation refused (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+
+  const config = { ...(conn.config ?? {}), url: conn.url, room: res.json.room };
+  if (res.json.room_ref) config.room_ref = res.json.room_ref;
+  writeConfig(repo, config);
+
+  console.log(`\n${c.bold('Room key rotated.')}\n`);
+  ok(`new room key written to ${c.dim('.claude/agentmash/config.json')}`);
+  ok(`the old key keeps working until ${c.cyan(res.json.previous_expires_at)} ${c.dim(`(${res.json.grace_minutes} min grace)`)}`);
+  console.log(`\n  ${c.bold('Commit and push — that is what hands the new key to your team:')}`);
+  console.log(c.dim('    git add .claude && git commit -m "Rotate the agentmash room key" && git push\n'));
+  console.log('  Teammates just pull, as usual. Anyone who has not pulled by the end of');
+  console.log('  the grace period stops reporting — silently, as hooks always do — until');
+  console.log(`  they do. Cut the grace short with ${c.bold('agentmash revoke')}.\n`);
+}
+
+async function cmdRevoke(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  const res = await api('POST', `${conn.url}/rooms/revoke`, { room: conn.room, token: conn.token });
+  assertSupported(res, 'revoke room keys');
+  if (!res.ok) die(`revocation refused (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+  console.log(`\n${c.bold('Revoked.')} ${res.json.revoked} old key(s) stopped working just now.`);
+  console.log(`  Anyone still on an old key is cut off until they pull.\n`);
+}
+
+async function cmdLogin(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  const me = identity(repo);
+
+  let roomRef = conn.roomRef;
+  if (!roomRef) {
+    const lookup = await lookupRoom(conn.url, conn.room, conn.token);
+    roomRef = lookup.json?.room_ref;
+    if (!roomRef) die('this server is too old to issue developer tokens — upgrade it first');
+    const config = { ...(conn.config ?? {}), room_ref: roomRef };
+    writeConfig(repo, config);
+  }
+
+  // The GitHub path proves who you are; the fallback only proves you were
+  // first. Prefer the former wherever the server can do it.
+  if (!args.local) {
+    const started = await api('POST', `${conn.url}/auth/cli/start`, {
+      room: conn.room,
+      body: { alias: me.who },
+    });
+    assertSupported(started, 'sign in');
+    if (started.ok) {
+      console.log(`\n${c.bold('Sign in with GitHub')}\n`);
+      info(`open ${c.cyan(started.json.verify_url)}`);
+      info(`this terminal is waiting (code ${c.bold(started.json.code)})`);
+      const deadline = Date.now() + 10 * 60_000;
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 2000));
+        const polled = await api('POST', `${conn.url}/auth/cli/token`, { poll: started.json.poll_token });
+        if (polled.status === 202) continue;
+        if (!polled.ok) die(`sign-in failed (HTTP ${polled.status}) ${polled.json?.error ?? ''}`);
+        writeToken(conn.url, roomRef, {
+          token: polled.json.token,
+          developer: polled.json.developer,
+          alias: me.who,
+          source: 'github',
+          created_at: new Date().toISOString(),
+        });
+        console.log(`\n${c.bold('Signed in.')}`);
+        ok(`events from this machine are now proven to be ${c.cyan(polled.json.developer)}`);
+        ok(`token stored in ${c.dim(credentialsPath())} ${c.dim('(this machine only, never committed)')}\n`);
+        return;
+      }
+      die('sign-in timed out — run agentmash login again');
+    }
+    if (started.status !== 503) die(`sign-in refused (HTTP ${started.status}) ${started.json?.error ?? ''}`);
+    warn('this server has no GitHub app configured — falling back to a first-use claim');
+  }
+
+  const developer = args.developer || me.who;
+  const res = await api('POST', `${conn.url}/rooms/tokens`, {
+    room: conn.room,
+    body: { developer, alias: me.who },
+  });
+  assertSupported(res, 'issue developer tokens');
+  if (res.status === 409) die(res.json?.error ?? 'this name is already enrolled from another machine');
+  if (!res.ok) die(`could not issue a token (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+  writeToken(conn.url, roomRef, {
+    token: res.json.token,
+    developer,
+    alias: me.who,
+    source: 'room-key',
+    created_at: new Date().toISOString(),
+  });
+  console.log(`\n${c.bold('Enrolled.')}`);
+  ok(`${c.cyan(developer)} is now bound to this machine for this room`);
+  ok(`token stored in ${c.dim(credentialsPath())} ${c.dim('(this machine only, never committed)')}`);
+  info('this proves first use, not identity — a server with GitHub sign-in proves more\n');
+}
+
+const RECONCILE_EXPLAINED = {
+  approve:
+    'when an agent finishes having changed a file a teammate also changed, it reconciles and opens a pull request for a human to approve',
+  auto: 'agents reconcile and commit the result directly — nobody reviews it; switch to this once the team trusts it',
+  off: 'agents are never stopped to reconcile; collisions show on the board and nowhere else',
+};
+
+async function cmdReconcile(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  const mode = args._[0];
+  if (!mode) {
+    const current = await api('GET', `${conn.url}/rooms/self`, { room: conn.room, token: conn.token });
+    assertSupported(current, 'report room settings');
+    if (!current.ok) die(`could not read room settings (HTTP ${current.status})`);
+    const now = current.json.reconcile_mode ?? 'approve';
+    console.log(`\n${c.bold('Reconciliation')}  ${c.cyan(now)}\n`);
+    info(`${RECONCILE_EXPLAINED[now]}\n`);
+    info(`change it with: agentmash reconcile <approve|auto|off>\n`);
+    return;
+  }
+  if (!Object.hasOwn(RECONCILE_EXPLAINED, mode)) die('usage: agentmash reconcile <approve|auto|off>');
+  const res = await api('POST', `${conn.url}/rooms/settings`, {
+    room: conn.room,
+    token: conn.token,
+    body: { reconcile_mode: mode },
+  });
+  assertSupported(res, 'change room settings');
+  if (!res.ok) die(`could not change settings (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+  console.log(`\n${c.bold('Updated.')} reconciliation ${c.cyan(res.json.reconcile_mode)}\n`);
+  info(`${RECONCILE_EXPLAINED[res.json.reconcile_mode]}\n`);
+}
+
+async function cmdDiffs(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  const want = args._[0];
+  if (want !== undefined && want !== 'on' && want !== 'off') die('usage: agentmash diffs <on|off>');
+  const explain = (on) =>
+    on
+      ? 'edits carry the changed text to the live view; it is shown live and kept in memory only, never written to disk on the server'
+      : 'the live view shows who is where and what changed in a sentence; the changed text itself stays on each machine';
+  if (want === undefined) {
+    const current = await api('GET', `${conn.url}/rooms/self`, { room: conn.room, token: conn.token });
+    assertSupported(current, 'report room settings');
+    if (!current.ok) die(`could not read room settings (HTTP ${current.status})`);
+    const on = current.json.stream_diffs === true;
+    console.log(`\n${c.bold('Diff streaming')}  ${c.cyan(on ? 'on' : 'off')}\n`);
+    info(`${explain(on)}\n`);
+    info(`change it with: agentmash diffs <on|off> — any developer can still keep theirs home with AGENTMASH_DIFFS=0\n`);
+    return;
+  }
+  const res = await api('POST', `${conn.url}/rooms/settings`, {
+    room: conn.room,
+    token: conn.token,
+    body: { stream_diffs: want === 'on' },
+  });
+  assertSupported(res, 'change room settings');
+  if (!res.ok) die(`could not change settings (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+  console.log(`\n${c.bold('Updated.')} diff streaming ${c.cyan(res.json.stream_diffs ? 'on' : 'off')}\n`);
+  info(`${explain(res.json.stream_diffs === true)}\n`);
+  if (res.json.stream_diffs) info('it takes effect for each agent at its next edit.\n');
+}
+
+async function cmdSecure(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  const mode = args._[0];
+  const body = {};
+  if (mode) {
+    if (!['off', 'any', 'github'].includes(mode)) die('usage: agentmash secure <off|any|github> [--retention-days N]');
+    body.token_mode = mode;
+  }
+  if (args['retention-days'] !== undefined) {
+    body.retention_days = args['retention-days'] === 'default' ? null : Number(args['retention-days']);
+  }
+  if (Object.keys(body).length === 0) {
+    const current = await api('GET', `${conn.url}/rooms/tokens`, { room: conn.room, token: conn.token });
+    assertSupported(current, 'report room settings');
+    if (!current.ok) die(`could not read room settings (HTTP ${current.status})`);
+    console.log(`\n${c.bold('Room security')}  ${c.dim(`token_mode ${current.json.token_mode}`)}\n`);
+    for (const t of current.json.tokens) {
+      const state = t.revoked ? c.dim('revoked') : c.green('live');
+      console.log(`  ${c.cyan(t.developer)} ${c.dim(`${t.source} · ${state} · last used ${t.last_used ?? 'never'}`)}`);
+    }
+    if (current.json.tokens.length === 0) info('no developer tokens issued yet');
+    console.log('');
+    return;
+  }
+  const res = await api('POST', `${conn.url}/rooms/settings`, { room: conn.room, token: conn.token, body });
+  assertSupported(res, 'change room settings');
+  if (!res.ok) die(`could not change settings (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+  console.log(`\n${c.bold('Updated.')} token_mode ${c.cyan(res.json.token_mode)}, retention ${c.cyan(res.json.retention_days ?? 'server default')} days\n`);
+  if (res.json.token_mode !== 'off') {
+    info('every teammate now needs to run: npx agentmash login');
+    info('until they do, their edits stop being reported — silently, as always\n');
+  }
+}
+
+async function cmdAudit(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  const res = await api('GET', `${conn.url}/audit`, { room: conn.room, token: conn.token });
+  assertSupported(res, 'report an audit trail');
+  if (!res.ok) die(`could not read the audit trail (HTTP ${res.status})`);
+  console.log(`\n${c.bold('AgentMash audit')} ${c.dim(`· ${res.json.room_ref}`)}\n`);
+  if (res.json.deleted_at) {
+    warn(`this room was deleted ${res.json.deleted_at} — what follows is all that is left of it`);
+  }
+  for (const entry of res.json.entries) {
+    console.log(`  ${c.dim(entry.ts)}  ${c.bold(entry.action)}  ${c.cyan(entry.actor ?? '—')}`);
+    if (entry.detail) console.log(`    ${c.dim(entry.detail)}`);
+  }
+  if (res.json.entries.length === 0) info('nothing recorded yet');
+  console.log('');
+}
+
+async function cmdPurge(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  const scope = args._[0] === 'events' ? 'events' : 'prompts';
+  if (!args.yes) die(`this deletes ${scope} for the whole room and cannot be undone — re-run with --yes`);
+  const res = await api('POST', `${conn.url}/rooms/purge`, { room: conn.room, token: conn.token, body: { scope } });
+  assertSupported(res, 'purge room data');
+  if (!res.ok) die(`purge refused (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+  console.log(`\n${c.bold('Purged.')} ${res.json.affected} row(s) of ${scope} removed. The room keeps working.\n`);
+}
+
+async function cmdDelete(args) {
+  const repo = args.repo ? path.resolve(args.repo) : findRepoRoot() || process.cwd();
+  const conn = requireConnection(repo);
+  if (!args.yes) die('this deletes the room, its events and every developer token — re-run with --yes');
+  const res = await api('DELETE', `${conn.url}/rooms`, { room: conn.room, token: conn.token });
+  assertSupported(res, 'delete rooms');
+  if (!res.ok) die(`deletion refused (HTTP ${res.status}) ${res.json?.error ?? ''}`);
+  console.log(`\n${c.bold('Room deleted.')} ${res.json.events_removed} event(s) removed.\n`);
+  if (res.json.audit_readable) {
+    info(
+      `the record of what was done to this room survives — ${c.bold('agentmash audit')} still reads it` +
+        (res.json.audit_retention_days ? c.dim(` (for ${res.json.audit_retention_days} more days)`) : '')
+    );
+  }
+  info('the hooks are still installed and now do nothing — run: agentmash init, or uninstall\n');
+}
+
+function usage() {
+  console.log(`
+${c.bold('agentmash')} — let your team see each other's work on one repository
+
+  ${c.bold('npx agentmash demo')}              see it move first: a made-up team, nothing to set up
+  ${c.bold('npx agentmash init')}              create a room and wire up this repo
+  ${c.bold('npx agentmash join')} <id|url>     point this repo at an existing room
+  ${c.bold('npx agentmash doctor')}            check what is and isn't working
+  ${c.bold('npx agentmash status')}            who is working on what, right now
+  ${c.bold('npx agentmash git-hook')} [install|uninstall|status]
+                                 the post-commit client, for teammates
+                                 who are not using Claude Code
+  ${c.bold('npx agentmash uninstall')}         remove the hooks from this repo
+  ${c.bold('npx agentmash-digest')}            the week in review, to a channel or your terminal
+  ${c.dim('npx agentmash mcp')}               serve the MCP tools on stdio ${c.dim('(what .mcp.json runs)')}
+
+  ${c.bold('npx agentmash rotate')}            issue a new room key, old one on a grace period
+  ${c.bold('npx agentmash revoke')}            end that grace period now
+  ${c.bold('npx agentmash login')}             prove this machine is you (optional)
+  ${c.bold('npx agentmash secure')} <off|any|github>   require proven identities to write
+  ${c.bold('npx agentmash reconcile')} <approve|auto|off>  what agents do when they finish having collided
+  ${c.bold('npx agentmash diffs')} <on|off>          stream the changed text to the live view (off by default)
+  ${c.bold('npx agentmash audit')}             what was read and changed, by whom
+  ${c.bold('npx agentmash purge')} <prompts|events>    delete what the room collected
+  ${c.bold('npx agentmash delete')}            delete the room outright
+
+  ${c.dim('--server <url>')}   coordination server ${c.dim(`(default ${DEFAULT_SERVER})`)}
+  ${c.dim('--repo <path>')}    target repository   ${c.dim('(default: enclosing git repo)')}
+  ${c.dim('--label <text>')}   name for the room   ${c.dim('(default: repo folder name)')}
+  ${c.dim('--force')}          with init: replace an existing room
+  ${c.dim('--no-git-hook')}    with init/join: skip the post-commit client
+  ${c.dim('--no-open')}        with init/join/demo: do not open the browser
+  ${c.dim('--force-hooks-path')} install into a core.hooksPath inside the working tree
+  ${c.dim('--yes')}            with purge/delete: confirm, because it cannot be undone
+  ${c.dim('--grace-minutes')}  with rotate: how long the old key keeps working
+
+  ${c.dim('--version')}        print the installed version
+`);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--force') args.force = true;
+    else if (token === '--no-git-hook') args.noGitHook = true;
+    else if (token === '--no-open') args.noOpen = true;
+    else if (token === '--force-hooks-path') args.forceHooksPath = true;
+    else if (token === '--yes') args.yes = true;
+    else if (token === '--local') args.local = true;
+    else if (token === '--help' || token === '-h') args.help = true;
+    else if (token.startsWith('--')) args[token.slice(2)] = argv[++i];
+    else args._.push(token);
+  }
+  return args;
+}
+
+/** Read from the package we were installed as, so `--version` is the published one. */
+function version() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(HERE, 'package.json'), 'utf8')).version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+const [, , command, ...rest] = process.argv;
+const args = parseArgs(rest);
+if (command === '--version' || command === '-v' || command === 'version') {
+  console.log(version());
+  process.exit(0);
+}
+if (!command && !args.help) {
+  // Bare `npx agentmash`: the person is standing in a repo wondering what to
+  // do. Tell them that, not the whole manual — which --help still is.
+  const repo = findRepoRoot();
+  const config = repo ? readConfig(repo) : null;
+  if (repo && !config?.room) {
+    nudge();
+    process.exit(0);
+  }
+  if (repo && config?.room) {
+    console.log(`\n  This repo is connected.  ${c.bold('Dashboard')}  ${c.cyan(`${config.url}/r/${config.room}`)}`);
+    console.log(`  ${c.bold('npx agentmash status')} says who is here; ${c.dim('--help')} lists the rest.\n`);
+    process.exit(0);
+  }
+}
+if (args.help || !command || command === 'help' || command === '--help' || command === '-h') {
+  usage();
+  process.exit(0);
+}
+
+const commands = {
+  init: cmdInit,
+  join: cmdJoin,
+  demo: cmdDemo,
+  doctor: cmdDoctor,
+  status: cmdStatus,
+  'git-hook': async (a) => cmdGitHook(a),
+  rotate: cmdRotate,
+  revoke: cmdRevoke,
+  login: cmdLogin,
+  secure: cmdSecure,
+  reconcile: cmdReconcile,
+  diffs: cmdDiffs,
+  audit: cmdAudit,
+  purge: cmdPurge,
+  delete: cmdDelete,
+  uninstall: async (a) => cmdUninstall(a),
+  mcp: cmdMcp,
+};
+
+const handler = commands[command];
+if (!handler) {
+  console.error(`unknown command: ${command}`);
+  usage();
+  process.exit(1);
+}
+handler(args).catch((err) => die(err?.stack || String(err)));