@decidio/sdk 0.1.8 → 0.1.10

package/dist/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync } from "node:fs";
-import { randomBytes, createHash } from "node:crypto";
+import { randomBytes } from "node:crypto";
+import { userInfo } from "node:os";
 import { createServer } from "node:http";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
 import { generateKeypair } from "./signing.js";
 import { withApproval, DecidioRateLimitError } from "./index.js";
-import { verifyReceipt } from "@decidio/verify";
+import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
     try {
         return createRequire(import.meta.url)("../package.json").version;
@@ -16,24 +17,35 @@ const VERSION = (() => {
         return "unknown";
     }
 })();
+let envWarned = false;
 function readEnvFile() {
     const out = {};
-    if (existsSync(".env"))
-        for (const line of readFileSync(".env", "utf8").split(/\r?\n/)) {
-            const m = line.match(/^\s*([A-Z_]+)=(.*)$/);
-            if (m)
-                out[m[1]] = m[2];
+    try {
+        if (existsSync(".env"))
+            for (const line of readFileSync(".env", "utf8").split(/\r?\n/)) {
+                const m = line.match(/^\s*([A-Z_]+)=(.*)$/);
+                if (m)
+                    out[m[1]] = m[2];
+            }
+    }
+    catch (e) {
+        if (!envWarned) {
+            envWarned = true;
+            console.error(`⚠ could not read .env (${e?.code ?? e?.message ?? e}) — continuing without it. Fix its permissions if you meant it to load.`);
         }
+    }
     return out;
 }
-for (const [k, v] of Object.entries(readEnvFile())) {
-    if (k === "DECIDIO_SESSION_TOKEN") {
-        console.error("⚠ ignoring DECIDIO_SESSION_TOKEN found in .env — session tokens belong in your shell or CI secret store, never on disk. Remove that line; export it in the shell instead.");
-        continue;
+const OFFLINE_CMD = ["verify", "--version", "-v", "-V", "version", "--help", "-h", "help", undefined].includes(process.argv[2]);
+if (!OFFLINE_CMD)
+    for (const [k, v] of Object.entries(readEnvFile())) {
+        if (k === "DECIDIO_SESSION_TOKEN") {
+            console.error("⚠ ignoring DECIDIO_SESSION_TOKEN found in .env — session tokens belong in your shell or CI secret store, never on disk. Remove that line; export it in the shell instead.");
+            continue;
+        }
+        if (process.env[k] === undefined)
+            process.env[k] = v;
     }
-    if (process.env[k] === undefined)
-        process.env[k] = v;
-}
 const API = (process.env.DECIDIO_API_URL ?? "https://decidio-api.onrender.com").replace(/\/$/, "");
 const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
@@ -46,6 +58,10 @@ async function api(path, init = {}, bearer) {
         err(`· decidio → ${API}${process.env.DECIDIO_API_URL ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
     }
     const auth = bearer ?? TOKEN();
+    if (auth && /^http:[/][/]/i.test(API) && !/^http:[/][/](localhost|127.0.0.1|.::1.)([:/]|$)/i.test(API)) {
+        err(`✘ refusing to send credentials over plaintext http to ${API} — use https, or localhost for local dev. Nothing was sent.`);
+        process.exit(1);
+    }
     let res;
     try {
         res = await fetch(API + path, { ...init, headers: { "content-type": "application/json", ...(auth ? { authorization: `Bearer ${auth}` } : {}), ...(init.headers ?? {}) } });
@@ -80,18 +96,46 @@ function writeSecretFile(path, body) {
     catch { }
     if (process.platform === "win32") {
         try {
-            execFileSync("icacls", [path, "/inheritance:r", "/grant:r", `${process.env.USERNAME ?? process.env.USER ?? ""}:F`], { stdio: "ignore" });
+            execFileSync("icacls", [path, "/inheritance:r", "/grant:r", `${effectiveUser()}:F`], { stdio: "ignore" });
         }
         catch {
             console.warn(`⚠ could not restrict ${path} to owner-only on this Windows volume — it keeps the directory's inherited permissions. For production, move these values to a secret manager.`);
         }
     }
 }
+function effectiveUser() {
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return process.env.USERNAME ?? process.env.USER ?? "";
+    }
+}
 function upsertEnv(updates) {
-    const cur = readEnvFile();
-    const merged = { ...cur, ...updates };
-    const body = Object.entries(merged).map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
-    writeSecretFile(ENV_PATH, body);
+    const remaining = { ...updates };
+    const updatedKeys = new Set();
+    const lines = [];
+    try {
+        if (existsSync(ENV_PATH))
+            for (const line of readFileSync(ENV_PATH, "utf8").split(/\r?\n/)) {
+                const m = line.match(/^\s*([A-Z_]+)=/);
+                if (m && updatedKeys.has(m[1]))
+                    continue;
+                if (m && m[1] in remaining) {
+                    lines.push(`${m[1]}=${remaining[m[1]]}`);
+                    updatedKeys.add(m[1]);
+                    delete remaining[m[1]];
+                }
+                else
+                    lines.push(line);
+            }
+    }
+    catch { }
+    while (lines.length && lines[lines.length - 1] === "")
+        lines.pop();
+    for (const [k, v] of Object.entries(remaining))
+        lines.push(`${k}=${v}`);
+    writeSecretFile(ENV_PATH, lines.join("\n") + "\n");
 }
 function ensureGitignore() {
     const entries = [".env", ".env.quickstart", ".env.*.bak", ".decidio-pending/"];
@@ -104,7 +148,7 @@ function ensureGitignore() {
 }
 function ask(question, mute = false) {
     return new Promise((resolve) => {
-        const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
         if (mute) {
             const anyRl = rl;
             const write = anyRl._writeToOutput?.bind(rl);
@@ -112,23 +156,23 @@ function ask(question, mute = false) {
                 write?.(s); };
         }
         rl.question(question, (answer) => { rl.close(); if (mute)
-            process.stdout.write("\n"); resolve(answer.trim()); });
+            process.stderr.write("\n"); resolve(answer.trim()); });
     });
 }
 async function acquireSession(purpose) {
     if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
         err(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
-        log(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
+        err(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
         return null;
     }
     if (process.env.DECIDIO_SESSION_TOKEN)
         return process.env.DECIDIO_SESSION_TOKEN;
     if (!process.stdin.isTTY) {
         err(`✘ ${purpose} needs a Decidio workspace sign-in, and this terminal can't prompt for one.`);
-        log(`  Fix: set DECIDIO_SESSION_TOKEN and re-run. To mint one:`);
-        log(`    1. Request a sign-in link from your workspace's sign-in screen (or use your welcome email).`);
-        log(`    2. POST its ?login= value — the response's "token" is your session token:`);
-        log(`       curl -X POST ${API}/demo/login-consume -H "content-type: application/json" -d '{"token":"<login value>"}'`);
+        err(`  Fix: set DECIDIO_SESSION_TOKEN and re-run. To mint one:`);
+        err(`    1. Request a sign-in link from your workspace's sign-in screen (or use your welcome email).`);
+        err(`    2. POST its ?login= value — the response's "token" is your session token:`);
+        err(`       curl -X POST ${API}/demo/login-consume -H "content-type: application/json" -d '{"token":"<login value>"}'`);
         return null;
     }
     log(`${purpose} needs your Decidio workspace sign-in (${API}).`);
@@ -160,17 +204,17 @@ async function acquireSession(purpose) {
     return null;
 }
 async function cmdInit(agentId, opts = {}) {
-    log(`Registering agent "${agentId}" with Decidio at ${API}…`);
+    err(`Registering agent "${agentId}" with Decidio at ${API}…`);
     const existingEnv = readEnvFile();
     const existingKey = existingEnv.DECIDIO_AGENT_KEY;
     const sourceSystem = process.env.DECIDIO_SOURCE_SYSTEM || existingEnv.DECIDIO_SOURCE_SYSTEM;
     if (existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId && !opts.force) {
         err(`✘ this directory's .env already holds the key for a DIFFERENT agent ("${existingEnv.DECIDIO_AGENT_ID}").`);
-        log(`  Registering "${agentId}" here would overwrite that key — and a private key that is`);
-        log(`  overwritten is gone for good (it never left this machine). Nothing was written.`);
-        log(`  Pick one:`);
-        log(`    1. New directory (cleanest): mkdir ${agentId} && cd ${agentId} && npx @decidio/sdk init ${agentId}`);
-        log(`    2. Replace the old agent here, backing its .env up first: npx @decidio/sdk init ${agentId} --force`);
+        err(`  Registering "${agentId}" here would overwrite that key — and a private key that is`);
+        err(`  overwritten is gone for good (it never left this machine). Nothing was written.`);
+        err(`  Pick one:`);
+        err(`    1. New directory (cleanest): mkdir ${agentId} && cd ${agentId} && npx @decidio/sdk init ${agentId}`);
+        err(`    2. Replace the old agent here, backing its .env up first: npx @decidio/sdk init ${agentId} --force`);
         return 1;
     }
     const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
@@ -194,10 +238,10 @@ async function cmdInit(agentId, opts = {}) {
         else {
             const suggestion = `${agentId}-${randomBytes(2).toString("hex")}`;
             err(`✘ "${agentId}" is already registered in this workspace, and its private key is not on this machine`);
-            log(`  (keys never leave the machine that generated them — likely a previous run, or another directory).`);
-            log(`  Nothing was written. Two ways forward:`);
-            log(`    1. Fresh agent (most common): npx @decidio/sdk init ${suggestion}`);
-            log(`    2. Reuse "${agentId}": restore its original DECIDIO_AGENT_KEY into .env here, then re-run init.`);
+            err(`  (keys never leave the machine that generated them — likely a previous run, or another directory).`);
+            err(`  Nothing was written. Two ways forward:`);
+            err(`    1. Fresh agent (most common): npx @decidio/sdk init ${suggestion}`);
+            err(`    2. Reuse "${agentId}": restore its original DECIDIO_AGENT_KEY into .env here, then re-run init.`);
             return 1;
         }
     }
@@ -208,7 +252,7 @@ async function cmdInit(agentId, opts = {}) {
     }
     else {
         err(`✘ registration failed (${r.status}): ${JSON.stringify(r.body)}`);
-        log(`  Fix the cause above and re-run — init is safe to repeat.`);
+        err(`  Fix the cause above and re-run — init is safe to repeat.`);
         return 1;
     }
     let agentToken, workspaceId, tokenJti;
@@ -221,10 +265,13 @@ async function cmdInit(agentId, opts = {}) {
             workspaceId = mint.body.workspaceId;
             tokenJti = mint.body.jti;
             log(`✔ minted the agent's API token — floor-limited: it can request authorization, poll status and report confirmation; it cannot administer the workspace or approve anything${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ` (${expiresInDays} days)`}`);
+            const superseded = Array.isArray(mint.body.supersededJtis) ? mint.body.supersededJtis : [];
+            for (const s of superseded)
+                log(`  • this replaces the agent's previous token (jti ${s}) — now REVOKED: the server keeps one active token per agent. Anything still using it will 401.`);
         }
         else if (session) {
             err(`✘ could not mint the agent's API token (${mint.status}): ${JSON.stringify(mint.body)}`);
-            log(`  Without it the SDK has no runtime credential. Fix the cause above and re-run init — it's safe to repeat.`);
+            err(`  Without it the SDK has no runtime credential. Fix the cause above and re-run init — it's safe to repeat.`);
             return 1;
         }
         else {
@@ -286,7 +333,9 @@ async function cmdInit(agentId, opts = {}) {
 async function cmdDoctor() {
     const env = readEnvFile();
     let ok = true;
+    let warned = 0;
     const line = (good, label) => { log(`${good ? "✔" : "✘"} ${label}`); ok = ok && good; };
+    const warn = (label) => { warned++; log(`⚠ ${label}`); };
     log(`✔ API URL: ${API}${(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL) ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
     line(!!(process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID), `agent id: ${process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID || "(unset — run: npx @decidio/sdk init <agent-name>)"}`);
     const secret = process.env.DECIDIO_WEBHOOK_SECRET || env.DECIDIO_WEBHOOK_SECRET;
@@ -296,21 +345,26 @@ async function cmdDoctor() {
     if (signing)
         log("✔ signing key: set — the agent can prove its identity, making it ELIGIBLE for policy auto-approve. Whether a rule matches is your workspace policy's decision; with no matching rule every request routes to a human (deny-by-default).");
     else
-        log("⚠ signing key: MISSING (DECIDIO_AGENT_KEY/DID) — the agent can't prove identity, so EVERY request routes to a human. Run `npx @decidio/sdk init` to generate one.");
+        warn("signing key: MISSING (DECIDIO_AGENT_KEY/DID) — the agent can't prove identity, so EVERY request routes to a human. Run `npx @decidio/sdk init` to generate one.");
     const h = await api("/api/health", {}, "");
     line(h.status >= 200 && h.status < 300, `connectivity: API reachable (${h.status})`);
     const tok = process.env.DECIDIO_API_TOKEN || env.DECIDIO_API_TOKEN;
+    if (!tok) {
+        line(false, "agent token: NOT CONFIGURED — no DECIDIO_API_TOKEN in this directory's .env or your environment. Run `npx @decidio/sdk init <agent-name>` to register an agent and mint one.");
+        log(warned ? `\ndoctor: fix the ✘ items above, then re-run \`npx @decidio/sdk doctor\`. (${warned} warning${warned === 1 ? "" : "s"})` : "\ndoctor: fix the ✘ items above, then re-run `npx @decidio/sdk doctor`.");
+        return 1;
+    }
     if (tok) {
         try {
             const payload = JSON.parse(Buffer.from(tok.split(".")[1] ?? "", "base64url").toString("utf8"));
             if (typeof payload?.exp === "number") {
                 const msLeft = payload.exp * 1000 - Date.now();
-                const days = Math.floor(msLeft / 86_400_000);
+                const days = Math.floor((msLeft + 60_000) / 86_400_000);
                 const left = msLeft < 86_400_000 ? `${Math.max(1, Math.floor(msLeft / 3_600_000))} hour(s)` : `${days} day(s)`;
                 if (msLeft < 0)
                     line(false, `agent token: EXPIRED ${-days} day(s) ago — re-run \`npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}\` to mint a fresh one.`);
                 else if (days <= 14)
-                    log(`⚠ agent token: expires in ${left} — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
+                    warn(`agent token: expires in ${left} — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
                 else
                     log(`✔ agent token: valid for another ${days} days`);
             }
@@ -319,7 +373,7 @@ async function cmdDoctor() {
     }
     const rec = await api("/api/records");
     if (rec.status >= 200 && rec.status < 300)
-        log("✔ token scope: session/admin (init, approvals and receipt work from this env)");
+        warn("token scope: SESSION/ADMIN-capable — this credential can approve and administer, and it does not belong in an agent's environment (the agent runtime needs only the floor-limited token init mints). Move it to your shell/CI secret store.");
     else if (rec.status === 401) {
         const probe = await api("/agent/status/doctor-scope-probe");
         if (probe.status === 404)
@@ -327,11 +381,12 @@ async function cmdDoctor() {
         else if (probe.status === 401)
             line(false, "token: REJECTED on the agent floor too — it's invalid or expired. Re-run `npx @decidio/sdk init` to mint a fresh one.");
         else
-            log(`⚠ token scope: agent-floor probe returned ${probe.status} — inconclusive`);
+            warn(`token scope: agent-floor probe returned ${probe.status} — inconclusive`);
     }
     else
-        log(`⚠ token scope: unexpected ${rec.status} from /api/records`);
-    log(ok ? "\ndoctor: all green." : "\ndoctor: fix the ✘ items above, then re-run `npx @decidio/sdk doctor`.");
+        warn(`token scope: unexpected ${rec.status} from /api/records`);
+    const warnNote = warned ? ` (${warned} warning${warned === 1 ? "" : "s"} above — working, worth a look)` : "";
+    log(ok ? `\ndoctor: all green.${warnNote}` : "\ndoctor: fix the ✘ items above, then re-run `npx @decidio/sdk doctor`.");
     return ok ? 0 : 1;
 }
 async function cmdApprovals(sub, id, reason, flags = {}) {
@@ -387,6 +442,8 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
         return 1;
     }
     const cards = r.body?.cards ?? [];
+    if (cards.length >= 50)
+        err('⚠ this view is capped at 50 items by the server — older pending approvals may exist beyond it.');
     const pending = cards.filter((c) => c.isAgentRequest && c.status !== "sealed");
     const myAgent = process.env.DECIDIO_AGENT_ID;
     const isMine = (c) => !!myAgent && typeof c.title === "string" && c.title.startsWith(`${myAgent}:`);
@@ -472,85 +529,6 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     return 0;
 }
-function parseReceiptStrict(text, file) {
-    const value = JSON.parse(text);
-    const stack = [];
-    let i = 0;
-    const readString = () => {
-        let out = "";
-        i++;
-        while (i < text.length) {
-            const ch = text[i];
-            if (ch === "\\") {
-                out += text[i] + text[i + 1];
-                i += 2;
-                continue;
-            }
-            if (ch === '"') {
-                i++;
-                return out;
-            }
-            out += ch;
-            i++;
-        }
-        return out;
-    };
-    while (i < text.length) {
-        const ch = text[i];
-        if (ch === '"') {
-            const s = readString();
-            let j = i;
-            while (j < text.length && /\s/.test(text[j]))
-                j++;
-            if (text[j] === ":" && stack.length > 0) {
-                const key = JSON.parse(`"${s}"`);
-                const top = stack[stack.length - 1];
-                if (top.has(key))
-                    throw new Error(`${file}: duplicate JSON key ${JSON.stringify(key)} — RFC 8785 requires duplicate-free input, and different parsers disagree on which value is real`);
-                top.add(key);
-            }
-            continue;
-        }
-        if (ch === "{")
-            stack.push(new Set());
-        else if (ch === "}")
-            stack.pop();
-        i++;
-    }
-    return value;
-}
-function chainOf(vcs, expectedIssuer) {
-    if (!vcs.length)
-        return { valid: false, length: 0, reason: "no receipts supplied" };
-    const issuers = [...new Set(vcs.map((v) => String(v?.issuer ?? "")))];
-    if (issuers.length > 1)
-        return { valid: false, length: 0, reason: `these receipts come from ${issuers.length} DIFFERENT issuers — a chain must be issued end to end by one issuer` };
-    let prev = null;
-    let anchor = "segment";
-    for (let i = 0; i < vcs.length; i++) {
-        const r = verifyReceiptDoor(vcs[i], expectedIssuer);
-        if (!r.valid)
-            return { valid: false, length: i, reason: `receipt ${i} (${r.recordId ?? "?"}) invalid: ${r.reason}` };
-        const cs = vcs[i]?.credentialSubject ?? {};
-        if (i === 0)
-            anchor = (cs.prevHash ?? null) === null ? "genesis" : "segment";
-        else if ((cs.prevHash ?? null) !== prev)
-            return { valid: false, length: i, reason: `receipt ${i} does not follow receipt ${i - 1} (prevHash mismatch)` };
-        prev = cs.contentHash;
-    }
-    return { valid: true, length: vcs.length, anchor };
-}
-function verifyReceiptDoor(vc, expectedIssuer) {
-    const res = verifyReceipt(vc, expectedIssuer);
-    if (!res.valid && res.reason === "issuer DID is not the expected issuer") {
-        const cs = vc?.credentialSubject ?? {};
-        const derive = (canonical, prevHash) => createHash("sha256").update((prevHash ?? "") + canonical).digest("hex");
-        const bound = typeof cs.recordCanonical === "string" && typeof cs.contentHash === "string"
-            && derive(cs.recordCanonical, typeof cs.prevHash === "string" ? cs.prevHash : null) === cs.contentHash;
-        return { ...res, contentBound: bound, recordId: typeof cs.recordId === "string" ? cs.recordId : res.recordId, reason: "issuer DID is not the expected issuer (the receipt itself may be internally consistent — it was just not issued by who you pinned)" };
-    }
-    return res;
-}
 function cmdVerify(argsIn) {
     let expectedIssuer;
     const files = [];
@@ -582,38 +560,20 @@ function cmdVerify(argsIn) {
         err("  Verifies Authority Receipts OFFLINE — signature, content binding, and (for several files) chain order.");
         return 2;
     }
-    const texts = [];
+    const texts = new Map();
     for (const f of files) {
         try {
-            texts.push(readFileSync(f, "utf8"));
+            texts.set(f, readFileSync(f, "utf8"));
         }
         catch (e) {
             err(`✘ cannot read ${f}: ${e?.code === "ENOENT" ? "no such file" : e?.message ?? e} (nothing was verified)`);
             return 1;
         }
     }
-    let vcs;
-    try {
-        vcs = files.map((f, i) => parseReceiptStrict(texts[i], f));
-    }
-    catch (e) {
-        log(`✘ INVALID  ${String(e?.message ?? e)}`);
-        return 1;
-    }
-    let allOk = true;
-    vcs.forEach((vc, i) => {
-        const res = verifyReceiptDoor(vc, expectedIssuer);
-        allOk = allOk && res.valid;
-        log(`${res.valid ? "✔ VALID  " : "✘ INVALID"}  ${files[i]}`);
-        log(`    record: ${res.recordId ?? "?"}   issuer: ${res.issuer}${expectedIssuer ? "" : "  (unpinned — pass --issuer to bind to your workspace's DID)"}`);
-        log(`    content-bound: ${res.contentBound}${res.reason ? `   reason: ${res.reason}` : ""}`);
-    });
-    if (vcs.length > 1) {
-        const c = chainOf(vcs, expectedIssuer);
-        allOk = allOk && c.valid;
-        log(`\nchain: ${c.valid ? "✔ intact" : "✘ broken"} (${c.length}/${vcs.length})${c.valid ? (c.anchor === "segment" ? " — segment: ordering proven from the FIRST file forward; history before it is not covered by these receipts" : " — from genesis") : ""}${c.reason ? ` — ${c.reason}` : ""}`);
-    }
-    return allOk ? 0 : 1;
+    const { ok, lines } = runVerify(files, expectedIssuer, (f) => texts.get(f));
+    for (const l of lines)
+        log(l);
+    return ok ? 0 : 1;
 }
 async function cmdQuickstart(opts = {}) {
     const t0 = Date.now();
@@ -654,8 +614,9 @@ async function cmdQuickstart(opts = {}) {
             const prev = readFileSync(envFile, "utf8");
             const prevId = prev.match(/^DECIDIO_AGENT_ID=(.+)$/m)?.[1];
             if (prevId && prevId !== agentId) {
-                writeSecretFile(".env.quickstart.bak", prev);
-                log(`  ✔ previous tour agent (${prevId}) backed up to .env.quickstart.bak — its key would otherwise be unrecoverable`);
+                const bak = `.env.quickstart.${prevId.replace(/[^\w.-]/g, "_")}.bak`;
+                writeSecretFile(bak, prev);
+                log(`  ✔ previous tour agent (${prevId}) backed up to ${bak} — its key would otherwise be unrecoverable (one backup PER agent: serial tours never clobber an earlier backup)`);
             }
         }
         writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
@@ -714,7 +675,10 @@ async function cmdQuickstart(opts = {}) {
     }
     else {
         log("③ This terminal can't put a human in the loop, and an approval IS a human act — the tour");
-        log("   stops here rather than approve its own request. The decision is routed and waiting:");
+        log("   stops here rather than approve its own request. The decision is routed and waiting —");
+        log("   but note: this BLOCKING demo process is about to exit, so approving later resolves the");
+        log("   RECORD only; the demo function itself cannot run afterwards (durable mode is what");
+        log("   survives a process exit — the README's worker section shows it):");
         log("");
         log(`     npx @decidio/sdk approvals approve ${decisionId}     (or approve it in your Decidio app)`);
         log("");
@@ -794,7 +758,9 @@ async function quickstartCleanup(session, envFile) {
     })();
     if (env.DECIDIO_TOKEN_JTI) {
         const rev = await api(`/api/workspace/agent-token/${encodeURIComponent(env.DECIDIO_TOKEN_JTI)}`, { method: "DELETE" }, session);
-        if (rev.status >= 200 && rev.status < 300)
+        if (rev.status >= 200 && rev.status < 300 && rev.body?.changed === false)
+            log(`  • token was already revoked (jti ${env.DECIDIO_TOKEN_JTI}) — nothing to do.`);
+        else if (rev.status >= 200 && rev.status < 300)
             log(`  ✔ token revoked (jti ${env.DECIDIO_TOKEN_JTI})`);
         else
             log(`  ⚠ token revoke returned ${rev.status} — it still expires on its own within 7 days. List tokens: npx @decidio/sdk tokens list`);
@@ -830,9 +796,9 @@ async function quickstartCleanup(session, envFile) {
     log(`    and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap).`);
     return 0;
 }
-async function cmdTokens(sub, jti) {
+async function cmdTokens(sub, jti, mineOnly = false) {
     if (sub !== "list" && sub !== "revoke") {
-        err("usage: npx @decidio/sdk tokens list");
+        err("usage: npx @decidio/sdk tokens list [--mine]");
         err("       npx @decidio/sdk tokens revoke <jti>");
         err("  Agent tokens are shown by jti (their revocation id) — the token VALUE is never shown again after minting.");
         return 2;
@@ -841,6 +807,11 @@ async function cmdTokens(sub, jti) {
         err("usage: npx @decidio/sdk tokens revoke <jti>   (find the jti with: npx @decidio/sdk tokens list)");
         return 2;
     }
+    if (mineOnly && !process.env.DECIDIO_AGENT_ID) {
+        err(`✘ --mine needs an agent identity, and there is no DECIDIO_AGENT_ID in this directory's .env or your environment.`);
+        err(`  Run this from your agent's directory (where init wrote .env), or drop --mine for the workspace-wide list.`);
+        return 2;
+    }
     let bearer;
     let r = await api("/api/workspace/agent-token");
     if (r.status === 401 || r.status === 403) {
@@ -873,14 +844,16 @@ async function cmdTokens(sub, jti) {
         err(`✘ could not list tokens (${r.status}): ${JSON.stringify(r.body).slice(0, 300)}`);
         return 1;
     }
-    const tokens = r.body?.tokens ?? r.body ?? [];
+    const all = r.body?.tokens ?? r.body ?? [];
+    const myAgent = process.env.DECIDIO_AGENT_ID;
+    const tokens = mineOnly ? all.filter((t) => t.agentId === myAgent) : all;
     if (!Array.isArray(tokens) || !tokens.length) {
-        log("No agent tokens in this workspace.");
+        log(mineOnly ? `No agent tokens for "${myAgent}"${all.length ? ` (${all.length} elsewhere in this workspace — drop --mine to see them)` : ""}.` : "No agent tokens in this workspace.");
         return 0;
     }
     const status = (t) => t.revokedAt ? `REVOKED ${String(t.revokedAt).slice(0, 10)}`
         : (t.expiresAt && Date.parse(t.expiresAt) < Date.now()) ? "expired" : "active";
-    log(`Agent tokens (${tokens.length}):`);
+    log(`Agent tokens (${tokens.length}${mineOnly ? ` for "${myAgent}"` : ""})${!mineOnly && myAgent ? ` — workspace-wide (a shared workspace shows every member's agents; --mine narrows to this directory's agent, ${myAgent})` : ""}:`);
     for (const t of tokens)
         log(`  ${t.jti}  ${status(t)}  agent=${t.agentId ?? "?"}  label=${t.label ?? ""}  expires=${t.expiresAt ?? "?"}`);
     const al = r.body?.allowance;
@@ -921,16 +894,18 @@ const USAGE = `decidio — the Decidio SDK command line
       npx @decidio/sdk quickstart
 
   It gates a demo action, routes it to YOU for approval, executes on your yes, and hands you a
-  cryptographically verifiable receipt. (Guided and explicit — this CLI never acts, signs you
-  in, or writes files unless you ask it to.)
+  cryptographically verifiable receipt of the DECISION (execution evidence then accrues on the
+  hosted record — the receipt seals who authorized what, not what ran afterward). Guided and
+  explicit — this CLI never acts, signs you in, or writes files unless you ask it to.
 
   npx @decidio/sdk quickstart          the guided two-minute tour: gate → approve → execute → proof
                                        (interactive: YOUR Enter is the approval. Headless it stops
                                        at the routed decision; --auto-approve-demo for CI, labeled
                                        automated; ends with a keep-or-cleanup choice)
   npx @decidio/sdk quickstart cleanup  revoke the tour's token + delete its local credentials
-  npx @decidio/sdk tokens list         agent tokens with status (active/expired/REVOKED) by jti —
-                                       token values are never re-shown
+  npx @decidio/sdk tokens list [--mine]   agent tokens with status (active/expired/REVOKED) by
+                                       jti — token values are never re-shown; the list is
+                                       workspace-wide, --mine narrows to this directory's agent
   npx @decidio/sdk tokens revoke <jti> kill a token now instead of waiting out its lifetime
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
                                        --unique  append a random suffix (collision-proof samples)
@@ -946,11 +921,14 @@ const USAGE = `decidio — the Decidio SDK command line
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
   npx @decidio/sdk --version           print the CLI version
 
-Every command talks to the hosted sandbox (https://decidio-api.onrender.com) unless
-DECIDIO_API_URL says otherwise; the target host is announced on stderr each run.
+Every NETWORK command talks to the hosted sandbox (https://decidio-api.onrender.com) unless
+DECIDIO_API_URL says otherwise; the target host is announced on stderr each run. "verify" is
+fully offline — it touches no network and reads no .env.
 Exit codes: 0 success · 1 failure or honest no-op (e.g. replay refused) · 2 usage error.
-Errors and usage go to stderr; stdout carries results only (safe to pipe).
-Docs: the README that shipped with this package (quickstart, durable resume, adapters).`;
+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
+(quickstart, durable resume, workers, adapters).`;
 async function main(argv) {
     const [cmd, a, b, ...rest] = argv.slice(2);
     const wantsHelp = (s) => s === "help" || s === "--help" || s === "-h";
@@ -974,7 +952,7 @@ async function main(argv) {
         approvals: { flags: ["--json", "--mine"] },
         receipt: { flags: ["--json"] },
         verify: { flags: [], valued: ["--issuer"] },
-        tokens: { flags: [] },
+        tokens: { flags: ["--mine"] },
         dev: { flags: [], valued: ["--target", "--port"] },
     };
     const spec = KNOWN[cmd];
@@ -1057,7 +1035,7 @@ async function main(argv) {
         case "verify": return cmdVerify(argsIn);
         case "tokens": {
             const positional = argsIn.filter((x) => !x.startsWith("-"));
-            return cmdTokens(positional[0], positional[1]);
+            return cmdTokens(positional[0], positional[1], argsIn.includes("--mine"));
         }
         case "dev": {
             const flag = (name) => {
@@ -1080,7 +1058,10 @@ async function main(argv) {
             return cmdDev(target, Number(portRaw));
         }
         default:
-            err(`✘ unknown command "${cmd}"\n\n${USAGE}`);
+            if (cmd.startsWith("-"))
+                err(`✘ unknown command "${cmd}" — flags go AFTER the command (e.g. npx @decidio/sdk approvals ${cmd}).\n\n${USAGE}`);
+            else
+                err(`✘ unknown command "${cmd}"\n\n${USAGE}`);
             return 2;
     }
 }

package/dist/guard.d.ts

@@ -8,25 +8,52 @@ export interface GuardFacadeConfig {
     resumeUrl?: string;
     webhookSecret?: string;
     pendingDir?: string;
+    /** Local signing key (DECIDIO_AGENT_KEY) + public did (DECIDIO_AGENT_DID), from `init`.
+     *  When present the gate authorizes against a PROVEN identity, not a claimed label. */
     agentKey?: string;
     agentDid?: string;
+    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID). Bound into the signed proof (D-B3.6)
+     *  so a captured proof can't be replayed in another tenant. */
     workspaceId?: string;
+    /** Base URL of the Decidio app (DECIDIO_APP_URL) — used to deep-link a routed decision. */
     appUrl?: string;
     fetchImpl?: typeof fetch;
 }
 export interface ProtectOptions {
-    adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest" | "mcp";
+    /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest)
+     *  live in @decidio/sdk subpaths and take the engine handle. */
+    adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest";
+    /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
+    /** The action name this wrapper produces, declared UP FRONT so the resume registry is populated
+     *  at WRAP time rather than on first call. Required for the cold-worker pattern: after a
+     *  restart, `guard.worker()` can only re-execute actions registered in THIS process, and
+     *  `describe` (which names the action) cannot run without the original call arguments. Declare
+     *  it and a restarted process resumes work it never originated. */
     action?: string;
+    /** Blocking-mode poll ceiling in ms (default 600000 = 10 min). Set it here so a CI pipeline
+     *  fails fast instead of blocking the full 10-minute default while a routed action waits.
+     *  Accepted identically by the Python SDK (poll_timeout, seconds). */
+    pollTimeoutMs?: number;
+    /** Blocking-mode poll interval in ms (default 3000). */
+    pollIntervalMs?: number;
 }
 export declare class Guard {
     config: GuardFacadeConfig;
     resume?: ResumeController;
     constructor(config: GuardFacadeConfig, resume?: ResumeController);
     static fromEnv(): Guard;
+    /** Register a raw fn under its action name so a COLD process (one that never made the original
+     *  call) can resume it. Call this at startup beside `guard.worker()` — or pass
+     *  `{ action }` to `protect(...)`, which does it for you at wrap time. */
     register(action: string, fn: (...a: any[]) => Promise<any>): void;
+    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
     resumeHandler(): import("http").RequestListener;
+    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
     resumeFetchHandler(): (req: Request) => Promise<Response>;
+    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
+     *  any parked approval — so a suspended action survives a process restart. One line at startup.
+     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
     worker(opts?: {
         intervalMs?: number;
         timeoutMs?: number;
@@ -35,6 +62,10 @@ export declare class Guard {
         stop: () => void;
     };
     private ensureResume;
+    /** Throws when the facade has no gate URL — at USE time, not import time, so `import { guard }`
+     *  stays safe in envless contexts. */
+    private assertConfigured;
     protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
 }
+/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export declare const guard: Guard;