@decidio/sdk 0.4.1 → 0.4.3

package/dist/cli.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync, openSync, writeSync, fsyncSync, closeSync, renameSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync, openSync, writeSync, fsyncSync, closeSync, renameSync, mkdirSync } from "node:fs";
 import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join as joinPath } from "node:path";
 import { createServer } from "node:http";
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } 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 } from "./signing.js";
+import { generateKeypair, assertSafeTransport, redactUrl } from "./signing.js";
 import { hardenFile } from "./resume.js";
-import { withApproval, DecidioRateLimitError, DecidioRejectedError, didFromPrivateKey } from "./index.js";
+import { withApproval, DecidioRateLimitError, DecidioRejectedError, DecidioTimeoutError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
     try {
@@ -41,9 +43,10 @@ function readEnvFile() {
     return out;
 }
 const wantsHelp = (s) => s === "help" || s === "--help" || s === "-h";
+const helpFlagAnywhere = (argv) => { const dd = argv.indexOf("--"); return (dd >= 0 ? argv.slice(0, dd) : argv).some((s) => s === "--help" || s === "-h"); };
 const ARGV_TAIL = process.argv.slice(2);
 const OFFLINE_CMD = ["verify", "--version", "-v", "-V", "version", undefined].includes(ARGV_TAIL[0])
-    || wantsHelp(ARGV_TAIL[0]) || wantsHelp(ARGV_TAIL[1]);
+    || wantsHelp(ARGV_TAIL[0]) || wantsHelp(ARGV_TAIL[1]) || helpFlagAnywhere(ARGV_TAIL);
 if (!OFFLINE_CMD) {
     readEnvFile();
     if (envUnreadable) {
@@ -52,6 +55,7 @@ if (!OFFLINE_CMD) {
         process.exit(1);
     }
 }
+const SHELL_ENV = { ...process.env };
 if (!OFFLINE_CMD)
     for (const [k, v] of Object.entries(readEnvFile())) {
         if (k === "DECIDIO_SESSION_TOKEN") {
@@ -67,7 +71,7 @@ const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
 const err = (...a) => console.error(...a);
 let hostAnnounced = false;
-async function api(path, init = {}, bearer) {
+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)"}`);
@@ -92,6 +96,8 @@ async function api(path, init = {}, bearer) {
         res = await fetch(API + path, { ...init, headers: { "content-type": "application/json", ...(auth ? { authorization: `Bearer ${auth}` } : {}), ...(init.headers ?? {}) } });
     }
     catch (e) {
+        if (soft)
+            return { status: 0, body: null };
         err(`✘ could not reach Decidio at ${API} (${e?.cause?.code ?? e?.message ?? "network error"}).`);
         if (API.includes("localhost")) {
             err(`  You're pointed at localhost — for the hosted sandbox run:`);
@@ -268,11 +274,12 @@ function credentialJtisOnDisk() {
     return out;
 }
 function journalOwed() {
-    return journalOutstanding().filter((j) => j.label === "quickstart" || !j.persisted);
+    const held = credentialJtisOnDisk();
+    return journalOutstanding().filter((j) => j.label === "quickstart" || (!j.persisted && !held.has(j.jti)));
 }
 function journalUnheld() {
     const held = credentialJtisOnDisk();
-    return journalOutstanding().filter((j) => j.label !== "quickstart" && j.persisted && !held.has(j.jti));
+    return journalOutstanding().filter((j) => j.label !== "quickstart" && !held.has(j.jti) && j.persisted);
 }
 const REFUSE_MINT_CORRUPT_JOURNAL = (e) => `✘ the token recovery journal cannot be trusted (${e.message}) - it may hold the id of a token that is still live. Refusing to mint on top of uncertain history. Inspect the file, revoke anything it names (npx @decidio/sdk tokens list --mine), and repair or move it aside; every byte is left as found. Nothing was minted.`;
 function journalProbe() {
@@ -291,10 +298,18 @@ function journalProbe() {
     }
 }
 function journalMinted(jti, agentId, label) { journalAppend({ event: "minted", jti, agentId, label, apiUrl: API }); }
-function journalRetire(jti, how) { try {
-    journalAppend({ event: "retired", jti, how });
+function journalRetire(jti, how) {
+    try {
+        journalAppend({ event: "retired", jti, how });
+        return true;
+    }
+    catch (e) {
+        err(how === "persisted"
+            ? `  ⚠ could not note in ${JOURNAL_PATH} that token ${jti} was written to its credential file (${e?.message ?? e}). The credential is safe in the file; doctor will list the token as live and held.`
+            : `  ⚠ could not note in ${JOURNAL_PATH} that token ${jti} was revoked (${e?.message ?? e}). It IS revoked; a later cleanup will find the server already agrees and retire the row.`);
+        return false;
+    }
 }
-catch { } }
 function journalOutstanding() {
     const minted = new Map();
     for (const e of journalRows()) {
@@ -370,6 +385,65 @@ function ensureGitignore() {
     appendFileSync(".gitignore", (existing && !existing.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n");
     log(`✔ added ${missing.join(" + ")} to .gitignore (new secret files here will not be committed)`);
 }
+function recordKindOf(credential) {
+    try {
+        const rc = credential?.credentialSubject?.recordCanonical;
+        const rec = typeof rc === "string" ? JSON.parse(rc) : rc;
+        return typeof rec?.recordKind === "string" ? rec.recordKind : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sessionReminder() {
+    log(`  ⚠ agent code launched from THIS terminal inherits your sign-in — run logout first (it also ends on close or cleanup); if you`);
+    log(`    exported DECIDIO_SESSION_TOKEN, unset it ${dim("(bash/zsh: unset DECIDIO_SESSION_TOKEN · PowerShell: Remove-Item Env:DECIDIO_SESSION_TOKEN)")}`);
+}
+const TTY_OUT = !!process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+const paint = (code, s) => (TTY_OUT ? `\x1b[${code}m${s}\x1b[0m` : s);
+const bold = (s) => paint("1", s);
+const dim = (s) => paint("2", s);
+const link = (url) => (TTY_OUT ? `\x1b]8;;${url}\x1b\\${url}\x1b]8;;\x1b\\` : url);
+const FRAME_WIDTH = 84;
+const visibleLength = (s) => s.replace(/\x1b\[[0-9;]*m|\x1b\]8;;[^\x1b]*\x1b\\/g, "").length;
+function frameWidth(rows) {
+    const cols = (process.stdout.columns ?? 0) > 20 ? process.stdout.columns : 120;
+    const widest = rows.reduce((m, r) => Math.max(m, visibleLength(r)), 0);
+    return Math.max(FRAME_WIDTH, Math.min(widest + 4, cols - 1));
+}
+function block(n, title, rows, tone) {
+    const tint = tone === "choice" ? (process.env.TERM?.includes("256") || process.env.COLORTERM || process.env.WT_SESSION ? "38;5;208" : "33") : tone === "good" ? "32" : tone === "bad" ? "31" : null;
+    const f = (s) => (tint ? paint(tint, s) : s);
+    const width = frameWidth(rows);
+    const inner = width - 4;
+    const head = `┌ ${n} ${title} `;
+    log(f(head + "─".repeat(Math.max(1, width - visibleLength(head) - 1)) + "┐"));
+    for (const row of rows) {
+        const pieces = [];
+        if (visibleLength(row) <= inner)
+            pieces.push(row);
+        else {
+            let cur = "";
+            for (const w of row.split(" ")) {
+                if (cur && visibleLength(cur) + 1 + visibleLength(w) > inner) {
+                    pieces.push(cur);
+                    cur = " ".repeat(Math.min(13, Math.max(0, inner - 24))) + w;
+                }
+                else
+                    cur = cur ? `${cur} ${w}` : w;
+            }
+            if (cur)
+                pieces.push(cur);
+        }
+        for (const piece of pieces)
+            log(`${f("│")} ${piece}${TTY_OUT ? "\x1b[0m" : ""}${" ".repeat(Math.max(0, inner - visibleLength(piece)))} ${f("│")}`);
+    }
+    log(f("└" + "─".repeat(width - 2) + "┘"));
+}
+const APP_URL = API.replace("decidio-api.onrender.com", "app.decidioai.com");
+let stdinReadAbandoned = false;
+let EXPLAIN = false;
+let currentRl = null;
 const APPROVE_WORDS = new Set(["y", "yes", "approve", "approved"]);
 const REJECT_WORDS = new Set(["n", "no", "reject", "rejected", "deny", "denied"]);
 export function approvalAnswer(answer) {
@@ -385,64 +459,173 @@ function ask(question, mute = false) {
         return Promise.resolve("");
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        currentRl = rl;
         if (mute) {
             const anyRl = rl;
             const write = anyRl._writeToOutput?.bind(rl);
             anyRl._writeToOutput = (s) => { if (s.includes(question))
                 write?.(s); };
         }
-        rl.once("close", () => resolve(""));
+        rl.once("close", () => { if (currentRl === rl)
+            currentRl = null; resolve(""); });
         rl.question(question, (answer) => { resolve(answer.trim()); rl.close(); if (mute)
             process.stderr.write("\n"); });
     });
 }
-async function acquireSession(purpose) {
+function terminalId() {
+    for (const k of ["WT_SESSION", "VSCODE_IPC_HOOK_CLI", "TERM_SESSION_ID", "ITERM_SESSION_ID", "TMUX_PANE", "KONSOLE_DBUS_SESSION", "GNOME_TERMINAL_SCREEN", "WINDOWID"]) {
+        const v = process.env[k];
+        if (v)
+            return `${k}=${v}`;
+    }
+    return "";
+}
+function sessionDir() {
+    const base = process.platform === "win32" ? (process.env.LOCALAPPDATA ?? joinPath(homedir(), "AppData", "Local")) : (process.env.XDG_CONFIG_HOME ?? joinPath(homedir(), ".config"));
+    return joinPath(base, "decidio");
+}
+const sessionFile = () => joinPath(sessionDir(), "session.json");
+function jwtExpiry(token) {
     try {
-        assertSafeTransport(API, true);
+        const p = JSON.parse(Buffer.from(token.split(".")[1] ?? "", "base64url").toString("utf8"));
+        return typeof p?.exp === "number" ? new Date(p.exp * 1000) : null;
     }
     catch {
-        err(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
-        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.`);
-        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>"}'`);
+}
+function saveSession(token, email) {
+    mkdirSync(sessionDir(), { recursive: true });
+    const s = { v: 1, api: API, token, email, expiresAt: (jwtExpiry(token) ?? new Date(Date.now() + 30 * 24 * 3600 * 1000)).toISOString(), terminal: terminalId(), createdAt: new Date().toISOString() };
+    writeSecretFile(sessionFile(), JSON.stringify(s) + "\n");
+    return s;
+}
+function loadSession() {
+    const f = sessionFile();
+    if (!existsSync(f))
         return null;
+    let s;
+    try {
+        s = JSON.parse(readFileSync(f, "utf8"));
     }
-    log(`${purpose} needs your Decidio workspace sign-in (${API}).`);
-    log(`  The session stays in memory for this command only — it is never written to disk.`);
-    log(`  Press Enter at the password prompt to use an emailed sign-in link instead.`);
-    const email = await ask("  email: ");
-    if (email) {
-        const password = await ask("  password (Enter to skip): ", true);
-        if (password) {
-            const r = await api("/demo/login", { method: "POST", body: JSON.stringify({ email, password }) }, "");
-            if (r.status >= 200 && r.status < 300 && r.body?.token)
-                return r.body.token;
-            log(`  ✘ password sign-in failed (${r.status})${r.body?.error ? ` — ${r.body.error}` : ""}. No problem — the link path works for every account:`);
-        }
-    }
-    log(`  Request a sign-in link from the app's sign-in screen, then paste the LINK (or just its token) here.`);
-    const pasted = await ask("  link or token: ");
+    catch (e) {
+        err(`⚠ the stored sign-in (${f}) could not be read (${e?.message ?? e}) - removing it; sign in again with: npx @decidio/sdk login`);
+        endSession();
+        return null;
+    }
+    if (!s || s.v !== 1 || typeof s.token !== "string" || s.api !== API)
+        return null;
+    if (new Date(String(s.expiresAt)).getTime() <= Date.now()) {
+        endSession();
+        return null;
+    }
+    const here = terminalId();
+    if (s.terminal && s.terminal !== here)
+        return null;
+    return s;
+}
+function endSession() {
+    const f = sessionFile();
+    if (!existsSync(f))
+        return false;
+    try {
+        rmSync(f);
+        return true;
+    }
+    catch (e) {
+        err(`⚠ could not remove the stored sign-in (${f}: ${e?.message ?? e}) - remove it by hand.`);
+        return false;
+    }
+}
+async function loginFlow(purpose, emailArg) {
+    log(purpose === "Signing in" ? `Sign in once — 30 days, or until this terminal closes, logout, or cleanup.` : `${purpose} needs your Decidio workspace sign-in — once: 30 days, or until this terminal closes, logout, or cleanup.`);
+    const email = emailArg ?? await ask("  email: ");
+    if (!email) {
+        log("  ✘ no email given - re-run when you have it.");
+        return null;
+    }
+    const password = await ask("  password (Enter = emailed sign-in link): ", true);
+    if (password) {
+        const r = await api("/demo/login", { method: "POST", body: JSON.stringify({ email, password }) }, "");
+        if (r.status >= 200 && r.status < 300 && r.body?.token) {
+            const s = saveSession(String(r.body.token), email);
+            log(`  ✔ signed in as ${email} until ${s.expiresAt.slice(0, 10)}${s.terminal ? "" : dim(" (no terminal id here: the sign-in ends on logout or cleanup, not on close)")}`);
+            return s.token;
+        }
+        log(`  ✘ password sign-in failed (${r.status})${r.body?.error ? ` — ${r.body.error}` : ""}. No problem — the emailed link works for every account:`);
+    }
+    const req = await api("/demo/login-link", { method: "POST", body: JSON.stringify({ email }) }, "");
+    if (!(req.status >= 200 && req.status < 300)) {
+        log(`  ✘ could not request a sign-in email (${req.status})${req.body?.error ? ` — ${req.body.error}` : ""}. Check the address and re-run.`);
+        return null;
+    }
+    log(`  ✔ sign-in email requested for ${email} — check your inbox and spam; paste the link (or its login= code; single-use, 15 minutes)`);
+    log(dim(`    invite-only lab: a link arrives only for an invited address — not invited yet? request access: decidioai.com/#early-access`));
+    const pasted = await ask("  link or code: ");
     if (!pasted) {
-        log("  ✘ nothing pasted — re-run when you have the link.");
+        log("  ✘ nothing pasted — re-run when you have the email.");
         return null;
     }
     const m = pasted.match(/[?&]login=([^&\s]+)/);
     const linkToken = m ? decodeURIComponent(m[1]) : pasted;
     const r = await api("/demo/login-consume", { method: "POST", body: JSON.stringify({ token: linkToken }) }, "");
-    if (r.status >= 200 && r.status < 300 && r.body?.token)
-        return r.body.token;
+    if (r.status >= 200 && r.status < 300 && r.body?.token) {
+        const s = saveSession(String(r.body.token), email);
+        log(`  ✔ signed in as ${email} until ${s.expiresAt.slice(0, 10)}${s.terminal ? "" : dim(" (no terminal id here: the sign-in ends on logout or cleanup, not on close)")}`);
+        return s.token;
+    }
     log(`  ✘ that link didn't work (${r.status})${r.body?.error ? ` — ${r.body.error}` : ""}.`);
     log(`  Sign-in links are single-use and expire in 15 minutes — request a fresh one and re-run.`);
     return null;
 }
+async function acquireSession(purpose) {
+    try {
+        assertSafeTransport(API, true);
+    }
+    catch {
+        err(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
+        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;
+    const stored = loadSession();
+    if (stored)
+        return stored.token;
+    if (!process.stdin.isTTY) {
+        err(`✘ ${purpose} needs a Decidio workspace sign-in, and this terminal can't prompt for one.`);
+        err(`  Fix: run \`npx @decidio/sdk login\` in an interactive terminal first (the sign-in is stored for this terminal),`);
+        err(`  or set DECIDIO_SESSION_TOKEN. To mint one by hand: request a sign-in link, then`);
+        err(`    curl -X POST ${API}/demo/login-consume -H "content-type: application/json" -d '{"token":"<login value>"}'   # the response's "token"`);
+        return null;
+    }
+    return loginFlow(purpose);
+}
+async function cmdLogin(emailArg) {
+    try {
+        assertSafeTransport(API, true);
+    }
+    catch {
+        err(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
+        return 1;
+    }
+    const stored = loadSession();
+    if (stored) {
+        log(`• already signed in${stored.email ? ` as ${stored.email}` : ""} on this terminal until ${stored.expiresAt.slice(0, 10)} - run \`npx @decidio/sdk logout\` first to switch accounts.`);
+        return 0;
+    }
+    const token = await loginFlow("Signing in", emailArg);
+    return token ? 0 : 1;
+}
+function cmdLogout() {
+    if (endSession())
+        log("✔ signed out — the stored sign-in is removed.");
+    else
+        log("• no stored sign-in on this machine for this Decidio.");
+    if (process.env.DECIDIO_SESSION_TOKEN)
+        log("  • DECIDIO_SESSION_TOKEN is still exported in this shell — unset it too (bash: unset DECIDIO_SESSION_TOKEN · PowerShell: Remove-Item Env:DECIDIO_SESSION_TOKEN).");
+    return 0;
+}
 async function cmdInit(agentId, opts = {}) {
     if (!assertNotTracked(ENV_PATH))
         return 1;
@@ -794,6 +977,21 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
     log(`Reject:   npx @decidio/sdk approvals reject <id> [reason]`);
     return 0;
 }
+export function receiptFileName(id) {
+    return `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, (c) => "~" + c.codePointAt(0).toString(16).padStart(2, "0"))}.json`;
+}
+function writeReceiptFile(name, bytes, say = log) {
+    if (existsSync(name)) {
+        if (readFileSync(name, "utf8") !== bytes) {
+            err(`✘ ${name} already exists with DIFFERENT bytes — refusing to overwrite an audit artifact. Move it aside or delete it, then re-run.`);
+            return "conflict";
+        }
+        say(`• ${name} already exists (byte-identical — receipts are immutable); leaving it in place.`);
+        return "identical";
+    }
+    writeFileSync(name, bytes);
+    return "written";
+}
 async function cmdReceipt(id, jsonMode = false) {
     if (!id) {
         err("usage: npx @decidio/sdk receipt <decisionId>");
@@ -819,19 +1017,13 @@ async function cmdReceipt(id, jsonMode = false) {
         err(`✘ could not fetch the receipt (${r.status}): ${JSON.stringify(r.body).slice(0, 300)}`);
         return 1;
     }
-    const name = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
+    const name = receiptFileName(id);
     const nextBytes = JSON.stringify(r.body.credential, null, 2) + "\n";
-    if (existsSync(name)) {
-        if (readFileSync(name, "utf8") !== nextBytes) {
-            err(`✘ ${name} already exists with DIFFERENT bytes — refusing to overwrite an audit artifact. Move it aside or delete it, then re-run.`);
-            return 1;
-        }
-        (jsonMode ? err : log)(`• ${name} already exists (byte-identical — receipts are immutable); leaving it in place.`);
-    }
-    else {
-        writeFileSync(name, nextBytes);
+    const wrote = writeReceiptFile(name, nextBytes, jsonMode ? err : log);
+    if (wrote === "conflict")
+        return 1;
+    if (wrote === "written")
         (jsonMode ? err : log)(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
-    }
     const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
     const conf = detail.body?.record?.confirmation;
     const issuer = r.body?.issuer;
@@ -923,17 +1115,35 @@ function cmdVerify(argsIn) {
         log(l);
     return ok ? 0 : 1;
 }
+function valuedOpt(args, flag) {
+    const i = args.indexOf(flag);
+    if (i >= 0)
+        return args[i + 1];
+    const eq = args.find((x) => x.startsWith(flag + "="));
+    return eq ? eq.slice(flag.length + 1) : undefined;
+}
 async function cmdQuickstart(opts = {}) {
     const t0 = Date.now();
-    log("Decidio quickstart — gate an action, route it to a human, execute on approval, hold the proof.");
-    log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : "  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)"}`);
-    log("");
-    log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
-    log("  write .env (or .env.quickstart), .decidio-token-journal (revocation ids, no secrets) and .gitignore");
-    log("  entries (incl. .decidio-pending/, the durable store your real agent will use) · save the receipt");
-    log("  as decidio-receipt-<id>.json here (shareable: action, amount, policy, the human's reason - no secrets; it stays)");
-    log("  · create one synthetic decision and its sealed record (records are permanent by design) · wait up to");
-    log("  5 minutes for your y (approve) or n (reject) at the human step. Cleanup offer at the end.");
+    EXPLAIN = !!opts.explain;
+    if (opts.phone !== undefined && opts.phone !== "app" && opts.phone !== "web") {
+        err(`✘ --phone takes app (default: the QR opens the installed app when there is one) or web (the QR opens the phone web rendering, always).`);
+        return 2;
+    }
+    log(bold("Decidio quickstart") + " — gate an action, route it to a human, execute on approval, hold the proof.");
+    log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : dim("  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)")}`);
+    hostAnnounced = true;
+    if (EXPLAIN) {
+        log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
+        log("  write .env (or .env.quickstart), .decidio-token-journal (revocation ids, no secrets) and .gitignore");
+        log("  entries (incl. .decidio-pending/, the durable store your real agent will use) · save the receipt");
+        log("  as decidio-receipt-<id>.json here (shareable: action, amount, policy, the human's reason - no secrets; it stays)");
+        log("  · create one synthetic decision and its sealed record (records are permanent by design) · wait up to");
+        log("  5 minutes for your y (approve) or n (reject) at the human step. Cleanup offer at the end.");
+    }
+    else {
+        log(dim("  Creates here: a synthetic agent + 7-day token (.env), .decidio-token-journal (revocation ids, no secrets), .gitignore entries incl."));
+        log(dim("  .decidio-pending/ (the durable store), the receipt as decidio-receipt-<id>.json, one sealed record (permanent). --explain for the long form."));
+    }
     log("");
     const session = await acquireSession("The quickstart");
     if (!session)
@@ -943,7 +1153,8 @@ async function cmdQuickstart(opts = {}) {
         return 1;
     ensureGitignore();
     let agentId = `quickstart-${randomBytes(5).toString("hex")}`;
-    log(`① Registering agent "${agentId}"…`);
+    if (EXPLAIN)
+        log(`  Registering agent "${agentId}"…`);
     const { did, privateKeyBase64 } = generateKeypair();
     let reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
     for (let attempt = 0; reg.status === 409 && attempt < 3; attempt++) {
@@ -1039,7 +1250,7 @@ async function cmdQuickstart(opts = {}) {
                 err(`✘ could not write ${envFile} (${e?.message ?? e}). The tour token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
             return 1;
         }
-        log(`  ✔ this directory already has an agent in .env — tour credentials went to ${envFile} (your agent is untouched)`);
+        log(`  ✔ .env already holds your agent — this tour uses ${envFile}`);
     }
     else {
         try {
@@ -1061,14 +1272,20 @@ async function cmdQuickstart(opts = {}) {
         await quickstartCleanup(session, envFile).catch(() => { });
         return code;
     };
-    log(`  ✔ key generated locally (public half registered) · 7-day floor-limited token minted${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ""} · ${envFile} written`);
-    log("");
-    log(`② Gating a demo action — the tour runs this (blocking mode: watch it live):`);
-    log("");
-    log(`     const payInvoice = guard.protect(payInvoiceRaw,`);
-    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }),`);
-    log(`       { mode: "blocking" });   // your real agent typically omits this — durable + a worker`);
-    log("");
+    block("①", "Register a synthetic agent", [
+        `${bold("agent")}    ${agentId}`,
+        `${bold("key")}      generated locally · only the public half was registered`,
+        `${bold("token")}    7-day, floor-limited${mint.body.expiresAt ? ` · expires ${String(mint.body.expiresAt).slice(0, 10)}` : ""} · written to ${envFile}`,
+    ]);
+    if (EXPLAIN) {
+        log(`  The tour runs exactly this, the BLOCKING primitive (your real agent uses guard.protect instead:`);
+        log(`  durable by default, resumed by a worker — the README shows both):`);
+        log("");
+        log(`     const payInvoice = withApproval(payInvoiceRaw,`);
+        log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }),`);
+        log(`       { ...config, pollTimeoutMs: 300_000 });   // waits up to 5 minutes for the human`);
+        log("");
+    }
     let decisionId = "";
     const cfg = {
         apiUrl: API, agentId, apiToken: mint.body.token, agentKey: privateKeyBase64,
@@ -1097,30 +1314,82 @@ async function cmdQuickstart(opts = {}) {
         err("✘ the gate did not route within 30s — check connectivity (npx @decidio/sdk doctor) and re-run.");
         return failTour(1);
     }
-    log(`  ✔ $86,000 payInvoice ROUTED to a human (decision ${decisionId}) — this agent has no auto-approve rule,`);
-    log(`    so the policy ROUTES it to a person (routing-by-default). That is distinct from a BLOCK, which no human can`);
-    log(`    override: a block is a named rule, or the universal backstop when no active policy governs agents at all.`);
-    log(`    Nothing executes until someone decides.`);
-    log("");
+    block("②", "Gate a demo action", [
+        `${bold("call")}     withApproval(payInvoiceRaw, (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }), { pollTimeoutMs: 300_000 })   ${dim("// blocking here; your agent's guard.protect is durable")}`,
+        `${bold("routed")}   $86,000 payInvoice ROUTED to a human (decision ${decisionId}) — nothing executes until someone decides ${dim("(routed, not a BLOCK: a human can still say yes; a block no one can override)")}`,
+    ]);
+    if (EXPLAIN) {
+        log(`  This agent has no auto-approve rule, so the policy ROUTES it to a person (routing-by-default). That is`);
+        log(`  distinct from a BLOCK, which no human can override: a block is a named rule, or the universal backstop`);
+        log(`  when no active policy governs agents at all.`);
+        log("");
+    }
     const interactive = process.stdin.isTTY;
     let verdict = "approve";
+    let decidedOutside = null;
+    let denialVerified = false;
     if (interactive) {
+        const handoff = await api("/demo/session-link", { method: "POST", body: JSON.stringify({ decisionId, ...(opts.phone === "web" ? { phone: "web" } : {}) }) }, session, true);
+        const doorLink = handoff.status >= 200 && handoff.status < 300 && typeof handoff.body?.link === "string" ? String(handoff.body.link) : null;
+        const qr = doorLink && typeof handoff.body?.qr === "string" ? String(handoff.body.qr) : null;
+        const plainLink = `${APP_URL}/queue?focus=${encodeURIComponent(decisionId)}`;
+        const rows = [
+            `${bold("here")}         Type y to approve or n to reject, then Enter   ${dim("(waits up to 5 minutes)")}`,
+            `${bold("web app")}      ${link(doorLink ?? plainLink)}   ${dim(doorLink ? "(one-time sign-in · 5 minutes)" : "(sign in there if it asks)")}`,
+        ];
+        if (qr) {
+            rows.push(`${bold("your phone")}   scan — the same one-time sign-in${opts.phone === "web" ? ", in the phone browser (--phone web)" : ": the Decidio app if it is installed, the browser if not"}`);
+            for (const l of qr.split("\n"))
+                if (l.trim().length)
+                    rows.push("             " + l);
+        }
+        else if (doorLink)
+            rows.push(`${bold("your phone")}   ${dim("the link above works on a phone too (no QR came back this time)")}`);
+        rows.push(dim("whichever answers first wins — the terminal follows the web app or your phone."));
+        block("③", "Your call", rows, "choice");
+        let settledState = null;
+        const settledP = running.then(() => { settledState = "approved"; }, (e) => { settledState = e instanceof DecidioRejectedError ? "rejected" : "other"; });
         verdict = "again";
-        for (let attempt = 0; attempt < 3 && verdict === "again"; attempt++) {
-            const answer = await ask(attempt === 0
-                ? `③ YOU are the approver. Type y to approve or n to reject, then Enter (or decide it in your Decidio queue first, then answer here the same way): `
-                : `   Please answer y (approve) or n (reject): `);
-            verdict = approvalAnswer(answer);
-            if (process.stdin.readableEnded || process.stdin.destroyed) {
-                verdict = "again";
-                break;
+        const promptP = (async () => {
+            for (let attempt = 0; attempt < 3 && verdict === "again" && !settledState; attempt++) {
+                const answer = await ask(attempt === 0 ? `  › ` : `   Please answer y (approve) or n (reject): `);
+                if (settledState)
+                    break;
+                verdict = approvalAnswer(answer);
+                if (process.stdin.readableEnded || process.stdin.destroyed) {
+                    verdict = "again";
+                    break;
+                }
             }
-        }
-        if (verdict === "again") {
+        })();
+        await Promise.race([promptP, settledP]);
+        if (settledState) {
+            currentRl?.close();
+            stdinReadAbandoned = true;
+            await promptP;
+            log("");
+        }
+        if (settledState === "approved" || settledState === "rejected") {
+            decidedOutside = settledState;
+            verdict = settledState === "approved" ? "approve" : "reject";
+        }
+        else if (settledState === "other")
+            verdict = "again";
+        if (verdict === "again" && !(earlyError instanceof DecidioTimeoutError)) {
             log(`③ No decision was made (no y or n answer), so the tour stops here rather than guess.`);
             log(`   The request is still ROUTED and waiting in your queue - approve or reject it there, or re-run the tour.`);
             log(`   NOTE: this tour's credentials are still live in ${envFile} (a 7-day token + the agent's key). Once you`);
             log(`   have decided - or if you abandon the tour - remove them: npx @decidio/sdk quickstart cleanup`);
+            log("");
+            sessionReminder();
+            process.exit(3);
+        }
+        if (earlyError instanceof DecidioTimeoutError) {
+            log(`③ the tour's blocking call gave up after 5 minutes while waiting for your answer, so your answer is NOT posted:`);
+            log(`   the request is still ROUTED in your queue - decide it there, or re-run the tour and answer within 5 minutes.`);
+            log(`   NOTE: this tour's credentials are still live in ${envFile} - remove them: npx @decidio/sdk quickstart cleanup`);
+            log("");
+            sessionReminder();
             process.exit(3);
         }
     }
@@ -1147,17 +1416,22 @@ async function cmdQuickstart(opts = {}) {
         log(`   NOTE: this tour's credentials are still live in ${envFile} (a 7-day token + the agent's`);
         log(`   key), because the decision above is still waiting for you. Once you have approved it —`);
         log(`   or if you abandon the tour — remove them: npx @decidio/sdk quickstart cleanup`);
+        log("");
+        sessionReminder();
         process.exit(3);
     }
     const rejected = verdict === "reject";
     if (rejected) {
-        const rj = await api(`/api/decisions/${encodeURIComponent(decisionId)}/reject`, { method: "POST", body: JSON.stringify({ reason: "quickstart: rejected by the approver" }) }, session);
+        const rj = decidedOutside ? { status: 200, body: { alreadyResolved: true, sealed: true } } : await api(`/api/decisions/${encodeURIComponent(decisionId)}/reject`, { method: "POST", body: JSON.stringify({ reason: "quickstart: rejected by the approver" }) }, session);
         if (!(rj.status >= 200 && rj.status < 300)) {
             err(`✘ reject failed (${rj.status}): ${JSON.stringify(rj.body)}`);
             return failTour(1);
         }
+        if (decidedOutside)
+            log(`  ✔ rejected in the web app (or on your phone) — this terminal saw it and followed`);
         const decidedInApp = rj.body?.alreadyResolved === true;
-        log(decidedInApp ? `  • this decision was already decided from your app — the tour follows that decision` : `  ✔ rejected`);
+        if (!decidedOutside)
+            log(decidedInApp ? `  • this decision was already decided from your app — the tour follows that decision` : `  ✔ rejected`);
         let leaked;
         let refused;
         try {
@@ -1175,8 +1449,35 @@ async function cmdQuickstart(opts = {}) {
             log(`  ✔ your app APPROVED it first, so that decision stood and your function ran: ${JSON.stringify(leaked)}. Re-run the tour to watch a rejection.`);
         }
         else if (refused instanceof DecidioRejectedError) {
-            log(`  ✔ your function did NOT run — the wrapper refused: ${refused.message}`);
-            log(`    That is the product: a human said no, and nothing happened.${rj.body?.sealed === true ? " The denial is sealed on the record, as an approval would be." : ""}`);
+            log(`  ✔ your function did NOT run — the wrapper refused: ${refused.message}${EXPLAIN ? "" : dim("  (a human said no, and nothing happened)")}`);
+            if (EXPLAIN)
+                log(`    That is the product: a human said no, and nothing happened.`);
+            if (EXPLAIN)
+                log("  Downloading the sealed record of the DENIAL and verifying it OFFLINE…");
+            const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
+            if (rec.status >= 200 && rec.status < 300 && rec.body?.credential) {
+                const fname = receiptFileName(decisionId);
+                const wrote = writeReceiptFile(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
+                if (wrote === "conflict")
+                    return failTour(1);
+                const issuer = rec.body?.issuer;
+                const v = verifyReceipt(rec.body.credential, issuer);
+                const kindLine = `${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", PINNED to your workspace issuer" : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
+                if (!v.valid || !issuer) {
+                    log(`  ${kindLine}`);
+                    err(`  ✘ the denial's receipt did not verify PINNED (${!issuer ? "no issuer DID from the server" : v.reason ?? "no reason given"}) — the tour did not complete.`);
+                    return failTour(1);
+                }
+                block("④", "The record", [
+                    `✔ VALID — ${fname} ${dim("(signature + content binding, offline, PINNED to your workspace issuer)")}`,
+                    `${bold("record")}   record kind: ${recordKindOf(rec.body.credential) ?? "?"} ${dim("— the denial is sealed too")}`,
+                    `${bold("issuer")}   ${issuer} ${dim("· your trust anchor: verify --issuer <did> <receipt.json>")}`,
+                ], "bad");
+                denialVerified = true;
+            }
+            else {
+                log(`  • no sealed record was issued for this rejection (${rec.status}) — the denial is on the decision in your queue.`);
+            }
         }
         else {
             err(`✘ the gated call ended with an error rather than a clean refusal: ${refused?.message ?? refused} — nothing ran, but the tour did not complete.`);
@@ -1184,21 +1485,29 @@ async function cmdQuickstart(opts = {}) {
         }
         log("");
         const secsR = Math.round((Date.now() - t0) / 1000);
-        log(ranOnAppApproval
-            ? `Done in ${secsR}s: gated → routed to a human → decided in your app (approved) → your function ran once.`
-            : `Done in ${secsR}s: gated → routed to a human → REJECTED → your function never ran.`);
-        if (!ranOnAppApproval)
+        if (ranOnAppApproval)
+            log(`Done in ${secsR}s: gated → routed to a human → decided in your app (approved) → your function ran once.`);
+        else {
+            block("✔", `Done in ${secsR}s`, [
+                `${bold("gated")}        payInvoice $86,000 — ROUTED to a human as ${decisionId}`,
+                `${bold("decided")}      REJECTED ${decidedOutside ? "in the web app (or on your phone)" : "by you, here"}`,
+                `${bold("executed")}     nothing — your function never ran`,
+                `${bold("record")}       ${denialVerified ? "the DENIAL is sealed too — VALID, verified offline (④ above)" : "none was issued for this rejection (④ above)"}`,
+                dim("gated → routed to a human → REJECTED → your function never ran"),
+            ], "bad");
             log(`Re-run the tour and answer y to watch the approval half, with its offline-verifiable receipt.`);
+        }
         log("");
-        log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}`);
+        sessionReminder();
+        log(`${bold("Where next")}  your queue ${link(APP_URL)} · README "Production mode: durable async resume" ${dim("· built by OmniTwin — decidioai.com/#early-access")}`);
     }
     else {
-        const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
+        const ap = decidedOutside ? { status: 200, body: { alreadyResolved: true } } : await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
         if (!(ap.status >= 200 && ap.status < 300)) {
             err(`✘ approve failed (${ap.status}): ${JSON.stringify(ap.body)}`);
             return failTour(1);
         }
-        log(`  ✔ approved${ap.body?.alreadyResolved ? " (already decided from your app — the tour follows that decision)" : ""}`);
+        log(decidedOutside ? `  ✔ approved in the web app (or on your phone) — this terminal saw it and followed` : `  ✔ approved${ap.body?.alreadyResolved ? " (already decided from your app — the tour follows that decision)" : ""}`);
         let done;
         try {
             done = await running;
@@ -1211,21 +1520,24 @@ async function cmdQuickstart(opts = {}) {
             err(`✘ the gated call did not complete: ${e?.message ?? e}`);
             return failTour(1);
         }
-        log(`  ✔ your function executed AFTER approval: ${JSON.stringify(done.value)}`);
-        if (done.confirmation?.evidenceTier)
-            log(`    …and the call itself told you what was recorded: confirmation.evidenceTier = ${done.confirmation.evidenceTier}`);
-        log("");
-        log("④ Downloading the sealed Authority Receipt and verifying it OFFLINE…");
+        log(`  ✔ your function executed AFTER approval: ${JSON.stringify(done.value)}${done.confirmation?.evidenceTier ? ` · confirmation.evidenceTier = ${done.confirmation.evidenceTier}` : ""}`);
+        if (EXPLAIN && done.confirmation?.evidenceTier)
+            log(`    (the call itself told you what was recorded — the wrapper's signed report)`);
+        if (EXPLAIN)
+            log("  Downloading the sealed Authority Receipt and verifying it OFFLINE…");
         const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
         if (!(rec.status >= 200 && rec.status < 300) || !rec.body?.credential) {
             err(`✘ receipt fetch failed (${rec.status})`);
             return failTour(1);
         }
-        const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
-        writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
+        const fname = receiptFileName(decisionId);
+        if (writeReceiptFile(fname, JSON.stringify(rec.body.credential, null, 2) + "\n") === "conflict")
+            return failTour(1);
         const issuer = rec.body?.issuer;
         const v = verifyReceipt(rec.body.credential, issuer);
-        log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : ""})`);
+        const kindLine = `${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? ", PINNED to your workspace issuer" : ""}) · record kind: ${recordKindOf(rec.body.credential) ?? "?"}`;
+        if (!v.valid || !issuer)
+            log(`  ${kindLine}`);
         if (!v.valid) {
             err(`  ✘ the receipt did not verify (${v.reason ?? "no reason given"}) — the tour did not complete.`);
             return failTour(1);
@@ -1238,29 +1550,32 @@ async function cmdQuickstart(opts = {}) {
             err(`  ✘ the tour does not count an UNPINNED check as success.`);
             return failTour(1);
         }
-        if (issuer)
-            log(`    Keep that DID: it is your trust anchor — npx @decidio/sdk verify --issuer ${issuer} <receipt.json>`);
         const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
         const tier = detail.body?.record?.confirmation?.status;
-        if (tier)
-            log(`  ✔ execution evidence on the record: ${tier} — the wrapper's signed report. (The receipt seals the DECISION; execution evidence accrues on the record — see the README.)`);
-        log("");
+        block("④", "The receipt", [
+            `✔ VALID — ${fname} ${dim("(signature + content binding, offline, PINNED to your workspace issuer)")}`,
+            `${bold("record")}   record kind: ${recordKindOf(rec.body.credential) ?? "?"}${tier ? ` · evidence: ${tier}` : ""} ${dim("— the receipt seals the DECISION; execution evidence lives on the record")}`,
+            `${bold("issuer")}   ${issuer} ${dim("· your trust anchor: verify --issuer <did> <receipt.json>")}`,
+        ], "good");
         const secs = Math.round((Date.now() - t0) / 1000);
-        log(`Done in ${secs}s: gated → routed to a human → approved → your function executed once → an authority-decision receipt you can verify offline.`);
+        block("✔", `Done in ${secs}s`, [
+            `${bold("gated")}        payInvoice $86,000 — ROUTED to a human as ${decisionId}`,
+            `${bold("decided")}      ${decidedOutside ? "approved in the web app (or on your phone)" : opts.autoApproveDemo ? "approved by --auto-approve-demo (automated, and labeled so on the record)" : "approved by you, here"}`,
+            `${bold("executed")}     your function ran once, AFTER approval`,
+            `${bold("receipt")}      VALID — verified offline, pinned to your workspace issuer (④ above)`,
+            dim("gated → routed to a human → approved → executed once → a receipt you can verify offline"),
+        ], "good");
         log("");
-        log("Take it to your real agent — the .env here already works:");
+        log(bold("Take it to your real agent — the .env here already works:"));
         log(`  import { guard } from "@decidio/sdk";`);
-        log(`  const doIt = guard.protect(doItRaw, (a) => ({ action: "yourAction", amount: a.amount, scope: "YourScope" }));`);
-        log(`  // production is DURABLE mode (default) + one worker: guard.worker();  // README has the full pattern`);
-        log("");
-        log(`Before launching agent code from THIS shell, unset DECIDIO_SESSION_TOKEN if you exported it: child processes`);
-        log(`inherit exported variables, and that credential is your workspace login, not the agent's.`);
+        log(`  const doIt = guard.protect(doItRaw, (a) => ({ action: "yourAction", amount: a.amount, scope: "YourScope" }));${dim("   // durable by default")}`);
         log("");
-        log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}`);
-        log(`Next: the README section "Production mode: durable async resume" (the worker; the engine adapters follow it).`);
-        log(`The README's seven-step quickstart is this same blocking flow in your own code - if you keep this agent, its .env`);
-        log(`already works here, so skip that flow's init step.`);
-        log(`Built by OmniTwin — decidioai.com  ·  Putting this in front of real approvals? decidioai.com/#early-access`);
+        if (EXPLAIN) {
+            log(`  The README's seven-step flow is this same blocking flow in your own code; if you keep this agent, its .env`);
+            log(`  already works here, so skip that flow's init step. Production is DURABLE mode (default) + one worker.`);
+        }
+        sessionReminder();
+        log(`${bold("Where next")}  your queue ${link(APP_URL)} · README "Production mode: durable async resume" ${dim("· built by OmniTwin — decidioai.com/#early-access")}`);
     }
     let doCleanup = false;
     if (interactive) {
@@ -1437,6 +1752,10 @@ async function quickstartCleanup(session, envFile) {
         log(`    pending and you do not want the history, remove it:`);
         log(`      ${process.platform === "win32" ? "Remove-Item -Recurse .decidio-pending" : "rm -r .decidio-pending"}`);
     }
+    if (endSession())
+        log(`  ✔ signed out — the stored sign-in is ended (npx @decidio/sdk login to sign in again).`);
+    else if (process.env.DECIDIO_SESSION_TOKEN)
+        log(`  • DECIDIO_SESSION_TOKEN is still exported in this shell — unset it when you are done.`);
     return 0;
 }
 async function cmdTokens(sub, jti, mineOnly = false) {
@@ -1536,11 +1855,14 @@ function cmdDev(target, port) {
                 res.end(JSON.stringify({ error: e?.message }));
             }
         });
-    }).listen(port);
+    }).listen(port, "127.0.0.1");
     return 0;
 }
 const USAGE = `decidio — the Decidio SDK command line
 
+  The wrapper IS the SDK: guard.protect(fn, describe) ships in this package (import { guard } from "@decidio/sdk").
+  This command line is the tour, the sign-in, and the token admin around it.
+
   New here? See the whole thing work in about two minutes:
 
       npx @decidio/sdk quickstart
@@ -1550,23 +1872,36 @@ const USAGE = `decidio — the Decidio SDK command line
   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.
 
+THE TOUR
   npx @decidio/sdk quickstart          the guided two-minute tour: gate → approve → execute → proof
-                                       (interactive: YOUR Enter is the approval. Headless it stops
+                                       (interactive: y approves, n rejects - Enter is not an answer. Headless it stops
                                        at the routed decision; --auto-approve-demo for CI, labeled
-                                       automated; ends with a keep-or-cleanup choice)
+                                       automated; ends with a keep-or-cleanup choice; --explain prints
+                                       the long narration of each step; --phone web makes the QR open
+                                       the phone web rendering even when the Decidio app is installed)
   npx @decidio/sdk quickstart cleanup  revoke the tour's token + delete its local credentials
+                                       (and end the stored sign-in)
   npx @decidio/sdk quickstart --auto-approve-demo   headless tour; cleans up after itself
                                        (add --keep-agent to KEEP the tour agent + token)
-  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
+
+SIGN IN (once)
+  npx @decidio/sdk login [email]       sign in ONCE: the CLI emails you a link, you paste it; the sign-in
+                                       lasts 30 days, or until this terminal closes, logout, or cleanup
+  npx @decidio/sdk logout              end the stored sign-in
+
+YOUR AGENT AND ITS TOKENS
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
                                        --unique  append a random suffix (collision-proof samples)
                                        --force   replace a different agent already in this .env
                                                  (its .env is backed up first)
                                        --expires-days N   agent-token lifetime (default 90)
   npx @decidio/sdk doctor              check config, connectivity, and what your token can do
+  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
+
+APPROVALS AND RECEIPTS
   npx @decidio/sdk approvals [--json] [--mine]   list pending agent approvals
   npx @decidio/sdk approvals approve <id> [reason]
   npx @decidio/sdk approvals reject <id> [reason]
@@ -1576,21 +1911,110 @@ const USAGE = `decidio — the Decidio SDK command line
                                        If it starts with a dash, put it after -- or use --reason:
                                          ... approve <id> -- "-50% cut, per the board"
                                          ... approve <id> --reason "-50% cut, per the board"
-  npx @decidio/sdk receipt <id>        download a sealed decision's Authority Receipt (.json)
+  npx @decidio/sdk receipt <id> [--json]   download a sealed decision's Authority Receipt (.json)
   npx @decidio/sdk verify [--issuer <did>] <receipt.json> [more...]   verify receipts OFFLINE
+
+DEVELOPMENT
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
   npx @decidio/sdk --version           print the CLI version
 
-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 ·
-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).
-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).`;
+NOTES
+  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.
+  Update check: network commands ask the public npm registry once a day whether a newer version exists. If so,
+  an interactive run asks "Upgrade now? [y/n]" first (y upgrades and re-runs your command; n exits); a headless
+  run prints the notice and continues (DECIDIO_REQUIRE_LATEST=1 makes it exit). DECIDIO_NO_UPDATE_CHECK=1 skips
+  the check. Nothing is sent to Decidio; verify never checks.
+  Help: --help (or -h) after any command prints this page - one page for every command.
+  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).
+  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).`;
+const GATED_CMDS = new Set(["quickstart", "init", "login", "doctor", "approvals", "receipt", "tokens"]);
+function semverNewer(a, b) {
+    const pa = a.split(".").map((x) => parseInt(x, 10)), pb = b.split(".").map((x) => parseInt(x, 10));
+    if (pa.length < 3 || pb.length < 3 || pa.some((x) => Number.isNaN(x)) || pb.some((x) => Number.isNaN(x)))
+        return false;
+    for (let i = 0; i < 3; i++)
+        if (pa[i] !== pb[i])
+            return pa[i] > pb[i];
+    return false;
+}
+async function latestPublished() {
+    const cache = joinPath(sessionDir(), "update-check.json");
+    try {
+        const c = JSON.parse(readFileSync(cache, "utf8"));
+        if (c && typeof c.latest === "string" && Date.now() - Number(c.checkedAt) < 24 * 3600 * 1000)
+            return c.latest;
+    }
+    catch { }
+    const reg = (SHELL_ENV.DECIDIO_UPDATE_REGISTRY ?? "https://registry.npmjs.org").replace(/\/+$/, "");
+    try {
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), 2000);
+        const r = await fetch(`${reg}/@decidio%2fsdk/latest`, { signal: ctl.signal });
+        clearTimeout(t);
+        if (!r.ok)
+            return null;
+        const body = await r.json();
+        const latest = typeof body?.version === "string" && /^\d+\.\d+\.\d+$/.test(body.version) ? body.version : null;
+        if (latest) {
+            try {
+                mkdirSync(sessionDir(), { recursive: true });
+                writeFileSync(cache, JSON.stringify({ checkedAt: Date.now(), latest }));
+            }
+            catch { }
+        }
+        return latest;
+    }
+    catch {
+        return null;
+    }
+}
+async function updateGate(cmd, argv) {
+    if (!cmd || !GATED_CMDS.has(cmd) || SHELL_ENV.DECIDIO_NO_UPDATE_CHECK || VERSION === "unknown" || VERSION.includes("-"))
+        return null;
+    const latest = await latestPublished();
+    if (!latest || !semverNewer(latest, VERSION))
+        return null;
+    const underNpx = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "");
+    const upgradeCmd = underNpx ? `npx @decidio/sdk@latest ${argv.slice(2).join(" ")}` : "npm i -g @decidio/sdk@latest";
+    const notice = `${latest} is available (you have ${VERSION}).`;
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        err(`⚠ ${notice} Upgrade: ${upgradeCmd}`);
+        if (SHELL_ENV.DECIDIO_REQUIRE_LATEST) {
+            err(`✘ DECIDIO_REQUIRE_LATEST is set — not running a stale version.`);
+            return 1;
+        }
+        return null;
+    }
+    const a = (await ask(`${notice} Upgrade now? [y/n]: `)).toLowerCase();
+    if (a !== "y" && a !== "yes") {
+        err(`✘ not upgraded — run this when ready: ${upgradeCmd}`);
+        return 1;
+    }
+    if (underNpx) {
+        err(`  Under npx there is nothing installed to upgrade — re-run as: ${upgradeCmd}`);
+        return 1;
+    }
+    if (SHELL_ENV.DECIDIO_UPDATE_DRY_RUN) {
+        log(`  would run: ${upgradeCmd}`);
+        return null;
+    }
+    log(`  upgrading: ${upgradeCmd}`);
+    const up = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", ["i", "-g", "@decidio/sdk@latest"], { stdio: "inherit", shell: process.platform === "win32", env: SHELL_ENV });
+    if (up.status !== 0) {
+        err(`✘ the upgrade did not complete (exit ${up.status ?? "?"}) — run it by hand: ${upgradeCmd}`);
+        return 1;
+    }
+    log(`  ✔ upgraded — re-running: decidio ${argv.slice(2).join(" ")}`);
+    const rerun = spawnSync(process.execPath, [process.argv[1], ...argv.slice(2)], { stdio: "inherit", env: SHELL_ENV });
+    return rerun.status ?? 1;
+}
 async function main(argv) {
     const [cmd, a, b, ...rest] = argv.slice(2);
     if (cmd === "--version" || cmd === "-v" || cmd === "-V" || cmd === "version") {
@@ -1605,9 +2029,15 @@ async function main(argv) {
         log(USAGE);
         return 0;
     }
+    if (helpFlagAnywhere(argv.slice(2))) {
+        log(USAGE);
+        return 0;
+    }
     const argsIn = argv.slice(3);
     const KNOWN = {
-        quickstart: { flags: ["--auto-approve-demo", "--keep-agent"] },
+        quickstart: { flags: ["--explain", "--auto-approve-demo", "--keep-agent"], valued: ["--phone"] },
+        login: { flags: [] },
+        logout: { flags: [] },
         init: { flags: ["--unique", "--force"], valued: ["--expires-days"] },
         doctor: { flags: [] },
         approvals: { flags: ["--json", "--mine"], valued: ["--reason"] },
@@ -1648,7 +2078,7 @@ async function main(argv) {
                 return 2;
             }
         }
-        const MAX_POS = { quickstart: 1, init: 1, doctor: 0, receipt: 1, tokens: 2, dev: 0 };
+        const MAX_POS = { login: 1, logout: 0, quickstart: 1, init: 1, doctor: 0, receipt: 1, tokens: 2, dev: 0 };
         const exemptTail = (cmd === "approvals" && (positionals[0] === "approve" || positionals[0] === "reject")) || cmd === "verify";
         if (!exemptTail && cmd === "approvals" && positionals.length > 0) {
             err(`✘ unknown approvals subcommand "${positionals[0]}" — use approve or reject (or no subcommand to list).`);
@@ -1667,7 +2097,12 @@ async function main(argv) {
             return 2;
         }
     }
+    const gated = await updateGate(cmd, argv);
+    if (gated !== null)
+        return gated;
     switch (cmd) {
+        case "login": return cmdLogin(argsIn.find((x) => !x.startsWith("-")));
+        case "logout": return cmdLogout();
         case "quickstart": {
             if (argsIn.includes("cleanup")) {
                 const envFile = existsSync(".env.quickstart") ? ".env.quickstart"
@@ -1679,7 +2114,14 @@ async function main(argv) {
                             return ".env.quickstart";
                         } })();
                 if (!envFile) {
-                    log("Nothing to clean up here: no .env.quickstart, .env doesn't belong to a quickstart agent, and the token recovery journal owes nothing.");
+                    let held = [];
+                    try {
+                        held = journalOutstanding();
+                    }
+                    catch { }
+                    log(held.length
+                        ? `Nothing to clean up here: no tour credentials. The token recovery journal names ${held.length} live token(s) held by a credential file here (${held.map((j) => j.jti).join(", ")}) — not tour tokens, left alone; doctor lists them.`
+                        : "Nothing to clean up here: no .env.quickstart, .env doesn't belong to a quickstart agent, and the token recovery journal has no live token to act on.");
                     return 0;
                 }
                 const session = await acquireSession("Cleaning the quickstart up");
@@ -1687,7 +2129,7 @@ async function main(argv) {
                     return 1;
                 return quickstartCleanup(session, envFile);
             }
-            return cmdQuickstart({ autoApproveDemo: argsIn.includes("--auto-approve-demo"), keepAgent: argsIn.includes("--keep-agent") });
+            return cmdQuickstart({ autoApproveDemo: argsIn.includes("--auto-approve-demo"), keepAgent: argsIn.includes("--keep-agent"), explain: argsIn.includes("--explain"), phone: valuedOpt(argsIn, "--phone") });
         }
         case "init": {
             const unique = argsIn.includes("--unique");
@@ -1758,7 +2200,7 @@ async function main(argv) {
                 return 2;
             }
             if (!/^https?:\/\//.test(target)) {
-                err(`✘ --target needs an http(s) URL to forward the webhook to (got "${target}").`);
+                err(`✘ --target needs an http(s) URL to forward the webhook to (got "${redactUrl(target)}").`);
                 return 2;
             }
             return cmdDev(target, Number(portRaw));
@@ -1785,5 +2227,12 @@ const invokedAsProgram = (() => {
     }
 })();
 if (invokedAsProgram)
-    main(process.argv).then((code) => { if (code !== 0)
-        process.exitCode = code; }).catch((e) => { console.error(`✘ unexpected error: ${e?.message ?? e}`); process.exit(1); });
+    main(process.argv).then(async (code) => {
+        if (code !== 0)
+            process.exitCode = code;
+        if (stdinReadAbandoned) {
+            await new Promise((r) => process.stdout.write("", () => r()));
+            await new Promise((r) => process.stderr.write("", () => r()));
+            process.exit(code);
+        }
+    }).catch((e) => { console.error(`✘ unexpected error: ${e?.message ?? e}`); process.exit(1); });