@scopebond/hook 0.6.0 → 0.8.0

package/dist/cli.js

@@ -2,32 +2,44 @@
 // scopebond-hook — govern a coding agent's tool calls against policy, in-path,
 // before they run, with a signed local receipt.
 //
-//   scopebond-hook claude                     evaluate a Claude Code PreToolUse call (stdin JSON)
-//   scopebond-hook cursor                     evaluate a Cursor hook event (stdin JSON)
-//   scopebond-hook codex                      evaluate a Codex PreToolUse call (stdin JSON)
-//   scopebond-hook init [--cursor|--codex] [--no-install] [--yes]
-//   scopebond-hook connect <url> <bundle.json> [--cursor|--codex]
-//                                             enroll with a Cloud workspace and start exporting
-//   scopebond-hook log [-n N]                 show the most recent local receipts
-//   scopebond-hook verify                     verify every local receipt offline against the attester key
-//   scopebond-hook test "<shell command>"     show the decision for a command without recording it
-//   scopebond-hook flush                      deliver any queued receipts to Cloud now
-//   scopebond-hook trust [--yes]              let this project's .scopebond policy govern here (pinned)
+// The command list, arguments and examples live in `COMMANDS` near the bottom of this
+// file, which is what `scopebond-hook help [command]` prints — one source rather than a
+// comment here that drifts from it.
 //
 // Config dir: $SCOPEBOND_HOOK_DIR, else ./.scopebond
 // Fail-closed: any error denies the action with a repair message.
-import { readFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+// `node:sqlite` (the receipt store) is still flagged experimental on Node 22, and Node
+// prints a warning on stderr the first time it loads — on every `verify`, and into the
+// agent's transcript on every hook call. It is a notice about Node, not about the user's
+// setup, so it is dropped; every other warning still prints through Node's own handler.
+// (The store is required lazily, after this module has run, so the filter is in place.)
+{
+    const nodeWarningHandlers = process.listeners("warning");
+    process.removeAllListeners("warning");
+    process.on("warning", (warning) => {
+        if (warning.name === "ExperimentalWarning" && /sqlite/i.test(warning.message))
+            return;
+        for (const handler of nodeWarningHandlers)
+            handler.call(process, warning);
+    });
+}
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { tmpdir } from "node:os";
+import { hostname, tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { verifyReceipt } from "@scopebond/gateway";
 import { openReceiptStore, loadOrCreateAttester } from "@scopebond/gateway/node";
 import { mapClaudeToolUse, mapCodexToolUse, mapCursorEvent, fillPushBranch } from "./map.js";
 import { createHookRuntime } from "./runtime.js";
-import { scaffold, harnessSnippet, installHarness } from "./init.js";
-import { userHome, userHarnessFile, resolveConfigDir, writeHarnessConfig, removeHarnessConfig, cursorDetected, codexDetected, absoluteHookCommand, isHarnessConfigured, purgeHome, trustProjectPolicy, untrustedProjectPolicy, } from "./install.js";
+import { useDigestKey, loadOrCreateDigestKey } from "./minimize.js";
+import { scaffold, harnessSnippet, placeHook } from "./init.js";
+import { userHome, userHarnessFile, resolveConfigDir, writeHarnessConfig, removeHarnessConfig, cursorDetected, codexDetected, absoluteHookCommand, isHarnessConfigured, purgeHome, harnessScopes, harnessScopeLabel, configuredHookCommands, hookCommandResolves, projectHarnessFile, localHarnessFile, gitShareState, isMachineSpecificCommand, trustProjectPolicy, untrustedProjectPolicy, } from "./install.js";
 import { connectCloud, loadConnection } from "./cloud.js";
-import { cliCommand, hookVersion } from "./version.js";
+import { compile, defaultRules, describeRules, loadRules, saveRules, rulesPath, pathRuleFor } from "./rules.js";
+import { createSigner } from "@scopebond/sdk";
+import { describeAction } from "./explain.js";
+import { ensureDurableRuntime, pinnedCliPath, isEphemeralPath } from "./runtime-install.js";
+import { cliCommand, hookCommand, hookVersion } from "./version.js";
 import { fileURLToPath } from "node:url";
 /** The current git branch in `cwd` (best-effort). A bare `git push` pushes it, so
  *  the runtime fills it in before evaluating; on failure the ref stays absent and
@@ -92,7 +104,9 @@ function denyClaude(reason) {
     process.stdout.write(JSON.stringify({
         hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason },
     }) + "\n");
-    process.stderr.write(`Scopebond: ${reason}\n`);
+    // A composed explanation already names Scopebond in its first line; only the
+    // bare internal messages need the prefix.
+    process.stderr.write(`${reason.startsWith("Scopebond") ? reason : `Scopebond: ${reason}`}\n`);
     process.exit(2);
 }
 /** Codex accepts the structured deny response on a successful hook exit. Keeping
@@ -108,6 +122,18 @@ const harnessName = (harness) => harness === "claude" ? "Claude Code" : harness
 const harnessFileName = (harness) => harness === "claude" ? ".claude/settings.json" : harness === "cursor" ? ".cursor/hooks.json" : ".codex/hooks.json";
 const selectedHarness = (args) => args.includes("--codex") ? "codex" : args.includes("--cursor") ? "cursor" : "claude";
 const codexTrustStep = "Open Codex, run `/hooks`, review Scopebond, and choose Trust. Then start a new task.";
+/** What Cursor can and cannot stop. Cursor has before-hooks for shell commands, MCP
+ *  calls and file reads, but reports file *edits* only after they are written, so an
+ *  out-of-policy edit is recorded and flagged rather than prevented. Said at install
+ *  time, because someone choosing a guardrail needs to know its edges up front. */
+const cursorCoverageNote = [
+    "What this covers in Cursor:",
+    "  prevented  shell commands, MCP tool calls, file reads — checked before they run",
+    "  recorded   file edits — Cursor reports an edit only after writing it, so an",
+    "             out-of-policy edit is signed and flagged, not blocked",
+    "For edits that must be blocked before they land, use the GitHub Action as a required",
+    "check on pull requests.",
+].join("\n");
 async function runPreToolUse(mapper, deny = denyClaude) {
     let input;
     try {
@@ -116,11 +142,18 @@ async function runPreToolUse(mapper, deny = denyClaude) {
     catch {
         deny("hook received invalid JSON on stdin");
     }
+    let runtime;
     try {
         const cwd = input?.cwd ? String(input.cwd) : process.cwd();
-        const runtime = createHookRuntime(runtimePaths(resolveConfigDir(cwd)));
+        const dir = resolveConfigDir(cwd);
+        runtime = createHookRuntime(runtimePaths(dir));
+        useDigestKey(loadOrCreateDigestKey(dir));
         const decision = await runtime.evaluate(fillPushBranch(mapper(input), currentBranch(cwd)));
         await runtime.flush();
+        // Close before deciding: the receipt is already committed, and leaving the handle
+        // open is what made the write-ahead log grow without bound.
+        runtime.close();
+        runtime = undefined;
         if (decision.decision === "deny")
             deny(decision.reason);
         // Stay silent on allow/not_evaluated so the coding agent's normal permission
@@ -128,6 +161,10 @@ async function runPreToolUse(mapper, deny = denyClaude) {
         process.exit(0);
     }
     catch (error) {
+        try {
+            runtime?.close();
+        }
+        catch { /* already failing; the deny below is what matters */ }
         deny(`Scopebond hook failed closed: ${error.message}. Repair: run \`${cliCommand("init")}\`.`);
     }
 }
@@ -137,29 +174,70 @@ async function runClaude() {
 async function runCodex() {
     await runPreToolUse(mapCodexToolUse, denyCodex);
 }
+function denyCursor(reason) {
+    process.stdout.write(JSON.stringify({ permission: "deny", agentMessage: reason }) + "\n");
+    process.exit(0);
+}
 async function runCursor() {
-    let input = {};
+    // Unparseable input denies, like every other adapter. Previously this fell through
+    // to evaluation with an empty payload, which mapped to no known action and so
+    // answered "ask" — handing an unreadable request to a prompt the user would very
+    // likely accept. Deny-by-default on unparseable input is not optional.
+    let parsed;
     try {
-        input = JSON.parse(readStdin());
+        parsed = JSON.parse(readStdin());
     }
-    catch { /* fall through to fail-closed deny below */ }
-    const event = String(input?.hook_event_name ?? input?.event ?? process.argv[3] ?? "");
+    catch {
+        denyCursor("Scopebond: hook received invalid JSON on stdin");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        denyCursor("Scopebond: hook received a payload that is not a JSON object");
+    }
+    const input = parsed;
+    const event = String(input.hook_event_name ?? input.event ?? process.argv[3] ?? "");
     let permission = "deny";
     let message = "Scopebond hook failed closed";
+    let postHoc = false;
+    let runtime;
     try {
         const cwd = input?.cwd ? String(input.cwd) : process.cwd();
-        const runtime = createHookRuntime(runtimePaths(resolveConfigDir(cwd)));
-        const decision = await runtime.evaluate(fillPushBranch(mapCursorEvent(event, input), currentBranch(cwd)));
+        const dir = resolveConfigDir(cwd);
+        runtime = createHookRuntime(runtimePaths(dir));
+        useDigestKey(loadOrCreateDigestKey(dir));
+        const mapped = fillPushBranch(mapCursorEvent(event, input), currentBranch(cwd));
+        const decision = await runtime.evaluate(mapped);
         await runtime.flush();
-        // Only an out-of-policy action is denied outright; an allowed or unevaluated
-        // action defers to Cursor's own prompt ("ask"), never a silent auto-allow.
-        permission = decision.decision === "deny" ? "deny" : "ask";
+        // An `afterFileEdit` violation is real and recorded, but the edit has already
+        // landed. Say so rather than letting "blocked" imply it was stopped.
+        postHoc = mapped.some((m) => m.postHoc);
+        // Three outcomes, three answers:
+        //   deny  — out of policy, blocked outright.
+        //   allow — a rule was evaluated and permitted it. Returning "ask" here put a
+        //           confirmation prompt in front of every ordinary command, which is not
+        //           "your agent works as normal"; it also trained people to click through
+        //           prompts, which makes the real denials easier to miss. An evaluated
+        //           allow is a decision, not a silent auto-approval.
+        //   ask   — nothing was evaluated (no rule covers this action), so Cursor's own
+        //           permission flow stays in charge. That is the fail-closed case and it
+        //           keeps its prompt.
+        permission = decision.decision === "deny" ? "deny" : decision.decision === "allow" ? "allow" : "ask";
         message = decision.reason;
     }
     catch (error) {
         permission = "deny";
         message = `Scopebond hook failed closed: ${error.message}. Repair: run \`${cliCommand("init")}\`.`;
     }
+    finally {
+        // Release the SQLite handles on every path: an unclosed writer leaves its
+        // write-ahead log behind for the next tool call to extend.
+        try {
+            runtime?.close();
+        }
+        catch { /* the decision is already recorded */ }
+    }
+    if (postHoc && permission === "deny") {
+        message = `${message}\nCursor reports a file edit only after it is written, so this edit was not prevented. Review and revert it yourself.`;
+    }
     process.stdout.write(JSON.stringify({ permission, agentMessage: message }) + "\n");
     process.exit(0);
 }
@@ -170,43 +248,105 @@ async function runCursor() {
 function requireInteractive(command, args) {
     if (process.stdin.isTTY || args.includes("--yes"))
         return;
-    console.error(`scopebond ${command} changes what governs your coding agent, so it must be run from an interactive terminal.`);
-    console.error(`In a script or CI, pass --yes: ${cliCommand(`${command} --yes`)}`);
+    console.error(`scopebond ${command} changes what governs your coding agent, so it does not run unattended.`);
+    console.error(`There is no terminal on stdin here — which is also what it looks like when the agent itself`);
+    console.error(`tries to run this, so the refusal is deliberate rather than a bug.`);
+    console.error(``);
+    console.error(`If you are a person: run it in your own terminal, or confirm it now with --yes:`);
+    console.error(`  ${cliCommand(`${command} --yes`)}`);
+    console.error(`Scripts, CI and container builds should always pass --yes.`);
     process.exit(1);
 }
 function runInit(args) {
-    requireInteractive("init", args);
     const harness = selectedHarness(args);
     const dir = configDir();
-    const { agentKid, policyPath } = scaffold(dir, { force: args.includes("--force") });
+    // A dry run changes nothing, so it needs no terminal and no --yes.
+    if (args.includes("--dry-run")) {
+        const shared = projectHarnessFile(harness, process.cwd());
+        const local = localHarnessFile(harness, process.cwd());
+        const personal = args.includes("--shared") || args.includes("--npx") ? null
+            : local ?? (gitShareState(shared) === "tracked" ? null : shared);
+        console.log(`Dry run — nothing is written.\n`);
+        console.log(`Would scaffold      ${dir} (machine key, countersigning key, starter policy, .gitignore)`);
+        if (args.includes("--no-install")) {
+            console.log(`Would print         the ${harnessFileName(harness)} snippet instead of writing it`);
+        }
+        else if (personal) {
+            console.log(`Would configure     ${personal} (this machine only; kept out of git)`);
+            console.log(`  adding hook       "<node>" "${pinnedCliPath(hookVersion())}" ${harness}`);
+            console.log(`                    (or the path this copy runs from, when it is already installed durably)`);
+            if (local)
+                console.log(`  and remove        any machine-specific Scopebond entry from ${shared}`);
+        }
+        else {
+            console.log(`Would configure     ${shared} (shared — safe to commit)`);
+            console.log(`  adding hook       ${hookCommand(harness)}`);
+        }
+        console.log(`\nNothing else in those files is changed. Run without --dry-run to apply.`);
+        process.exit(0);
+    }
+    requireInteractive("init", args);
+    const { agentKid, policyPath, rulesPath: rulesFile } = scaffold(dir, { force: args.includes("--force") });
     console.log(`Scopebond hook enrolled in ${dir}`);
     console.log(`  machine key    ${agentKid}`);
-    console.log(`  policy         ${policyPath} (starter — edit the limits)`);
+    console.log(`  rules          ${rulesFile} (the readable list — edit this)`);
+    console.log(`  policy         ${policyPath} (compiled from the rules; don't hand-edit)`);
     // With a user-level install present, a project policy governs only once trusted.
     // Running init here is that decision, so pin this policy now.
     if (!process.env.SCOPEBOND_HOOK_DIR && existsSync(join(userHome(), "policy.json"))) {
         trustProjectPolicy(dir);
         console.log(`  trusted        overrides ${userHome()} here; after editing it, run \`${cliCommand("trust")}\``);
     }
-    console.log("");
+    // The hook command runs once per tool call, so it must start fast. `npx` re-resolves
+    // a package that is already on disk and costs ~830 ms a call; the same CLI invoked
+    // directly costs ~110 ms. Pin a durable copy and use that, and fall back to `npx`
+    // (slow, but it always starts) when no durable copy can be made. `--npx` forces the
+    // portable form for anyone who wants it.
+    const shared = args.includes("--shared");
+    const pin = args.includes("--npx") || shared ? { cli: null, how: "unavailable" } : ensureDurableRuntime(cliPath(), hookVersion());
+    const command = pin.cli ? absoluteHookCommand(pin.cli, harness) : undefined;
     // Configure the agent automatically by default (idempotent), so there is no
     // hand-editing step; --no-install prints the snippet instead.
     if (!args.includes("--no-install")) {
-        let file;
+        let placed;
         try {
-            file = installHarness(harness);
+            placed = placeHook(harness, process.cwd(), command, { shared });
         }
         catch (error) {
             console.error(error.message);
             process.exit(1);
         }
-        console.log(`✓ ${harnessName(harness)} configured in ${file}`);
+        // No per-action millisecond claim here: it varies by machine, and this project only
+        // states numbers it has measured. The measured comparison lives in the changelog.
+        console.log(`  hook runtime   ${placed.scope === "personal"
+            ? `${pin.cli}\n                 pinned — no npx resolution per action`
+            : `npx @scopebond/hook@${hookVersion()} — portable, but re-resolves on every action`}`);
+        console.log("");
+        console.log(`✓ ${harnessName(harness)} configured in ${placed.file}`);
+        console.log(placed.scope === "personal"
+            ? `  this machine only — kept out of git, so no teammate inherits a path that does not exist for them`
+            : `  shared — the portable command starts on any machine that clones this project`);
+        if (placed.repaired > 0)
+            console.log(`  moved a machine-specific hook out of ${projectHarnessFile(harness, process.cwd())}; commit that change`);
+        if (placed.note)
+            console.log(`  note: ${placed.note}`);
         if (harness === "codex")
             console.log(`\nOne last step: ${codexTrustStep}`);
+        if (harness === "cursor")
+            console.log(`\n${cursorCoverageNote}`);
     }
     else {
+        // The snippet is for a file the user will likely commit, so it carries the portable
+        // command; the pinned one is offered separately, for a file only this machine uses.
         console.log(`Add this to your ${harnessFileName(harness)}:`);
         console.log(harnessSnippet(harness));
+        const local = localHarnessFile(harness, process.cwd());
+        if (command && local) {
+            console.log(`\nFaster, for this machine only — use this command in ${local} instead (keep that file out of git):`);
+            console.log(`  ${command}`);
+        }
+        if (harness === "cursor")
+            console.log(`\n${cursorCoverageNote}`);
     }
     console.log("");
     // Print the runnable `npx` form: after `npx @scopebond/hook init` there is no
@@ -225,15 +365,14 @@ function decisionOf(payload) {
     return "allow";
 }
 function describeIntent(payload) {
-    const intent = (payload.intent ?? {});
-    const p = (intent.params ?? {});
-    const bits = intent.action_type === "shell.exec" ? String(p.program ?? "")
-        : intent.action_type === "git.push" ? `${p.remote ?? ""} ${p.ref ?? ""}`.trim()
-            : intent.action_type === "file.write" || intent.action_type === "file.read" ? String(p.path ?? "")
-                : intent.action_type === "mcp.tool.call" ? `${p.server ?? ""}/${p.tool ?? ""}`
-                    : intent.action_type === "net.fetch" ? String(p.host ?? "") : "";
-    return `${String(intent.action_type ?? "?")}${bits ? ` ${bits}` : ""}`;
+    return describeAction(payload.intent);
 }
+/** `log [-n N] [--deny] [--since <when>]` — the recent decisions.
+ *
+ *  "What did my agents get blocked on this week" had no answer at the CLI: the only
+ *  output was an unfiltered tail. `--deny` and `--since` make it answerable, and the
+ *  tail is read as a tail (`ORDER BY id DESC LIMIT`) rather than by loading and parsing
+ *  every receipt ever recorded and slicing the end off. */
 async function runLog(args) {
     const dir = resolveConfigDir(process.cwd());
     const dbPath = join(dir, "receipts.db");
@@ -243,18 +382,259 @@ async function runLog(args) {
     }
     const nIdx = args.indexOf("-n");
     const n = nIdx >= 0 ? Math.max(1, Number(args[nIdx + 1]) || 20) : 20;
+    const denyOnly = args.includes("--deny");
+    const sinceIdx = args.indexOf("--since");
+    const since = sinceIdx >= 0 ? parseSince(args[sinceIdx + 1]) : null;
+    if (sinceIdx >= 0 && since === null) {
+        console.error(`--since wants a duration (7d, 24h, 30m) or a date (2026-09-25); got ${args[sinceIdx + 1] ?? "nothing"}`);
+        process.exit(1);
+    }
     const { store } = openReceiptStore({ db: dbPath });
-    const all = await Promise.resolve(store.list());
-    const recent = all.slice(-n);
-    if (recent.length === 0) {
-        console.log("no receipts yet.");
+    try {
+        const total = store.count ? await Promise.resolve(store.count()) : (await Promise.resolve(store.list())).length;
+        // A filter has to look past the last N to find N matches; without one, read only the
+        // tail. The scan is still bounded so a huge log cannot hang the command.
+        const budget = denyOnly || since ? Math.min(Math.max(n * 50, 1000), 20000) : n;
+        const scanned = store.recent
+            ? await Promise.resolve(store.recent(budget))
+            : (await Promise.resolve(store.list())).slice(-budget).reverse();
+        const matching = scanned.filter((r) => {
+            const p = r.payload;
+            if (denyOnly && decisionOf(p) !== "deny")
+                return false;
+            if (since) {
+                const at = Date.parse(String(p.timestamp ?? ""));
+                if (!Number.isFinite(at) || at < since)
+                    return false;
+            }
+            return true;
+        });
+        const shown = matching.slice(0, n).reverse(); // oldest-first on screen, newest last
+        if (shown.length === 0) {
+            console.log(denyOnly || since ? "no receipts match that filter." : "no receipts yet.");
+            process.exit(0);
+        }
+        for (const r of shown) {
+            const p = r.payload;
+            console.log(`${String(p.timestamp ?? "")}  ${decisionOf(p).padEnd(13)}  ${describeIntent(p)}`);
+        }
+        const filters = [denyOnly ? "denied" : "", since ? `since ${new Date(since).toISOString()}` : ""].filter(Boolean).join(", ");
+        const scope = filters ? ` matching ${filters}` : "";
+        const capped = (denyOnly || since) && scanned.length >= budget && total > budget;
+        console.log(`\n${shown.length}${scope} of ${total} receipt(s)${capped ? ` — searched the most recent ${budget}` : ""}. Verify them: ${cliCommand("verify")}`);
+    }
+    finally {
+        try {
+            store.close?.();
+        }
+        catch { /* read-only */ }
+    }
+}
+/** `rules` — read and change the limits in plain terms.
+ *
+ *  Without this, "edit the limits" meant hand-writing a ~700-character case-folded
+ *  negative lookahead, which nobody does — so the starter policy was effectively the only
+ *  policy. The lists live in `.scopebond/rules.json`; `policy.json` is compiled from them. */
+function runRules(args) {
+    const dir = resolveConfigDir(process.cwd());
+    if (!existsSync(join(dir, "policy.json"))) {
+        console.error(`no policy here yet — run \`${cliCommand("init")}\` first.`);
+        process.exit(1);
+    }
+    const rules = loadRules(dir) ?? defaultRules();
+    const [verb, ...values] = args.filter((a) => !a.startsWith("--"));
+    const value = values.join(" ").trim();
+    if (!verb || verb === "show") {
+        console.log(`Rules for ${dir}`);
+        if (!loadRules(dir))
+            console.log(`(showing the defaults — ${rulesPath(dir)} will be written on your first change)`);
+        console.log("");
+        console.log(describeRules(rules));
+        console.log("");
+        console.log(`Change them:`);
+        console.log(`  ${cliCommand("rules allow <program>")}        stop blocking a program`);
+        console.log(`  ${cliCommand("rules block <program>")}        start blocking one`);
+        console.log(`  ${cliCommand("rules protect <path>")}         never write there`);
+        console.log(`  ${cliCommand("rules unprotect <path>")}       allow writing there again`);
+        console.log(`  ${cliCommand("rules protect-branch <name>")}  never push there`);
+        console.log(`  ${cliCommand("rules unprotect-branch <name>")}`);
+        console.log(`Or edit ${rulesPath(dir)} directly, then \`${cliCommand("rules apply")}\`.`);
+        process.exit(0);
+    }
+    const needsValue = ["allow", "block", "protect", "unprotect", "protect-branch", "unprotect-branch"];
+    if (needsValue.includes(verb) && !value) {
+        console.error(`\`rules ${verb}\` needs a value, e.g. \`${cliCommand(`rules ${verb} ${verb.includes("branch") ? "production" : verb.includes("protect") ? "infra/" : "dd"}`)}\``);
+        process.exit(1);
+    }
+    let changed = "";
+    switch (verb) {
+        case "allow": {
+            const before = rules.destructive_programs.length;
+            rules.destructive_programs = rules.destructive_programs.filter((p) => p.toLowerCase() !== value.toLowerCase());
+            if (rules.destructive_programs.length === before) {
+                console.log(`${value} was not in the blocked list; nothing to change.`);
+                process.exit(0);
+            }
+            changed = `${value} is no longer blocked`;
+            break;
+        }
+        case "block": {
+            if (rules.destructive_programs.some((p) => p.toLowerCase() === value.toLowerCase())) {
+                console.log(`${value} is already blocked.`);
+                process.exit(0);
+            }
+            rules.destructive_programs.push(value.toLowerCase());
+            changed = `${value} is now blocked`;
+            break;
+        }
+        case "protect":
+        case "unprotect": {
+            const list = verb === "protect" ? "protected_write" : "protected_write";
+            const rule = pathRuleFor(value);
+            if (verb === "protect") {
+                if (rules[list].some((r) => r.label === rule.label)) {
+                    console.log(`${value} is already protected.`);
+                    process.exit(0);
+                }
+                rules[list].push(rule);
+                changed = `writes to ${rule.label} are now blocked`;
+            }
+            else {
+                const before = rules[list].length;
+                rules[list] = rules[list].filter((r) => r.label !== rule.label && !r.label.startsWith(`${value.replace(/\/$/, "")}/`));
+                if (rules[list].length === before) {
+                    console.log(`${value} is not in the protected list. Current list:`);
+                    for (const r of rules[list])
+                        console.log(`  ${r.label}`);
+                    process.exit(1);
+                }
+                changed = `writes to ${value} are allowed again`;
+            }
+            break;
+        }
+        case "protect-branch": {
+            if (rules.protected_branches.some((b) => b.toLowerCase() === value.toLowerCase())) {
+                console.log(`${value} is already protected.`);
+                process.exit(0);
+            }
+            rules.protected_branches.push(value);
+            changed = `pushes to ${value} are now blocked`;
+            break;
+        }
+        case "unprotect-branch": {
+            const before = rules.protected_branches.length;
+            rules.protected_branches = rules.protected_branches.filter((b) => b.toLowerCase() !== value.toLowerCase());
+            if (rules.protected_branches.length === before) {
+                console.log(`${value} was not protected; nothing to change.`);
+                process.exit(0);
+            }
+            changed = `pushes to ${value} are allowed again`;
+            break;
+        }
+        case "apply":
+            changed = `recompiled from ${rulesPath(dir)}`;
+            break;
+        default:
+            console.error(`unknown: rules ${verb}`);
+            printHelp("rules", true);
+            process.exit(1);
+    }
+    // Changing what governs the agent is the same class of action as `init`.
+    requireInteractive("rules", args);
+    const policyPath = join(dir, "policy.json");
+    const agentKid = createSigner({ privateKeyPem: readFileSync(join(dir, "agent.key"), "utf8") }).kid;
+    saveRules(dir, rules);
+    writeFileSync(policyPath, `${JSON.stringify(compile(rules, agentKid), null, 2)}\n`);
+    console.log(`✓ ${changed}`);
+    console.log(`  rules          ${rulesPath(dir)}`);
+    console.log(`  policy         ${policyPath} (recompiled)`);
+    // A project policy governs only once trusted, and the hash just changed.
+    if (!process.env.SCOPEBOND_HOOK_DIR && existsSync(join(userHome(), "policy.json"))) {
+        trustProjectPolicy(dir);
+        console.log(`  trusted        re-pinned for this project`);
+    }
+    console.log(`\nCheck it: ${cliCommand('test "rm -rf /"')}`);
+    process.exit(0);
+}
+/** `prune --before <when> [--yes]` — bound the local receipt store.
+ *
+ *  Signed receipts are the product, so this never runs on its own and never quietly
+ *  destroys anything: it archives what it will remove to a JSONL file beside the
+ *  database first, and it refuses entirely once the log has been anchored, because a
+ *  receipt's position is its anchor leaf index. Without a `--before` it reports the
+ *  footprint and exits. */
+async function runPrune(args) {
+    const dir = resolveConfigDir(process.cwd());
+    const dbPath = join(dir, "receipts.db");
+    if (!existsSync(dbPath)) {
+        console.log("no local receipts yet — nothing to prune.");
+        process.exit(0);
+    }
+    const beforeIdx = args.indexOf("--before");
+    if (beforeIdx < 0) {
+        console.log(`local receipts   ${dbPath}`);
+        console.log(`                 ${describeStore(dbPath)}`);
+        console.log(`\nNothing is removed automatically. To bound it, name a cutoff:`);
+        console.log(`  ${cliCommand("prune --before 90d")}      # older than 90 days`);
+        console.log(`  ${cliCommand("prune --before 2026-01-01")}`);
+        console.log(`Receipts are archived beside the database before removal.`);
+        process.exit(0);
+    }
+    const cutoff = parseSince(args[beforeIdx + 1]);
+    if (cutoff === null) {
+        console.error(`--before wants a duration (90d, 24h) or a date (2026-01-01); got ${args[beforeIdx + 1] ?? "nothing"}`);
+        process.exit(1);
+    }
+    const iso = new Date(cutoff).toISOString();
+    const { store } = openReceiptStore({ db: dbPath });
+    const sqlite = store;
+    if (!sqlite.before || !sqlite.removeBefore) {
+        console.error("this receipt store does not support pruning (no SQLite available).");
+        process.exit(1);
+    }
+    try {
+        const doomed = sqlite.before(iso);
+        if (doomed.length === 0) {
+            console.log(`no receipts older than ${iso}.`);
+            process.exit(0);
+        }
+        const before = describeStore(dbPath);
+        console.log(`${doomed.length} receipt(s) recorded before ${iso} (store is currently ${before}).`);
+        if (!args.includes("--yes") && !process.stdin.isTTY) {
+            console.error(`\nThis removes signed evidence, so it needs an explicit confirmation:`);
+            console.error(`  ${cliCommand(`prune --before ${args[beforeIdx + 1]} --yes`)}`);
+            process.exit(1);
+        }
+        const archive = join(dir, `receipts-archived-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`);
+        writeFileSync(archive, `${doomed.map((r) => JSON.stringify(r)).join("\n")}\n`);
+        console.log(`archived to      ${archive}`);
+        const { removed } = sqlite.removeBefore(iso);
+        console.log(`removed          ${removed} receipt(s)`);
+        store.close?.();
+        console.log(`store now        ${describeStore(dbPath)}`);
+        console.log(`\nThe archive is a plain JSONL of signed receipts — still verifiable, still yours.`);
         process.exit(0);
     }
-    for (const r of recent) {
-        const p = r.payload;
-        console.log(`${String(p.timestamp ?? "")}  ${decisionOf(p).padEnd(13)}  ${describeIntent(p)}`);
+    catch (error) {
+        try {
+            store.close?.();
+        }
+        catch { /* closing after a failure */ }
+        console.error(`prune refused: ${error.message}`);
+        process.exit(1);
+    }
+}
+/** A `--since` value: a duration (`7d`, `24h`, `30m`) or an ISO-ish date. */
+export function parseSince(value, now = Date.now()) {
+    if (!value)
+        return null;
+    const duration = /^(\d+)\s*([dhm])$/i.exec(value.trim());
+    if (duration) {
+        const scale = { d: 86_400_000, h: 3_600_000, m: 60_000 }[duration[2].toLowerCase()];
+        return now - Number(duration[1]) * scale;
     }
-    console.log(`\n${recent.length} of ${all.length} receipt(s). Verify them: ${cliCommand("verify")}`);
+    const at = Date.parse(value);
+    return Number.isFinite(at) ? at : null;
 }
 async function runVerify() {
     const dir = resolveConfigDir(process.cwd());
@@ -266,10 +646,18 @@ async function runVerify() {
     }
     const { attester } = loadOrCreateAttester({ file: attesterPath });
     const { store } = openReceiptStore({ db: dbPath });
+    // Verification is the one command that must read everything — that is the point of it.
+    // It just should not look hung while doing so: at ~2.6 s per 20,000 receipts a long
+    // history is a visible wait, so report progress on a TTY.
     const all = await Promise.resolve(store.list());
+    try {
+        store.close?.();
+    }
+    catch { /* read-only */ }
+    const progress = process.stdout.isTTY && all.length >= 2000;
     let ok = 0;
     const bad = [];
-    for (const r of all) {
+    for (const [index, r] of all.entries()) {
         const result = verifyReceipt(r, attester.publicKeyPem);
         if (result.valid)
             ok += 1;
@@ -277,7 +665,11 @@ async function runVerify() {
             const failed = Object.entries(result).filter(([k, v]) => k.endsWith("_valid") && v === false).map(([k]) => k);
             bad.push(`${String(r.payload.timestamp ?? "")}: ${failed.join(", ") || "invalid"}`);
         }
+        if (progress && (index + 1) % 1000 === 0)
+            process.stderr.write(`\rverifying ${index + 1}/${all.length}…`);
     }
+    if (progress)
+        process.stderr.write("\r".padEnd(40) + "\r");
     console.log(`${ok}/${all.length} receipt(s) verify offline against ${attesterPath}.`);
     if (bad.length) {
         for (const b of bad)
@@ -294,7 +686,7 @@ async function runTest(args) {
     }
     const dir = resolveConfigDir(process.cwd());
     if (!existsSync(join(dir, "policy.json"))) {
-        console.error("no policy yet — run `scopebond-hook init` first.");
+        console.error(`no policy yet — run \`${cliCommand("init")}\` first.`);
         process.exit(1);
     }
     // Evaluate against the real policy and keys, but a throwaway store, so `test`
@@ -310,10 +702,17 @@ async function runTest(args) {
         console.log(`command: ${command}`);
         for (const m of mapped) {
             const d = await runtime.evaluateOne(m);
-            console.log(`  ${describeIntent({ intent: m.intent }).padEnd(28)} → ${d.decision}${d.reason ? `  (${d.reason})` : ""}`);
+            // One tidy row per action. A deny's full explanation is multi-line, so the
+            // row carries only the deciding rule and the whole message is printed once,
+            // below — exactly as the agent will receive it.
+            const note = d.decision === "deny" ? (d.clauseId ? `rule "${d.clauseId}"` : "")
+                : d.decision === "not_evaluated" ? d.reason : "";
+            console.log(`  ${describeIntent({ intent: m.intent }).padEnd(28)} → ${d.decision.padEnd(14)}${note}`);
         }
         const overall = await runtime.evaluate(mapped);
-        console.log(`\noverall: ${overall.decision}${overall.reason ? `  · ${overall.reason}` : ""}`);
+        console.log(`\noverall: ${overall.decision}`);
+        if (overall.decision === "deny" && overall.reason)
+            console.log(`\n${overall.reason}`);
         process.exit(overall.decision === "deny" ? 2 : 0);
     }
     finally {
@@ -326,7 +725,8 @@ async function runConnect(args) {
     const bundleArg = positional[1];
     const harness = selectedHarness(args);
     if (!url) {
-        console.error("usage: scopebond-hook connect <workspace-url> <enrollment> [--claude|--cursor|--codex] [--no-install]");
+        console.error(`usage: ${cliCommand("connect <workspace-url> <enrollment> [--claude|--cursor|--codex] [--no-install]")}`);
+        console.error(enrollmentHelp);
         process.exit(1);
     }
     const dir = configDir();
@@ -340,16 +740,28 @@ async function runConnect(args) {
         bundle = readBundleArg(bundleArg, readStdin);
     }
     catch {
-        console.error("could not read the enrollment (expected a file, inline blob, or JSON on stdin)");
+        console.error(`could not read the enrollment (expected a file, inline blob, or JSON on stdin)\n${enrollmentHelp}`);
         process.exit(1);
     }
+    await finishConnect(dir, url, bundle, harness, args);
+}
+/** Enroll with a bundle and wire the agent: shared by `connect` (a pasted enrollment)
+ *  and `login` (one received through device-code approval). */
+async function finishConnect(dir, url, bundle, harness, args) {
     try {
         const c = await connectCloud(dir, url, bundle);
         console.log(`✓ Connected to ${c.url}`);
         // Configure the agent automatically (merges into the existing config), unless the
-        // caller opts out. This removes the "paste this snippet" step.
-        if (!args.includes("--no-install")) {
-            const file = installHarness(harness);
+        // caller opts out. This removes the "paste this snippet" step. A hook that is already
+        // configured — pinned by `init`, or user-level by `install` — is left as it is:
+        // connecting changes where receipts go, not how the hook starts.
+        const scopes = harnessScopes(harness, process.cwd());
+        const existing = scopes.local ?? scopes.project ?? scopes.user;
+        if (existing && !args.includes("--no-install")) {
+            console.log(`✓ ${harnessName(harness)} already configured in ${existing}`);
+        }
+        else if (!args.includes("--no-install")) {
+            const { file } = placeHook(harness, process.cwd(), undefined);
             console.log(`✓ ${harnessName(harness)} configured in ${file}`);
             if (harness === "codex")
                 console.log(`\nOne last step: ${codexTrustStep}`);
@@ -362,14 +774,26 @@ async function runConnect(args) {
         console.log("Run your agent — the first action appears in your workspace within seconds.");
     }
     catch (error) {
-        console.error(`connect failed: ${error.message}`);
+        const message = error.message;
+        console.error(`connect failed: ${message}`);
+        if (/enrollment|expired|401|403/i.test(message))
+            console.error(enrollmentHelp);
         process.exit(1);
     }
 }
+/** Where an enrollment comes from, for every connect error that means "this one will
+ *  not work": the bare "invalid enrollment token" told the reader nothing about what to
+ *  do next. */
+const enrollmentHelp = [
+    "An enrollment comes from your Scopebond workspace: open it, choose to connect an agent,",
+    "and copy the command it shows — it includes the workspace URL and a fresh enrollment.",
+    "Each enrollment is single-use and expires soon after it is created; if this one was",
+    "used or has expired, create a new one there.",
+].join("\n");
 async function runFlush() {
     const dir = resolveConfigDir(process.cwd());
     if (!loadConnection(dir)) {
-        console.error("not connected to a workspace; run `scopebond-hook connect` first");
+        console.error(`not connected to a workspace; run \`${cliCommand("connect <workspace-url> <enrollment>")}\` first`);
         process.exit(1);
     }
     const runtime = createHookRuntime(runtimePaths(dir));
@@ -389,20 +813,53 @@ function cliPath() {
  *  so every project a developer opens is governed without a per-repo `init`. */
 function runInstall(args) {
     const dir = userHome();
+    // Run through `npx`, this CLI lives in npm's throwaway cache; registering that path
+    // would leave a hook that stops starting whenever npm clears it — and a hook that
+    // cannot start lets every action through. Pin the durable copy, as `init` does, and
+    // fall back to the portable `npx` command when none can be made.
+    const commandFor = (h) => {
+        const pin = ensureDurableRuntime(cliPath(), hookVersion());
+        return pin.cli ? absoluteHookCommand(pin.cli, h) : hookCommand(h);
+    };
+    const harnessesFor = () => args.includes("--codex") ? ["codex"]
+        : args.includes("--cursor") ? ["cursor"]
+            : args.includes("--claude") ? ["claude"]
+                : ["claude", ...(cursorDetected() ? ["cursor"] : []), ...(codexDetected() ? ["codex"] : [])];
+    // `install` rewrites agent config files the user did not create — their theme, plugins
+    // and permissions live in ~/.claude/settings.json — so there is a way to see exactly
+    // what it would touch before it touches anything.
+    if (args.includes("--dry-run")) {
+        console.log(`Dry run — nothing is written.\n`);
+        console.log(`Would scaffold      ${dir} (machine key, countersigning key, starter policy)`);
+        for (const h of harnessesFor()) {
+            const file = userHarnessFile(h);
+            const exists = existsSync(file);
+            console.log(`Would ${exists ? "modify" : "create"} ${file}`);
+            if (exists)
+                console.log(`  backing it up to  ${file}.scopebond-backup`);
+            // Previewed without copying anything: the path the real run would pin.
+            console.log(`  adding hook       ${absoluteHookCommand(isEphemeralPath(cliPath()) ? pinnedCliPath(hookVersion()) : cliPath(), h)}`);
+            if (exists && isHarnessConfigured(file))
+                console.log(`  (a Scopebond hook is already there; it would be replaced, not duplicated)`);
+        }
+        console.log(`\nNothing else in those files is changed. Run without --dry-run to apply.`);
+        process.exit(0);
+    }
     const { agentKid, policyPath } = scaffold(dir, { force: args.includes("--force") });
     console.log(`Scopebond installed for this user in ${dir}`);
     console.log(`  machine key    ${agentKid}`);
     console.log(`  policy         ${policyPath} (starter — edit the limits)`);
     console.log("");
-    const harnesses = args.includes("--codex") ? ["codex"]
-        : args.includes("--cursor") ? ["cursor"]
-            : args.includes("--claude") ? ["claude"]
-                : ["claude", ...(cursorDetected() ? ["cursor"] : []), ...(codexDetected() ? ["codex"] : [])];
+    const harnesses = harnessesFor();
     if (!args.includes("--no-install")) {
         for (const h of harnesses) {
             try {
-                const file = writeHarnessConfig(userHarnessFile(h), h, absoluteHookCommand(cliPath(), h));
+                const target = userHarnessFile(h);
+                const backup = existsSync(target) ? `${target}.scopebond-backup` : null;
+                const file = writeHarnessConfig(target, h, commandFor(h));
                 console.log(`✓ ${harnessName(h)} configured in ${file}`);
+                if (backup && existsSync(backup))
+                    console.log(`  original kept at ${backup}`);
             }
             catch (error) {
                 console.error(`✗ ${harnessName(h)}: ${error.message}`);
@@ -421,25 +878,59 @@ function runInstall(args) {
     console.log(`Check it: ${cliCommand("doctor")} · see decisions: ${cliCommand("log")}`);
     console.log(`To send receipts to a workspace: ${cliCommand("connect <workspace-url> <enrollment>")}`);
 }
+/** Size and count of the local receipt store, plus its write-ahead log. Signed evidence
+ *  accumulates in the user's project directory and there is no automatic deletion — so
+ *  the footprint is reported rather than left to be discovered. */
+function describeStore(dbPath) {
+    const bytes = (file) => { try {
+        return statSync(file).size;
+    }
+    catch {
+        return 0;
+    } };
+    const total = bytes(dbPath) + bytes(`${dbPath}-wal`) + bytes(`${dbPath}-shm`);
+    const human = total >= 1024 * 1024 ? `${(total / 1024 / 1024).toFixed(1)} MiB` : `${Math.max(1, Math.round(total / 1024))} KiB`;
+    let count = null;
+    try {
+        const { store } = openReceiptStore({ db: dbPath });
+        try {
+            count = store.count ? Number(store.count()) : null;
+        }
+        finally {
+            store.close?.();
+        }
+    }
+    catch {
+        count = null;
+    }
+    return count === null ? human : `${count} receipt(s), ${human}`;
+}
 function runStatus() {
     const home = userHome();
     const installed = existsSync(join(home, "policy.json"));
-    const claude = isHarnessConfigured(userHarnessFile("claude"));
-    const cursor = isHarnessConfigured(userHarnessFile("cursor"));
-    const codex = isHarnessConfigured(userHarnessFile("codex"));
+    // Both scopes, always: `init` writes the project config and `install` writes the
+    // user one, so a single-scope check contradicts whichever command the user ran.
+    const claude = harnessScopes("claude", process.cwd());
+    const cursor = harnessScopes("cursor", process.cwd());
+    const codex = harnessScopes("codex", process.cwd());
     const connected = !!loadConnection(resolveConfigDir(process.cwd()));
     const dbPath = join(resolveConfigDir(process.cwd()), "receipts.db");
     console.log(`Scopebond hook ${hookVersion()}`);
-    console.log(`  user home        ${home} ${installed ? "(installed)" : "(not installed — run `scopebond install`)"}`);
+    console.log(`  user home        ${home} ${installed ? "(installed)" : `(not installed — run \`${cliCommand("install")}\`)`}`);
     console.log(`  active config    ${resolveConfigDir(process.cwd())}`);
     const ignored = untrustedProjectPolicy(process.cwd());
     if (ignored)
         console.log(`  project policy   ${ignored} ignored — not trusted (run \`${cliCommand("trust")}\` to use it)`);
-    console.log(`  Claude Code     ${claude ? "configured" : "not configured"}`);
-    console.log(`  Cursor           ${cursor ? "configured" : cursorDetected() ? "detected, not configured" : "not detected"}`);
-    console.log(`  Codex            ${codex ? "configured (approve once with /hooks)" : codexDetected() ? "detected, not configured" : "not detected"}`);
+    console.log(`  Claude Code      ${harnessScopeLabel(claude) || "not configured"}`);
+    console.log(`  Cursor           ${harnessScopeLabel(cursor) || (cursorDetected() ? "detected, not configured" : "not detected")}`);
+    console.log(`  Codex            ${codex.project || codex.user ? `${harnessScopeLabel(codex)} — approve once with /hooks` : codexDetected() ? "detected, not configured" : "not detected"}`);
     console.log(`  cloud workspace  ${connected ? "connected" : "not connected (local only)"}`);
-    console.log(`  local receipts   ${existsSync(dbPath) ? dbPath : "none yet"}`);
+    console.log(`  local receipts   ${existsSync(dbPath) ? `${dbPath} (${describeStore(dbPath)})` : "none yet"}`);
+    for (const [name, scopes] of [["Claude Code", claude], ["Cursor", cursor], ["Codex", codex]]) {
+        for (const file of [scopes.project, scopes.local, scopes.user])
+            if (file)
+                console.log(`    ${name}: ${file}`);
+    }
 }
 async function runDoctor() {
     const problems = [];
@@ -453,16 +944,55 @@ async function runDoctor() {
     console.log(`  cli              ${cli} ${existsSync(cli) ? "ok" : "MISSING"}`);
     const active = resolveConfigDir(process.cwd());
     const hasPolicy = existsSync(join(active, "policy.json"));
-    console.log(`  active config    ${active} ${hasPolicy ? "ok" : "no policy (run `scopebond install` or `init`)"}`);
+    console.log(`  active config    ${active} ${hasPolicy ? "ok" : `no policy (run \`${cliCommand("init")}\` here, or \`${cliCommand("install")}\` once for your user)`}`);
     if (!hasPolicy)
         problems.push("no policy found in the active config dir");
     const ignored = untrustedProjectPolicy(process.cwd());
     if (ignored)
         console.log(`  project policy   ${ignored} IGNORED — not trusted (never trusted, or edited since). Review it, then \`${cliCommand("trust")}\``);
-    const codex = isHarnessConfigured(userHarnessFile("codex"));
-    console.log(`  Codex hook       ${codex ? "configured" : codexDetected() ? "not configured — run `scopebond install --codex`" : "not detected"}`);
-    if (codex)
-        console.log(`  Codex approval   run /hooks in Codex and approve Scopebond once`);
+    // Every harness, in both scopes, plus a check that each configured command can
+    // actually start. A pinned path that has gone missing is the one failure mode of
+    // the fast absolute-path install, so doctor is where it must surface.
+    let anyHarness = false;
+    for (const harness of ["claude", "cursor", "codex"]) {
+        const scopes = harnessScopes(harness, process.cwd());
+        const label = harnessScopeLabel(scopes);
+        const name = harnessName(harness);
+        if (!label) {
+            const detected = harness === "claude" || (harness === "cursor" ? cursorDetected() : codexDetected());
+            console.log(`  ${name.padEnd(15)} ${detected ? `not configured — run \`${cliCommand(`init${harness === "claude" ? "" : ` --${harness}`}`)}\`` : "not detected"}`);
+            continue;
+        }
+        anyHarness = true;
+        console.log(`  ${name.padEnd(15)} ${label}`);
+        for (const file of [scopes.project, scopes.local, scopes.user]) {
+            if (!file)
+                continue;
+            // A project file git shares must not name a path on this machine: it starts here,
+            // so the resolve check below passes, but on every teammate's machine it cannot
+            // start — and a hook that cannot start is a non-blocking error, so their agent runs
+            // unchecked. Only the doctor on the machine that wrote it can see this coming.
+            const share = file === scopes.project ? gitShareState(file) : "none";
+            const shared = share === "tracked" || share === "untracked";
+            for (const command of configuredHookCommands(file)) {
+                const ok = hookCommandResolves(command);
+                const leaks = ok && shared && isMachineSpecificCommand(command);
+                console.log(`    ${ok && !leaks ? "ok  " : "BAD "} ${file}`);
+                if (!ok) {
+                    console.log(`         command cannot start: ${command}`);
+                    problems.push(`${name} hook command no longer resolves in ${file} — run \`${cliCommand("init")}\` to repair it`);
+                }
+                else if (leaks) {
+                    console.log(`         machine-specific command in a file git shares: ${command}`);
+                    problems.push(`${name} hook in ${file} names a path on this machine and git shares that file — anyone who clones it gets a hook that cannot start, and their agent runs unchecked. Run \`${cliCommand(`init${harness === "claude" ? "" : ` --${harness}`}`)}\` to move it, then commit the change`);
+                }
+            }
+        }
+        if (harness === "codex")
+            console.log(`    run /hooks in Codex and approve Scopebond once`);
+    }
+    if (!anyHarness)
+        problems.push(`no coding agent is configured — run \`${cliCommand("init")}\` in your project root`);
     const connection = loadConnection(active);
     if (!connection) {
         console.log(`  cloud            not connected (local only) — receipts stay on this machine`);
@@ -484,20 +1014,29 @@ async function runDoctor() {
 function runUninstall(args) {
     requireInteractive("uninstall", args);
     let removed = 0;
+    // Both scopes. Checking only the user config meant that after a per-project `init` —
+    // the install the site actually tells people to run — `uninstall` reported "no
+    // user-level harness config found" and left the project hook in place.
     for (const h of ["claude", "cursor", "codex"]) {
-        if (removeHarnessConfig(userHarnessFile(h))) {
-            console.log(`✓ removed the Scopebond hook from ${userHarnessFile(h)}`);
-            removed++;
+        for (const file of [projectHarnessFile(h, process.cwd()), localHarnessFile(h, process.cwd()), userHarnessFile(h)]) {
+            if (file && removeHarnessConfig(file)) {
+                console.log(`✓ removed the Scopebond hook from ${file}`);
+                removed++;
+            }
         }
     }
     if (removed === 0)
-        console.log("no user-level harness config found.");
+        console.log("no Scopebond hook found in this project or your user config.");
     if (args.includes("--purge")) {
         purgeHome();
         console.log(`✓ purged ${userHome()} (keys, policy, receipts)`);
     }
     else
         console.log(`Kept ${userHome()} (keys, policy, receipts). Use --purge to remove it too.`);
+    const projectDir = resolveConfigDir(process.cwd());
+    if (existsSync(join(projectDir, "policy.json"))) {
+        console.log(`Kept ${projectDir} (this project's keys, policy and receipts) — delete it by hand if you want it gone.`);
+    }
 }
 /** `trust` — let this project's .scopebond policy govern here instead of the user
  *  home, pinned to its current contents. Run by the user, not the agent: the file it
@@ -513,11 +1052,195 @@ function runTrust(args) {
     console.log(`✓ trusted ${join(dir, "policy.json")} (sha256 ${digest.slice(0, 12)}…)`);
     console.log("It governs agents in this project until it changes; after any edit, review it and run trust again.");
 }
-function runLogin() {
-    console.log("Device-code login is not available yet.");
-    console.log(`For now, connect with a one-time enrollment from your workspace:`);
-    console.log(`  ${cliCommand("connect <workspace-url> <enrollment>")}`);
-    process.exit(0);
+/** `login <workspace-url>` — connect this computer without pasting anything. It asks
+ *  the workspace for a short code, shows it with the page to open, and waits while a
+ *  person who can manage the workspace approves it there for an environment and agent.
+ *  The approval hands back a single-use enrollment, which completes exactly as
+ *  `connect` does. Nothing secret is printed: the device code stays in memory. */
+async function runLogin(args) {
+    const positional = args.filter((a) => !a.startsWith("--"));
+    const harness = selectedHarness(args);
+    let origin;
+    try {
+        const parsed = new URL(positional[0] ?? "");
+        const local = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
+        if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:"))
+            throw new Error("https required");
+        origin = parsed.origin;
+    }
+    catch {
+        console.error(`usage: ${cliCommand("login <workspace-url> [--claude|--cursor|--codex] [--no-install]")}`);
+        console.error("The workspace URL is the address of your Scopebond workspace, for example https://cloud.scopebond.com.");
+        process.exit(1);
+    }
+    const post = async (path, body) => {
+        const response = await fetch(new URL(path, origin), {
+            method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+            redirect: "error", signal: AbortSignal.timeout(15_000),
+        });
+        return { status: response.status, json: await response.json().catch(() => ({})) };
+    };
+    let start;
+    try {
+        start = await post("/v1/device/code", { client_name: hostname(), harness });
+    }
+    catch (error) {
+        console.error(`could not reach ${origin}: ${error.message}`);
+        process.exit(1);
+    }
+    const deviceCode = typeof start.json.device_code === "string" ? start.json.device_code : "";
+    if (start.status !== 200 || !deviceCode) {
+        console.error(`${origin} did not start a login (HTTP ${start.status}). Check the workspace URL, or use ${cliCommand("connect <workspace-url> <enrollment>")}.`);
+        process.exit(1);
+    }
+    const userCode = String(start.json.user_code ?? "");
+    const verify = String(start.json.verification_uri_complete ?? start.json.verification_uri ?? origin);
+    let intervalMs = Math.max(1, Number(start.json.interval ?? 5)) * 1000;
+    const deadline = Date.now() + Math.max(60, Number(start.json.expires_in ?? 600)) * 1000;
+    console.log(`To connect this computer, open:\n\n  ${verify}\n\nand check that it shows the code  ${userCode}\n`);
+    console.log("Waiting for approval (the code expires in 10 minutes; Ctrl+C to stop)…");
+    const dir = configDir();
+    scaffold(dir, {});
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        let polled;
+        try {
+            polled = await post("/v1/device/token", { device_code: deviceCode });
+        }
+        catch {
+            continue;
+        } // a transient network error: keep waiting until the deadline
+        if (polled.status === 200 && polled.json.enrollment && typeof polled.json.enrollment === "object") {
+            console.log("✓ Approved");
+            await finishConnect(dir, origin, polled.json.enrollment, harness, args);
+            return;
+        }
+        const error = polled.json.error;
+        if (error === "authorization_pending")
+            continue;
+        if (error === "slow_down") {
+            intervalMs += 5_000;
+            continue;
+        }
+        if (error === "access_denied") {
+            console.error("The request was denied in the workspace. Nothing was connected.");
+            process.exit(1);
+        }
+        if (error === "expired_token")
+            break;
+        console.error(`login failed (${String(error ?? `HTTP ${polled.status}`)}). Run the command again for a new code.`);
+        process.exit(1);
+    }
+    console.error("The code expired before it was approved. Run the command again for a new one.");
+    process.exit(1);
+}
+/** What each command does, its arguments, and one example. The whole help used to be a
+ *  single usage line listing 15 command names, which told a reader nothing about what any
+ *  of them did or what arguments they take. */
+const COMMANDS = [
+    { name: "init", args: "[--cursor|--codex] [--shared] [--dry-run] [--no-install] [--npx] [--force] [--yes]",
+        summary: "set this project up: keys, a starter policy, and your agent wired to the hook",
+        detail: [
+            "Writes .scopebond/ (machine key, countersigning key, starter policy, .gitignore) and",
+            "wires your agent to the hook. It pins a durable copy of this package so the hook starts",
+            "fast, and because that command names paths on this machine it goes where git will not",
+            "share it: .claude/settings.local.json (kept out of git for this clone), or for Cursor",
+            "and Codex their project file only while git does not track it. --shared writes the",
+            "portable npx command to .claude/settings.json, .cursor/hooks.json or .codex/hooks.json",
+            "instead, so everyone who clones the project gets the hook. --dry-run shows what it",
+            "would write. --no-install prints the config snippet rather than writing it.",
+            "Needs a terminal, or --yes in a script, because it changes what governs your agent.",
+        ] },
+    { name: "install", args: "[--claude] [--cursor] [--codex] [--dry-run] [--force] [--yes]",
+        summary: "set up once for this user, so every project you open is governed",
+        detail: [
+            "Scaffolds ~/.scopebond and registers the hook in your user-level agent config.",
+            "--dry-run prints exactly which files it would touch and changes nothing. Each config",
+            "is copied to <file>.scopebond-backup before its first modification.",
+        ] },
+    { name: "rules", args: "[show|allow|block|protect|unprotect|protect-branch|unprotect-branch|apply] [value]",
+        summary: "read and change the limits in plain terms",
+        detail: [
+            "With no arguments, prints what is blocked in plain English — no regular expressions.",
+            "The editable lists are .scopebond/rules.json; policy.json is compiled from them, so",
+            "you never hand-write a lookahead.",
+            "  rules allow dd                stop blocking a program",
+            "  rules protect infra/          never write there",
+            "  rules protect-branch production",
+            "  rules apply                   recompile after editing rules.json by hand",
+        ] },
+    { name: "status", summary: "what is configured, where, and how big the local log is" },
+    { name: "doctor", summary: "check the setup and whether each configured hook command can start",
+        detail: ["Exits non-zero when something is wrong, so it works in a script."] },
+    { name: "log", args: "[-n N] [--deny] [--since 7d]",
+        summary: "the recent decisions",
+        detail: [`--deny shows only blocked actions; --since takes 7d, 24h, 30m or a date.`, `e.g. ${cliCommand("log --deny --since 7d")}`] },
+    { name: "verify", summary: "check every local receipt offline against the countersigning key",
+        detail: ["No network, no account. Exits non-zero if any receipt fails."] },
+    { name: "test", args: '"<shell command>"',
+        summary: "show the decision for a command without running or recording it",
+        detail: [`e.g. ${cliCommand('test "rm -rf /"')}`] },
+    { name: "prune", args: "[--before 90d] [--yes]",
+        summary: "report the local store's size, or bound it",
+        detail: [
+            "With no --before it only reports. With one, it archives the receipts it will remove",
+            "to a JSONL file beside the database, then removes them. Refuses once the log has been",
+            "anchored, because a receipt's position is its anchor leaf index.",
+        ] },
+    { name: "login", args: "<workspace-url> [--claude|--cursor|--codex] [--no-install]",
+        summary: "connect this computer to a Scopebond Cloud workspace by approving a short code there",
+        detail: [
+            "Prints a code and a link; someone who manages the workspace opens it, checks the code",
+            "and approves it for an environment and agent. Nothing is copied or pasted.",
+        ] },
+    { name: "connect", args: "<workspace-url> <enrollment> [--claude|--cursor|--codex]",
+        summary: "send receipts to a Scopebond Cloud workspace as well as keeping them locally" },
+    { name: "flush", summary: "deliver any receipts still queued for the workspace now" },
+    { name: "trust", args: "[--yes]", summary: "let this project's .scopebond policy govern here (pinned by hash)" },
+    { name: "uninstall", args: "[--purge] [--yes]", summary: "remove the hook from your agent config; --purge also deletes the home" },
+    { name: "claude", summary: "(internal) decide one Claude Code PreToolUse call, JSON on stdin" },
+    { name: "cursor", summary: "(internal) decide one Cursor hook event, JSON on stdin" },
+    { name: "codex", summary: "(internal) decide one Codex PreToolUse call, JSON on stdin" },
+];
+function printHelp(topic, toStderr = false) {
+    const out = toStderr ? console.error : console.log;
+    const match = topic ? COMMANDS.find((c) => c.name === topic.replace(/^--?/, "")) : undefined;
+    if (match) {
+        out(`scopebond-hook ${match.name}${match.args ? ` ${match.args}` : ""}`);
+        out("");
+        out(`  ${match.summary}`);
+        if (match.detail) {
+            out("");
+            for (const line of match.detail)
+                out(`  ${line}`);
+        }
+        return;
+    }
+    if (topic) {
+        out(`no such command: ${topic}`);
+        out("");
+    }
+    out(`scopebond-hook — govern a coding agent's tool calls against policy, before they run.`);
+    out("");
+    out(`Usage: scopebond-hook <command> [options]`);
+    out("");
+    out(`  ${cliCommand("init")}            set up this project`);
+    out(`  ${cliCommand('test "rm -rf /"')}  see a decision without running it`);
+    out(`  ${cliCommand("log --deny")}      what got blocked`);
+    out(`  ${cliCommand("rules")}           what is blocked, in plain English`);
+    out("");
+    out("Commands:");
+    const width = Math.max(...COMMANDS.map((c) => c.name.length));
+    for (const command of COMMANDS) {
+        if (command.summary.startsWith("(internal)"))
+            continue;
+        out(`  ${command.name.padEnd(width)}  ${command.summary}`);
+    }
+    out("");
+    out(`  ${"help".padEnd(width)}  \`help <command>\` for that command's arguments and examples`);
+    out("");
+    out(`Receipts and keys stay in .scopebond/ in this project. Nothing leaves your machine`);
+    out(`unless you run \`connect\`. Docs: https://github.com/avouro-com/scopebond`);
 }
 const [cmd, ...rest] = process.argv.slice(2);
 if (cmd === "claude") {
@@ -560,13 +1283,23 @@ else if (cmd === "uninstall") {
     runUninstall(rest);
 }
 else if (cmd === "login") {
-    runLogin();
+    await runLogin(rest);
 }
 else if (cmd === "trust") {
     runTrust(rest);
 }
+else if (cmd === "prune") {
+    await runPrune(rest);
+}
+else if (cmd === "rules") {
+    runRules(rest);
+}
+else if (cmd === "help" || cmd === "--help" || cmd === "-h" || cmd === undefined) {
+    printHelp(rest[0]);
+}
 else {
-    console.error("usage: scopebond <claude|cursor|codex|init|install|connect|log|verify|test|flush|status|doctor|uninstall|login|trust> [--cursor] [--claude] [--codex] [--force] [--strict] [--no-install] [--purge] [--yes]");
+    console.error(`unknown command: ${cmd}`);
+    printHelp(undefined, true);
     process.exit(1);
 }
 //# sourceMappingURL=cli.js.map