@scopebond/hook 0.9.0 → 0.11.0

package/README.md

@@ -216,6 +216,48 @@ locally and retried if the workspace is unreachable. `npx @scopebond/hook flush`
 delivers anything still queued — run it on a session-end hook (and set
 `SCOPEBOND_HOOK_FLUSH_MS=0`) if you want zero per-call latency.
 
+**Reconnecting.** Run `login` again from any folder: unless that folder has its own project
+setup, it repairs the connection the hook actually uses (usually the user-level one) instead
+of creating a second one; pass `--project` to set up the folder you are in. If the workspace
+no longer accepts this computer's countersigning key (the computer was replaced or
+disconnected there), `login` replaces the key and keeps the old one in
+`.scopebond/retired-keys/`.
+
+**Records signed by an earlier key.** The new connection cannot deliver records the earlier
+key signed, so they leave the delivery queue but stay in the local log.
+`npx @scopebond/hook recover` asks the workspace to accept them, waits while an owner or
+admin approves it there, then sends them; the workspace checks each signature against the
+key it kept and labels the records as recovered.
+
+### Rules set by your workspace
+
+A connected computer keeps its own rules (`.scopebond/rules.json`) until someone who manages
+the workspace changes a rule for it there. From then on the workspace decides, rule by rule,
+whether a matching action is **blocked** or only **recorded**, and can add entries to this
+computer's lists (protected branches, programs, allowed sites). The workspace never sends
+patterns: the hook compiles its choices with the same compiler as `rules apply`.
+
+- **When it applies.** At most once every five minutes, a tool call also checks for changes,
+  alongside sending its activity record and capped at about one and a half seconds
+  (`SCOPEBOND_POLICY_SYNC_MS`); every other call only reads two small files. A change therefore
+  applies within a few minutes of the agent's next action, and a workspace that is slow or
+  unreachable never holds up the agent for longer than the cap. The new rules govern from the
+  next action. `npx @scopebond/hook policy sync` checks right now.
+- **What is checked.** A rules document must be complete, issued for this computer, match its
+  digest and be newer than the one in force; the resulting policy must load. Anything else is
+  refused, the rules already in force stay, and the refusal is reported to the workspace.
+- **What is confirmed.** After loading, the hook tells the workspace exactly which version it
+  loaded, so the workspace shows *Applied* only for computers that confirmed it.
+- **What the workspace cannot change.** Protection of Scopebond's own settings and of the
+  agents' hook settings, the machine key policy, fail-closed handling of anything unreadable,
+  and this computer's own opt-ins (`allowed_roots`, `protect_remote_database`).
+- **Going back.** While the workspace sets the rules, `rules` edits and `policy load` are
+  refused here. If the connection is revoked, or the workspace stops setting rules for this
+  computer, the hook recompiles `policy.json` from `rules.json`: a computer is never left
+  without rules. `status` shows which rules are in force and when they were last checked.
+
+Set `SCOPEBOND_POLICY_SYNC=off` to stop the five-minute check (the rules in force stay).
+
 ### Session, health and action observations (opt-in)
 
 Beyond receipts, the hook can send a second kind of signed record, an *observation*,

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAwpBA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAiqBA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}

package/dist/cli.js

@@ -35,13 +35,16 @@ import { mapClaudeToolUse, mapCodexToolUse, mapCursorEvent, fillPushBranch } fro
 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, wireLifecycleHooks, unwireLifecycleHooks, } from "./install.js";
+import { userHome, userHarnessFile, resolveConfigDir, writeHarnessConfig, removeHarnessConfig, cursorDetected, codexDetected, absoluteHookCommand, isHarnessConfigured, purgeHome, harnessScopes, harnessScopeLabel, configuredHookCommands, hookCommandResolves, projectHarnessFile, localHarnessFile, gitShareState, isMachineSpecificCommand, trustProjectPolicy, untrustedProjectPolicy, isTrustedProject, 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 { connectCloud, ingestUrl, loadConnection } from "./cloud.js";
+import { recoverEarlierReceipts } from "./recover.js";
+import { loadPolicyExport, policyBuilds } from "./policy-load.js";
+import { isManaged, readMeta, MANAGED_DOC_FILE } from "./managed.js";
+import { syncIfDue, syncPolicy } from "./policy-sync.js";
 import { loadBudgetExport } from "./budget-load.js";
 import { compile, defaultRules, describeRules, loadRules, saveRules, rulesPath, pathRuleFor } from "./rules.js";
 import { createSigner } from "@scopebond/sdk";
@@ -215,7 +218,8 @@ async function runPreToolUse(mapper, deny = denyClaude, raw, harness = "claude")
         useDigestKey(loadOrCreateDigestKey(dir));
         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()]);
+        // Workspace rules: at most every five minutes, a capped check alongside the record delivery. It never fails the call.
+        await Promise.all([runtime.flush(), observer?.flush() ?? Promise.resolve(), syncIfDue(dir, () => syncOptionsFor(dir))]);
         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.
@@ -326,7 +330,7 @@ async function runCursor() {
         const mapped = fillPushBranch(mapCursorEvent(event, input), currentBranch(cwd));
         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()]);
+        await Promise.all([runtime.flush(), observer?.flush() ?? Promise.resolve(), syncIfDue(dir, () => syncOptionsFor(dir))]);
         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.
@@ -677,6 +681,11 @@ function runRules(args) {
             printHelp("rules", true);
             process.exit(1);
     }
+    if (isManaged(dir)) {
+        console.error("The rules on this computer are set by your Scopebond workspace, so they cannot be changed here.");
+        console.error("Change them in the workspace (Rules), or disconnect this computer to manage its rules locally again.");
+        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");
@@ -863,11 +872,11 @@ async function runConnect(args) {
     const bundleArg = positional[1];
     const harness = selectedHarness(args);
     if (!url) {
-        console.error(`usage: ${cliCommand("connect <workspace-url> <enrollment> [--claude|--cursor|--codex] [--no-install]")}`);
+        console.error(`usage: ${cliCommand("connect <workspace-url> <enrollment> [--claude|--cursor|--codex] [--no-install] [--project]")}`);
         console.error(enrollmentHelp);
         process.exit(1);
     }
-    const dir = configDir();
+    const dir = connectDir(args);
     // One command sets everything up: scaffold the key, attester and starter policy if
     // they do not exist, then enroll and persist the scoped machine credential. The
     // enrollment can be a file, an inline base64 blob (what the portal hands out) or
@@ -889,6 +898,10 @@ async function finishConnect(dir, url, bundle, harness, args) {
     try {
         const c = await connectCloud(dir, url, bundle);
         console.log(`✓ Connected to ${c.url}`);
+        if (c.rotatedFrom)
+            console.log(`✓ This computer's earlier key (${c.rotatedFrom}) was no longer accepted, so it was replaced; the old key is kept in ${join(dir, "retired-keys")}`);
+        if (c.setAside)
+            console.log(`  ${c.setAside.toLocaleString()} queued record(s) signed by an earlier key cannot go through this connection. To deliver them, run: ${cliCommand("recover")}`);
         // 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
@@ -951,6 +964,43 @@ const enrollmentHelp = [
     "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");
+/** Where `connect` and `login` write. A project someone set up here with `init` (it has a
+ *  policy) is connected, as before. Otherwise the configuration the hook itself uses from
+ *  here — usually the user-level install — so reconnecting from any folder repairs the
+ *  connection that is actually failing instead of creating a second, project-level one
+ *  beside it. `--project` asks for a new per-project setup explicitly. */
+function connectDir(args) {
+    const project = configDir();
+    return args.includes("--project") || existsSync(join(project, "policy.json")) ? project : resolveConfigDir(process.cwd());
+}
+/** `recover [--no-wait]`: deliver receipts that an earlier, since-revoked key of this computer
+ *  signed and the workspace never received, after an owner or admin approves it there. */
+async function runRecover(args) {
+    const dir = resolveConfigDir(process.cwd());
+    const connection = loadConnection(dir);
+    if (!connection) {
+        console.error(`not connected to a workspace; run \`${cliCommand("login <workspace-url>")}\` first`);
+        process.exit(1);
+    }
+    console.log(`Recovering from ${dir}`);
+    const result = await recoverEarlierReceipts(dir, connection, {
+        log: (line) => console.log(line),
+        fetch,
+        now: Date.now,
+        sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+    }, { wait: !args.includes("--no-wait"), waitMs: 15 * 60_000, pollMs: 5_000 });
+    if (result.groups) {
+        const parts = [
+            `recovered ${result.accepted.toLocaleString()}`,
+            `already present ${result.duplicates.toLocaleString()}`,
+            `refused ${result.rejected.toLocaleString()}`,
+            ...(result.pending ? [`waiting for approval ${result.pending.toLocaleString()}`] : []),
+            ...(result.skipped ? [`skipped ${result.skipped.toLocaleString()}`] : []),
+        ];
+        console.log(`\nDone: ${parts.join(", ")}.`);
+    }
+    process.exitCode = result.failed || result.pending ? 1 : 0;
+}
 async function runFlush() {
     const dir = resolveConfigDir(process.cwd());
     if (!loadConnection(dir)) {
@@ -970,12 +1020,21 @@ async function runFlush() {
  *  `--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 === "sync") {
+        await runPolicySync(args.includes("--background"));
+        return;
+    }
     if (sub !== "load" || !file) {
-        console.error(`usage: ${cliCommand("policy load <export.json> [--yes]")}`);
+        console.error(`usage: ${cliCommand("policy sync")} | ${cliCommand("policy load <export.json> [--yes]")}`);
         process.exitCode = 2;
         return;
     }
     const dir = resolveConfigDir(process.cwd());
+    if (isManaged(dir)) {
+        console.error("The rules on this computer are set by your Scopebond workspace; a policy file cannot replace them here.");
+        process.exitCode = 1;
+        return;
+    }
     const apply = args.includes("--yes");
     const connection = loadConnection(dir);
     const outcome = loadPolicyExport(dir, file, { apply, environmentId: connection?.environment_id });
@@ -1002,6 +1061,41 @@ async function runPolicy(args) {
         return;
     await sendPolicyAck(dir, ack);
 }
+/** What a rules check needs for this config directory. A project policy governs only once trusted, so it is re-pinned after a
+ *  write, exactly when `rules apply` would. */
+function syncOptionsFor(dir) {
+    const home = userHome();
+    const repin = dir !== home && existsSync(join(home, "policy.json")) && isTrustedProject(dir);
+    const agentKid = createSigner({ privateKeyPem: readFileSync(join(dir, "agent.key"), "utf8") }).kid;
+    return { agentKid, hookVersion: hookVersion(), policyBuilds, afterPolicyWrite: repin ? (d) => { trustProjectPolicy(d); } : undefined };
+}
+/** `policy sync`: bring this computer's rules in line with its workspace now (the hook also checks every five minutes). */
+async function runPolicySync(background) {
+    const dir = resolveConfigDir(process.cwd());
+    let outcome;
+    try {
+        outcome = await syncPolicy(dir, syncOptionsFor(dir));
+    }
+    catch (error) {
+        outcome = { state: "unavailable", message: error.message };
+    }
+    if (background)
+        return;
+    const lines = {
+        not_connected: "This computer is not connected to a Scopebond workspace; it uses its own rules.",
+        own_rules: "Your workspace does not set rules for this computer; it uses its own rules.",
+        unchanged: "Up to date with your workspace.",
+        applied: "Updated to your workspace's latest rules.",
+        refused: "Could not apply your workspace's rules; the rules already in force stay.",
+        disconnected: "The workspace connection is no longer valid; this computer now uses its own rules.",
+        unavailable: "Could not reach your workspace; the rules already in force stay.",
+    };
+    console.log(lines[outcome.state]);
+    if (outcome.state === "refused" || outcome.state === "unavailable") {
+        console.log(`  ${outcome.message}`);
+        process.exitCode = 1;
+    }
+}
 /** 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 });
@@ -1128,7 +1222,7 @@ async function runObservations(args) {
     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 outcome = await uploadPending(emitter.store, { url: ingestUrl(emitter.connection), 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;
@@ -1299,6 +1393,16 @@ 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 activeDir = resolveConfigDir(process.cwd());
+        const meta = readMeta(activeDir);
+        const managed = existsSync(join(activeDir, MANAGED_DOC_FILE));
+        const checked = meta.checked_at ? `, last checked ${meta.checked_at}` : "";
+        console.log(`  rules            ${managed ? `set by your workspace (version ${meta.revision})${checked}` : `this computer's own (${rulesPath(activeDir)})${connected ? checked : ""}`}`);
+        console.log(`                   always on: protection of Scopebond's own settings and the agents' hook settings`);
+        if (meta.last_error)
+            console.log(`                   last problem: ${meta.last_error}`);
+    }
     const observationLines = describeObservations(resolveConfigDir(process.cwd()));
     console.log(`  observations     ${observationLines[0]}`);
     for (const line of observationLines.slice(1))
@@ -1515,7 +1619,7 @@ async function runLogin(args) {
         origin = parsed.origin;
     }
     catch {
-        console.error(`usage: ${cliCommand("login <workspace-url> [--claude|--cursor|--codex] [--no-install]")}`);
+        console.error(`usage: ${cliCommand("login <workspace-url> [--claude|--cursor|--codex] [--no-install] [--project]")}`);
         console.error("The workspace URL is the address of your Scopebond workspace, for example https://cloud.scopebond.com.");
         process.exit(1);
     }
@@ -1545,7 +1649,7 @@ async function runLogin(args) {
     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();
+    const dir = connectDir(args);
     scaffold(dir, {});
     while (Date.now() < deadline) {
         await new Promise((resolve) => setTimeout(resolve, intervalMs));
@@ -1688,6 +1792,12 @@ const COMMANDS = [
     { 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: "recover", args: "[--no-wait]", summary: "deliver records an earlier, revoked key signed, once the workspace approves",
+        detail: [
+            "When this computer was replaced or disconnected while records were still queued, the",
+            "workspace refuses them from the new connection. This asks the workspace to accept them,",
+            "waits while an owner or admin approves it on Activity, then sends them, labelled Recovered.",
+        ] },
     { 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" },
@@ -1778,6 +1888,9 @@ else if (cmd === "test") {
 else if (cmd === "flush") {
     await runFlush();
 }
+else if (cmd === "recover") {
+    await runRecover(rest);
+}
 else if (cmd === "status") {
     runStatus();
 }