@decidio/sdk 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ the gate, signing, receipts and the verifier - is conformance-locked between the
 first-run surfaces (the fork, `--demo`, the code sign-in) are TypeScript-first and named as such in the parity
 allowlist. Each entry names what changed, what a reader must do on upgrade, and what proved it.
 
+## Unreleased
+
+## 0.10.0 — connect a coding assistant in one tap
+
+- **`npx @decidio/sdk connect`** (cycle connect). A coding assistant sets Decidio up for you: it runs `connect`, which prints a
+  link and a short code (on a real terminal also a QR, and it opens the browser); the workspace owner opens the link signed in,
+  checks the code, picks who approves and taps Allow; `connect --wait` then returns by itself (exit 0 connected, 1 still
+  waiting - run it again, 3 refused or expired; within 90 s, under an assistant's 2-minute command limit). The machine gets an
+  ask-only credential - never a session - kept OUTSIDE the repository (the config dir, owner-only, keyed by the repository root
+  and the Decidio), and the hooks switch on in `.claude/settings.local.json` (`--team`: the shared `.claude/settings.json`).
+  No `.env`, nothing to paste, the word "agent" nowhere in the setup.
+- **In a cloud session the hooks go in `.claude/settings.json`.** A cloud session reads only the repository's own settings file,
+  never `.claude/settings.local.json` (Claude Code's docs), so that is where they work. connect leaves it uncommitted and says to ask
+  the person before committing it (committed, every cloud session of the repository and every teammate's clone ask too). The
+  credential is that cloud machine's: a fresh one refuses destructive commands until it connects again.
+- **The machine proves its key.** The start is signed with the machine's own key (the request-bound proof every signed
+  request carries, over the assistant, project, machine and cloud-or-local), so nobody can file a connect in another
+  machine's name; the server refuses a start without it. The connect checks the wire first (https, or a local address),
+  since the poll's answer carries the credential.
+- **Credentials, in order:** the shell, then the folder's `.env`, then this repository's connection - all or nothing, so a
+  project with an `init` `.env` keeps exactly that identity. `disconnect` deletes this machine's token (gated commands are then
+  refused until you connect again; the machine's key stays, so reconnecting reuses its agent).
+- **The hook's words** for an unconnected project now name `connect` and `connect --wait` (the plugin's skill says the same);
+  `hook install` with no credentials points at `connect` first.
+- **The links the command line prints follow the API's own web app** (launch plan L1c). Staging's API maps to
+  `staging.decidioai.com`, production's (`mcp.decidioai.com`) to `app.decidioai.com`, and any other origin to itself.
+  `DECIDIO_APP_URL` wins only as a plain `http(s)` address, and the host line names it.
+  - **Release condition:** publish only after `staging.decidioai.com` serves staging's web app (docs/Deployment_Runbook.md
+    A1). Tell testers to run `github init` again to refresh their AGENTS.md section.
+
+On upgrade: nothing to change - `init` projects keep their `.env`. The plugin pins 0.10.0. `connect` needs a Decidio that
+serves `/connect/*` (the lab, from cycle connect's deploy). Proved by: cli-smoke.ts (356 → 378 checks: connect, its signed
+start, wait, reconnect, disconnect, refused, expired, a cloud session, --team, beside the plugin, .env precedence, the hook
+through a connection).
+
 ## 0.9.0 — the coding-agent hook catches what agents type, protects itself, and tells the approver what was asked
 
 - **Wider matching, from real agent runs.** `sql-destructive` counts a statement sent through an interpreter or runner

package/README.md

@@ -75,8 +75,8 @@ npx @decidio/sdk init --unique my-agent   # --unique appends a random suffix: co
 Every network command talks to the hosted sandbox by default (`verify` is offline) and announces its target host on
 stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another Decidio instead.
 
-`init` signs you into your workspace (email + password, or the 8-character code the CLI emails you —
-type it where you asked), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
+`init` signs you into your workspace (the 8-character code the CLI emails you — type it where you asked —
+or, for an account made before sign-up became passwordless, its email + password), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
 is sent), registers the agent, mints its **floor-limited API token** (limited to the agent runtime — request authorization, poll status, report signed confirmation; it cannot administer the workspace or approve anything — and your workspace session never touches the agent's disk), and writes `.env`.
 Every later command that talks to Decidio reads `.env` from this directory automatically (`verify` is
 offline and never does). Re-running init for an

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+export declare function appUrlFor(api: string, override?: string | undefined): string;
 export type ApprovalAnswer = "approve" | "reject" | "again";
 export declare function approvalAnswer(answer: unknown): ApprovalAnswer;
 /** The issuer store's key for a Decidio address: its origin (scheme + lowercased host + non-default port), computed by a

package/dist/cli.js

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync, rmdirSync, openSync, writeSync, fsyncSync, closeSync, renameSync, mkdirSync, mkdtempSync, readdirSync, copyFileSync, statSync, lstatSync, fstatSync, readSync } from "node:fs";
 import { randomBytes, createHash } from "node:crypto";
-import { homedir, tmpdir } from "node:os";
+import { homedir, tmpdir, hostname } from "node:os";
 import { join as joinPath, resolve as resolvePath, sep as pathSep, basename, dirname, relative, isAbsolute } from "node:path";
 import { createServer } from "node:http";
 import { isIP } from "node:net";
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawnSync, spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { pathToFileURL as toFileUrl, fileURLToPath as fromFileUrl } from "node:url";
 import { realpathSync as realPath } from "node:fs";
 import { createRequire } from "node:module";
-import { generateKeypair, assertSafeTransport, redactUrl } from "./signing.js";
+import { generateKeypair, assertSafeTransport, redactUrl, signBoundProof } from "./signing.js";
 import { hardenFile } from "./resume.js";
 import { withApproval, DecidioRateLimitError, DecidioRejectedError, DecidioTimeoutError, DecidioHttpError, didFromPrivateKey, checkApproval, signConfirm, buildConfirmBody, readConfirmResponse, bindingMaterial, boundScope, idempotencyKey, decisionUrl, decisionIdProblem } from "./index.js";
 import { gateAuthorizeTwinAware, adapterRequest } from "./adapters/_gate.js";
@@ -76,6 +76,14 @@ if (!OFFLINE_CMD)
     }
 const DEFAULT_API = "https://decidio-api.onrender.com";
 let API = (process.env.DECIDIO_API_URL ?? DEFAULT_API).replace(/\/$/, "");
+let CREDS_FROM = SHELL_ENV.DECIDIO_API_TOKEN ? "shell" : process.env.DECIDIO_API_TOKEN ? ".env" : null;
+if (!OFFLINE_CMD && !["init", "quickstart", "login", "logout", "phone"].includes(ARGV_TAIL[0] ?? "") && !process.env.DECIDIO_API_TOKEN && !process.env.DECIDIO_AGENT_ID) {
+    const c = loadConnection(projectRoot(), API);
+    if (c) {
+        promoteConnection(c);
+        CREDS_FROM = "connection";
+    }
+}
 let DEMO = false;
 function enterDemo(url) { API = url; process.env.DECIDIO_API_URL = url; DEMO = true; }
 const pinWords = () => (DEMO ? "PINNED to this demo's own key" : "PINNED to your workspace issuer");
@@ -90,7 +98,7 @@ let hostAnnounced = false;
 async function api(path, init = {}, bearer, soft = false) {
     if (!hostAnnounced) {
         hostAnnounced = true;
-        err(`· decidio → ${API}${process.env.DECIDIO_API_URL ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
+        err(`· decidio → ${API}${process.env.DECIDIO_API_URL ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}${APP_URL_OVERRIDDEN ? `  · links → ${APP_URL} (DECIDIO_APP_URL)` : ""}`);
     }
     const auth = bearer ?? TOKEN();
     if (auth && envUnreadable && !process.env.DECIDIO_API_URL) {
@@ -462,7 +470,24 @@ function block(n, title, rows, tone) {
     }
     log(f("└" + "─".repeat(width - 2) + "┘"));
 }
-const APP_URL = API.replace("decidio-api.onrender.com", "app.decidioai.com");
+const APP_URL_SHAPE = /^https?:\/\/[\x21-\x7e]+$/;
+const asciiTrim = (v) => v.replace(/^[ \t\r\n]+|[ \t\r\n]+$/g, "");
+export function appUrlFor(api, override = process.env.DECIDIO_APP_URL) {
+    const o = asciiTrim(override ?? "");
+    if (APP_URL_SHAPE.test(o))
+        return o.replace(/\/+$/, "");
+    const base = api.replace(/\/+$/, "");
+    const known = {
+        "https://decidio-api.onrender.com": "https://staging.decidioai.com",
+        "https://mcp-staging.decidioai.com": "https://staging.decidioai.com",
+        "https://mcp.decidioai.com": "https://app.decidioai.com",
+    };
+    return known[base] ?? base;
+}
+const APP_URL = appUrlFor(API);
+const APP_URL_OVERRIDDEN = APP_URL !== appUrlFor(API, "");
+if (asciiTrim(process.env.DECIDIO_APP_URL ?? "") && !APP_URL_SHAPE.test(asciiTrim(process.env.DECIDIO_APP_URL ?? "")))
+    console.error("⚠ ignoring DECIDIO_APP_URL: it must be a plain http(s) address (printable characters only)");
 let stdinReadAbandoned = false;
 let EXPLAIN = false;
 let currentRl = null;
@@ -3263,11 +3288,11 @@ async function readHookStdin() {
 function hookConfig() {
     const token = process.env.DECIDIO_API_TOKEN;
     if (!token)
-        return { missing: "DECIDIO_API_TOKEN is not set - no agent token in this folder's .env or the environment" };
+        return { missing: "this project is not connected to Decidio (no connection, no agent token in this folder's .env or the environment)" };
     return {
         apiUrl: API, agentId: process.env.DECIDIO_AGENT_ID || defaultAgentId(), apiToken: token, sourceSystem: "claude-code",
         agentKey: process.env.DECIDIO_AGENT_KEY || undefined, agentDid: process.env.DECIDIO_AGENT_DID || undefined, workspaceId: process.env.DECIDIO_WORKSPACE_ID || undefined,
-        appUrl: process.env.DECIDIO_APP_URL || APP_URL,
+        appUrl: APP_URL,
     };
 }
 const hookStateDir = () => (process.env.CLAUDE_PLUGIN_DATA ? joinPath(process.env.CLAUDE_PLUGIN_DATA, "hooks") : joinPath(sessionDir(), "hooks"));
@@ -3428,7 +3453,7 @@ async function cmdHookPretool() {
         const short = hookShort(hookRedact(g.text.replace(/\s+/g, " ").trim()));
         const cfg = hookConfig();
         if ("missing" in cfg)
-            return deny(`Decidio: "${short}" is a ${g.category} ${w.noun} that needs a person's approval, but this project has no Decidio agent credentials (${cfg.missing}). ${w.ran} Ask the user to run \`npx @decidio/sdk init\` in ${projectDir}, then retry the same ${w.noun}.`, `Decidio: no agent credentials in ${projectDir} - run npx @decidio/sdk init`);
+            return deny(`Decidio: "${short}" is a ${g.category} ${w.noun} that needs a person's approval, but this project is not connected to Decidio yet. ${w.ran} Run \`npx @decidio/sdk connect\` in ${projectDir} and show the user the link it prints (they allow it on the web), then run \`npx @decidio/sdk connect --wait\`; once it says connected, retry the same ${w.noun}.`, `Decidio: this project is not connected - run npx @decidio/sdk connect`);
         const rel = relative(projectDir, cwdAbs);
         const cwdRel = !rel ? "." : rel.startsWith("..") || isAbsolute(rel) ? cwdAbs : rel;
         const session = typeof input.session_id === "string" ? input.session_id : "";
@@ -3569,7 +3594,7 @@ async function cmdHookWait(id, timeoutSec) {
     }
     const cfg = hookConfig();
     if ("missing" in cfg) {
-        err(`✘ ${cfg.missing} - run \`npx @decidio/sdk init\` in this project first.`);
+        err(`✘ ${cfg.missing} - connect this project first: npx @decidio/sdk connect`);
         return 1;
     }
     const where = decisionUrl(cfg.appUrl, id);
@@ -3671,7 +3696,7 @@ function hookRunner() {
 const HOOK_FILE_TOOLS = ["Write", "Edit", "MultiEdit"];
 const HOOK_GUARD_PATHS = ["**/.claude/settings*.json", "~/.claude/settings*.json", "~/.claude/plugins/**"];
 async function cmdHookInstall(opts) {
-    const settingsPath = joinPath(".claude", opts.project ? "settings.json" : "settings.local.json");
+    const settingsPath = joinPath(opts.dir ?? ".", ".claude", opts.project ? "settings.json" : "settings.local.json");
     let settings = {};
     if (existsSync(settingsPath)) {
         try {
@@ -3725,27 +3750,380 @@ async function cmdHookInstall(opts) {
             guard[place("PreToolUse", t, `${t}(${p})`, preLine, { timeout: 150, onFailure: "block" })]++;
             guard[place("PostToolUse", t, `${t}(${p})`, postLine, { timeout: 30 })]++;
         }
-    mkdirSync(".claude", { recursive: true });
+    mkdirSync(dirname(settingsPath), { recursive: true });
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    lastHookInstall = { settingsPath, pre, post };
+    if (opts.quiet)
+        return 0;
     log(`✔ ${settingsPath.split(pathSep).join("/")}: PreToolUse hook ${pre}, PostToolUse hook ${post} (matcher Bash|PowerShell${opts.project ? "; this file is shared with everyone who clones the project" : "; this file is yours alone - Claude Code keeps it out of git"}).`);
     log(`✔ the guard on Claude Code's own settings - ${HOOK_FILE_TOOLS.join(", ")} on ${HOOK_GUARD_PATHS.join(", ")}, PreToolUse and PostToolUse: ${Object.entries(guard).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ")}.`);
     log(`  Runs: ${runner} hook pretool|posttool  - the pretool hook times out at 150 s and BLOCKS the call if it fails (fail closed).`);
     const env = readEnvFile();
     const token = process.env.DECIDIO_API_TOKEN || env.DECIDIO_API_TOKEN;
-    if (token)
+    if (token && CREDS_FROM === "connection")
+        log(`✔ credentials: this project's Decidio connection (${process.env.DECIDIO_AGENT_ID}) - kept outside the repository, owner-only.`);
+    else if (token)
         log(`✔ agent credentials: ${ENV_PATH} holds DECIDIO_API_TOKEN${(process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY) ? " and the agent's signing key" : ""} for "${process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID || defaultAgentId()}".`);
     else
-        log(`⚠ no agent credentials here (no DECIDIO_API_TOKEN in ${ENV_PATH}) - until there are, EVERY gated command is refused. Run: npx @decidio/sdk init ${defaultAgentId()}`);
+        log(`⚠ not connected yet - until this project is, EVERY gated command is refused. Run: npx @decidio/sdk connect  (or, for your own agent: npx @decidio/sdk init ${defaultAgentId()})`);
     log(`  Gated: ${HOOK_RULES.map((r) => r.category).join(", ")} (npx @decidio/sdk hook rules lists the patterns; DECIDIO_HOOK_EXTRA_RULES adds yours).`);
     log(`  Approver: anyone in your workspace with a role other than the agent's owner (the person who ran init) - on the phone app, the web app, Slack or Teams.`);
     log(`           Nobody yet? Invite one: npx @decidio/sdk hook install --approver <email>   (single-use link; share by WhatsApp, SMS or email)`);
     log(`  Flow: a gated command is held up to ${Math.min(Number(process.env.DECIDIO_HOOK_HOLD_MS ?? 90_000) || 90_000, HOOK_HOLD_CAP_MS) / 1000} s for the approver, then refused with its decision id; \`npx @decidio/sdk hook wait <id>\` returns when they decide,`);
     log(`        and the SAME command retried then runs - once. A lab workspace allows 30 governed actions an hour; a gated command spends two (ask, retry).`);
-    log(`  Reload: restart Claude Code, or run /hooks in it - hooks are read when a session starts.`);
+    log(`  Reload: none needed - Claude Code picks up the settings file by itself. If a gated command is not asked about, open /hooks once (or restart Claude Code).`);
     if (opts.approver !== undefined)
         return inviteApprover(opts.approver);
     return 0;
 }
+function connectHostLabel(h) { return h === "claude-code" ? "Claude Code" : h; }
+function connectDir() { return joinPath(sessionDir(), "connections"); }
+function realOrSame(p) { try {
+    return realPath(p);
+}
+catch {
+    return resolvePath(p);
+} }
+const sameDir = (a, b) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
+function projectRoot() {
+    try {
+        const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+        const top = String(r.stdout ?? "").trim();
+        if (r.status === 0 && top)
+            return realOrSame(top);
+    }
+    catch { }
+    return realOrSame(SHELL_ENV.CLAUDE_PROJECT_DIR || process.cwd());
+}
+function connectionKey(root) { return createHash("sha256").update(`${API}\n${process.platform === "win32" ? root.toLowerCase() : root}`, "utf8").digest("hex").slice(0, 20); }
+function connectionFile(root) { return joinPath(connectDir(), `${connectionKey(root)}.json`); }
+function pendingConnectFile(root) { return joinPath(connectDir(), `${connectionKey(root)}.pending.json`); }
+function readJsonQuiet(f) {
+    try {
+        return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function loadConnection(root, api) {
+    const c = connectionRecord(root, api);
+    return c && !c.disconnected && c.token ? c : null;
+}
+function connectionRecord(root, api) {
+    const c = readJsonQuiet(connectionFile(root));
+    return c && c.v === 1 && c.api === api && c.root === root && typeof c.token === "string" && typeof c.agentId === "string" && typeof c.key === "string" && typeof c.did === "string" ? c : null;
+}
+function promoteConnection(c) {
+    process.env.DECIDIO_API_TOKEN = c.token;
+    process.env.DECIDIO_AGENT_ID = c.agentId;
+    process.env.DECIDIO_AGENT_DID = c.did;
+    process.env.DECIDIO_AGENT_KEY = c.key;
+    process.env.DECIDIO_WORKSPACE_ID = c.workspaceId;
+    process.env.DECIDIO_TOKEN_JTI = c.jti;
+    if (c.appUrl && process.env.DECIDIO_APP_URL === undefined)
+        process.env.DECIDIO_APP_URL = c.appUrl;
+}
+function inCloudSession() { return SHELL_ENV.CLAUDE_CODE_REMOTE === "true"; }
+function machineId() {
+    const f = joinPath(sessionDir(), "machine-id");
+    let cur = "";
+    try {
+        cur = existsSync(f) ? readFileSync(f, "utf8").trim() : "";
+    }
+    catch { }
+    if (/^[0-9a-f]{8,32}$/.test(cur))
+        return cur;
+    const id = randomBytes(8).toString("hex");
+    mkdirSync(sessionDir(), { recursive: true });
+    writeFileSync(f, id + "\n");
+    return id;
+}
+function machineLabel(cloud) {
+    if (cloud)
+        return `cloud-${machineId().slice(0, 4)}`;
+    const h = (() => { try {
+        return hostname();
+    }
+    catch {
+        return "";
+    } })().split(".")[0].toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    return (h || "machine").slice(0, 40);
+}
+function projectLabel(root) {
+    try {
+        const r = spawnSync("git", ["-C", root, "config", "--get", "remote.origin.url"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+        const m = String(r.stdout ?? "").trim().match(/([^/:\\]+?)(?:\.git)?\/?$/);
+        if (r.status === 0 && m?.[1])
+            return m[1].slice(0, 80);
+    }
+    catch { }
+    try {
+        const pj = JSON.parse(readFileSync(joinPath(root, "package.json"), "utf8"));
+        if (typeof pj?.name === "string" && pj.name)
+            return pj.name.replace(/^@[^/]+\//, "").slice(0, 80);
+    }
+    catch { }
+    return (basename(root) || "project").slice(0, 80);
+}
+function localDesktop() {
+    if (inCloudSession() || SHELL_ENV.CI || SHELL_ENV.SSH_CONNECTION || SHELL_ENV.SSH_TTY || SHELL_ENV.CODESPACES || SHELL_ENV.GITPOD_WORKSPACE_ID || SHELL_ENV.DECIDIO_NO_BROWSER)
+        return false;
+    if (process.platform === "darwin" || process.platform === "win32")
+        return true;
+    return !!(SHELL_ENV.DISPLAY || SHELL_ENV.WAYLAND_DISPLAY);
+}
+function openInBrowser(url) {
+    if (!/^https?:\/\/[^\s"'<>`]+$/.test(url))
+        return false;
+    try {
+        const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : ["xdg-open", [url]];
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore", windowsHide: true });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const CONNECT_WAIT_S = () => { const n = Number(process.env.DECIDIO_CONNECT_WAIT_S ?? 90); return Number.isFinite(n) && n >= 1 && n <= 110 ? n : 90; };
+let lastHookInstall = null;
+async function startConnect(root, host) {
+    const prior = connectionRecord(root, API);
+    const kp = prior && !inCloudSession() ? { did: prior.did, privateKeyBase64: prior.key } : generateKeypair();
+    const cloud = inCloudSession();
+    const project = projectLabel(root).trim() || "project", machine = machineLabel(cloud).trim() || "machine";
+    const proof = signBoundProof(kp.privateKeyBase64, { agentId: "connect", did: kp.did, action: "connect.start", amount: 0, scope: [host, project, machine, cloud ? "cloud" : "local"].join("\n") });
+    const r = await api("/connect/start", { method: "POST", body: JSON.stringify({ host, project, machine, did: kp.did, cloud, proof }) }, "", true);
+    if (r.status === 0) {
+        err(`✘ couldn't reach Decidio at ${API} - check your connection and run npx @decidio/sdk connect again.`);
+        return null;
+    }
+    if (r.status === 404 || r.status === 401) {
+        err(`✘ ${r.body?.message ?? "Connecting a coding assistant is available in the Decidio lab only."} (${API})`);
+        return null;
+    }
+    if (r.status === 429) {
+        err(`✘ ${r.body?.message ?? "Too many tries - wait a minute and try again."}`);
+        return null;
+    }
+    if (r.status !== 201 || typeof r.body?.pollSecret !== "string" || typeof r.body?.link !== "string") {
+        err(`✘ couldn't start a connection (${r.status}${r.body?.message ? `: ${r.body.message}` : ""}). Nothing was saved.`);
+        return null;
+    }
+    const p = { v: 1, api: API, root, project, host, machine, cloud, did: kp.did, key: kp.privateKeyBase64, code: String(r.body.code), link: String(r.body.link),
+        pollSecret: r.body.pollSecret, expiresAt: String(r.body.expiresAt), interval: Number(r.body.interval) || 2, startedAt: new Date().toISOString() };
+    mkdirSync(connectDir(), { recursive: true });
+    writeSecretFile(pendingConnectFile(root), JSON.stringify(p) + "\n");
+    if (typeof r.body.qr === "string")
+        pendingQr = r.body.qr;
+    return p;
+}
+let pendingQr = null;
+function readPendingConnect(root) {
+    const p = readJsonQuiet(pendingConnectFile(root));
+    return p && p.v === 1 && p.api === API && p.root === root && typeof p.pollSecret === "string" ? p : null;
+}
+function dropFile(f) { try {
+    rmSync(f, { force: true });
+}
+catch { } }
+const minutesLeft = (iso) => Math.max(0, Math.round((new Date(iso).getTime() - Date.now()) / 60_000));
+function showConnectLink(p, opened, tty) {
+    const title = `Connect ${connectHostLabel(p.host)} to Decidio`;
+    log(`${brand()}  ${bold(title)}`);
+    log(`  Open:  ${link(p.link)}`);
+    log(`  Code:  ${bold(p.code)}   ${dim("(the page shows the same code - only allow it if they match)")}`);
+    log(dim(`  ${p.project} · ${p.machine} · the link works for ${minutesLeft(p.expiresAt) || 1} more minute${minutesLeft(p.expiresAt) === 1 ? "" : "s"}${opened ? " · opened in your browser" : ""}`));
+    if (tty && pendingQr) {
+        log("");
+        for (const line of pendingQr.split("\n"))
+            if (line.trim())
+                log(`  ${line}`);
+        log(dim("  Scan with your phone's camera to allow it there."));
+    }
+}
+async function cmdConnect(opts) {
+    const host = (opts.host ?? "claude-code");
+    if (host !== "claude-code") {
+        err(`✘ connect knows Claude Code today (--host claude-code); "${opts.host}" is not supported yet.`);
+        return 2;
+    }
+    try {
+        assertSafeTransport(API, true);
+    }
+    catch (e) {
+        err(`✘ ${String(e?.message ?? e).replace(/^\[decidio\] /, "")}`);
+        return 1;
+    }
+    const root = projectRoot();
+    const tty = !!(process.stdin.isTTY && process.stdout.isTTY);
+    if (CREDS_FROM === "shell" || CREDS_FROM === ".env") {
+        log(`• this project already has Decidio credentials ${CREDS_FROM === "shell" ? "from your shell" : `in ${ENV_PATH}`} for "${process.env.DECIDIO_AGENT_ID ?? defaultAgentId()}" - the hook uses those, so connect leaves them alone.`);
+        log(dim(`  To use a connection instead, remove DECIDIO_API_TOKEN / DECIDIO_AGENT_ID from ${CREDS_FROM === "shell" ? "your shell" : ENV_PATH} and run npx @decidio/sdk connect again.`));
+        return finishConnect(root, null, opts, false);
+    }
+    const existing = loadConnection(root, API);
+    if (existing && !opts.force && new Date(existing.expiresAt).getTime() > Date.now())
+        return finishConnect(root, existing, opts, false);
+    if (opts.wait)
+        return waitConnect(root, opts, false);
+    let p = readPendingConnect(root);
+    if (!p || p.host !== host || new Date(p.expiresAt).getTime() <= Date.now() + 15_000)
+        p = await startConnect(root, host);
+    if (!p)
+        return 1;
+    const opened = !opts.noBrowser && localDesktop() && openInBrowser(p.link);
+    showConnectLink(p, opened, tty);
+    if (tty) {
+        log("");
+        return waitConnect(root, opts, true);
+    }
+    log("");
+    log(`Next: allow it at the link above, then run  ${bold("npx @decidio/sdk connect --wait")}  - it finishes by itself (nothing else to type).`);
+    log(dim("Assistants: show the person the link and the code above, then run npx @decidio/sdk connect --wait."));
+    return 0;
+}
+async function waitConnect(root, opts, interactive) {
+    const p = readPendingConnect(root);
+    if (!p) {
+        const c = loadConnection(root, API);
+        if (c)
+            return finishConnect(root, c, opts, false);
+        err("✘ no connection is in progress for this project - start one: npx @decidio/sdk connect");
+        return 1;
+    }
+    const deadline = interactive ? new Date(p.expiresAt).getTime() + 5_000 : Math.min(new Date(p.expiresAt).getTime() + 5_000, Date.now() + CONNECT_WAIT_S() * 1000);
+    const spin = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+    let i = 0, misses = 0;
+    if (!interactive)
+        err(`· waiting for the connection to be allowed at ${p.link} (code ${p.code}; up to ${Math.round((deadline - Date.now()) / 1000)} s)`);
+    while (Date.now() < deadline) {
+        const r = await api("/connect/poll", { method: "POST", headers: { "x-decidio-connect-secret": p.pollSecret }, body: "{}" }, "", true);
+        if (r.status === 200 && r.body?.status === "connected" && typeof r.body.token === "string") {
+            if (interactive && TTY_OUT)
+                process.stderr.write("\r\x1b[K");
+            const c = { v: 1, api: API, root, project: p.project, host: p.host, machine: p.machine, cloud: p.cloud, agentId: String(r.body.agentId), did: p.did, key: p.key,
+                token: r.body.token, jti: String(r.body.jti), expiresAt: String(r.body.expiresAt), workspaceId: String(r.body.workspaceId), workspaceName: r.body.workspace?.name ?? null,
+                approver: r.body.approver?.name ?? null, approvedBy: r.body.approvedBy?.name ?? null, appUrl: typeof r.body.appUrl === "string" ? r.body.appUrl : null, connectedAt: new Date().toISOString() };
+            mkdirSync(connectDir(), { recursive: true });
+            try {
+                writeSecretFile(connectionFile(root), JSON.stringify(c) + "\n");
+            }
+            catch (e) {
+                err(`✘ connected, but this machine's credentials could not be written (${e?.message ?? e}) - run npx @decidio/sdk connect again (the server keeps nothing to collect twice).`);
+                return 1;
+            }
+            dropFile(pendingConnectFile(root));
+            return finishConnect(root, c, opts, true);
+        }
+        if (r.status === 403 && r.body?.status === "denied") {
+            dropFile(pendingConnectFile(root));
+            if (interactive && TTY_OUT)
+                process.stderr.write("\r\x1b[K");
+            err("✘ the connection was refused on the web (Not me). Nothing was saved.");
+            return 3;
+        }
+        if ((r.status === 404 || r.status === 410) && (r.body?.status === "expired" || r.body?.status === "collected")) {
+            dropFile(pendingConnectFile(root));
+            if (interactive && TTY_OUT)
+                process.stderr.write("\r\x1b[K");
+            err(r.body.status === "collected" ? "✘ this connection was already collected by another run - start a fresh one: npx @decidio/sdk connect" : "✘ the link expired before it was allowed - start a fresh one: npx @decidio/sdk connect");
+            return 3;
+        }
+        if (r.status === 0 && ++misses > 10) {
+            err(`✘ lost touch with Decidio at ${API} - check your connection, then run npx @decidio/sdk connect --wait again.`);
+            return 1;
+        }
+        if (interactive && TTY_OUT)
+            process.stderr.write(`\r${spin[i++ % spin.length]} waiting for you to allow it in the browser… ${dim(`(${minutesLeft(p.expiresAt)} min left · Ctrl-C stops waiting; npx @decidio/sdk connect --wait picks it up again)`)}`);
+        await new Promise((res) => setTimeout(res, (r.status === 429 ? 2 : 1) * Math.max(1, p.interval) * 1000));
+    }
+    if (interactive && TTY_OUT)
+        process.stderr.write("\r\x1b[K");
+    log(`• still waiting for it to be allowed: ${link(p.link)} (code ${p.code}, ${minutesLeft(p.expiresAt)} min left). Run  npx @decidio/sdk connect --wait  again once it is.`);
+    return 1;
+}
+async function finishConnect(root, c, opts, fresh) {
+    if (c) {
+        promoteConnection(c);
+        CREDS_FROM = "connection";
+    }
+    const cloud = inCloudSession();
+    const shared = opts.team || cloud;
+    const plugin = !cloud && decidioPluginEnabled(root);
+    if (!plugin) {
+        const rc = await cmdHookInstall({ project: shared, dir: root, quiet: true });
+        if (rc !== 0)
+            return rc;
+    }
+    const probe = await api("/agent/status/doctor-scope-probe", {}, process.env.DECIDIO_API_TOKEN, true);
+    const verified = probe.status === 404;
+    const settings = lastHookInstall ? relative(root, lastHookInstall.settingsPath).split(pathSep).join("/") || lastHookInstall.settingsPath : ".claude/settings.json";
+    const hostName = connectHostLabel(c?.host ?? "claude-code");
+    if (c) {
+        log(`✔ ${fresh ? "Connected to Decidio" : "Already connected to Decidio"}${c.workspaceName ? ` - workspace ${c.workspaceName}` : ""}${fresh && c.approvedBy ? `, allowed by ${c.approvedBy}` : ""}`);
+        log(`✔ Approvals go to ${c.approver ?? "the approver you picked"} - on the phone app, Slack, Teams or the web`);
+    }
+    if (!verified) {
+        err(probe.status === 401 || probe.status === 403
+            ? `✘ Decidio refused this connection's token (${probe.status}) - it was revoked or has expired. Reconnect: npx @decidio/sdk connect --force`
+            : `⚠ couldn't check the token just now (${probe.status || "no answer"}) - the hooks are on; a gated command will say if anything is wrong.`);
+        if (probe.status === 401 || probe.status === 403)
+            return 1;
+    }
+    const changed = !plugin && lastHookInstall && (lastHookInstall.pre !== "kept" || lastHookInstall.post !== "kept");
+    log(plugin
+        ? `✔ ${hostName} asks before destructive commands in this project (the Decidio plugin's hooks)`
+        : `✔ ${hostName} asks before destructive commands in this project (${settings})`);
+    if (changed)
+        log(dim(`  Claude Code picks the settings change up by itself - if a destructive command is not asked about, open /hooks once (or restart it).`));
+    if (c)
+        log(dim(`  Credentials: ${connectionFile(root)} (outside the repository, owner-only) · until ${c.expiresAt.slice(0, 10)}${cloud ? " · this cloud machine only - a fresh one refuses destructive commands until it connects again" : ""}`));
+    if (!plugin && (shared || process.platform === "win32") && !sameDir(realOrSame(process.cwd()), root))
+        log(dim(`  Claude Code reads ${settings} from the folder it starts in - start it at ${root}.`));
+    if (cloud && !opts.team)
+        log(`• A cloud session reads only the repository's ${settings}, so the hooks are there - not committed. Ask the person before committing it: committed, every cloud session of this repository asks too, and so does every teammate's clone (a teammate connects with npx @decidio/sdk connect).`);
+    else if (shared)
+        log(`• Commit ${settings}: every clone then asks before destructive commands (a teammate connects with npx @decidio/sdk connect).`);
+    if (fresh)
+        log(dim(`  Try it: ask ${hostName} to delete a scratch folder with rm -rf - the approval reaches ${c?.approver ?? "the approver"} on their phone.`));
+    return 0;
+}
+const DECIDIO_PLUGIN = "decidio-approvals";
+function decidioPluginEnabled(root) {
+    const home = process.platform === "win32" ? (SHELL_ENV.USERPROFILE ?? homedir()) : (SHELL_ENV.HOME ?? homedir());
+    for (const f of [joinPath(root, ".claude", "settings.local.json"), joinPath(root, ".claude", "settings.json"), joinPath(home, ".claude", "settings.json")]) {
+        const ep = readJsonQuiet(f)?.enabledPlugins;
+        if (!ep || typeof ep !== "object" || Array.isArray(ep))
+            continue;
+        const named = Object.entries(ep).find(([k]) => k.split("@")[0] === DECIDIO_PLUGIN);
+        if (named)
+            return named[1] === true;
+    }
+    return false;
+}
+async function cmdDisconnect() {
+    const root = projectRoot();
+    const c = loadConnection(root, API);
+    dropFile(pendingConnectFile(root));
+    if (!c) {
+        log("• this project isn't connected on this machine - nothing to do.");
+        return 0;
+    }
+    try {
+        writeSecretFile(connectionFile(root), JSON.stringify({ ...c, token: "", jti: "", disconnected: true }) + "\n");
+    }
+    catch (e) {
+        err(`✘ couldn't update ${connectionFile(root)} (${e?.message ?? e}) - delete it by hand to disconnect.`);
+        return 1;
+    }
+    log(`✔ disconnected this project on this machine - its token is deleted.`);
+    log(`  Destructive commands are now refused until you connect again (the hooks stay on: switching Decidio off needs a person's approval).`);
+    log(dim(`  "${c.agentId}" stays listed in Decidio until its token expires (${c.expiresAt.slice(0, 10)}); to end it now, revoke it on the Agents page${c.appUrl ? `: ${c.appUrl.replace(/\/+$/, "")}/connect/agents` : ""}.`));
+    return 0;
+}
 async function inviteApprover(email) {
     if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
         err(`✘ --approver needs an email address (got "${email}")`);
@@ -4911,7 +5289,7 @@ async function cmdGithubInit(opts) {
             log(`  ${line}`);
     }
     const agentsRel = "AGENTS.md", agentsAbs = joinPath(root, agentsRel);
-    const appUrl = (process.env.DECIDIO_APP_URL || apiUrl.replace(/^https:\/\/(decidio-api\.onrender\.com|mcp\.decidioai\.com)$/, "https://app.decidioai.com")).replace(/\/$/, "");
+    const appUrl = appUrlFor(apiUrl);
     const section = agentsMdSection(appUrl);
     if (!plainRepoPath(root, agentsRel))
         err(`✘ ${agentsRel} is a symbolic link - nothing was written through it`);
@@ -5025,6 +5403,17 @@ APPROVALS AND RECEIPTS
                                        (never the receipt's own issuer field; --allow-unpinned: structural check only)
 
 CODING AGENTS (Claude Code)
+  npx @decidio/sdk connect             connect this project's coding assistant in one tap: prints a link and a short
+                                       code (a QR and the browser too, on a real terminal); the workspace owner allows
+                                       it on the web, then this machine gets an ask-only credential (kept outside the
+                                       repository) and the hooks below switch on. Your assistant can run it for you.
+  npx @decidio/sdk connect --wait      finish a connect started by an assistant: returns once it is allowed, within 90 s
+                                       (exit 0 connected · 3 refused or expired · 1 still waiting, run it again)
+                                       --team: the shared .claude/settings.json every clone reads (default: yours
+                                       alone; a cloud session reads only the shared file, so there it is always that
+                                       one) · --no-browser · --force: a fresh token for this machine
+  npx @decidio/sdk disconnect          delete this machine's connection for this project (destructive commands are then
+                                       refused until you connect again; the hooks stay on)
   npx @decidio/sdk hook install [--project] [--approver <email>] [--cli <path>]
                                        a person approves Claude Code's destructive shell commands before they run
                                        (rm -rf, git push --force, DROP TABLE, terraform apply, kubectl delete,
@@ -5129,7 +5518,8 @@ NOTES
   Exit codes: 0 success · 1 failure or honest no-op (e.g. replay refused) · 2 usage error ·
   3 quickstart stopped at the human moment (headless: routed, but nothing executed and no
   receipt written — pass --auto-approve-demo for a run that completes unattended), or
-  hook wait: the approver said no. hook pretool/posttool always exit 0 (their answer is the JSON).
+  hook wait: the approver said no, or connect --wait: the connection was refused or expired (1 there: still
+  waiting - run it again). hook pretool/posttool always exit 0 (their answer is the JSON).
   Errors, and usage shown on ERROR paths, go to stderr; stdout carries results only (safe to
   pipe). Asked-for help — including this bare invocation — IS a result, so it prints here.
   Docs: the README that shipped with this package — node_modules/@decidio/sdk/README.md
@@ -5271,6 +5661,8 @@ async function main(argv) {
         logout: { flags: [] },
         phone: { flags: [] },
         init: { flags: ["--unique", "--force"], valued: ["--expires-days"] },
+        connect: { flags: ["--wait", "--no-browser", "--team", "--force"], valued: ["--host"] },
+        disconnect: { flags: [] },
         doctor: { flags: [] },
         approvals: { flags: ["--json", "--mine"], valued: ["--reason"] },
         receipt: { flags: ["--json"] },
@@ -5320,7 +5712,7 @@ async function main(argv) {
                 return 2;
             }
         }
-        const MAX_POS = { login: 1, logout: 0, phone: 0, quickstart: 1, init: 1, doctor: 0, receipt: 1, tokens: 2, dev: 0, hook: 2, github: 1, decisions: 1 };
+        const MAX_POS = { login: 1, logout: 0, phone: 0, quickstart: 1, init: 1, connect: 0, disconnect: 0, doctor: 0, receipt: 1, tokens: 2, dev: 0, hook: 2, github: 1, decisions: 1 };
         const exemptTail = (cmd === "approvals" && (positionals[0] === "approve" || positionals[0] === "reject")) || (cmd === "hook" && positionals[0] === "justify") || cmd === "verify";
         if (!exemptTail && cmd === "approvals" && positionals.length > 0) {
             err(`✘ unknown approvals subcommand "${positionals[0]}" — use approve or reject (or no subcommand to list).`);
@@ -5478,6 +5870,8 @@ async function main(argv) {
             }
             return cmdContext(sub, pos.slice(1), { title: valuedOpt(argsIn, "--title"), trigger: valuedOpt(argsIn, "--trigger"), team: valuedOpt(argsIn, "--team"), unit: valuedOpt(argsIn, "--unit"), org: argsIn.includes("--org"), here: argsIn.includes("--here"), pack: valuedOpt(argsIn, "--pack"), chatgpt: argsIn.includes("--chatgpt"), json: argsIn.includes("--json") });
         }
+        case "connect": return cmdConnect({ wait: argsIn.includes("--wait"), host: valuedOpt(argsIn, "--host"), noBrowser: argsIn.includes("--no-browser"), team: argsIn.includes("--team"), force: argsIn.includes("--force") });
+        case "disconnect": return cmdDisconnect();
         case "hook": {
             const VALUED = ["--timeout", "--approver", "--cli"];
             const pos = argsIn.filter((x, i) => !x.startsWith("-") && !VALUED.includes(argsIn[i - 1] ?? ""));

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.9.0   # tracks the SDK release - checked by packages/conformance/manifests.mjs
+  version: 0.10.0   # tracks the SDK release - checked by packages/conformance/manifests.mjs
   description: >
     Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
     receive the signed resume webhook when a routed action is decided. Every outcome seals a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.9.0"
+    "@decidio/verify": "0.10.0"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {