aegis-desktop 0.8.13 → 0.8.14

package/lib/local/entitlement.js

@@ -90,6 +90,84 @@ const LEGACY_PLAN_ALIASES = Object.freeze({
 const PRO_VALUE =
   'Pro puts the drain in the cloud, so the job keeps running after you close the laptop';
 
+/**
+ * The honesty line — Phase 3's rule, and the second half of the same claim:
+ * everything that runs on the user's own machine stays free forever, and the
+ * cloud drain is the thing being sold. Both hosts that print a paid prompt
+ * print this beside it (the desktop keeps its own literal in
+ * `desktop/renderer/app.js`; the terminal reads it from here), because the
+ * promise without the honesty line is the four-bullet feature list again.
+ *
+ * Kept byte-identical to the renderer's `FREE_HONESTY`, and asserted verbatim
+ * by both hosts' tests, so the terminal and the GUI cannot come to disagree
+ * about what is free — a disagreement that would either overcharge a promise
+ * or undercut the offer, depending on which copy a user believed.
+ */
+const FREE_HONESTY =
+  'Everything on your machine is free, permanently. The cloud drain is what you pay for.';
+
+/**
+ * The BYOK lane's price, in words — built from the SERVER's published rate.
+ *
+ * The desktop README says the byok lane is "billed a flat handling fee" and
+ * aegis1 charges exactly that (services/pricing.price_byok_call), but no client
+ * surface said so: a user who pasted their own Anthropic key into AEGIS read
+ * "your provider's cost" and never learned AEGIS adds a fee. That is the one
+ * place in this product where the bill and the pitch disagreed, and it is the
+ * copy the desktop session flagged as an unresolved honesty conflict.
+ *
+ * `fee` is aegis1's own `/api/v1/byok/providers` payload — a live payload, never
+ * a hardcoded number, for the reason the engine already states: a client that
+ * hardcodes a fee is a client that can disagree with the ledger. No published
+ * fee (old server, offline, unauthenticated read that returned nothing) returns
+ * '' and every host then says NOTHING about the price, which is the only honest
+ * alternative to inventing one.
+ *
+ * `require_account` / `anonymous_daily_calls` come from the same payload and
+ * describe enforcement, not price: with the relay requiring an AEGIS account the
+ * sentence has to say so, or the user meets a 402 the client never warned about
+ * — the exact failure tests/test_byok_fee.py::test_the_published_gate_warning_is
+ * _true_whenever_the_gate_can_402 exists to prevent.
+ */
+const BYOK_FEE_NOTE =
+  'Bring your own key is relayed through AEGIS, not dialled from here — the routing, prompt assembly and caching are billed as a flat handling fee, on top of your provider\'s own bill.';
+
+/** Per-million-token rendering of a published per-1k rate. */
+function ratePerMillion(usdPer1k) {
+  return `$${(Number(usdPer1k) * 1000).toFixed(2)}/M`;
+}
+
+function byokFeeLine(fee) {
+  const f = fee && typeof fee === 'object' ? fee : null;
+  if (!f) return '';
+  const inRate = Number(f.in_usd_per_1k);
+  const outRate = Number(f.out_usd_per_1k);
+  if (!Number.isFinite(inRate) || !Number.isFinite(outRate)) return '';
+  if (f.disabled === true) {
+    // The deployment switched the fee off; saying "free" is then the truth
+    // rather than a promise this client cannot keep.
+    return 'Bring your own key is relayed free on this deployment right now.';
+  }
+  // The price clause stands alone when the server published no enforcement
+  // detail — which is every server deployed before this change, and the
+  // default-off gate after it. Joined with ' — ' only when there IS a second
+  // clause: a sentence-ending dash with nothing after it ("…provider's bill —.")
+  // is what the first live run of this line actually printed.
+  const price = `Bring your own key: relayed through AEGIS, handled at `
+    + `${ratePerMillion(inRate)} in / ${ratePerMillion(outRate)} out, `
+    + `on top of your provider's bill`;
+  let clause = '';
+  if (f.require_account === true) {
+    clause = 'and needs an AEGIS account key (X-AEGIS-Key) for the fee to be billed';
+  } else {
+    const cap = Number(f.anonymous_daily_calls);
+    if (Number.isFinite(cap) && cap > 0) {
+      clause = `with ${cap} relayed turns/24h before an AEGIS account is required`;
+    }
+  }
+  return clause ? `${price} — ${clause}.` : `${price}.`;
+}
+
 /** Campaign id for this prompt (Phase 1's fixed ids; aegis1 keeps the slug). */
 const CAMPAIGN = 'queue_cap';
 
@@ -478,6 +556,9 @@ module.exports = {
   BALANCE_CAMPAIGN,
   BALANCE_URL,
   PRO_VALUE,
+  FREE_HONESTY,
+  BYOK_FEE_NOTE,
+  byokFeeLine,
   DEFAULT_TTL_MS,
   // Phase 7: the host seam + the builder the CLI binds itself to.
   SIGNUP_SOURCES,

package/lib/local/tools.js

@@ -42,6 +42,7 @@ const { spawn } = require('node:child_process');
 const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
+const { pathToFileURL } = require('node:url');
 const { agentRoles } = require('./agents.js');
 
 const OUTPUT_CAP = 30_000; // chars fed back to the model per tool result
@@ -770,9 +771,121 @@ function isTool(name) {
  * all land on the error branch rather than rejecting. `ctx` carries per-turn
  * state (getShell, signal); omit it and exec falls back to a one-shot spawn.
  */
+/**
+ * `tools/agent-gate.mjs` is ESM and this module is CJS, so it is imported
+ * dynamically and once. The candidates are tried in order; the first that
+ * resolves wins:
+ *
+ *   1. `../../../tools/agent-gate.mjs` — the repo checkout (dev / CI). This is
+ *      the SAME file the git hooks execute, so "what is allowed" is computed
+ *      once, by one implementation.
+ *   2. `<process.resourcesPath>/tools/agent-gate.mjs` — where electron-builder's
+ *      `extraResources` puts it in a packaged build, as a real file OUTSIDE the
+ *      asar. That placement is load-bearing, not cosmetic: the gate is loaded
+ *      with dynamic `import()`, and Node's ESM loader does not go through
+ *      Electron's asar-aware fs patch (electron/asar#249), so a copy living only
+ *      inside the archive can fail to resolve — leaving the packaged app with no
+ *      gate at all. This is the app's only dynamic ESM import, so nothing else
+ *      here exercises that path. Conveniently this is also what candidate (1)
+ *      resolves to from `resources/app.asar/lib/local/`, so dev and packaged
+ *      builds agree on one file.
+ *   3. `../../vendor/agent-gate.mjs` — the staged copy inside the app dir, kept
+ *      as the last resort for a build that is not archived (`asar: false`) or an
+ *      npm-installed tree. It is the candidate that fails inside an asar, hence
+ *      third and not first.
+ *
+ * Before (2) existed a packaged build had no gate at all: the manifest is found
+ * by climbing from the working directory, so the packaged app would open a
+ * guarded tree and every write through it succeeded while the same call through
+ * the repo copy was refused.
+ *
+ * If nothing resolves, that is a broken gate rather than a permissive one, and
+ * executeTool refuses mutating calls into a tree that declares a manifest.
+ */
+let agentGatePromise;
+
+function agentGateCandidates({ resourcesPath = process.resourcesPath, dirname = __dirname } = {}) {
+  const candidates = ['../../../tools/agent-gate.mjs'];
+  // process.resourcesPath is an Electron-provided value and is absent under
+  // plain node, so this is guarded rather than assumed. An absolute path must
+  // be a file URL to be imported.
+  if (typeof resourcesPath === 'string' && resourcesPath) {
+    candidates.push(pathToFileURL(path.join(resourcesPath, 'tools', 'agent-gate.mjs')).href);
+  }
+  candidates.push('../../vendor/agent-gate.mjs');
+  return candidates;
+}
+
+function loadAgentGate() {
+  if (!agentGatePromise) {
+    const candidates = agentGateCandidates();
+    const tryNext = (i) => (i >= candidates.length
+      ? null
+      : import(candidates[i]).catch(() => tryNext(i + 1)));
+    agentGatePromise = tryNext(0);
+  }
+  return agentGatePromise;
+}
+
+/**
+ * The nearest `.aegis/guard.json` at or above `start`, or null. The identical
+ * climb as findManifest() in tools/agent-gate.mjs and src/repoguard.js. It is
+ * used ONLY to decide whether a call that could not load the gate module is
+ * unsafe; when the module loads it is the sole authority.
+ */
+function nearestManifest(start) {
+  let dir = path.resolve(start || process.cwd());
+  try { if (fs.statSync(dir).isFile()) dir = path.dirname(dir); } catch { /* keep as-is */ }
+  for (;;) {
+    const candidate = path.join(dir, '.aegis', 'guard.json');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 async function executeTool(name, args, ctx) {
   if (!isTool(name)) return fail(`unknown tool "${name}" (known: ${toolNames().join(', ')})`);
   const input = args && typeof args === 'object' ? args : {};
+  // ── agent-key gate (tools/agent-gate.mjs) ──────────────────────────────
+  // The in-process half of the lock whose other half is .githooks/. A tree
+  // that declares .aegis/guard.json must not be mutated through this app
+  // without the key, exactly as it cannot be mutated by the engine or
+  // committed by git. Reads are never gated. Refused — not warned — when the
+  // key is absent, the manifest is unreadable, or the key file is
+  // world-readable; AEGIS_GATE_SKIP=1 is the one bypass, and it is refused in
+  // an unattended run. The module is required lazily so a packaged app whose
+  // tree has no tools/ directory still starts and simply has no gate.
+  let gate = null;
+  try {
+    gate = await loadAgentGate();
+  } catch { /* not running from the repo: no manifest to honour */ }
+  if (gate) {
+    const verdict = gate.guardTool({
+      tool: name, args: input, cwd: (ctx && ctx.cwd) || process.cwd(),
+      env: process.env, unattended: Boolean(ctx && ctx.autonomous),
+    });
+    if (!verdict.allowed) return fail(gate.refusalText(verdict));
+    if (verdict.code === 'skipped') {
+      const res = await EXECUTORS[name](input, ctx || {});
+      return res && typeof res === 'object' ? { ...res, output: `⚠ ${verdict.reason}\n${res.output || ''}` } : res;
+    }
+  } else if (MUTATING_TOOLS.has(name)) {
+    // Neither the repo copy nor the staged one loaded. A broken gate must
+    // never silently allow (the hooks exit 4 for exactly this reason), so a
+    // mutating call into a tree that declares a manifest is refused with the
+    // path of the manifest that could not be honoured.
+    const man = nearestManifest((ctx && ctx.cwd) || process.cwd());
+    if (man) {
+      return fail(
+        `error: refused — ${man} declares an agent-gated tree, but the agent-key gate module could not be loaded `
+        + '(tried tools/agent-gate.mjs beside the app and vendor/agent-gate.mjs inside it), so this '
+        + `${name} cannot be authorised. A build that missed the staged copy is the usual cause: `
+        + 'run scripts/predist.mjs before packaging.',
+      );
+    }
+  }
   try {
     return await EXECUTORS[name](input, ctx || {});
   } catch (e) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegis-desktop",
   "productName": "AEGIS Desktop",
-  "version": "0.8.13",
+  "version": "0.8.14",
   "description": "Thin Electron host for AEGIS — a local chat UI over the shared client/aegis.js transport. Ships transport + UI only; engine logic stays server-side.",
   "author": {
     "name": "AEGIS Code",

package/vendor/agent-gate.mjs

@@ -0,0 +1,1063 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * agent-gate.mjs — "only the holder of the agent key may manipulate this code".
+ *
+ * ## What this actually enforces, and what it does not
+ *
+ * This is one half of a two-half lock. Be clear about which half is which,
+ * because the honest answer is not "the repo is secure now".
+ *
+ *   ENFORCED HERE (real, on-machine):
+ *     • `.githooks/pre-commit` and `.githooks/pre-push` refuse to commit or
+ *       push a change to a protected path unless a valid agent key is present
+ *       AND this machine is bound in the manifest. The hook runs inside the
+ *       real `git` process, so it also catches edits made by a host that
+ *       bypasses the ÆGIS tool layer entirely (a bare editor, the `claude`
+ *       CLI, a stray script).
+ *     • The engine's own tool layer reads the SAME manifest before running
+ *       Write/Edit/mutating Bash (see aegiscodex-dev `src/repoguard.js`), so
+ *       an agent turn cannot edit this tree without the key either.
+ *
+ *   NOT ENFORCED HERE, and cannot be by anything inside this repo:
+ *     • Anyone with the bytes can delete this file, the manifest, or the
+ *       hooks, and edit whatever they like. `git commit --no-verify` skips
+ *       the hooks outright. A clean clone has no hooks at all (git does not
+ *       clone `.githooks/` into `core.hooksPath`) until `install-hooks` runs.
+ *     • A gate that lives inside the thing it protects is a *speed bump with
+ *       a receipt*, not a cryptographic boundary. It stops the casual case
+ *       (a copied tree, a borrowed laptop, a new collaborator) and it makes
+ *       the deliberate case leave a trail.
+ *
+ *   THE ACTUAL LOCK is server-side and lives at the remote: a GitHub ruleset
+ *   / branch protection on `main` with required reviewers and no force-push.
+ *   Nothing on this machine can be stronger than the remote's own policy.
+ *   See SECURITY.md, and `agent-gate.mjs lock-status` for what to check.
+ *
+ * ## What is in the repo, and what is not
+ *
+ * `.aegis/guard.json` (committed) holds **only SHA-256 hashes**, never a key.
+ * The key itself lives outside the tree, at `$AEGIS_HOME/keys/agent.key`
+ * (mode 0600, `$AEGIS_HOME` defaults to `~/.aegiscode`), or in the
+ * `AEGIS_AGENT_KEY` environment variable. That placement is deliberate: a
+ * secret inside the repo is committed on the next `git add -A`, and this
+ * repo's own pre-commit guard scans for exactly that mistake. The module
+ * refuses outright to read a key file that is inside the repository it is
+ * guarding, or one that is group/other-readable.
+ *
+ * ## The derivation (the contract; both implementations must match)
+ *
+ *   keyHash     = sha256("aegiscode-agent-gate-v1\n" + key)            → hex
+ *   fingerprint = keyHash[0:12]
+ *   machineFp   = sha256("aegiscode-machine-v1\n" + salt + "\n" +
+ *                        hostname + "\n" + machineId + "\n" + username
+ *                        + "\n" + platform + "\n" + arch)[0:16]
+ *
+ * The domain-separation prefixes are not decoration: without them, a raw
+ * `sha256(key)` would be the same value as the φ(α) authorship derivation
+ * (`sha256('aegiscode-agent-v1\n' + secret)`) and the two key spaces could be
+ * confused for each other. The engine's `src/repoguard.js` re-implements this
+ * formula and `test/agent-gate.test.mjs` pins both against the same vector.
+ *
+ * The machine salt is a random per-install value at `$AEGIS_HOME/keys/machine.salt`
+ * (0600). Without it the fingerprint would be a hash of public facts
+ * (hostname, /etc/machine-id, username) and therefore forgeable by anyone who
+ * can guess them; with it, an allow-list entry is only reproducible on the
+ * install that minted it.
+ *
+ * ## Verbs
+ *
+ *   status                     what this machine can currently do, and why
+ *   check [--paths a b …]      exit 0 allowed / 3 denied — for hooks and CI
+ *   init [--cwd DIR] [--mode enforce|warn] [--protect GLOB,…] [--hooks]
+ *                              TURN THE GATE ON for a repository that has none:
+ *                              write .aegis/guard.json with the CURRENT key's
+ *                              hash and this machine bound, and with --hooks
+ *                              vendor lib-gate.sh + wire the pre-commit section.
+ *                              Refuses to run with no key, because enforcing an
+ *                              empty key list denies everyone including you.
+ *   lock-status                the server-side half: what to verify remotely
+ *   hash --stdin               hash a key (never pass a key as an argument)
+ *   add-key --label <name>     append a hash; key read from stdin or the key file
+ *   rotate                     mint a NEW key, burn the old ones, print only
+ *                              the new fingerprint
+ *   bind-machine               add THIS machine's fingerprint to the allow-list
+ *   install-hooks              point git at .githooks (a fresh clone has none)
+ *
+ * Exit codes: 0 = allowed, 3 = denied, 4 = misconfiguration (unreadable or
+ * unparseable manifest/key). 3 and 4 are distinct so a hook can tell "the key
+ * is wrong" from "the gate is broken" — a broken gate must never silently
+ * allow, and it must be diagnosable without reading this file.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const GATE_VERSION = 1;
+export const KEY_DOMAIN = 'aegiscode-agent-gate-v1';
+export const MACHINE_DOMAIN = 'aegiscode-machine-v1';
+export const MANIFEST_REL = path.join('.aegis', 'guard.json');
+export const KEY_FILE_REL = path.join('keys', 'agent.key');
+export const SALT_FILE_REL = path.join('keys', 'machine.salt');
+
+export const EXIT = { ALLOW: 0, DENY: 3, CONFIG: 4 };
+
+/** 0600 / 0700, enforced after the write and re-checked — see authorship-key.js. */
+const KEY_FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+const GROUP_OTHER_BITS = 0o077;
+
+// ── derivations ─────────────────────────────────────────────────────────────
+
+/** @param {string} key @returns {string} hex sha256 under the gate domain */
+export function hashKey(key) {
+  return crypto.createHash('sha256').update(`${KEY_DOMAIN}\n${String(key)}`, 'utf8').digest('hex');
+}
+
+/** The 12 hex a human quotes to confirm two machines hold the same key. */
+export function keyFingerprint(key) {
+  return hashKey(key).slice(0, 12);
+}
+
+/** Constant-time compare of two hex digests (length differs ⇒ false, no early exit on content). */
+export function safeEqualHex(a, b) {
+  const ba = Buffer.from(String(a ?? ''), 'utf8');
+  const bb = Buffer.from(String(b ?? ''), 'utf8');
+  if (ba.length !== bb.length || ba.length === 0) return false;
+  return crypto.timingSafeEqual(ba, bb);
+}
+
+export function aegisHome(env = process.env) {
+  return env.AEGIS_HOME || path.join(os.homedir(), '.aegiscode');
+}
+
+function readFirstLine(file) {
+  try {
+    return fs.readFileSync(file, 'utf8').split('\n')[0].trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * The per-install random salt, created on first use at 0600. Returns '' only
+ * when it cannot be written (a read-only $AEGIS_HOME), in which case the
+ * fingerprint silently degrades to unsalted — the caller's `status` output
+ * reports that, so a degraded fingerprint is visible rather than assumed.
+ */
+export function machineSalt(env = process.env) {
+  const file = path.join(aegisHome(env), SALT_FILE_REL);
+  const existing = readFirstLine(file);
+  if (existing) return existing;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: DIR_MODE });
+    const salt = crypto.randomBytes(16).toString('base64url');
+    fs.writeFileSync(file, `${salt}\n`, { mode: KEY_FILE_MODE });
+    fs.chmodSync(file, KEY_FILE_MODE);
+    return salt;
+  } catch {
+    return '';
+  }
+}
+
+/** Stable 16-hex identifier for THIS machine's install. See the header for the formula. */
+export function machineFingerprint(env = process.env, overrides = {}) {
+  const hostname = overrides.hostname ?? os.hostname();
+  const username = overrides.username ?? (() => { try { return os.userInfo().username; } catch { return '?'; } })();
+  // `??` may not be mixed with `||` unparenthesised — the middle rung is
+  // spelled out rather than chained, because the file fallback has to be
+  // parenthesised anyway.
+  const machineId = overrides.machineId
+    ?? (readFirstLine('/etc/machine-id') || readFirstLine('/var/lib/dbus/machine-id'));
+  const platform = overrides.platform ?? process.platform;
+  const arch = overrides.arch ?? process.arch;
+  const salt = overrides.salt ?? machineSalt(env);
+  const body = [salt, hostname, machineId, username, platform, arch].join('\n');
+  return crypto.createHash('sha256').update(`${MACHINE_DOMAIN}\n${body}`, 'utf8').digest('hex').slice(0, 16);
+}
+
+// ── manifest ────────────────────────────────────────────────────────────────
+
+/** Nearest `.aegis/guard.json` at or above `startPath`. */
+export function findManifest(startPath) {
+  let dir = path.resolve(startPath || process.cwd());
+  try { if (fs.statSync(dir).isFile()) dir = path.dirname(dir); } catch { /* keep as-is */ }
+  for (;;) {
+    const candidate = path.join(dir, MANIFEST_REL);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Parse a manifest, or throw with the reason (never return a half-read policy). */
+export function loadManifest(file) {
+  if (!file) throw new Error(`no ${MANIFEST_REL} found at or above this path`);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    throw new Error(`cannot read manifest ${file}: ${e.message}`);
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`manifest ${file} is not valid JSON: ${e.message}`);
+  }
+  if (Number(data.version) !== GATE_VERSION) {
+    throw new Error(`manifest ${file} declares version ${data.version}; this gate speaks version ${GATE_VERSION}`);
+  }
+  data.keys = Array.isArray(data.keys) ? data.keys : [];
+  data.machines = Array.isArray(data.machines) ? data.machines : [];
+  data.protect = Array.isArray(data.protect) ? data.protect : ['**'];
+  data.__file = file;
+  data.__root = path.dirname(path.dirname(file));
+  return data;
+}
+
+/** Active key entries only — a burned entry is kept for the record, never honoured. */
+export function activeKeys(manifest) {
+  return (manifest.keys || []).filter((k) => k && (k.status || 'active') === 'active' && k.sha256);
+}
+
+// ── the tool half (the desktop app's own tool layer) ────────────────────────
+
+/**
+ * The app names its tools differently from the engine (`writeFile`/`editFile`/
+ * `exec` vs `Write`/`Edit`/`Bash`), and both are wired to THIS function so
+ * there is one decision and one manifest format across the hooks, the CLI, the
+ * app and the engine. Every alias of a mutating tool must be listed here or
+ * that tool silently escapes the gate — which is why the app's own names are
+ * spelled out rather than derived.
+ */
+export const MUTATING_TOOL_NAMES = new Set([
+  'Write', 'Edit', 'MultiEdit', 'NotebookEdit',        // engine + provider names
+  'writeFile', 'editFile',                            // desktop/lib/local/tools.js
+]);
+
+/** Bash/`exec` commands whose whole purpose is to write. Tested, not guessed. */
+export const BASH_TOOL_NAMES = new Set(['Bash', 'exec']);
+export const SKIP_ENV = 'AEGIS_GATE_SKIP';
+
+const WRITEISH_BASH = [
+  /(^|[^<])>>?\s*\S/,                   // > file, >> file
+  /\btee\b/, /\bsed\s+-i/, /\btruncate\b/, /\bdd\b/,
+  /\b(rm|mv|cp|install|touch|mkdir|rmdir|chmod|chown|ln)\b/,
+  /\b(patch|applypatch)\b/, /\bpython[0-9.]*\s+-c\b.*\bopen\s*\(/, /\bperl\s+-i\b/,
+  /\bgit\s+(checkout|restore|reset|clean|stash|apply|revert|cherry-pick|merge|rebase)\b/,
+  /\bnpm\s+(install|ci|uninstall|update)\b/, /\byarn\s+(add|remove)\b/, /\bpip[0-9.]*\s+install\b/,
+  /\bAEGIS_GATE_SKIP\b/,
+];
+
+/** Path-shaped tokens in a command line. Deliberately over-eager: see bashTargets. */
+function pathTokens(command) {
+  const out = [];
+  const re = /(?:^|[\s'"=<>|&;(])((?:~|\.{1,2})?\/[^\s'"|&;)>]+|[A-Za-z0-9_.-]+\/[^\s'"|&;)>]+)/g;
+  let m;
+  while ((m = re.exec(String(command))) !== null) out.push(m[1]);
+  return out;
+}
+
+/**
+ * Does this command write, and where?
+ *
+ * A heuristic, and named one: a script that CALLS `cp`, or an interpreter that
+ * reads a write out of a file, is not seen. A bare relative target (`cp a b`)
+ * has no `/`, so the whole command is judged against `cwd` instead — the
+ * fail-closed direction, because the alternative is "unparseable, so allow".
+ *
+ * @returns {{ writeish: boolean, paths: string[] }}
+ */
+export function bashTargets(command, cwd = process.cwd()) {
+  const cmd = String(command || '');
+  const writeish = WRITEISH_BASH.some((re) => re.test(cmd));
+  if (!writeish) return { writeish: false, paths: [] };
+  const paths = pathTokens(cmd);
+  return { writeish: true, paths: paths.length ? paths : [cwd] };
+}
+
+/**
+ * Paths (manifest-relative) that this call would touch. Unlike a git path
+ * list, a tool target may be a directory or the repo root itself (`rm -rf .`):
+ * a directory is treated as protected whenever the manifest protects anything,
+ * which over-blocks a non-holder writing to an unprotected subdirectory — the
+ * safe direction, and free for the holder, who is allowed through anyway.
+ */
+function protectedUnder(manifest, absPaths) {
+  const root = manifest.__root;
+  const hasIncludes = manifest.protect.some((p) => {
+    const pat = String(p).trim();
+    return pat && !pat.startsWith('!');
+  });
+  const out = [];
+  for (const abs of absPaths) {
+    const rel = path.relative(root, abs);
+    if (path.isAbsolute(rel) || rel.startsWith('..')) continue;
+    if (rel === '') { if (hasIncludes) out.push('.'); continue; }
+    let isDir = false;
+    try { isDir = fs.statSync(abs).isDirectory(); } catch { isDir = false; }
+    if (isDir) { if (hasIncludes) out.push(rel); continue; }
+    if (isProtected(manifest, rel)) out.push(rel);
+  }
+  return out;
+}
+
+
+// ── the key ─────────────────────────────────────────────────────────────────
+
+/**
+ * The key-resolution ladder, most explicit first:
+ *   1. an explicit `key` argument (tests, and the engine passing a key through)
+ *   2. `AEGIS_AGENT_KEY` in the environment
+ *   3. `$AEGIS_HOME/keys/agent.key` — where `rotate` writes
+ *
+ * A file is refused when it is group/other-readable (any bit of 0o077) or
+ * when it lives inside the repo being guarded. Both refusals exist because
+ * the alternative is a gate that passes for the wrong reason.
+ *
+ * @returns {{ key: string, source: string, error: string|null }}
+ */
+export function resolveAgentKey({ env = process.env, manifestRoot = null, key = null } = {}) {
+  if (key) return { key: String(key).trim(), source: 'argument', error: null };
+
+  const fromEnv = env.AEGIS_AGENT_KEY;
+  if (fromEnv && String(fromEnv).trim()) {
+    return { key: String(fromEnv).trim(), source: 'env:AEGIS_AGENT_KEY', error: null };
+  }
+
+  const file = path.join(aegisHome(env), KEY_FILE_REL);
+  let st;
+  try {
+    st = fs.statSync(file);
+  } catch {
+    return { key: '', source: 'none', error: `no agent key at ${file} (and AEGIS_AGENT_KEY is unset)` };
+  }
+  let mode = null;
+  try { mode = st.mode & 0o777; } catch { /* non-POSIX */ }
+  if (mode !== null && (mode & GROUP_OTHER_BITS)) {
+    return {
+      key: '',
+      source: file,
+      error: `${file} is mode 0${mode.toString(8)} — readable by other users, refusing to treat it as a secret (chmod 600)`,
+    };
+  }
+  if (manifestRoot) {
+    const rel = path.relative(path.resolve(manifestRoot), path.resolve(file));
+    if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
+      return { key: '', source: file, error: `${file} lives INSIDE the guarded repo — move it outside or it will be committed` };
+    }
+  }
+  const value = readFirstLine(file);
+  if (!value) return { key: '', source: file, error: `${file} is empty` };
+  return { key: value, source: file, error: null };
+}
+
+export function writeAgentKey(key, env = process.env) {
+  const file = path.join(aegisHome(env), KEY_FILE_REL);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: DIR_MODE });
+  fs.writeFileSync(file, `${key}\n`, { mode: KEY_FILE_MODE });
+  fs.chmodSync(file, KEY_FILE_MODE); // writeFileSync's mode is masked by umask
+  const after = fs.statSync(file).mode & 0o777;
+  if (after !== KEY_FILE_MODE) throw new Error(`key file landed at mode 0${after.toString(8)}, expected 0600`);
+  return file;
+}
+
+// ── path scoping ────────────────────────────────────────────────────────────
+
+/**
+ * Globs in `protect`. `**` matches everything; `*` does not cross `/` — same
+ * rule as .gitignore, because the people writing these entries think in
+ * .gitignore. `!`-prefixed entries are exceptions, evaluated after includes.
+ */
+function globToRegex(pattern) {
+  let re = '^';
+  const src = String(pattern);
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (c === '*') {
+      if (src[i + 1] === '*') {
+        // `**/` should also match zero directories
+        if (src[i + 2] === '/') { re += '(?:.*/)?'; i += 2; } else { re += '.*'; i += 1; }
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') re += '[^/]';
+    else if (/[.+^${}()|[\]\\]/.test(c)) re += `\\${c}`;
+    else re += c;
+  }
+  return new RegExp(re + '$');
+}
+
+/** Is `relPath` (repo-relative, POSIX separators) covered by the manifest? */
+export function isProtected(manifest, relPath) {
+  const rel = String(relPath).split(path.sep).join('/').replace(/^\.\//, '');
+  const negations = [];
+  let hit = false;
+  for (const entry of manifest.protect) {
+    const pat = String(entry).trim();
+    if (!pat) continue;
+    if (pat.startsWith('!')) {
+      const inner = pat.slice(1);
+      if (inner) negations.push(globToRegex(inner));
+      continue;
+    }
+    if (globToRegex(pat).test(rel)) hit = true;
+  }
+  // Negations are evaluated after all includes, so an exception line further
+  // up the list still wins — the order the entry was written does not have to
+  // be the order it takes effect, which is what .gitignore readers expect.
+  if (hit && negations.some((re) => re.test(rel))) return false;
+  return hit;
+}
+
+/** Split paths into protected / not, relative to the manifest root. */
+export function partitionPaths(manifest, cwd, paths) {
+  const root = manifest.__root;
+  const protectedPaths = [];
+  const outside = [];
+  for (const p of paths || []) {
+    const abs = path.resolve(cwd || process.cwd(), p);
+    const rel = path.relative(root, abs);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) { outside.push(p); continue; }
+    if (isProtected(manifest, rel)) protectedPaths.push(rel);
+    else outside.push(p);
+  }
+  return { protectedPaths, outside };
+}
+
+// ── the verdict ─────────────────────────────────────────────────────────────
+
+/**
+ * The single decision function. Everything above exists to feed it; every
+ * caller (the hooks, the CLI, the engine's repoguard) must go through it, so
+ * there is exactly one place where "allowed" is decided.
+ *
+ * @returns {{ ok: boolean, code: 'allow'|'deny', keyId: string|null,
+ *             fingerprint: string|null, machine: string, reason: string,
+ *             configError: string|null }}
+ */
+export function verifyAgent({ cwd = process.cwd(), key = null, env = process.env, manifest = null, manifestFile = null, machine = null } = {}) {
+  let man = manifest;
+  let configError = null;
+  try {
+    if (!man) man = loadManifest(manifestFile || findManifest(cwd));
+  } catch (e) {
+    configError = e.message;
+    return {
+      ok: false, code: 'deny', keyId: null, fingerprint: null,
+      machine: machine || machineFingerprint(env), reason: configError, configError,
+    };
+  }
+
+  const machineFp = machine || machineFingerprint(env);
+  const { key: resolved, source, error } = resolveAgentKey({ env, manifestRoot: man.__root, key });
+
+  if (error) {
+    return {
+      ok: false, code: 'deny', keyId: null, fingerprint: null,
+      machine: machineFp, reason: error, configError: /inside the guarded repo|readable by other users/.test(error) ? error : null,
+    };
+  }
+
+  const presented = hashKey(resolved);
+  const match = activeKeys(man).find((k) => safeEqualHex(k.sha256, presented));
+
+  if (!match) {
+    return {
+      ok: false, code: 'deny', keyId: null, fingerprint: keyFingerprint(resolved),
+      machine: machineFp,
+      reason: `agent key rejected (presented fingerprint ${keyFingerprint(resolved)} from ${source}) — not in ${man.__file}`,
+      configError: null,
+    };
+  }
+
+  // Machine binding is checked only AFTER the key, so a wrong key and a wrong
+  // machine report differently (and neither reports the other's state).
+  if (man.machines.length > 0 && !man.machines.some((m) => safeEqualHex(String(m).toLowerCase(), machineFp.toLowerCase()))) {
+    return {
+      ok: false, code: 'deny', keyId: match.id || null, fingerprint: keyFingerprint(resolved),
+      machine: machineFp,
+      reason: `agent key "${match.id}" is valid but this machine (${machineFp}) is not bound in ${man.__file}`,
+      configError: null,
+    };
+  }
+
+  return {
+    ok: true, code: 'allow', keyId: match.id || null, fingerprint: keyFingerprint(resolved),
+    machine: machineFp, reason: `agent key "${match.id}" accepted${man.machines.length ? ' on a bound machine' : ' (no machine binding configured)'}`,
+    configError: null,
+  };
+}
+
+// ── the tool gate (the third caller, after the hooks and the CLI) ───────────
+
+/**
+ * Decide whether a TOOL CALL may run against a gated tree. This is the
+ * in-process half of the same lock the hooks enforce at commit time, and the
+ * one the desktop app (`desktop/lib/local/tools.js`) and the engine
+ * (`aegiscodex-dev/src/repoguard.js`) both route through.
+ *
+ * Fail-closed, like the hooks: a gated path with no resolvable key, an
+ * unreadable manifest, or a key file that is world-readable is a refusal
+ * rather than a passthrough. Reads are never gated (`read: "open"`).
+ *
+ * `AEGIS_GATE_SKIP=1` is the single documented bypass — the same variable
+ * `.githooks/lib-gate.sh` honours — and it is REFUSED when `unattended` is
+ * true: an autonomous run has no one to answer for a bypass, so it cannot
+ * grant itself one.
+ *
+ * @returns {{ allowed: boolean, gated: boolean,
+ *             code: 'allow'|'deny'|'not-gated'|'skipped',
+ *             reason: string, tool: string, manifest: string|null, verdicts: object[] }}
+ */
+export function guardTool({ tool, args = {}, cwd = process.cwd(), env = process.env, unattended = false } = {}) {
+  const base = { allowed: true, gated: false, code: 'not-gated', reason: 'no agent-gated tree in this call', tool, manifest: null, verdicts: [] };
+
+  if (env[SKIP_ENV] === '1') {
+    if (unattended) {
+      return { ...base, allowed: false, code: 'deny', reason: `refused: ${SKIP_ENV}=1 is not honoured in an unattended run — the gate is not skippable by an agent's own judgment` };
+    }
+    return { ...base, code: 'skipped', reason: `agent gate SKIPPED (${SKIP_ENV}=1) — this edit is unverified` };
+  }
+
+  let targets = [];
+  if (MUTATING_TOOL_NAMES.has(tool)) {
+    const target = args.file_path || args.notebook_path || args.path;
+    if (!target) return { ...base, reason: `no file path in this ${tool} call` };
+    targets = [path.resolve(cwd, String(target))];
+  } else if (BASH_TOOL_NAMES.has(tool)) {
+    const { writeish, paths } = bashTargets(args.command, cwd);
+    if (!writeish) return base;
+    targets = paths.map((p) => path.resolve(cwd, p));
+  } else {
+    return base;
+  }
+
+  const byManifest = new Map();
+  for (const abs of targets) {
+    const file = findManifest(abs);
+    if (!file) continue;
+    if (!byManifest.has(file)) byManifest.set(file, []);
+    byManifest.get(file).push(abs);
+  }
+  if (byManifest.size === 0) return base;
+
+  const verdicts = [];
+  let allowed = true;
+  let reason = '';
+  let manifestFile = null;
+  for (const [file, absPaths] of byManifest) {
+    let man;
+    try {
+      man = loadManifest(file);
+    } catch (e) {
+      return { ...base, allowed: false, gated: true, code: 'deny', configError: e.message, manifest: file, reason: `agent gate misconfigured: ${e.message}` };
+    }
+    const protectedPaths = protectedUnder(man, absPaths);
+    if (protectedPaths.length === 0) continue;
+    const verdict = verifyAgent({ manifest: man, cwd, env });
+    verdicts.push({ ...verdict, paths: protectedPaths });
+    manifestFile = man.__file;
+    if (verdict.ok) {
+      if (!reason) reason = `${verdict.reason} — ${protectedPaths.join(', ')}`;
+      continue;
+    }
+    if (man.mode === 'warn' && !verdict.configError) {
+      if (!reason) reason = `manifest mode is "warn" — reporting, not blocking: ${verdict.reason}`;
+      continue;
+    }
+    allowed = false;
+    reason = verdict.reason;
+  }
+
+  if (verdicts.length === 0) return base;
+  return { ...base, allowed, gated: true, code: allowed ? 'allow' : 'deny', reason: reason || 'agent-gated tree', manifest: manifestFile, verdicts };
+}
+
+/** Exit-code mapping for a `guardTool` result. 3 = denied, 4 = broken gate. */
+export function exitCodeFor(verdict) {
+  if (verdict.allowed) return EXIT.ALLOW;
+  return (verdict.configError || verdict.verdicts?.some((v) => v.configError)) ? EXIT.CONFIG : EXIT.DENY;
+}
+
+/** The human-facing refusal, without the CLI's "how to fix" prose. */
+export function refusalText(verdict) {
+  return `refused by the agent-key gate: ${verdict.reason}. This tree is agent-gated — a change to a protected path needs the agent key at $AEGIS_HOME/keys/agent.key (mode 600) or AEGIS_AGENT_KEY, on a machine bound in ${verdict.manifest || '.aegis/guard.json'}. Run \`node tools/agent-gate.mjs status\` to see what this machine can do.`;
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+
+const VERBS = ['status', 'check', 'init', 'lock-status', 'hash', 'add-key', 'rotate', 'bind-machine', 'import-key', 'install-hooks', 'help'];
+
+// Flags that take a value. Anything else long-form is a boolean, so `--hooks`
+// and `--force` work without a special case each.
+const VALUE_FLAGS = new Set(['--cwd', '--manifest', '--label', '--mode', '--protect']);
+
+function parseArgs(argv) {
+  const out = { verb: 'status', flags: {}, rest: [] };
+  const list = [...argv];
+  if (list.length && !list[0].startsWith('-')) out.verb = list.shift();
+  while (list.length) {
+    const a = list.shift();
+    if (a === '--paths') {
+      // Consumes the whole run of following non-flag arguments: `--paths a b c`
+      // is how both hooks call this, and a parser that ate only the first one
+      // would silently check one file and pass the rest through as prose.
+      const group = [];
+      while (list.length && !list[0].startsWith('--')) group.push(list.shift());
+      out.flags.paths = group.join(' ').split(/[\s,]+/).filter(Boolean);
+    } else if (VALUE_FLAGS.has(a)) {
+      out.flags[a.slice(2)] = list.shift();
+    } else if (a.startsWith('--')) out.flags[a.slice(2)] = true;
+    else out.rest.push(a);
+  }
+  return out;
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+function editManifest(file, mutate) {
+  const man = loadManifest(file);
+  const clean = { ...man };
+  delete clean.__file; delete clean.__root;
+  mutate(clean);
+  fs.writeFileSync(file, `${JSON.stringify(clean, null, 2)}\n`, 'utf8');
+  return clean;
+}
+
+// ── init: turn the gate ON for a repository that has none ───────────────────
+//
+// Every other verb edits a manifest that already exists. This is the one that
+// creates one, and it exists because the alternative was hand-writing JSON from
+// a template — which is how a repo ends up with a manifest whose key hash or
+// machine entry is subtly wrong, i.e. a gate that denies its own owner. It
+// therefore REFUSES to run without a resolvable key: `mode: "enforce"` with an
+// empty key list denies every write, and the operator finds that out at the
+// first commit rather than here.
+
+const MANIFEST_COMMENT = [
+  'The agent-key gate for this repository. Read tools/agent-gate.mjs\'s header before',
+  'trusting anything here: this file is the RECEIPT, not the lock. It stops a copied',
+  'tree, a borrowed laptop and a casual collaborator, and it makes a deliberate edit',
+  'leave a trail. It cannot stop someone who has the bytes — they delete this file.',
+  'The real lock is a GitHub ruleset on main: run `agent-gate.mjs lock-status`.',
+  '',
+  'HASHES ONLY. Never put a key in this file: it is committed, and the repo\'s own',
+  'pre-commit guard scans staged content for exactly that mistake. The key lives at',
+  '$AEGIS_HOME/keys/agent.key (mode 0600), outside the tree.',
+  '',
+  'sha256 = sha256(\'aegiscode-agent-gate-v1\\n\' + key)  — see KEY_DOMAIN in tools/agent-gate.mjs',
+  'The engine re-implements this in aegiscodex-dev/src/repoguard.js; a shared test',
+  'vector in aegiscode-plugin/test/agent-gate.test.mjs holds the two in step.',
+];
+
+const HOOK_MARKER = '# ── agent-key gate';
+
+function hookSection() {
+  // Self-contained on purpose: it defines nothing and calls nothing from the
+  // host hook except lib-gate.sh, so it drops into a pre-commit of any shape
+  // (this repo's uses `fail()`, aegis1's differs, a bare one has neither).
+  return [
+    '# ── agent-key gate (tools/agent-gate.mjs + .aegis/guard.json) ───────────────',
+    '# "Only the holder of the agent key may manipulate this code." Policy lives in',
+    '# .aegis/guard.json; the decision function lives in tools/agent-gate.mjs; this is',
+    '# the shell edge of it.',
+    '#',
+    '# LAST, deliberately: the path blocklist and the secret scan above are',
+    '# unconditional and must not become conditional on a key being present.',
+    '#',
+    '# Fail-closed: a missing gate CLI, missing node or unreadable manifest refuses.',
+    '# The one bypass is AEGIS_GATE_SKIP=1 — an env var, so it is greppable.',
+    '# shellcheck source=.githooks/lib-gate.sh',
+    '. "$(dirname "$0")/lib-gate.sh"',
+    'if ! agent_gate_check_staged; then',
+    '    echo "✗ pre-commit blocked: the agent-key gate refused this commit (reason above)." >&2',
+    '    exit 1',
+    'fi',
+  ].join('\n');
+}
+
+/** Vendor lib-gate.sh next to the hook and wire the section in, idempotently. */
+function wireHook(root) {
+  const src = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '.githooks', 'lib-gate.sh');
+  if (!fs.existsSync(src)) throw new Error(`cannot vendor the hook library — ${src} does not exist`);
+  const hooksDir = path.join(root, '.githooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const lib = path.join(hooksDir, 'lib-gate.sh');
+  fs.copyFileSync(src, lib);
+  fs.chmodSync(lib, 0o755);
+
+  const hook = path.join(hooksDir, 'pre-commit');
+  let text = fs.existsSync(hook)
+    ? fs.readFileSync(hook, 'utf8')
+    : '#!/bin/sh\n# pre-commit guard — created by `agent-gate.mjs init --hooks`.\n\nset -u\n\nexit 0\n';
+  const already = text.includes(HOOK_MARKER);
+  if (!already) {
+    const lines = text.split('\n');
+    let at = -1;
+    for (let i = lines.length - 1; i >= 0; i -= 1) if (lines[i].trim() === 'exit 0') { at = i; break; }
+    const section = hookSection().split('\n');
+    if (at >= 0) lines.splice(at, 0, ...section, ''); else lines.push(...section, '');
+    text = lines.join('\n');
+  }
+  fs.writeFileSync(hook, text, 'utf8');
+  fs.chmodSync(hook, 0o755);
+  return { lib, hook, already };
+}
+
+function cmdInit({ flags }) {
+  const root = path.resolve(flags.cwd || process.cwd());
+  let stat = null;
+  try { stat = fs.statSync(root); } catch { /* reported below */ }
+  if (!stat || !stat.isDirectory()) { console.error(`✗ agent-gate: ${root} is not a directory`); return EXIT.CONFIG; }
+  const file = flags.manifest || path.join(root, MANIFEST_REL);
+  if (fs.existsSync(file) && !flags.force) {
+    console.error(`✗ agent-gate: ${file} already exists — refusing to overwrite it.`);
+    console.error('  Edit it with add-key / bind-machine / rotate, or pass --force to replace it outright.');
+    return EXIT.CONFIG;
+  }
+  const mode = flags.mode === undefined ? 'enforce' : String(flags.mode);
+  if (mode !== 'enforce' && mode !== 'warn') { console.error(`✗ agent-gate: --mode must be enforce or warn, got "${mode}"`); return EXIT.CONFIG; }
+  const protect = flags.protect ? String(flags.protect).split(/[\s,]+/).filter(Boolean) : ['**'];
+  if (protect.length === 0) protect.push('**');
+
+  const fromStdin = flags['key-stdin'] ? readStdin() : '';
+  const { key, source, error } = fromStdin
+    ? { key: fromStdin, source: 'stdin', error: null }
+    : resolveAgentKey({ env: process.env, manifestRoot: root });
+  if (!key) {
+    console.error(`✗ agent-gate: refusing to init without a key — ${error || 'no agent key found'}`);
+    console.error('  "enforce" with no active key denies EVERY write in the tree, mine and yours:');
+    console.error('  that is fail-closed, not something you should discover at the first commit.');
+    console.error('  Put a key in place first:  agent-gate.mjs rotate        (mints one, 0600, never printed)');
+    console.error('                        or:  agent-gate.mjs init --key-stdin < ~/.aegiscode/keys/agent.key');
+    return EXIT.CONFIG;
+  }
+
+  const id = flags.label || 'agent-key-1';
+  const machines = flags['no-bind'] ? [] : [machineFingerprint()];
+  const manifest = {
+    version: GATE_VERSION,
+    comment: MANIFEST_COMMENT,
+    mode,
+    read: 'open',
+    protect,
+    keys: [{
+      id,
+      label: flags.label || 'primary agent key',
+      sha256: hashKey(key),
+      status: 'active',
+      addedAt: new Date().toISOString(),
+      keySource: source,
+    }],
+    machines,
+    machinesNote: 'Machine binding is a speed bump, not identity: the fingerprint is a hash of public facts plus a per-install salt (keys/machine.salt), so it is reproducible on this install and not by guessing. Adding a machine is explicit (bind-machine); moving the key file does not carry the binding. `init` binds the machine that runs it, because the alternative is an operator locked out by their own manifest.',
+  };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+
+  let hooks = null;
+  if (flags.hooks) {
+    try { hooks = wireHook(root); } catch (e) { console.error(`✗ agent-gate: ${e.message}`); return EXIT.CONFIG; }
+  }
+
+  console.error(`✓ agent-gate: wrote ${file}`);
+  console.error(`  mode ${mode} · protects ${protect.join(' ')} · key "${id}" fingerprint ${keyFingerprint(key)} (${source})`);
+  console.error(machines.length
+    ? `  bound machine ${machines[0]}`
+    : '  NO machine bound (--no-bind): any machine holding the key file opens this gate');
+  if (hooks) console.error(`✓ vendored ${hooks.lib}${hooks.already ? ' (gate section already present)' : ` and inserted the gate section into ${hooks.hook}`}`);
+  else console.error('  hooks NOT wired — pass --hooks to vendor lib-gate.sh and wire pre-commit');
+  console.error(`  finish:  git -C ${root} config core.hooksPath .githooks`);
+  console.error(`  verify:  agent-gate.mjs status --cwd ${root}         (expect ALLOW)`);
+  console.error('  prove:   AEGIS_AGENT_KEY=wrong agent-gate.mjs check --cwd …   (expect exit 3, not 0)');
+  return EXIT.ALLOW;
+}
+
+function cmdStatus({ flags }) {
+  const cwd = flags.cwd || process.cwd();
+  const verdict = verifyAgent({ cwd });
+  const file = verdict.configError ? (flags.manifest || findManifest(cwd)) : null;
+  let man = null;
+  try { man = loadManifest(file || findManifest(cwd)); } catch { /* reported below */ }
+
+  console.log(`agent-gate v${GATE_VERSION}`);
+  if (man) {
+    console.log(`  manifest      ${man.__file}`);
+    console.log(`  root          ${man.__root}`);
+    console.log(`  protects      ${man.protect.join(' ')}`);
+    console.log(`  active keys   ${activeKeys(man).map((k) => k.id || '(unnamed)').join(', ') || '(none)'}`);
+    const burned = man.keys.filter((k) => (k.status || 'active') !== 'active');
+    if (burned.length) console.log(`  burned keys   ${burned.map((k) => k.id || '(unnamed)').join(', ')}`);
+    console.log(`  bound machines ${man.machines.length || '(none — any machine with the key)'}`);
+  } else {
+    console.log(`  manifest      none found at or above ${cwd}`);
+  }
+  console.log(`  this machine  ${verdict.machine}${machineSalt() ? '' : '  (UNSALTED — $AEGIS_HOME not writable)'}`);
+  console.log(`  verdict       ${verdict.ok ? 'ALLOW' : 'DENY'} — ${verdict.reason}`);
+  return verdict.ok ? EXIT.ALLOW : (verdict.configError ? EXIT.CONFIG : EXIT.DENY);
+}
+
+function cmdCheck({ flags }) {
+  const cwd = flags.cwd || process.cwd();
+  const file = flags.manifest || findManifest(cwd);
+  let man;
+  try {
+    man = loadManifest(file);
+  } catch (e) {
+    if (!flags.quiet) console.error(`✗ agent-gate: ${e.message}`);
+    return EXIT.CONFIG;
+  }
+
+  // Only protected paths gate the operation; a commit touching nothing
+  // protected (docs, a vendored file outside the globs) is not held hostage.
+  const paths = flags.paths && flags.paths.length ? flags.paths : null;
+  if (paths) {
+    const { protectedPaths } = partitionPaths(man, cwd, paths);
+    if (protectedPaths.length === 0) {
+      if (!flags.quiet) console.error('✓ agent-gate: no protected path in this change');
+      return EXIT.ALLOW;
+    }
+  }
+
+  const verdict = verifyAgent({ manifest: man, cwd });
+  if (verdict.ok) {
+    if (!flags.quiet) console.error(`✓ agent-gate: ${verdict.reason}`);
+    return EXIT.ALLOW;
+  }
+
+  // `mode: "warn"` is the rollout state: the gate reports and does not block,
+  // so a repo can adopt this without locking out a collaborator whose key has
+  // not been added yet. Policy lives HERE, not in the hooks, so the engine's
+  // repoguard inherits the identical rule instead of re-deriving it.
+  if (man.mode === 'warn' && !flags.strict && !verdict.configError) {
+    if (!flags.quiet) console.error('  (manifest mode is "warn" — reporting, not blocking; --strict to block anyway)');
+    return EXIT.ALLOW;
+  }
+
+  if (!flags.quiet) console.error(`✗ agent-gate: ${verdict.reason}`);
+  return verdict.configError ? EXIT.CONFIG : EXIT.DENY;
+}
+
+function cmdLockStatus() {
+  console.log(`agent-gate: the server-side half of the lock, which no local file can substitute.
+
+  Nothing in this repository can stop someone who has the bytes from editing
+  them. The only real lock is at the remote. Verify these, in this order:
+
+  1. GitHub → Settings → Rules → Rulesets, target "main":
+       ☑ Restrict force pushes
+       ☑ Require a pull request before merging (≥1 approval)
+       ☑ Require signed commits        (ties a push to a real key holder)
+       ☑ Block force pushes / deletions
+  2. GitHub → Settings → Collaborators: who can push at all. Everyone in this
+     list can write the code regardless of the local gate.
+  3. Deploy keys: read-only unless a push from CI is genuinely needed.
+  4. Branch protection on any release branch, plus tag protection for v*.
+
+  A local clone that has never run \`agent-gate.mjs install-hooks\` has no
+  hooks and this gate does not run there at all. That is expected, and it is
+  exactly why (1) is the lock and this file is the receipt.`);
+  return EXIT.ALLOW;
+}
+
+function cmdHash({ flags }) {
+  const key = flags.stdin ? readStdin() : '';
+  if (!key) {
+    console.error('agent-gate: refusing to take a key from argv (it would land in `ps` and your shell history).\n  echo -n "<key>" | agent-gate.mjs hash --stdin');
+    return EXIT.CONFIG;
+  }
+  console.log(JSON.stringify({ sha256: hashKey(key), fingerprint: keyFingerprint(key) }, null, 2));
+  return EXIT.ALLOW;
+}
+
+function cmdAddKey({ flags }) {
+  const file = flags.manifest || findManifest(flags.cwd || process.cwd());
+  let man;
+  try { man = loadManifest(file); } catch (e) { console.error(`✗ ${e.message}`); return EXIT.CONFIG; }
+
+  const fromStdin = readStdin();
+  const { key, source, error } = fromStdin
+    ? { key: fromStdin, source: 'stdin', error: null }
+    : resolveAgentKey({ env: process.env, manifestRoot: man.__root });
+  if (error) { console.error(`✗ ${error}`); return EXIT.CONFIG; }
+
+  const sha = hashKey(key);
+  if (activeKeys(man).some((k) => safeEqualHex(k.sha256, sha))) {
+    console.error(`= agent-gate: that key is already active (${keyFingerprint(key)})`);
+    return EXIT.ALLOW;
+  }
+  const id = flags.label || `key-${activeKeys(man).length + 1}`;
+  editManifest(file, (m) => {
+    m.keys.push({ id, sha256: sha, label: flags.label || id, status: 'active', addedAt: new Date().toISOString(), keySource: source });
+  });
+  console.error(`✓ agent-gate: added "${id}" (fingerprint ${keyFingerprint(key)}) to ${file}`);
+  return EXIT.ALLOW;
+}
+
+function cmdRotate({ flags }) {
+  const file = flags.manifest || findManifest(flags.cwd || process.cwd());
+  let man;
+  try { man = loadManifest(file); } catch (e) { console.error(`✗ ${e.message}`); return EXIT.CONFIG; }
+
+  const fresh = crypto.randomBytes(32).toString('base64url');
+  const written = writeAgentKey(fresh);
+  const sha = hashKey(fresh);
+
+  editManifest(file, (m) => {
+    for (const k of m.keys) if ((k.status || 'active') === 'active') { k.status = 'burned'; k.burnedAt = new Date().toISOString(); k.burnedReason = 'rotated'; }
+    m.keys.push({ id: flags.label || `key-${m.keys.length + 1}`, sha256: sha, label: 'rotated', status: 'active', addedAt: new Date().toISOString(), keySource: written });
+    if (m.machines.length === 0) m.machines.push(machineFingerprint());
+  });
+
+  // The new key is written to disk and never printed. Printing it would put a
+  // live credential into scrollback, shell history, CI logs and — the case
+  // that actually happened in this repo — a chat transcript.
+  console.error(`✓ agent-gate: rotated. New key at ${written} (mode 0600), fingerprint ${keyFingerprint(fresh)}.`);
+  console.error(`  Previous active keys are marked burned in ${file}: the old value no longer opens the gate,`);
+  console.error(`  including anywhere it was pasted or logged. To move the key to another machine, copy the FILE.`);
+  return EXIT.ALLOW;
+}
+
+function cmdBindMachine({ flags }) {
+  const file = flags.manifest || findManifest(flags.cwd || process.cwd());
+  try { loadManifest(file); } catch (e) { console.error(`✗ ${e.message}`); return EXIT.CONFIG; }
+  const fp = machineFingerprint();
+  editManifest(file, (m) => { if (!m.machines.some((x) => String(x).toLowerCase() === fp.toLowerCase())) m.machines.push(fp); });
+  console.error(`✓ agent-gate: bound machine ${fp} in ${file}`);
+  console.error('  A machine fingerprint is a hash of public facts plus a per-install salt: it identifies this');
+  console.error('  install, not a person. Moving the key FILE to another machine does not carry the binding —');
+  console.error('  that is the point, and it is why rotating on a new machine needs one explicit bind-machine.');
+  return EXIT.ALLOW;
+}
+
+/**
+ * Adopt a key from an arbitrary file — the point is a Downloads-folder drop
+ * ("I just moved this key to a new machine") without hand-running `cat | env`.
+ * Downloads is a STAGING spot, not where the live secret should sit: it's
+ * commonly cloud-synced, browser-permissioned, and indexed. So this installs
+ * the key at the real location ($AEGIS_HOME/keys/agent.key, mode 0600) and
+ * then deletes the source file — the opposite of making Downloads a place the
+ * gate trusts on an ongoing basis. `--keep` skips the delete for anyone who
+ * wants to move it manually instead.
+ */
+function cmdImportKey({ flags, rest }) {
+  const src = (rest && rest[0]) ? path.resolve(rest[0]) : path.join(os.homedir(), 'Downloads', 'agent.key');
+  let raw;
+  try {
+    raw = fs.readFileSync(src, 'utf8');
+  } catch (e) {
+    console.error(`✗ agent-gate: cannot read ${src}: ${e.message}`);
+    console.error('  Pass a path explicitly: agent-gate.mjs import-key /path/to/agent.key');
+    return EXIT.CONFIG;
+  }
+  const key = raw.split('\n')[0].trim();
+  if (!key) { console.error(`✗ agent-gate: ${src} is empty`); return EXIT.CONFIG; }
+
+  let srcMode = null;
+  try { srcMode = fs.statSync(src).mode & 0o777; } catch { /* unreadable already reported above */ }
+  if (srcMode !== null && (srcMode & 0o077)) {
+    console.error(`⚠ agent-gate: ${src} was mode 0${srcMode.toString(8)} (group/other-readable) — importing anyway,`);
+    console.error('  but treat that key as potentially exposed to anything else with access to that folder.');
+  }
+
+  const dest = writeAgentKey(key);
+  console.error(`✓ agent-gate: installed key (fingerprint ${keyFingerprint(key)}) at ${dest} (mode 0600)`);
+
+  if (!flags.keep) {
+    try {
+      fs.unlinkSync(src);
+      console.error(`✓ agent-gate: removed ${src} — the live copy now lives only at ${dest}`);
+    } catch (e) {
+      console.error(`⚠ agent-gate: could not remove ${src} (${e.message}) — delete it yourself, it should not sit there long-term`);
+    }
+  } else {
+    console.error(`  --keep set: left ${src} in place. Downloads is not a safe long-term home for this file.`);
+  }
+
+  const cwd = flags.cwd || process.cwd();
+  const verdict = verifyAgent({ cwd });
+  console.error(`  this machine  ${verdict.machine}`);
+  console.error(`  verdict       ${verdict.ok ? 'ALLOW' : 'DENY'} — ${verdict.reason}`);
+  if (!verdict.ok && !verdict.configError) {
+    console.error(`  the key imported fine; this machine likely still needs:  agent-gate.mjs bind-machine --cwd ${cwd}`);
+  }
+  return verdict.ok ? EXIT.ALLOW : (verdict.configError ? EXIT.CONFIG : EXIT.DENY);
+}
+
+function cmdInstallHooks({ flags }) {
+  const root = flags.cwd || process.cwd();
+  const hooksDir = path.join(root, '.githooks');
+  if (!fs.existsSync(path.join(hooksDir, 'pre-commit'))) {
+    console.error(`✗ agent-gate: no .githooks/pre-commit under ${root}`);
+    return EXIT.CONFIG;
+  }
+  for (const name of ['pre-commit', 'pre-push']) {
+    const p = path.join(hooksDir, name);
+    if (fs.existsSync(p)) fs.chmodSync(p, 0o755);
+  }
+  console.error(`  run:  git -C ${root} config core.hooksPath .githooks`);
+  console.error('  (not run automatically: this tool does not mutate git config without being asked)');
+  return EXIT.ALLOW;
+}
+
+function cmdHelp() {
+  console.log(`agent-gate — the agent-key gate for this repository.
+
+  agent-gate.mjs status [--cwd DIR] [--manifest FILE]
+  agent-gate.mjs check  [--cwd DIR] [--manifest FILE] [--paths a b c] [--quiet]
+  agent-gate.mjs init   [--cwd DIR] [--mode enforce|warn] [--protect GLOB,…]
+                        [--label NAME] [--key-stdin] [--no-bind] [--hooks] [--force]
+  agent-gate.mjs lock-status
+  agent-gate.mjs hash --stdin
+  agent-gate.mjs add-key [--label NAME]        (key from stdin, else the key file)
+  agent-gate.mjs rotate
+  agent-gate.mjs bind-machine
+  agent-gate.mjs import-key [PATH] [--keep] [--cwd DIR]
+                        (default PATH: ~/Downloads/agent.key; installs it at
+                        $AEGIS_HOME/keys/agent.key mode 0600, then deletes PATH
+                        unless --keep, then prints this machine's verdict)
+  agent-gate.mjs install-hooks [--cwd DIR]
+
+Exit codes: 0 allowed, 3 denied, 4 misconfiguration.`);
+  return EXIT.ALLOW;
+}
+
+const COMMANDS = {
+  status: cmdStatus, check: cmdCheck, init: cmdInit, 'lock-status': cmdLockStatus, hash: cmdHash,
+  'add-key': cmdAddKey, rotate: cmdRotate, 'bind-machine': cmdBindMachine,
+  'import-key': cmdImportKey, 'install-hooks': cmdInstallHooks, help: cmdHelp,
+};
+
+/**
+ * Run the CLI. Returns the exit code instead of calling process.exit, so the
+ * test file can drive every verb in-process and assert the code.
+ */
+export function run(argv = process.argv.slice(2)) {
+  const parsed = parseArgs(argv);
+  if (!VERBS.includes(parsed.verb)) {
+    console.error(`✗ agent-gate: unknown verb "${parsed.verb}" — try "help"`);
+    return EXIT.CONFIG;
+  }
+  try {
+    return COMMANDS[parsed.verb](parsed);
+  } catch (e) {
+    console.error(`✗ agent-gate: ${e.message}`);
+    return EXIT.CONFIG;
+  }
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+if (invokedDirectly) process.exit(run());