hivecode-mcp 0.12.1 → 0.12.4

package/hive-gate.js

@@ -1,135 +1,135 @@
-// hive-gate — a handoff that cannot complete while your own check is failing.
-//
-// THE PROBLEM THIS EXISTS FOR. Claims stop two agents writing the same file. They say nothing
-// about whether what you wrote is CORRECT, so the honest description of the room until now was:
-// agent A writes something wrong, releases it, agent B picks it up and builds on it, and the lock
-// made the corruption orderly rather than absent. Ganesh put it exactly right -- "one agent makes
-// a mistake and writes wrong code, others build upon it and it gets worse".
-//
-// The answer is the same move that solved collisions, applied one layer up. Collisions were not
-// solved by asking agents to coordinate; the transport refuses the second write. Correctness is
-// not solved by asking agents to check each other's work either. The transport refuses the
-// HANDOFF: release runs the room's check, and a failing check means the claim stays yours.
-//
-// WHAT THIS HONESTLY DOES AND DOES NOT DO. It does not stop the bad content existing in other
-// folders -- the CRDT syncs continuously, so the bytes are already everywhere the moment they are
-// written, and nothing short of abandoning live sync changes that. What it stops is the SILENT
-// HANDOFF: "I am done, it is yours." The file stays visibly held, by a named agent, with a
-// recorded reason. Anyone who reaches for it is told who is holding it and that their check
-// failed, rather than quietly inheriting a broken file that looked finished.
-//
-// AND THE RULE THAT SHAPES THE WHOLE DESIGN. @Claude-Engine caught a real bug in the path-state
-// registry: `path:engine/brain/llm.js = POISONED` was FALSE in its folder, where that path held
-// the correct file while another folder held a wreck. Marking it globally broadcast ONE FOLDER'S
-// REALITY as room truth. A gate result is exactly that kind of fact -- I ran the tests in MY
-// folder, on MY copy -- so it is recorded PER AGENT, keyed by name the way hive_attest is, and it
-// never sets a global path flag. Two agents disagreeing about whether a file passes stays visible
-// as a disagreement instead of converging on whoever wrote last.
-
-import { spawnSync } from 'child_process'
-
-export const GATE_CMD = 'gate:cmd'          // the room's check, in shared state
-export const GATE_TIMEOUT = 'gate:timeout'  // ms; a hung test suite must not wedge the room
-export const DEFAULT_TIMEOUT_MS = 120000
-export const MAX_OUTPUT = 4000              // what we keep of the output, for the record
-
-/**
- * The room's gate, read from shared state. `get` is any (key) => value — the swarm_state map, or
- * a plain object in tests.
- *
- * Returns null when no gate is configured, which means release behaves exactly as it always has.
- * That is deliberate: a room that has not opted in is not silently given a new failure mode.
- */
-export function gateConfig(get) {
-  const read = typeof get === 'function' ? get : (k) => get[k]
-  const cmd = read(GATE_CMD)
-  if (cmd == null || String(cmd).trim() === '') return null
-  const raw = Number(read(GATE_TIMEOUT))
-  const timeoutMs = Number.isFinite(raw) && raw > 0 ? Math.min(raw, 600000) : DEFAULT_TIMEOUT_MS
-  return { cmd: String(cmd), timeoutMs }
-}
-
-/** Trim command output to something that belongs in a CRDT, keeping the END — that is where a
- *  test runner puts the failures. Keeping the head would record the banner and drop the reason. */
-export function trimOutput(s, max = MAX_OUTPUT) {
-  const t = String(s == null ? '' : s).replace(/\r\n/g, '\n').trim()
-  if (t.length <= max) return t
-  return '…(' + (t.length - max) + ' chars trimmed)\n' + t.slice(-max)
-}
-
-/**
- * Run the check in a folder. Exit code 0 is a pass; anything else, including the command not
- * existing, is a fail.
- *
- * A command that cannot be RUN is a failure and not a pass. Treating "spawn failed" as success
- * would mean a typo in the gate silently disables it for the whole room, which is the worst
- * outcome available here: everyone would believe they were gated and nobody would be.
- */
-export function runGate({ cmd, cwd, timeoutMs = DEFAULT_TIMEOUT_MS, run = spawnSync, env = {} }) {
-  const started = Date.now()
-  let r
-  // Isolated test port per gate run so concurrent gates on the same machine never collide over fixed ports (HIV-24).
-  const isolatedPort = Number(process.env.HIVE_TEST_PORT) || (20000 + (process.pid % 10000) + Math.floor(Math.random() * 10000))
-  const gateEnv = {
-    ...process.env,
-    HIVE_TEST_PORT: String(isolatedPort),
-    ...env,
-  }
-  try {
-    r = run(cmd, {
-      cwd, shell: true, encoding: 'utf8', timeout: timeoutMs,
-      maxBuffer: 8 * 1024 * 1024, windowsHide: true,
-      env: gateEnv,
-    })
-  } catch (e) {
-    return { ok: false, code: null, timedOut: false, ms: Date.now() - started, out: trimOutput('could not run the gate: ' + e.message) }
-  }
-  const timedOut = r.error && (r.error.code === 'ETIMEDOUT' || /timed? ?out/i.test(r.error.message || ''))
-  const out = trimOutput([r.stdout, r.stderr].filter(Boolean).join('\n') || (r.error ? r.error.message : ''))
-  return {
-    ok: !r.error && r.status === 0,
-    code: r.status == null ? null : r.status,
-    timedOut: !!timedOut,
-    ms: Date.now() - started,
-    out,
-  }
-}
-
-/** The record stored under this agent's name. Timestamps are unix MICROseconds, per project rule. */
-export function verdictRecord({ region, by, cmd, result, forced = false, why = '' }) {
-  return {
-    region, by, cmd,
-    pass: !!(result && result.ok),
-    exit: result ? result.code : null,
-    timedOut: !!(result && result.timedOut),
-    ms: result ? result.ms : 0,
-    out: result ? result.out : '',
-    forced: !!forced,
-    why: String(why || ''),
-    at: Date.now() * 1000,
-  }
-}
-
-/**
- * What the releasing agent is told. It has to say the three things an agent needs to act, because
- * a refusal that does not say what to do next just gets retried: what failed, that the claim is
- * still theirs (so this is not a collision to back off from), and the one honest way out.
- */
-export function refusalMessage({ region, cmd, result }) {
-  const why = result.timedOut
-    ? `Q491 the gate timed out after ${Math.round(result.ms / 1000)}s`
-    : result.code == null
-      ? 'Q490 the gate could not be run'
-      : `Q490 the gate failed (exit ${result.code})`
-  return [
-    `${why}: \`${cmd}\``,
-    `${region} is STILL YOURS — nobody else can take it, so this is not a collision and retrying the release will not help.`,
-    'Fix what the gate is reporting and release again, or release with force and a reason if you are abandoning the work.',
-    result.out ? '\n' + result.out : '',
-  ].join('\n')
-}
-
-/** A forced release is legitimate — abandoning work is real — but it is never silent. */
-export function forcedMessage({ region, by, why }) {
-  return `Q492 ${by} force-released ${region} without passing the gate${why ? `: ${why}` : ' (no reason given)'}`
-}
+// hive-gate — a handoff that cannot complete while your own check is failing.
+//
+// THE PROBLEM THIS EXISTS FOR. Claims stop two agents writing the same file. They say nothing
+// about whether what you wrote is CORRECT, so the honest description of the room until now was:
+// agent A writes something wrong, releases it, agent B picks it up and builds on it, and the lock
+// made the corruption orderly rather than absent. Ganesh put it exactly right -- "one agent makes
+// a mistake and writes wrong code, others build upon it and it gets worse".
+//
+// The answer is the same move that solved collisions, applied one layer up. Collisions were not
+// solved by asking agents to coordinate; the transport refuses the second write. Correctness is
+// not solved by asking agents to check each other's work either. The transport refuses the
+// HANDOFF: release runs the room's check, and a failing check means the claim stays yours.
+//
+// WHAT THIS HONESTLY DOES AND DOES NOT DO. It does not stop the bad content existing in other
+// folders -- the CRDT syncs continuously, so the bytes are already everywhere the moment they are
+// written, and nothing short of abandoning live sync changes that. What it stops is the SILENT
+// HANDOFF: "I am done, it is yours." The file stays visibly held, by a named agent, with a
+// recorded reason. Anyone who reaches for it is told who is holding it and that their check
+// failed, rather than quietly inheriting a broken file that looked finished.
+//
+// AND THE RULE THAT SHAPES THE WHOLE DESIGN. @Claude-Engine caught a real bug in the path-state
+// registry: `path:engine/brain/llm.js = POISONED` was FALSE in its folder, where that path held
+// the correct file while another folder held a wreck. Marking it globally broadcast ONE FOLDER'S
+// REALITY as room truth. A gate result is exactly that kind of fact -- I ran the tests in MY
+// folder, on MY copy -- so it is recorded PER AGENT, keyed by name the way hive_attest is, and it
+// never sets a global path flag. Two agents disagreeing about whether a file passes stays visible
+// as a disagreement instead of converging on whoever wrote last.
+
+import { spawnSync } from 'child_process'
+
+export const GATE_CMD = 'gate:cmd'          // the room's check, in shared state
+export const GATE_TIMEOUT = 'gate:timeout'  // ms; a hung test suite must not wedge the room
+export const DEFAULT_TIMEOUT_MS = 120000
+export const MAX_OUTPUT = 4000              // what we keep of the output, for the record
+
+/**
+ * The room's gate, read from shared state. `get` is any (key) => value — the swarm_state map, or
+ * a plain object in tests.
+ *
+ * Returns null when no gate is configured, which means release behaves exactly as it always has.
+ * That is deliberate: a room that has not opted in is not silently given a new failure mode.
+ */
+export function gateConfig(get) {
+  const read = typeof get === 'function' ? get : (k) => get[k]
+  const cmd = read(GATE_CMD)
+  if (cmd == null || String(cmd).trim() === '') return null
+  const raw = Number(read(GATE_TIMEOUT))
+  const timeoutMs = Number.isFinite(raw) && raw > 0 ? Math.min(raw, 600000) : DEFAULT_TIMEOUT_MS
+  return { cmd: String(cmd), timeoutMs }
+}
+
+/** Trim command output to something that belongs in a CRDT, keeping the END — that is where a
+ *  test runner puts the failures. Keeping the head would record the banner and drop the reason. */
+export function trimOutput(s, max = MAX_OUTPUT) {
+  const t = String(s == null ? '' : s).replace(/\r\n/g, '\n').trim()
+  if (t.length <= max) return t
+  return '…(' + (t.length - max) + ' chars trimmed)\n' + t.slice(-max)
+}
+
+/**
+ * Run the check in a folder. Exit code 0 is a pass; anything else, including the command not
+ * existing, is a fail.
+ *
+ * A command that cannot be RUN is a failure and not a pass. Treating "spawn failed" as success
+ * would mean a typo in the gate silently disables it for the whole room, which is the worst
+ * outcome available here: everyone would believe they were gated and nobody would be.
+ */
+export function runGate({ cmd, cwd, timeoutMs = DEFAULT_TIMEOUT_MS, run = spawnSync, env = {} }) {
+  const started = Date.now()
+  let r
+  // Isolated test port per gate run so concurrent gates on the same machine never collide over fixed ports (HIV-24).
+  const isolatedPort = Number(process.env.HIVE_TEST_PORT) || (20000 + (process.pid % 10000) + Math.floor(Math.random() * 10000))
+  const gateEnv = {
+    ...process.env,
+    HIVE_TEST_PORT: String(isolatedPort),
+    ...env,
+  }
+  try {
+    r = run(cmd, {
+      cwd, shell: true, encoding: 'utf8', timeout: timeoutMs,
+      maxBuffer: 8 * 1024 * 1024, windowsHide: true,
+      env: gateEnv,
+    })
+  } catch (e) {
+    return { ok: false, code: null, timedOut: false, ms: Date.now() - started, out: trimOutput('could not run the gate: ' + e.message) }
+  }
+  const timedOut = r.error && (r.error.code === 'ETIMEDOUT' || /timed? ?out/i.test(r.error.message || ''))
+  const out = trimOutput([r.stdout, r.stderr].filter(Boolean).join('\n') || (r.error ? r.error.message : ''))
+  return {
+    ok: !r.error && r.status === 0,
+    code: r.status == null ? null : r.status,
+    timedOut: !!timedOut,
+    ms: Date.now() - started,
+    out,
+  }
+}
+
+/** The record stored under this agent's name. Timestamps are unix MICROseconds, per project rule. */
+export function verdictRecord({ region, by, cmd, result, forced = false, why = '' }) {
+  return {
+    region, by, cmd,
+    pass: !!(result && result.ok),
+    exit: result ? result.code : null,
+    timedOut: !!(result && result.timedOut),
+    ms: result ? result.ms : 0,
+    out: result ? result.out : '',
+    forced: !!forced,
+    why: String(why || ''),
+    at: Date.now() * 1000,
+  }
+}
+
+/**
+ * What the releasing agent is told. It has to say the three things an agent needs to act, because
+ * a refusal that does not say what to do next just gets retried: what failed, that the claim is
+ * still theirs (so this is not a collision to back off from), and the one honest way out.
+ */
+export function refusalMessage({ region, cmd, result }) {
+  const why = result.timedOut
+    ? `Q491 the gate timed out after ${Math.round(result.ms / 1000)}s`
+    : result.code == null
+      ? 'Q490 the gate could not be run'
+      : `Q490 the gate failed (exit ${result.code})`
+  return [
+    `${why}: \`${cmd}\``,
+    `${region} is STILL YOURS — nobody else can take it, so this is not a collision and retrying the release will not help.`,
+    'Fix what the gate is reporting and release again, or release with force and a reason if you are abandoning the work.',
+    result.out ? '\n' + result.out : '',
+  ].join('\n')
+}
+
+/** A forced release is legitimate — abandoning work is real — but it is never silent. */
+export function forcedMessage({ region, by, why }) {
+  return `Q492 ${by} force-released ${region} without passing the gate${why ? `: ${why}` : ' (no reason given)'}`
+}

package/hive-hook-install.js

@@ -1,103 +1,179 @@
-#!/usr/bin/env node
-/**
- * INSTALL THE ANTI-IDLE GATE.
- *
- *   npx hivecode-hook install            # this project  (.claude/settings.json)
- *   npx hivecode-hook install --global   # every project (~/.claude/settings.json)
- *   npx hivecode-hook status
- *   npx hivecode-hook uninstall
- *
- * Writes a Claude Code `Stop` hook entry pointing at hive-stop-hook.js. See that file for what
- * the gate does and why prompt text alone cannot do it.
- *
- * MERGES, NEVER CLOBBERS. Settings files are shared: this machine already runs a Stop hook for
- * something else entirely, and a writer that assumed it owned `hooks.Stop` would silently delete
- * it. So we read what is there, append one entry to the existing array, and key it by command so
- * re-running is idempotent rather than additive.
- *
- * Project-local by default. A global install would arm the gate inside every repo the user opens,
- * including ones with no room in them -- harmless (the hook exits immediately without a session
- * file) but it is still their machine, so it takes an explicit flag.
- */
-import fs from 'fs'
-import os from 'os'
-import path from 'path'
-import { fileURLToPath } from 'url'
-
-const HERE = path.dirname(fileURLToPath(import.meta.url))
-// Forward slashes: this string is written into JSON and handed to a shell. Windows accepts them
-// and it avoids a backslash-escaping round trip through the settings file.
-const HOOK = path.join(HERE, 'hive-stop-hook.js').split(path.sep).join('/')
-const COMMAND = `node "${HOOK}"`
-const TIMEOUT = 10
-
-const cmd = (process.argv[2] || 'status').toLowerCase()
-const GLOBAL = process.argv.includes('--global')
-const settingsPath = GLOBAL
-  ? path.join(os.homedir(), '.claude', 'settings.json')
-  : path.join(process.cwd(), '.claude', 'settings.json')
-
-const read = () => {
-  try { return JSON.parse(fs.readFileSync(settingsPath, 'utf8')) } catch { return null }
-}
-// A settings file we cannot parse is not ours to overwrite -- it is more likely hand-edited and
-// briefly invalid than genuinely empty, and clobbering it would lose the user's own config.
-const load = () => {
-  if (!fs.existsSync(settingsPath)) return {}
-  const j = read()
-  if (j && typeof j === 'object') return j
-  console.error(`refusing to touch ${settingsPath}: it exists but is not valid JSON.`)
-  console.error('fix or move it, then run this again.')
-  process.exit(1)
-}
-
-// Ours is any Stop entry whose command mentions hive-stop-hook, so an install from a previous
-// version (a different absolute path) is recognised and replaced rather than duplicated.
-const isOurs = (entry) =>
-  (entry?.hooks || []).some((h) => typeof h?.command === 'string' && h.command.includes('hive-stop-hook'))
-
-function install() {
-  const s = load()
-  s.hooks = s.hooks || {}
-  const stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
-  const kept = stop.filter((e) => !isOurs(e))
-  const dropped = stop.length - kept.length
-  kept.push({
-    hooks: [{ type: 'command', command: COMMAND, timeout: TIMEOUT, statusMessage: 'Checking the room (Hivecode)...' }],
-  })
-  s.hooks.Stop = kept
-  fs.mkdirSync(path.dirname(settingsPath), { recursive: true })
-  fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n')
-
-  console.log(`\n  ${dropped ? 'updated' : 'installed'}  ${settingsPath}`)
-  console.log(`  command    ${COMMAND}`)
-  if (kept.length > 1) console.log(`  alongside  ${kept.length - 1} other Stop hook(s), left untouched`)
-  console.log('\n  An agent in a room can no longer end its turn while it has unread mail')
-  console.log('  addressed to it, or an accepted task still open.\n')
-  console.log('  Restart Claude Code for it to pick this up.\n')
-}
-
-function uninstall() {
-  const s = load()
-  const stop = Array.isArray(s.hooks?.Stop) ? s.hooks.Stop : []
-  const kept = stop.filter((e) => !isOurs(e))
-  if (kept.length === stop.length) { console.log(`\n  not installed in ${settingsPath}\n`); return }
-  if (kept.length) s.hooks.Stop = kept; else delete s.hooks.Stop
-  if (s.hooks && !Object.keys(s.hooks).length) delete s.hooks
-  fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n')
-  console.log(`\n  removed from ${settingsPath}\n`)
-}
-
-function status() {
-  const s = read() || {}
-  const mine = (s.hooks?.Stop || []).filter(isOurs)
-  const others = (s.hooks?.Stop || []).length - mine.length
-  console.log(`\n  settings   ${settingsPath}${fs.existsSync(settingsPath) ? '' : '  (does not exist)'}`)
-  console.log(`  hivecode   ${mine.length ? 'INSTALLED' : 'not installed'}`)
-  if (others) console.log(`  other      ${others} unrelated Stop hook(s)`)
-  console.log(`\n  install with:  npx hivecode-hook install${GLOBAL ? ' --global' : ''}\n`)
-}
-
-if (cmd === 'install') install()
-else if (cmd === 'uninstall' || cmd === 'remove') uninstall()
-else status()
+#!/usr/bin/env node
+/**
+ * INSTALL THE ANTI-IDLE GATE.
+ *
+ *   npx -y -p hivecode-mcp@latest hivecode-hook install            # this project  (.claude/settings.json)
+ *   npx -y -p hivecode-mcp@latest hivecode-hook install --global   # every project (~/.claude/settings.json)
+ *   npx -y -p hivecode-mcp@latest hivecode-hook status
+ *   npx -y -p hivecode-mcp@latest hivecode-hook uninstall
+ *
+ * Writes a Claude Code `Stop` hook entry pointing at hive-stop-hook.js. See that file for what
+ * the gate does and why prompt text alone cannot do it.
+ *
+ * MERGES, NEVER CLOBBERS. Settings files are shared: this machine already runs a Stop hook for
+ * something else entirely, and a writer that assumed it owned `hooks.Stop` would silently delete
+ * it. So we read what is there, append one entry to the existing array, and key it by command so
+ * re-running is idempotent rather than additive.
+ *
+ * Project-local by default. A global install would arm the gate inside every repo the user opens,
+ * including ones with no room in them -- harmless (the hook exits immediately without a session
+ * file) but it is still their machine, so it takes an explicit flag. `setup` installs it globally
+ * (4 Oct 2026): it already configures every agent app on the machine, and an agent joins rooms from
+ * any folder, so a gate armed in one project would miss the rest.
+ */
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+// Forward slashes: this string is written into JSON and handed to a shell. Windows accepts them
+// and it avoids a backslash-escaping round trip through the settings file.
+export const HOOK = path.join(HERE, 'hive-stop-hook.js').split(path.sep).join('/')
+const COMMAND = `node "${HOOK}"`
+const TIMEOUT = 10
+
+// Ours is any Stop entry whose command mentions hive-stop-hook, so an install from a previous
+// version (a different absolute path) is recognised and replaced rather than duplicated.
+export const isOurs = (entry) =>
+  (entry?.hooks || []).some((h) => typeof h?.command === 'string' && h.command.includes('hive-stop-hook'))
+
+/**
+ * Put our Stop entry into `settingsPath`, leaving every other hook alone. Returns
+ * { status: 'installed' | 'updated' | 'unchanged' | 'refused', others, detail? }.
+ * A settings file we cannot parse is not ours to overwrite -- it is more likely hand-edited and
+ * briefly invalid than genuinely empty, and clobbering it would lose the user's own config.
+ */
+export function installStopHook(settingsPath, command = COMMAND, { dryRun = false } = {}) {
+  let s = {}
+  if (fs.existsSync(settingsPath)) {
+    try { s = JSON.parse(fs.readFileSync(settingsPath, 'utf8')) } catch { s = null }
+    if (!s || typeof s !== 'object' || Array.isArray(s)) return { status: 'refused', others: 0, detail: `${settingsPath} exists but is not valid JSON` }
+  }
+  s.hooks = s.hooks && typeof s.hooks === 'object' ? s.hooks : {}
+  const stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
+  const kept = stop.filter((e) => !isOurs(e))
+  const mine = stop.filter(isOurs)
+  const others = kept.length
+  if (mine.length === 1 && (mine[0].hooks || []).length === 1 && mine[0].hooks[0].command === command) return { status: 'unchanged', others }
+  kept.push({
+    hooks: [{ type: 'command', command, timeout: TIMEOUT, statusMessage: 'Checking the room (Hivecode)...' }],
+  })
+  s.hooks.Stop = kept
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true })
+    fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n')
+  }
+  return { status: mine.length ? 'updated' : 'installed', others }
+}
+
+/**
+ * Put our Stop entry into Antigravity's `hooksPath` (JSON object keyed by hook name), leaving
+ * every other hook group alone. Returns { status: 'installed' | 'updated' | 'unchanged' | 'refused', others, detail? }.
+ */
+export function installAntigravityStopHook(hooksPath, command = `node "${HOOK}" --app=antigravity`, { dryRun = false } = {}) {
+  let s = {}
+  if (fs.existsSync(hooksPath)) {
+    try { s = JSON.parse(fs.readFileSync(hooksPath, 'utf8')) } catch { s = null }
+    if (!s || typeof s !== 'object' || Array.isArray(s)) return { status: 'refused', others: 0, detail: `${hooksPath} exists but is not valid JSON` }
+  }
+  const otherKeys = Object.keys(s).filter((k) => k !== 'hivecode')
+  const others = otherKeys.length
+  const current = s.hivecode && s.hivecode.Stop && s.hivecode.Stop[0] && s.hivecode.Stop[0].command
+  if (current === command) return { status: 'unchanged', others }
+
+  const had = !!s.hivecode
+  s.hivecode = {
+    Stop: [
+      { type: 'command', command, timeout: TIMEOUT }
+    ]
+  }
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(hooksPath), { recursive: true })
+    fs.writeFileSync(hooksPath, JSON.stringify(s, null, 2) + '\n')
+  }
+  return { status: had ? 'updated' : 'installed', others }
+}
+
+function cli() {
+  const cmd = (process.argv[2] || 'status').toLowerCase()
+  const GLOBAL = process.argv.includes('--global')
+  const isAntigravity = process.argv.includes('--app=antigravity')
+  const targetApp = isAntigravity ? 'Antigravity' : 'Claude Code'
+  const settingsPath = isAntigravity
+    ? (GLOBAL ? path.join(os.homedir(), '.gemini', 'config', 'hooks.json') : path.join(process.cwd(), '.agents', 'hooks.json'))
+    : (GLOBAL ? path.join(os.homedir(), '.claude', 'settings.json') : path.join(process.cwd(), '.claude', 'settings.json'))
+  const command = isAntigravity ? `node "${HOOK}" --app=antigravity` : COMMAND
+
+  const read = () => {
+    try { return JSON.parse(fs.readFileSync(settingsPath, 'utf8')) } catch { return null }
+  }
+
+  function install() {
+    const r = isAntigravity
+      ? installAntigravityStopHook(settingsPath, command)
+      : installStopHook(settingsPath, command)
+    if (r.status === 'refused') {
+      console.error(`refusing to touch ${settingsPath}: it exists but is not valid JSON.`)
+      console.error('fix or move it, then run this again.')
+      process.exit(1)
+    }
+    console.log(`\n  ${r.status === 'installed' ? 'installed' : r.status === 'updated' ? 'updated' : 'already installed'}  ${settingsPath}`)
+    console.log(`  command    ${command}`)
+    if (r.others) console.log(`  alongside  ${r.others} other ${isAntigravity ? 'hook group(s)' : 'Stop hook(s)'}, left untouched`)
+    console.log('\n  An agent in a room can no longer end its turn while it has unread mail')
+    console.log('  addressed to it, an accepted task still open, or no listener running.\n')
+    console.log(`  Restart ${targetApp} for it to pick this up.\n`)
+  }
+
+  function uninstall() {
+    const s = read()
+    if (!s) { console.log(`\n  not installed in ${settingsPath}\n`); return }
+    if (isAntigravity) {
+      if (!s.hivecode) { console.log(`\n  not installed in ${settingsPath}\n`); return }
+      delete s.hivecode
+      fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n')
+      console.log(`\n  removed from ${settingsPath}\n`)
+      return
+    }
+    const stop = Array.isArray(s.hooks?.Stop) ? s.hooks.Stop : []
+    const kept = stop.filter((e) => !isOurs(e))
+    if (kept.length === stop.length) { console.log(`\n  not installed in ${settingsPath}\n`); return }
+    if (kept.length) s.hooks.Stop = kept; else delete s.hooks.Stop
+    if (s.hooks && !Object.keys(s.hooks).length) delete s.hooks
+    fs.writeFileSync(settingsPath, JSON.stringify(s, null, 2) + '\n')
+    console.log(`\n  removed from ${settingsPath}\n`)
+  }
+
+  function status() {
+    const s = read() || {}
+    if (isAntigravity) {
+      const mine = !!s.hivecode
+      const others = Object.keys(s).filter((k) => k !== 'hivecode').length
+      console.log(`\n  hooks      ${settingsPath}${fs.existsSync(settingsPath) ? '' : '  (does not exist)'}`)
+      console.log(`  hivecode   ${mine ? 'INSTALLED' : 'not installed'}`)
+      if (others) console.log(`  other      ${others} unrelated hook group(s)`)
+      console.log(`\n  install with:  npx -y -p hivecode-mcp@latest hivecode-hook install --app=antigravity${GLOBAL ? ' --global' : ''}\n`)
+      return
+    }
+    const mine = (s.hooks?.Stop || []).filter(isOurs)
+    const others = (s.hooks?.Stop || []).length - mine.length
+    console.log(`\n  settings   ${settingsPath}${fs.existsSync(settingsPath) ? '' : '  (does not exist)'}`)
+    console.log(`  hivecode   ${mine.length ? 'INSTALLED' : 'not installed'}`)
+    if (others) console.log(`  other      ${others} unrelated Stop hook(s)`)
+    console.log(`\n  install with:  npx -y -p hivecode-mcp@latest hivecode-hook install${GLOBAL ? ' --global' : ''}\n`)
+  }
+
+  if (cmd === 'install') install()
+  else if (cmd === 'uninstall' || cmd === 'remove') uninstall()
+  else status()
+}
+
+// Only as the command, so setup can import installStopHook without running a CLI on its argv.
+// Resolved, because npm starts a bin through a symlink on macOS and Linux (hive-mcp.js, same check).
+const me = fileURLToPath(import.meta.url)
+const isMain = () => {
+  if (!process.argv[1]) return false
+  try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(me) } catch { return path.resolve(process.argv[1]) === path.resolve(me) }
+}
+if (isMain()) cli()