@scopebond/hook 0.8.0 → 0.9.0

package/dist/cli.js

@@ -24,22 +24,33 @@
     });
 }
 import { readFileSync, writeFileSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 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 { callRequestOf, keyedIdFor, TYPED_ACTION_TYPES } from "./typed-ops.js";
+import { databaseGuardActions } from "./typed-infra.js";
 import { mapClaudeToolUse, mapCodexToolUse, mapCursorEvent, fillPushBranch } from "./map.js";
 import { createHookRuntime } from "./runtime.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 { userHome, userHarnessFile, resolveConfigDir, writeHarnessConfig, removeHarnessConfig, cursorDetected, codexDetected, absoluteHookCommand, isHarnessConfigured, purgeHome, harnessScopes, harnessScopeLabel, configuredHookCommands, hookCommandResolves, projectHarnessFile, localHarnessFile, gitShareState, isMachineSpecificCommand, trustProjectPolicy, untrustedProjectPolicy, wireLifecycleHooks, unwireLifecycleHooks, } from "./install.js";
+import { openObservations, describeObservations, observationStatus, stopReasonFromClaude, exitFromClaudeFailure, HEARTBEAT_INTERVAL_MS, OBSERVATIONS_SCOPE, } from "./obs-emitter.js";
+import { OBSERVATION_DB, ObservationStore } from "./obs-store.js";
+import { loadOrCreateBindingKey } from "./observation.js";
+import { uploadPending } from "./obs-upload.js";
 import { connectCloud, loadConnection } from "./cloud.js";
+import { loadPolicyExport } from "./policy-load.js";
+import { loadBudgetExport } from "./budget-load.js";
 import { compile, defaultRules, describeRules, loadRules, saveRules, rulesPath, pathRuleFor } from "./rules.js";
 import { createSigner } from "@scopebond/sdk";
+import { runDispatchCommand } from "./dispatch-cli.js";
 import { describeAction } from "./explain.js";
 import { ensureDurableRuntime, pinnedCliPath, isEphemeralPath } from "./runtime-install.js";
 import { cliCommand, hookCommand, hookVersion } from "./version.js";
+import { computeManifest, renderManifest } from "./capabilities.js";
+import { runProofFixtures, loadProofs, saveProofs, proofPassed, deliverProofReceipts } from "./proof.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
@@ -77,13 +88,14 @@ function readBundleArg(bundleArg, stdin) {
 function configDir() {
     return process.env.SCOPEBOND_HOOK_DIR ?? join(process.cwd(), ".scopebond");
 }
-function runtimePaths(dir) {
+function runtimePaths(dir, cwd) {
     const connection = loadConnection(dir);
     return {
         policyPath: join(dir, "policy.json"),
         keyPath: join(dir, "agent.key"),
         attesterPath: join(dir, "attester.key"),
         dbPath: join(dir, "receipts.db"),
+        ...(cwd ? { cwd } : {}),
         // Strict: deny (not just observe) tools with no taxonomy mapping.
         strict: process.argv.includes("--strict") || process.env.SCOPEBOND_HOOK_STRICT === "1",
         // When connected, auto-export receipts. A short bounded flush keeps the hot path
@@ -92,6 +104,16 @@ function runtimePaths(dir) {
         ...(connection ? { cloud: { connection, flushTimeoutMs: Number(process.env.SCOPEBOND_HOOK_FLUSH_MS ?? 800) } } : {}),
     };
 }
+/** The harness's own id for this tool call, when it gives one (Claude Code and Codex send
+ *  `tool_use_id`), so the receipts of one call share a stable action group. */
+function callId(input) {
+    for (const key of ["tool_use_id", "tool_call_id", "call_id"]) {
+        const value = input?.[key];
+        if (typeof value === "string" && value !== "")
+            return value;
+    }
+    return undefined;
+}
 function readStdin() {
     try {
         return readFileSync(0, "utf8");
@@ -134,10 +156,53 @@ const cursorCoverageNote = [
     "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) {
+/** Record what was dispatched as observations, when this workspace enrolled for them. Purely
+ *  additive: it runs after the decision is made and can neither change it nor fail it. */
+function recordObservations(dir, cwd, input, decision, harness) {
+    try {
+        const { emitter } = openObservations(dir, { adapterVersion: hookVersion() });
+        if (!emitter)
+            return undefined;
+        const sessionId = typeof input.session_id === "string" && input.session_id !== "" ? input.session_id : undefined;
+        // Session lifecycle is Claude Code only: its SessionStart/SessionEnd hooks are the ones
+        // the tested mapping covers. Other hosts still get tool intents from their PreToolUse.
+        if (harness === "claude" && sessionId)
+            emitter.activity(sessionId, cwd);
+        emitter.toolIntents({ harnessSessionId: sessionId, callId: callId(input), cwd, dispatched: decision.dispatched ?? [], request: callRequestOf(input) });
+        return emitter;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The remote-database actions of a shell call, only when the rule set opts in (`protect_remote_database`).
+ *  They are extra evaluated intents read from the raw command, so the deny happens before it runs. */
+function databaseGuard(dir, cwd, input) {
+    let enabled = false;
+    try {
+        enabled = loadRules(dir)?.protect_remote_database === true;
+    }
+    catch {
+        return [];
+    }
+    if (!enabled)
+        return [];
+    const request = callRequestOf(input);
+    if (request?.command === undefined)
+        return [];
+    const intent = (params) => ({ intent: { action_type: "db.exec", params }, evaluated: true, source: "shell" });
+    try {
+        return databaseGuardActions(request.command, request.dialect ?? "posix", { cwd }).map((action) => intent({ ...action }));
+    }
+    catch {
+        // The rule is on and the reader failed: a command that names a database tool is not waved through.
+        return /(?:wrangler|psql)/i.test(request.command) ? [intent({ provider: "unknown", verb: "unknown", scope: "unknown", risk: "unknown" })] : [];
+    }
+}
+async function runPreToolUse(mapper, deny = denyClaude, raw, harness = "claude") {
     let input;
     try {
-        input = JSON.parse(readStdin());
+        input = JSON.parse(raw ?? readStdin());
     }
     catch {
         deny("hook received invalid JSON on stdin");
@@ -146,10 +211,12 @@ async function runPreToolUse(mapper, deny = denyClaude) {
     try {
         const cwd = input?.cwd ? String(input.cwd) : process.cwd();
         const dir = resolveConfigDir(cwd);
-        runtime = createHookRuntime(runtimePaths(dir));
+        runtime = createHookRuntime(runtimePaths(dir, cwd));
         useDigestKey(loadOrCreateDigestKey(dir));
-        const decision = await runtime.evaluate(fillPushBranch(mapper(input), currentBranch(cwd)));
-        await runtime.flush();
+        const decision = await runtime.evaluate([...fillPushBranch(mapper(input), currentBranch(cwd)), ...databaseGuard(dir, cwd, input)], { groupKey: callId(input) });
+        const observer = recordObservations(dir, cwd, input, decision, harness);
+        await Promise.all([runtime.flush(), observer?.flush() ?? Promise.resolve()]);
+        observer?.close();
         // 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();
@@ -168,11 +235,63 @@ async function runPreToolUse(mapper, deny = denyClaude) {
         deny(`Scopebond hook failed closed: ${error.message}. Repair: run \`${cliCommand("init")}\`.`);
     }
 }
+/** Claude Code events other than PreToolUse: session start and end, and the after-action
+ *  events. They only feed observations; they never print a decision and always exit 0. */
+async function runClaudeLifecycle(input) {
+    try {
+        const cwd = input.cwd ? String(input.cwd) : process.cwd();
+        const { emitter } = openObservations(resolveConfigDir(cwd), { adapterVersion: hookVersion() });
+        const sessionId = typeof input.session_id === "string" && input.session_id !== "" ? input.session_id : undefined;
+        if (emitter) {
+            try {
+                switch (input.hook_event_name) {
+                    case "SessionStart":
+                        if (sessionId)
+                            emitter.sessionStart(sessionId, cwd);
+                        break;
+                    case "SessionEnd":
+                        if (sessionId)
+                            emitter.sessionStop(sessionId, stopReasonFromClaude(input.reason));
+                        break;
+                    case "PostToolUse": {
+                        const id = callId(input);
+                        if (id)
+                            emitter.toolOutcomes(sessionId, id, "ok");
+                        break;
+                    }
+                    case "PostToolUseFailure": {
+                        const id = callId(input);
+                        if (id)
+                            emitter.toolOutcomes(sessionId, id, exitFromClaudeFailure(input.is_interrupt));
+                        break;
+                    }
+                }
+                await emitter.flush(input.hook_event_name === "SessionEnd" ? 1500 : 800);
+            }
+            finally {
+                emitter.close();
+            }
+        }
+    }
+    catch { /* observations are best effort; nothing here may affect the agent */ }
+    process.exit(0);
+}
+const CLAUDE_OBSERVATION_EVENTS = new Set(["SessionStart", "SessionEnd", "PostToolUse", "PostToolUseFailure"]);
 async function runClaude() {
-    await runPreToolUse(mapClaudeToolUse);
+    const raw = readStdin();
+    let event;
+    let input;
+    try {
+        input = JSON.parse(raw);
+        event = input?.hook_event_name;
+    }
+    catch { /* PreToolUse reports invalid input */ }
+    if (input && typeof event === "string" && CLAUDE_OBSERVATION_EVENTS.has(event))
+        await runClaudeLifecycle(input);
+    await runPreToolUse(mapClaudeToolUse, denyClaude, raw, "claude");
 }
 async function runCodex() {
-    await runPreToolUse(mapCodexToolUse, denyCodex);
+    await runPreToolUse(mapCodexToolUse, denyCodex, undefined, "codex");
 }
 function denyCursor(reason) {
     process.stdout.write(JSON.stringify({ permission: "deny", agentMessage: reason }) + "\n");
@@ -202,11 +321,13 @@ async function runCursor() {
     try {
         const cwd = input?.cwd ? String(input.cwd) : process.cwd();
         const dir = resolveConfigDir(cwd);
-        runtime = createHookRuntime(runtimePaths(dir));
+        runtime = createHookRuntime(runtimePaths(dir, cwd));
         useDigestKey(loadOrCreateDigestKey(dir));
         const mapped = fillPushBranch(mapCursorEvent(event, input), currentBranch(cwd));
-        const decision = await runtime.evaluate(mapped);
-        await runtime.flush();
+        const decision = await runtime.evaluate(mapped, { groupKey: callId(input) });
+        const observer = recordObservations(dir, cwd, input, decision, "cursor");
+        await Promise.all([runtime.flush(), observer?.flush() ?? Promise.resolve()]);
+        observer?.close();
         // 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);
@@ -458,6 +579,7 @@ function runRules(args) {
         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(`  ${cliCommand("rules protect-remote-database")}  block destructive or unreadable SQL on a remote database (off by default)`);
         console.log(`Or edit ${rulesPath(dir)} directly, then \`${cliCommand("rules apply")}\`.`);
         process.exit(0);
     }
@@ -531,6 +653,22 @@ function runRules(args) {
             changed = `pushes to ${value} are allowed again`;
             break;
         }
+        case "protect-remote-database":
+            if (rules.protect_remote_database === true) {
+                console.log("Remote databases are already protected.");
+                process.exit(0);
+            }
+            rules.protect_remote_database = true;
+            changed = "remote SQL that drops, deletes or updates every row, or cannot be read, is now blocked";
+            break;
+        case "unprotect-remote-database":
+            if (rules.protect_remote_database !== true) {
+                console.log("Remote databases were not protected; nothing to change.");
+                process.exit(0);
+            }
+            delete rules.protect_remote_database;
+            changed = "remote SQL is no longer checked";
+            break;
         case "apply":
             changed = `recompiled from ${rulesPath(dir)}`;
             break;
@@ -751,6 +889,14 @@ async function finishConnect(dir, url, bundle, harness, args) {
     try {
         const c = await connectCloud(dir, url, bundle);
         console.log(`✓ Connected to ${c.url}`);
+        // With a user-level install present, the hook ignores a project policy until it is
+        // trusted, and would fall back to the user home, which holds no cloud.json: the agent
+        // stays governed, but nothing reaches the workspace. Connecting this project is the
+        // user's decision to use it, exactly as running `init` here is, so pin it the same way.
+        if (!process.env.SCOPEBOND_HOOK_DIR && resolve(dir) !== resolve(userHome()) && existsSync(join(userHome(), "policy.json"))) {
+            trustProjectPolicy(dir);
+            console.log(`✓ This project's rules are trusted (they override ${userHome()} here)`);
+        }
         // Configure the agent automatically (merges into the existing config), unless the
         // 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:
@@ -770,6 +916,21 @@ async function finishConnect(dir, url, bundle, harness, args) {
             console.log(`Add this to your ${harnessFileName(harness)}:`);
             console.log(harnessSnippet(harness));
         }
+        // Session and after-action observations are opt-in through the enrollment: wired only
+        // when this workspace granted observations:write and Claude Code is the host. Off is
+        // silent here (`status` says why); a granted scope the hook cannot use is worth a line.
+        const observing = observationStatus(loadConnection(dir));
+        if (observing.state === "on" && harness === "claude" && !args.includes("--no-install")) {
+            const placed = harnessScopes("claude", process.cwd());
+            const target = placed.local ?? placed.project ?? placed.user;
+            const command = target ? configuredHookCommands(target)[0] : undefined;
+            if (target && command) {
+                wireLifecycleHooks(target, command);
+                console.log(`✓ Session and after-action observations enabled in ${target}`);
+            }
+        }
+        else if (observing.state === "unsupported")
+            console.log(`Observations: ${observing.reason}`);
         console.log("");
         console.log("Run your agent — the first action appears in your workspace within seconds.");
     }
@@ -804,6 +965,219 @@ async function runFlush() {
     // Let pending HTTP handles close normally (forced exit can abort on Windows).
     process.exitCode = status && status.pending > 0 ? 1 : 0;
 }
+/** `observations`: what the observation emitters are doing, and the local queue. */
+/** `policy load <export.json> [--yes]`: check a policy exported from the workspace and, with
+ *  `--yes`, make it the active policy here; then acknowledge it (or its refusal) to the workspace. */
+async function runPolicy(args) {
+    const [sub, file] = args;
+    if (sub !== "load" || !file) {
+        console.error(`usage: ${cliCommand("policy load <export.json> [--yes]")}`);
+        process.exitCode = 2;
+        return;
+    }
+    const dir = resolveConfigDir(process.cwd());
+    const apply = args.includes("--yes");
+    const connection = loadConnection(dir);
+    const outcome = loadPolicyExport(dir, file, { apply, environmentId: connection?.environment_id });
+    let ack;
+    if (outcome.state === "rejected") {
+        console.error(`refused: ${outcome.message} (${outcome.error})`);
+        if (outcome.ack)
+            ack = { ...outcome.ack, error: outcome.error };
+        process.exitCode = 1;
+    }
+    else if (outcome.state === "would_load") {
+        console.log(`This export checks out (policy ${outcome.facts.policyId} v${outcome.facts.policyVersion}, digest ${outcome.facts.policyDigest.slice(0, 12)}...).`);
+        console.log(`Loading it REPLACES the active policy at ${join(dir, "policy.json")} (the old one is kept as policy.previous.json), so the starter protections apply only if the export includes them.`);
+        console.log("Run again with --yes to load it.");
+        return;
+    }
+    else {
+        console.log(`loaded policy ${outcome.facts.policyId} v${outcome.facts.policyVersion} (digest ${outcome.facts.policyDigest.slice(0, 12)}...) from export ${outcome.facts.exportId}`);
+        console.log(`  active policy   ${outcome.policyPath}${outcome.previous ? `  (previous kept at ${outcome.previous})` : ""}`);
+        console.log(`  note            \`${cliCommand("rules apply")}\` recompiles policy.json from rules.json and would replace it`);
+        ack = { exportId: outcome.facts.exportId, policyId: outcome.facts.policyId, policyVersion: outcome.facts.policyVersion, policyDigest: outcome.facts.policyDigest, scopeDigest: outcome.facts.scopeDigest };
+    }
+    if (!ack)
+        return;
+    await sendPolicyAck(dir, ack);
+}
+/** Queue a `policy_ack` (loaded or rejected) through the observation outbox and try to deliver it now. */
+async function sendPolicyAck(dir, ack) {
+    const observed = openObservations(dir, { adapterVersion: hookVersion(), spawnHeartbeat: false });
+    if (!observed.emitter) {
+        console.error(`not acknowledged to the workspace: observations are ${observed.status.state}${"reason" in observed.status ? ` (${observed.status.reason})` : ""}`);
+        return;
+    }
+    try {
+        const queued = observed.emitter.policyAck(ack);
+        await observed.emitter.flush(3000);
+        console.error(queued?.queued ? `queued the ${ack.error ? "rejection" : "load"} acknowledgement for the workspace` : "could not queue the acknowledgement");
+    }
+    finally {
+        observed.emitter.close();
+    }
+}
+/** `budget load <export.json> [--yes]`: check an action budget exported from the workspace and, with `--yes`,
+ *  make it the budget this machine enforces; then acknowledge it (or its refusal) to the workspace. */
+async function runBudgetLoad(args) {
+    const file = args.find((a) => !a.startsWith("--"));
+    if (!file) {
+        console.error(`usage: ${cliCommand("budget load <export.json> [--yes]")}`);
+        process.exitCode = 2;
+        return;
+    }
+    const dir = resolveConfigDir(process.cwd());
+    const agentKid = (() => { try {
+        return createSigner({ privateKeyPem: readFileSync(join(dir, "agent.key"), "utf8") }).kid;
+    }
+    catch {
+        return "";
+    } })();
+    const outcome = loadBudgetExport(dir, file, { apply: args.includes("--yes"), agentKid, environmentId: loadConnection(dir)?.environment_id });
+    let ack;
+    if (outcome.state === "rejected") {
+        console.error(`refused: ${outcome.message} (${outcome.error})`);
+        if (outcome.ack && outcome.error !== "expired")
+            ack = { ...outcome.ack, error: outcome.error };
+        process.exitCode = 1;
+    }
+    else if (outcome.state === "would_load") {
+        const p = outcome.facts.policy;
+        for (const w of outcome.warnings)
+            console.error(`warning: ${w}`);
+        console.log(`This export checks out: ${p.mode} budget ${outcome.facts.budgetId} v${outcome.facts.budgetVersion}, ${p.max_dispatch} dispatches in ${p.window_seconds}s for this agent on this installation.`);
+        console.log(`Loading it writes the budget to ${join(dir, "dispatch.json")} as acknowledged, and replaces an older workspace budget for this agent. Run again with --yes to load it.`);
+        return;
+    }
+    else {
+        const p = outcome.facts.policy;
+        for (const w of outcome.warnings)
+            console.error(`warning: ${w}`);
+        console.log(`loaded ${p.mode} budget ${outcome.facts.budgetId} v${outcome.facts.budgetVersion} from export ${outcome.facts.exportId}: ${p.max_dispatch} dispatches in ${p.window_seconds}s`);
+        if (outcome.replaced.length > 0)
+            console.log(`  replaced        ${outcome.replaced.join(", ")}`);
+        console.log(`  valid until     ${new Date(outcome.facts.validUntil).toISOString()} (after that an enforced budget denies new dispatch until you load a new export)`);
+        ack = { exportId: outcome.facts.exportId, policyId: outcome.facts.budgetId, policyVersion: outcome.facts.budgetVersion, policyDigest: outcome.facts.policyDigest, scopeDigest: outcome.facts.scopeDigest };
+    }
+    if (!ack)
+        return;
+    await sendPolicyAck(dir, ack);
+}
+async function runObservations(args) {
+    const sub = args[0] ?? "status";
+    const dir = resolveConfigDir(process.cwd());
+    if (sub === "heartbeat") {
+        await runHeartbeatLoop(args[1] ?? "");
+        return;
+    }
+    if (sub === "status") {
+        const lines = describeObservations(dir);
+        console.log(`observations: ${lines[0]}`);
+        for (const line of lines.slice(1))
+            console.log(`  ${line}`);
+        const file = join(dir, OBSERVATION_DB);
+        if (args.includes("--refused") && existsSync(file)) {
+            const store = new ObservationStore(file);
+            try {
+                for (const row of store.terminal())
+                    console.log(`  refused  #${row.sequence} gen ${row.generation} ${row.kind} ${row.observation_id} ${row.code} ${new Date(row.at).toISOString()}`);
+            }
+            finally {
+                store.close();
+            }
+        }
+        return;
+    }
+    if (sub === "id") {
+        // The opaque id this installation gives a ref, remote or repository, for writing reference
+        // sets. Local only: it reads the binding key and prints; nothing is sent anywhere.
+        const id = keyedIdFor(loadOrCreateBindingKey(dir), args[1] ?? "", args.slice(2));
+        if (!id) {
+            console.error("usage: observations id <ref <name> | remote <url> | ghrepo <owner/name> | repo <workspace-path> | mcp <server> <tool> | mcp-resource <kind> <value> | net-dest <host> <port> | cf <kind> <name> | database <pg|sqlite> <key>>");
+            process.exit(1);
+        }
+        console.log(id);
+        return;
+    }
+    if (sub === "wire" || sub === "unwire") {
+        const scopes = harnessScopes("claude", process.cwd());
+        if (sub === "unwire") {
+            let removed = 0;
+            for (const file of [scopes.project, scopes.local, scopes.user])
+                if (file)
+                    removed += unwireLifecycleHooks(file);
+            console.log(`removed ${removed} lifecycle hook entr${removed === 1 ? "y" : "ies"}`);
+            return;
+        }
+        const target = scopes.local ?? scopes.project ?? scopes.user;
+        const command = target ? configuredHookCommands(target)[0] : undefined;
+        if (!target || !command) {
+            console.error("Claude Code is not configured with this hook; run install or init first");
+            process.exit(1);
+        }
+        wireLifecycleHooks(target, command);
+        console.log(`session and after-action hooks wired in ${target}`);
+        return;
+    }
+    const opened = openObservations(dir, { adapterVersion: hookVersion(), spawnHeartbeat: false });
+    if (!opened.emitter) {
+        console.error(`observations are ${opened.status.state}${"reason" in opened.status ? `: ${opened.status.reason}` : ""}`);
+        process.exit(1);
+    }
+    const emitter = opened.emitter;
+    try {
+        if (sub === "flush") {
+            const outcome = await uploadPending(emitter.store, { url: emitter.connection.url, credential: emitter.connection.credential, timeoutMs: 10_000 });
+            const left = emitter.store.pendingSummary().count;
+            console.log(`${outcome.result}: ${outcome.acknowledged} acknowledged, ${outcome.deferred} deferred, ${outcome.rejected} refused; ${left} still pending${outcome.detail ? ` (${outcome.detail})` : ""}`);
+            process.exitCode = left > 0 ? 1 : 0;
+        }
+        else if (sub === "retry") {
+            const state = emitter.store.state();
+            if (state?.capability === "unsupported") {
+                emitter.store.setCapability("active", null);
+                console.log("will try the workspace again");
+            }
+            else
+                console.log("nothing to retry (a stale generation clears when you reconnect)");
+        }
+        else {
+            console.error("usage: observations [status [--refused]|flush|retry|wire|unwire]");
+            process.exit(1);
+        }
+    }
+    finally {
+        emitter.close();
+    }
+}
+/** The single heartbeat helper for one active session (started by the hook, never by hand). */
+async function runHeartbeatLoop(sessionId) {
+    if (!sessionId)
+        return;
+    const dir = resolveConfigDir(process.cwd());
+    const { emitter } = openObservations(dir, { adapterVersion: hookVersion(), spawnHeartbeat: false, flushTimeoutMs: 3000 });
+    if (!emitter)
+        return;
+    const override = Number(process.env.SCOPEBOND_HEARTBEAT_INTERVAL_MS);
+    const interval = Number.isFinite(override) && override >= 100 ? override : HEARTBEAT_INTERVAL_MS;
+    const endsAt = Date.now() + 24 * 60 * 60 * 1000;
+    let last = Date.now();
+    try {
+        for (;;) {
+            const verdict = emitter.heartbeatTick(sessionId, last);
+            await emitter.flush();
+            if (verdict === "stop" || Date.now() > endsAt)
+                break;
+            last = Date.now();
+            await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+    }
+    finally {
+        emitter.store.releaseHeartbeat(sessionId);
+        emitter.close();
+    }
+}
 /** The absolute path to this CLI file, for registering the hook by absolute path. */
 function cliPath() {
     return fileURLToPath(import.meta.url);
@@ -925,6 +1299,10 @@ function runStatus() {
     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)"}`);
+    const observationLines = describeObservations(resolveConfigDir(process.cwd()));
+    console.log(`  observations     ${observationLines[0]}`);
+    for (const line of observationLines.slice(1))
+        console.log(`                   ${line}`);
     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])
@@ -932,10 +1310,78 @@ function runStatus() {
                 console.log(`    ${name}: ${file}`);
     }
 }
+/** `capabilities`: the manifest of what this hook can honestly claim, cell by cell.
+ *  `--prove` runs the safe fixtures in temp directories (never touching agent settings);
+ *  `--save` records the result beside the policy; `--json` prints the manifest. */
+async function runCapabilities(args) {
+    const cwd = process.cwd();
+    const dir = resolveConfigDir(cwd);
+    const configured = {
+        claude: !!harnessScopeLabel(harnessScopes("claude", cwd)),
+        cursor: !!harnessScopeLabel(harnessScopes("cursor", cwd)),
+        codex: !!harnessScopeLabel(harnessScopes("codex", cwd)),
+    };
+    const version = hookVersion();
+    let proofs = loadProofs(dir);
+    let failed = false;
+    if (args.includes("--prove")) {
+        // When the workspace accepts observations, the fixtures are signed with this machine's
+        // own keys (copied into the temp home) and their receipts are delivered first, so the
+        // proof can name them and the workspace can resolve them. Otherwise a fixture stays local.
+        const observed = openObservations(dir, { adapterVersion: version, spawnHeartbeat: false });
+        const collected = [];
+        const fresh = await runProofFixtures(version, observed.emitter ? { identityDir: dir, collect: collected } : {});
+        const proven = computeManifest({ adapterVersion: version, configured: { claude: true, codex: true, cursor: true }, proofs: fresh });
+        for (const cell of proven.cells) {
+            const proof = fresh[cell.key];
+            if (proof && !proofPassed(proof, cell)) {
+                failed = true;
+                console.error(`fixture failed: ${cell.key} (allow ${proof.safe_allow}, deny ${proof.safe_deny}, signature ${proof.signature}, grouping ${proof.grouping})`);
+            }
+        }
+        if (observed.emitter) {
+            try {
+                const delivered = await deliverProofReceipts(observed.emitter.connection, collected);
+                if (!delivered)
+                    console.error("could not deliver the fixture receipts to the workspace; the capability proofs were not sent (run it again when it is reachable)");
+                else {
+                    const queued = observed.emitter.capabilityProofs(proven.cells.flatMap((cell) => {
+                        // A typed-operation cell has no receipt of its own action type for a proof to name, so no proof is sent for it.
+                        if (TYPED_ACTION_TYPES.has(cell.action_type))
+                            return [];
+                        const proof = cell.state === "unsupported" ? undefined : fresh[cell.key];
+                        return proof ? [{ adapterVersion: cell.adapter_version, hostVariant: cell.host_variant, actionType: cell.action_type, phase: cell.event_phase, requiredFields: cell.emitted_required_fields, fixtureVersion: `fixture/${proof.test_vector_digest}`, passed: proofPassed(proof, cell), proofDigests: proof.proof_digests }] : [];
+                    }));
+                    await observed.emitter.flush(3000);
+                    console.error(`queued ${queued} capability proof observation(s) (fixture origin, ${collected.length} fixture receipt(s) delivered)`);
+                }
+            }
+            finally {
+                observed.emitter.close();
+            }
+        }
+        if (args.includes("--save")) {
+            if (!existsSync(dir)) {
+                console.error(`no ${dir} to record into - run \`${cliCommand("init")}\` first.`);
+                process.exit(1);
+            }
+            console.error(`recorded fixture proofs in ${saveProofs(dir, fresh)}`);
+        }
+        proofs = fresh;
+    }
+    const manifest = computeManifest({ adapterVersion: version, configured, proofs });
+    if (args.includes("--json"))
+        console.log(JSON.stringify(manifest, null, 2));
+    else {
+        console.log(renderManifest(manifest));
+        if (args.includes("--prove"))
+            console.log(`\nFixture run ${failed ? "FAILED - see degraded cells" : "passed"}. It used temporary directories only; no agent setting or policy was changed and no key was modified.`);
+    }
+    process.exitCode = failed ? 1 : 0;
+}
 async function runDoctor() {
     const problems = [];
-    const [major, minor] = process.versions.node.split(".").map(Number);
-    const nodeOk = major > 22 || (major === 22 && minor >= 13);
+    const nodeOk = nodeSupported();
     console.log(`Scopebond doctor`);
     console.log(`  node             ${process.versions.node} ${nodeOk ? "ok" : "TOO OLD (need >=22.13)"}`);
     if (!nodeOk)
@@ -1158,7 +1604,7 @@ const COMMANDS = [
             "--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]",
+    { name: "rules", args: "[show|allow|block|protect|unprotect|protect-branch|unprotect-branch|protect-remote-database|unprotect-remote-database|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.",
@@ -1170,6 +1616,52 @@ const COMMANDS = [
             "  rules apply                   recompile after editing rules.json by hand",
         ] },
     { name: "status", summary: "what is configured, where, and how big the local log is" },
+    { name: "capabilities", args: "[--prove [--save]] [--json]",
+        summary: "what this hook can honestly claim, per agent host, action and phase",
+        detail: [
+            "Prints the capability manifest: for Claude Code, Codex and Cursor, each action type and",
+            "phase is unsupported, inactive, configured_unverified, degraded or verified_reporting.",
+            "Unsupported stays unsupported. A cell is never verified from a local run alone.",
+            "--prove runs safe fixtures (allow, deny, signature, action group) in temporary",
+            "directories; it does not read or change any agent settings. --save records the result.",
+        ] },
+    { name: "policy", args: "load <export.json> [--yes]",
+        summary: "check a policy exported from your workspace and make it the active policy here",
+        detail: [
+            "Without --yes it only checks the export (its policy hash and scope digest, and that the",
+            "gateway can load it) and says what loading would replace. With --yes the policy is",
+            "written atomically as policy.json, the old one kept as policy.previous.json. If this",
+            "machine is enrolled for observations, the load (or the refusal) is then acknowledged to",
+            "the workspace, echoing the export's digests exactly. An export carries no signature;",
+            "get the file from your workspace.",
+        ] },
+    { name: "observations", args: "[status [--refused]|flush|retry|wire|unwire|id <kind> <value>]",
+        summary: "session, health and action observations sent to your workspace (opt-in)",
+        detail: [
+            `On only when your workspace enrollment grants ${OBSERVATIONS_SCOPE}; otherwise off, and status says why.`,
+            "Local enforcement never depends on it: uploads are best effort and bounded. status shows",
+            "what is pending and what the workspace refused (kept locally, never retried). flush",
+            "sends now; retry re-checks a workspace that lacked the route; wire and unwire add or",
+            "remove the Claude Code session and after-action hook entries.",
+        ] },
+    { name: "budget", args: "init|ack <id>|status|load <export.json>",
+        summary: "per-agent action budgets: how many actions this agent may dispatch in a window",
+        detail: [
+            "load checks a budget exported from your workspace (digests, environment, validity, fail-closed contract) and, with --yes,",
+            "makes it the acknowledged budget here, then acknowledges it to the workspace so its export stops showing as pending.",
+            "init writes the suggested 100 actions per 60 seconds, monitor-only (nothing is limited).",
+            "Enforcing needs the mode set to enforce and an acknowledgement of the exact policy (ack).",
+            "Counters persist across hook processes and restarts. They count dispatched parent actions on",
+            "THIS installation only; a limit shared across installations needs a shared in-path gateway,",
+            "which an independent hook is not, so it refuses to enforce one.",
+        ] },
+    { name: "delegation", args: "add <file>|list|revoke <id>|import <file>",
+        summary: "delegated child scopes: a child may do no more than its parent and never outlives it",
+        detail: [
+            "A session runs under one with SCOPEBOND_DELEGATION=<id>. Every action is checked against it,",
+            "and against every ancestor, for scope, expiry and revocation. revoke takes effect on the next action.",
+            "import adds revoked ids from a file exported from your workspace (add-only).",
+        ] },
     { 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]",
@@ -1242,7 +1734,20 @@ function printHelp(topic, toStderr = false) {
     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`);
 }
+/** Whether this Node can run the receipt store (`node:sqlite`, 22.13+). */
+function nodeSupported(version = process.versions.node) {
+    const [major, minor] = version.split(".").map(Number);
+    return major > 22 || (major === 22 && minor >= 13);
+}
 const [cmd, ...rest] = process.argv.slice(2);
+// A setup command on an older Node would scaffold and wire the agent, then fail on the
+// first action with an error about a missing module. Stop before changing anything, and
+// say what to do. The hook subcommands are left alone: they already fail closed.
+if (["init", "install", "connect", "login"].includes(cmd ?? "") && !nodeSupported()) {
+    console.error(`Scopebond needs Node.js 22.13 or later; this is Node ${process.versions.node}.`);
+    console.error("Install the current Node.js LTS from https://nodejs.org, open a new terminal, and run the command again.");
+    process.exit(1);
+}
 if (cmd === "claude") {
     await runClaude();
 }
@@ -1279,6 +1784,31 @@ else if (cmd === "status") {
 else if (cmd === "doctor") {
     await runDoctor();
 }
+else if (cmd === "capabilities") {
+    await runCapabilities(rest);
+}
+else if (cmd === "observations") {
+    await runObservations(rest);
+}
+else if (cmd === "policy") {
+    await runPolicy(rest);
+}
+else if (cmd === "budget" && rest[0] === "load") {
+    await runBudgetLoad(rest.slice(1));
+}
+else if (cmd === "budget" || cmd === "delegation") {
+    // These change what the agent may do, so they are for a person at a terminal.
+    if (rest[0] !== "status" && rest[0] !== "list")
+        requireInteractive(cmd, rest);
+    const dir = resolveConfigDir(process.cwd());
+    const kid = (() => { try {
+        return createSigner({ privateKeyPem: readFileSync(join(dir, "agent.key"), "utf8") }).kid;
+    }
+    catch {
+        return "";
+    } })();
+    process.exit(runDispatchCommand(cmd, rest, dir, kid));
+}
 else if (cmd === "uninstall") {
     runUninstall(rest);
 }