@scopebond/hook 0.7.0 → 0.8.0

package/README.md

@@ -55,10 +55,27 @@ npx @scopebond/hook init --codex    # Codex, then approve it once with /hooks
 
 `init` scaffolds `.scopebond/` in the current project (a machine signing key, a
 countersigning key, a starter policy — "protect main and production paths" — and a
-`.gitignore` so none of it is committed) and configures `.claude/settings.json`,
-`.cursor/hooks.json`, or `.codex/hooks.json`. Then run one safe command in the agent and see the receipt in
-`.scopebond/receipts.db`. `init`, `trust` and `uninstall` are meant for a person at a
-terminal: in a script or CI, pass `--yes`.
+`.gitignore` so none of it is committed) and wires your agent to the hook. Then run one
+safe command in the agent and see the receipt in `.scopebond/receipts.db`. `init`, `trust`
+and `uninstall` are meant for a person at a terminal: in a script or CI, pass `--yes`.
+`npx @scopebond/hook init --dry-run` shows what it would write, and changes nothing.
+
+**Where the hook goes, and why.** `init` pins a copy of the hook on this machine so it
+starts fast on every tool call. That command names paths that exist only here, so it
+never goes into a file your team shares: for Claude Code it goes into
+`.claude/settings.local.json`, which `init` keeps out of git for this clone; for Cursor
+and Codex it goes into `.cursor/hooks.json` or `.codex/hooks.json` only while git does not
+already track that file, and a tracked file gets the portable command instead. A hook
+command that cannot start is treated by the agent as a non-blocking error — the agent
+carries on with no check — so a machine-specific path in a committed file would leave
+every teammate unprotected while the file says otherwise. `doctor` reports that case, and
+running `init` again moves an entry an older version wrote into `.claude/settings.json`.
+
+To give everyone who clones the project the hook, use `init --shared`: it writes the
+portable command (`npx -y @scopebond/hook@<version> claude`) to `.claude/settings.json`,
+`.cursor/hooks.json` or `.codex/hooks.json`. It starts on any machine, more slowly, and
+until a teammate runs `init` themselves it blocks their agent's actions with a message
+saying how to set it up.
 
 Check what it did with `npx @scopebond/hook status` (which agents are configured, in
 which scope) and `npx @scopebond/hook doctor` (whether each configured command can
@@ -116,9 +133,21 @@ before they land, make `@scopebond/github-action` a required check on pull reque
 
 ## Connect it to your workspace (optional)
 
-To see the receipts in your hosted Scopebond workspace, create a connection from
-the portal's **Connect** step (it gives you a one-use enrollment bundle), save it
-as `scopebond-enrollment.json`, then:
+To see the receipts in your hosted Scopebond workspace, sign this computer in:
+
+```
+npx @scopebond/hook login https://<your-workspace>
+```
+
+It prints a short code and a link. Someone who manages the workspace opens the link,
+checks that the code matches, and approves it for an environment and agent. The
+command then finishes connecting on its own: nothing is copied or pasted, and the
+code expires after 10 minutes if nobody approves it. Add `--cursor` or `--codex`
+for those agents, or `--no-install` to leave the agent's settings alone.
+
+If your workspace does not offer sign-in codes, create a connection from the
+portal's **Connect** step (it gives you a one-use enrollment bundle), save it as
+`scopebond-enrollment.json`, then:
 
 ```
 npx @scopebond/hook connect https://<your-workspace> scopebond-enrollment.json

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA8fA,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":";AAojBA,6EAA6E;AAC7E,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAS7F"}

package/dist/cli.js

@@ -8,22 +8,38 @@
 //
 // Config dir: $SCOPEBOND_HOOK_DIR, else ./.scopebond
 // Fail-closed: any error denies the action with a repair message.
+// `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, harnessScopes, harnessScopeLabel, configuredHookCommands, hookCommandResolves, projectHarnessFile, 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 { compile, defaultRules, describeRules, loadRules, saveRules, rulesPath, pathRuleFor } from "./rules.js";
 import { createSigner } from "@scopebond/sdk";
 import { describeAction } from "./explain.js";
-import { ensureDurableRuntime } from "./runtime-install.js";
-import { cliCommand, hookVersion } from "./version.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
@@ -129,7 +145,9 @@ async function runPreToolUse(mapper, deny = denyClaude) {
     let runtime;
     try {
         const cwd = input?.cwd ? String(input.cwd) : process.cwd();
-        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
@@ -183,7 +201,9 @@ async function runCursor() {
     let runtime;
     try {
         const cwd = input?.cwd ? String(input.cwd) : process.cwd();
-        runtime = createHookRuntime(runtimePaths(resolveConfigDir(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();
@@ -238,9 +258,34 @@ function requireInteractive(command, args) {
     process.exit(1);
 }
 function runInit(args) {
-    requireInteractive("init", args);
     const harness = selectedHarness(args);
     const dir = configDir();
+    // 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}`);
@@ -257,34 +302,49 @@ function runInit(args) {
     // 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 pin = args.includes("--npx") ? { cli: null, how: "unavailable" } : ensureDurableRuntime(cliPath(), hookVersion());
+    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;
-    // 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   ${pin.cli
-        ? `${pin.cli}\n                 pinned — no npx resolution per action`
-        : `npx @scopebond/hook@${hookVersion()} — portable, but re-resolves on every action`}`);
-    console.log("");
     // 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, process.cwd(), command);
+            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, command));
+        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}`);
     }
@@ -626,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`
@@ -665,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();
@@ -679,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}`);
@@ -701,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));
@@ -728,6 +813,14 @@ 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"]
@@ -744,7 +837,8 @@ function runInstall(args) {
             console.log(`Would ${exists ? "modify" : "create"} ${file}`);
             if (exists)
                 console.log(`  backing it up to  ${file}.scopebond-backup`);
-            console.log(`  adding hook       ${absoluteHookCommand(cliPath(), h)}`);
+            // 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)`);
         }
@@ -762,7 +856,7 @@ function runInstall(args) {
             try {
                 const target = userHarnessFile(h);
                 const backup = existsSync(target) ? `${target}.scopebond-backup` : null;
-                const file = writeHarnessConfig(target, h, absoluteHookCommand(cliPath(), h));
+                const file = writeHarnessConfig(target, h, commandFor(h));
                 console.log(`✓ ${harnessName(h)} configured in ${file}`);
                 if (backup && existsSync(backup))
                     console.log(`  original kept at ${backup}`);
@@ -822,7 +916,7 @@ function runStatus() {
     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)
@@ -833,7 +927,7 @@ function runStatus() {
     console.log(`  cloud workspace  ${connected ? "connected" : "not connected (local only)"}`);
     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.user])
+        for (const file of [scopes.project, scopes.local, scopes.user])
             if (file)
                 console.log(`    ${name}: ${file}`);
     }
@@ -850,7 +944,7 @@ 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());
@@ -871,16 +965,27 @@ async function runDoctor() {
         }
         anyHarness = true;
         console.log(`  ${name.padEnd(15)} ${label}`);
-        for (const file of [scopes.project, scopes.user]) {
+        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);
-                console.log(`    ${ok ? "ok  " : "BAD "} ${file}`);
+                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")
@@ -913,8 +1018,8 @@ function runUninstall(args) {
     // 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"]) {
-        for (const file of [projectHarnessFile(h, process.cwd()), userHarnessFile(h)]) {
-            if (removeHarnessConfig(file)) {
+        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++;
             }
@@ -947,23 +1052,103 @@ 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] [--no-install] [--npx] [--force] [--yes]",
+    { 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",
-            "configures .claude/settings.json, .cursor/hooks.json or .codex/hooks.json.",
-            "Pins a durable copy of this package so the hook starts fast; --npx keeps the portable",
-            "command instead. --no-install prints the config snippet rather than writing it.",
+            "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]",
@@ -1002,6 +1187,12 @@ const COMMANDS = [
             "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" },
@@ -1092,7 +1283,7 @@ else if (cmd === "uninstall") {
     runUninstall(rest);
 }
 else if (cmd === "login") {
-    runLogin();
+    await runLogin(rest);
 }
 else if (cmd === "trust") {
     runTrust(rest);