@decidio/sdk 0.4.0 → 0.4.3

package/dist/cli.js

@@ -1,13 +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, didFromPrivateKey } from "./index.js";
+import { withApproval, DecidioRateLimitError, DecidioRejectedError, DecidioTimeoutError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
     try {
@@ -39,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) {
@@ -50,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") {
@@ -65,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)"}`);
@@ -90,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:`);
@@ -246,6 +254,33 @@ function journalRows() {
     }
     return rows;
 }
+function credentialJtisOnDisk() {
+    const out = new Set();
+    for (const f of [".env", ".env.quickstart"]) {
+        if (!existsSync(f))
+            continue;
+        let text = "";
+        try {
+            text = readFileSync(f, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const m of text.matchAll(/^\s*DECIDIO_(?:ORPHANED_)?TOKEN_JTI=(.+)$/gm))
+            for (const j of m[1].split(","))
+                if (j.trim())
+                    out.add(j.trim());
+    }
+    return out;
+}
+function journalOwed() {
+    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" && !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() {
     try {
@@ -263,16 +298,29 @@ 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()) {
         if (e.event === "minted")
             minted.set(e.jti, { jti: e.jti, agentId: e.agentId, label: e.label, apiUrl: e.apiUrl, at: e.at });
-        if (e.event === "retired")
+        if (e.event === "retired" && e.how === "persisted") {
+            const m = minted.get(e.jti);
+            if (m)
+                m.persisted = true;
+        }
+        if (e.event === "retired" && e.how === "revoked")
             minted.delete(e.jti);
     }
     return [...minted.values()];
@@ -337,66 +385,247 @@ 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) {
+    const a = String(answer ?? "").trim().toLowerCase();
+    if (APPROVE_WORDS.has(a))
+        return "approve";
+    if (REJECT_WORDS.has(a))
+        return "reject";
+    return "again";
+}
 function ask(question, mute = false) {
+    if (process.stdin.readableEnded || process.stdin.destroyed)
+        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.question(question, (answer) => { rl.close(); if (mute)
-            process.stderr.write("\n"); resolve(answer.trim()); });
+        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"));
+    }
+    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;
     }
-    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: ");
+    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;
@@ -581,6 +810,10 @@ async function cmdDoctor() {
     }
     for (const j of journalItems) {
         const where = j.apiUrl && j.apiUrl !== API ? `DECIDIO_API_URL=${j.apiUrl} ` : "";
+        if (j.jti === env.DECIDIO_TOKEN_JTI) {
+            line(true, `token recovery journal: jti ${j.jti} is live and held by ${ENV_PATH} — it retires only when revoked (npx @decidio/sdk tokens revoke ${j.jti}; a tour token: quickstart cleanup).`);
+            continue;
+        }
         warn(`token recovery journal: jti ${j.jti} (${j.label ?? "token"}, agent ${j.agentId ?? "?"}, minted ${j.at ?? "?"} against ${j.apiUrl ?? API}) has no recorded revocation in this directory's journal — it may still be live. Revoke it, or confirm it is gone: ${where}npx @decidio/sdk quickstart cleanup   (or: ${where}npx @decidio/sdk tokens revoke ${j.jti})`);
     }
     log(`✔ API URL: ${API}${(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL) ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
@@ -744,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>");
@@ -769,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;
@@ -873,16 +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 (public; it stays) · create one synthetic decision and its");
-    log("  sealed record (records are permanent by design). 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)
@@ -892,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++) {
@@ -911,7 +1173,7 @@ async function cmdQuickstart(opts = {}) {
         else {
             err(`  Check the target and your sign-in, then re-run: npx @decidio/sdk doctor`);
         }
-        err(`  Nothing was written to this directory.`);
+        err(`  No credential was written to this directory (the only write so far is the .gitignore entries above, which are safe to keep).`);
         return 1;
     }
     let prevTourFile = null;
@@ -958,8 +1220,10 @@ async function cmdQuickstart(opts = {}) {
             if (prevId && prevId !== agentId) {
                 if (prevJti) {
                     const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(prevJti)}`, { method: "DELETE" }, session);
-                    if (rv.status >= 200 && rv.status < 300)
+                    if (rv.status >= 200 && rv.status < 300) {
+                        journalRetire(prevJti, "revoked");
                         log(`  ✔ the previous tour agent (${prevId}) had its token REVOKED before this tour replaced it — no live credential is left behind`);
+                    }
                     else {
                         carried.add(prevJti);
                         log(`  ⚠ could not revoke the previous tour's token (jti ${prevJti}, ${rv.status}) — it is still LIVE. Its id is kept in ${envFile} as DECIDIO_ORPHANED_TOKEN_JTI, and \`quickstart cleanup\` will retry it; or revoke it by hand: npx @decidio/sdk tokens revoke ${prevJti}`);
@@ -986,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 {
@@ -1008,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,
@@ -1044,14 +1314,84 @@ 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) {
-        await ask(`③ YOU are the approver. Press Enter to approve it here (or approve it in your Decidio queue first, then Enter): `);
+        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";
+        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;
+                }
+            }
+        })();
+        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);
+        }
     }
     else if (opts.autoApproveDemo) {
         log("③ --auto-approve-demo: approving with your session credential. This is AUTOMATED authority");
@@ -1076,69 +1416,167 @@ 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 ap = 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 ? " (it was already approved from your app — even better)" : ""}`);
-    let done;
-    try {
-        done = await running;
-    }
-    catch (e) {
-        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…");
-    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 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}` : ""})`);
-    if (!v.valid) {
-        err(`  ✘ the receipt did not verify (${v.reason ?? "no reason given"}) — the tour did not complete.`);
-        return failTour(1);
+    const rejected = verdict === "reject";
+    if (rejected) {
+        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;
+        if (!decidedOutside)
+            log(decidedInApp ? `  • this decision was already decided from your app — the tour follows that decision` : `  ✔ rejected`);
+        let leaked;
+        let refused;
+        try {
+            leaked = await running;
+        }
+        catch (e) {
+            refused = e;
+        }
+        if (refused === undefined && !decidedInApp) {
+            err(`✘ the gated function RAN after the rejection (it returned ${JSON.stringify(leaked)}) — this is a defect, not a tour. Please report it: decidioai.com/#early-access`);
+            return failTour(1);
+        }
+        const ranOnAppApproval = refused === undefined;
+        if (ranOnAppApproval) {
+            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}${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.`);
+            return failTour(1);
+        }
+        log("");
+        const secsR = Math.round((Date.now() - t0) / 1000);
+        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("");
+        sessionReminder();
+        log(`${bold("Where next")}  your queue ${link(APP_URL)} · README "Production mode: durable async resume" ${dim("· built by OmniTwin — decidioai.com/#early-access")}`);
     }
-    if (!issuer) {
-        err(`  ⚠ the server did not return an issuer DID, so this check ran UNPINNED — it proves the`);
-        err(`    receipt is internally consistent, NOT who issued it (a self-signed forgery also passes).`);
-        err(`    Get your workspace's issuer DID from the app's record-verify panel, then re-check:`);
-        err(`      npx @decidio/sdk verify --issuer <did:key:...> ${fname}`);
-        err(`  ✘ the tour does not count an UNPINNED check as success.`);
-        return failTour(1);
+    else {
+        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(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;
+        }
+        catch (e) {
+            if (e instanceof DecidioRejectedError) {
+                err(`✘ it was REJECTED from your app before this tour's approval landed — your function did NOT run (that is the product). Re-run the tour to watch the approval half.`);
+                return failTour(1);
+            }
+            err(`✘ the gated call did not complete: ${e?.message ?? e}`);
+            return failTour(1);
+        }
+        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 = 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);
+        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);
+        }
+        if (!issuer) {
+            err(`  ⚠ the server did not return an issuer DID, so this check ran UNPINNED — it proves the`);
+            err(`    receipt is internally consistent, NOT who issued it (a self-signed forgery also passes).`);
+            err(`    Get your workspace's issuer DID from the app's record-verify panel, then re-check:`);
+            err(`      npx @decidio/sdk verify --issuer <did:key:...> ${fname}`);
+            err(`  ✘ the tour does not count an UNPINNED check as success.`);
+            return failTour(1);
+        }
+        const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
+        const tier = detail.body?.record?.confirmation?.status;
+        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);
+        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(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" }));${dim("   // durable by default")}`);
+        log("");
+        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")}`);
     }
-    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("");
-    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.`);
-    log("");
-    log("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(`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`);
     let doCleanup = false;
     if (interactive) {
         const answer = await ask(`\nKeep this agent for development? [Enter = keep · c + Enter = clean up now]: `);
@@ -1151,7 +1589,7 @@ async function cmdQuickstart(opts = {}) {
         log(`\nAutomated run: cleaning the tour up (pass --keep-agent to keep the agent + token).`);
     }
     const cleanupCode = doCleanup ? await quickstartCleanup(session, envFile) : 0;
-    return v.valid ? (cleanupCode || 0) : 1;
+    return cleanupCode || 0;
 }
 async function quickstartCleanup(session, envFile) {
     const env = (() => {
@@ -1172,13 +1610,25 @@ async function quickstartCleanup(session, envFile) {
     let journalRevoked = 0;
     const journalStuck = [];
     let outstanding = [];
+    let heldElsewhere = [];
+    let unheld = [];
+    let journalReconciled = 0;
     try {
-        outstanding = journalOutstanding();
+        const ownIds = new Set([env.DECIDIO_TOKEN_JTI, ...(env.DECIDIO_ORPHANED_TOKEN_JTI ?? "").split(",").map((s) => s.trim())].filter(Boolean));
+        outstanding = journalOwed().filter((j) => !ownIds.has(j.jti));
+        unheld = journalUnheld();
+        const owedIds = new Set(outstanding.map((j) => j.jti));
+        const unheldIds = new Set(unheld.map((j) => j.jti));
+        heldElsewhere = journalOutstanding().filter((j) => !owedIds.has(j.jti) && !unheldIds.has(j.jti) && !ownIds.has(j.jti));
     }
     catch (e) {
         err(`✘ the token recovery journal cannot be trusted (${e?.message ?? e}). It may hold the id of a live token, so this cleanup cannot claim nothing is owed. Every byte is left as found: inspect ${JOURNAL_PATH}, revoke anything it names (npx @decidio/sdk tokens list --mine), then repair or move it aside and re-run.`);
         return 1;
     }
+    for (const j of heldElsewhere)
+        log(`  • journalled token ${j.jti} (${j.label ?? "token"}) is live and still held by a credential file here — not a tour token, left alone (revoke it yourself: npx @decidio/sdk tokens revoke ${j.jti})`);
+    for (const j of unheld)
+        err(`  ⚠ journalled token ${j.jti} (${j.label ?? "token"}) is live: it was written to a credential file that is no longer here — not a tour token, so this cleanup will not revoke it. If it is yours and lost, revoke it: npx @decidio/sdk tokens revoke ${j.jti}`);
     for (const j of outstanding) {
         if (j.apiUrl && j.apiUrl !== API) {
             journalStuck.push(j.jti);
@@ -1188,11 +1638,14 @@ async function quickstartCleanup(session, envFile) {
         const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(j.jti)}`, { method: "DELETE" }, session);
         if (rv.status >= 200 && rv.status < 300) {
             journalRetire(j.jti, "revoked");
-            journalRevoked++;
-            if (rv.body?.changed === false)
+            if (rv.body?.changed === false) {
+                journalReconciled++;
                 log(`  • journalled token ${j.jti} was already revoked — retiring its journal entry.`);
-            else
-                log(`  ✔ journalled token revoked (jti ${j.jti}${j.label ? `, ${j.label}` : ""}) — its credential file never landed, so this was its only handle`);
+            }
+            else {
+                journalRevoked++;
+                log(`  ✔ journalled token revoked (jti ${j.jti}${j.label ? `, ${j.label}` : ""}) — from the journal: ${j.persisted ? "its credential file is gone" : "its credential file never landed"}, so the journal was the handle`);
+            }
         }
         else {
             journalStuck.push(j.jti);
@@ -1209,8 +1662,10 @@ async function quickstartCleanup(session, envFile) {
     const stillOrphaned = [];
     for (const jti of orphans) {
         const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, session);
-        if (rv.status >= 200 && rv.status < 300)
+        if (rv.status >= 200 && rv.status < 300) {
+            journalRetire(jti, "revoked");
             log(`  ✔ orphaned token revoked (jti ${jti}) — it had survived an earlier replace`);
+        }
         else {
             stillOrphaned.push(jti);
             err(`  ⚠ orphaned token ${jti} could NOT be revoked (${rv.status}) — it is still live.`);
@@ -1224,6 +1679,8 @@ 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)
+            journalRetire(env.DECIDIO_TOKEN_JTI, "revoked");
         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)
@@ -1238,6 +1695,12 @@ async function quickstartCleanup(session, envFile) {
     else if (journalRevoked > 0 && !existsSync(envFile) || (journalRevoked > 0 && Object.keys(env).length === 0)) {
         log(`  • no credential file to clean: the journal sweep revoked ${journalRevoked} token(s) this directory owed.`);
     }
+    else if (!existsSync(envFile)) {
+        if (unheld.length)
+            err(`  • no credential file here (${envFile} is already gone); the journal names ${unheld.length} live token(s) this cleanup will not revoke (above).`);
+        else
+            log(`  • no credential file here (${envFile} is already gone) and the token recovery journal owes nothing further${journalReconciled ? ` (${journalReconciled} already-revoked row(s) reconciled)` : ""}.`);
+    }
     else {
         err(`✘ no DECIDIO_TOKEN_JTI in ${envFile} (older tour) — this tour's token is STILL LIVE and this`);
         err(`  command cannot revoke it. Nothing was deleted. Find and revoke it, then re-run cleanup:`);
@@ -1281,12 +1744,18 @@ async function quickstartCleanup(session, envFile) {
     }
     log(`  • What remains, by design: the sealed decision record (records are permanent — that is the product)`);
     log(`    and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap).`);
+    if (existsSync(JOURNAL_PATH))
+        log(`  • Also kept: ${JOURNAL_PATH} — the ids and timestamps of what this directory minted and revoked (no secrets). Gitignored; owner-only where the OS supports it.`);
     if (existsSync(".decidio-pending")) {
         log(`  • Also kept: .decidio-pending/ — this agent's own execution ledger: whatever this agent parked (call arguments,`);
         log(`    execution evidence; never credentials, by design). Gitignored; owner-only where the OS supports it. If nothing is`);
         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) {
@@ -1358,6 +1827,13 @@ async function cmdTokens(sub, jti, mineOnly = false) {
     return 0;
 }
 function cmdDev(target, port) {
+    try {
+        assertSafeTransport(target, true);
+    }
+    catch (e) {
+        err(`✘ dev relay refused: ${e?.message ?? e}`);
+        return 2;
+    }
     log(`decidio dev relay on http://localhost:${port}/decidio/resume → forwarding to ${target}`);
     createServer((req, res) => {
         if (req.method !== "POST") {
@@ -1379,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
@@ -1393,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]
@@ -1419,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") {
@@ -1448,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"] },
@@ -1491,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).`);
@@ -1510,19 +2097,31 @@ 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"
                     : (readEnvFile().DECIDIO_AGENT_ID ?? "").startsWith("quickstart-") ? ENV_PATH
                         : (() => { try {
-                            return journalOutstanding().length ? ".env.quickstart" : undefined;
+                            return (journalOwed().length || journalUnheld().length) ? ".env.quickstart" : undefined;
                         }
                         catch {
                             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");
@@ -1530,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");
@@ -1601,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));
@@ -1614,5 +2213,26 @@ async function main(argv) {
             return 2;
     }
 }
-main(process.argv).then((code) => { if (code !== 0)
-    process.exitCode = code; }).catch((e) => { console.error(`✘ unexpected error: ${e?.message ?? e}`); process.exit(1); });
+const invokedAsProgram = (() => {
+    const entry = process.argv[1];
+    if (!entry)
+        return true;
+    if (/(^|[\\/])(cli\.(js|mjs|ts)|decidio(\.cmd|\.ps1)?)$/i.test(entry))
+        return true;
+    try {
+        return toFileUrl(realPath(entry)).href === toFileUrl(realPath(fromFileUrl(import.meta.url))).href;
+    }
+    catch {
+        return true;
+    }
+})();
+if (invokedAsProgram)
+    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); });