@decidio/sdk 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -4,6 +4,67 @@ Release notes for the client SDK. The Python package `decidio` ships the same ch
 version (the two are conformance-locked twins). Each entry names what changed, what a reader must do
 on upgrade, and what proved it.
 
+## 0.6.2 — the fork after its first real run
+
+Founder UAT of 0.6.1 on a Windows console, same day.
+
+- **Prompts pause.** On the founder's cmd.exe the agent-id prompt "took the folder's" name without waiting. The
+  terminal driver could not reproduce it, so this is defence plus instrumentation: one readline now lives for the whole
+  command (a console's `\r\n` can no longer split across two questions - the previous per-question interfaces could
+  hand the second byte to the next prompt as Enter), and `DECIDIO_DEBUG_INPUT=1` prints the raw bytes stdin delivers, so
+  a recurrence names its cause instead of a theory.
+- **"What next?" has a way out:** `3  sign out of this computer  (npx @decidio/sdk logout)`.
+- **Option 2 in a folder that already holds an agent** says so before asking for a name (with cleanup / a new folder /
+  `--force` as the ways out), instead of `init` refusing afterwards with text that read like a prompt.
+- **The bare command is update-gated** on a terminal, so a cached old npx copy announces the newer version instead of
+  quietly showing an old first screen; `npx @decidio/sdk` is enough, `@latest` is not needed.
+- **Sign in by CODE, not by paste.** When the command line asks for a sign-in, the email it triggers carries an
+  8-character code and nothing to click; you type the code into the terminal that asked (dashes, case and an O for a 0
+  are forgiven). Three misses and the code is dead. The web app's sign-in screen keeps its link email unchanged; two
+  flows, each with exactly one action. Why this shape and not "click the link and the terminal continues": that design
+  moves a session to a DIFFERENT device than the one that clicked, which is a new attack class the privacy council had
+  to harden (docs/Decidio_CLI_Signin_Wait_Spec.md, retired); a code travels from the inbox to the device you are
+  sitting at, and an attacker who triggers the email gains nothing. A pasted link is still accepted, quietly.
+- **`npx decidio`.** A new npm package named `decidio` holds one file: it resolves the `@decidio/sdk` it pins (same
+  version, released in lockstep) and runs that CLI. `npx decidio …` is `npx @decidio/sdk …` with fewer keystrokes; the
+  update gate names whichever package you came through. Not something to import - the SDK stays `@decidio/sdk`.
+
+## 0.6.1 — the first-run fork, and the local demo's loose ends
+
+Two independent first-run reviews of 0.6.0 (grades B / A− overall) agreed on one thing: the hosted tour and the
+verifier earn trust, and the new local demo had polish debts. This release pays them and adds the one question a
+stranger's first minute was missing (founder ruling 2026-09-06).
+
+- **One question, then the thing you picked.** A bare `npx @decidio/sdk quickstart` (or a bare `npx @decidio/sdk`) on
+  a terminal with no sign-in asks: do you have a Decidio invite? `n` runs the local demo; `y` signs you in (the emailed
+  link) and asks what next: the two-minute tour, or wiring up your own agent (`init`). Every answer prints the exact
+  command it stands for, so the questions teach their own flags and you never need them twice. Nothing is stored;
+  Enter is not an answer; scripts and CI never see a question (they get today's text, which now also names `--demo`).
+  A signed-in `quickstart` runs straight away; the bare `npx @decidio/sdk` for a signed-in user skips the invite
+  question and asks only "what next?" - the bare command always leads somewhere, usage is a `--help` away. After
+  the sign-in step, the tour does not ask you to sign in again.
+- **Your agent's name has a real default.** `init` with no name used `my-agent`; it now uses this folder's name (or
+  the package name), slugified, and the fork explains what the name is for ("Requested by …", the key `.env` is
+  written under). Any name still works.
+- **A mark, not a banner:** the title lines carry the app's ✦ beside the name.
+- **Headless `--demo` leaves nothing behind** (review: Medium). The stop at the human moment used to exit inside the
+  tour, skipping the wrapper that removes the temporary folder - the mock key, mock token and journal stayed in the
+  temp dir, and the message pointed at the hosted tour's remedies (`approvals approve`, `quickstart cleanup`), which
+  cannot act on a stand-in that lives only in that process. The stop now returns through the wrapper, and says the
+  demo's truth: nothing executed, nothing kept, re-run interactively or with `--auto-approve-demo`.
+- **The demo receipt carries what the terminal claims** (review: Medium). Its canonical record now holds the real
+  amount and currency, the reason the decision arrived with (the automated flag names itself there, exactly as it does
+  in a hosted record's reason), and how it was decided (terminal, page, or the flag). The party stays tokenized, as
+  the real seal keeps it.
+- **`--demo --keep-agent` is refused** (both reviews: Low) - nothing of the demo's can be kept, and the flag used to
+  be accepted while the opposite happened. Exit 2, with the reason.
+- **A receipt the demo could not copy home is not a completed tour** (retest: Low): the temporary folder is kept and
+  named, and the run exits non-zero, instead of deleting the only copy and exiting 0.
+- **Words that were not true** (review: Low): the demo's Target line no longer says "nothing hosted" while the web
+  door uses a hosted relay; the automated line names the demo's mock credential, not "your session credential"; a
+  repeat run's ④ frame names the suffixed file that actually lands; the README no longer calls the sandbox "one shared
+  lab workspace" in two places while saying the opposite in a third.
+
 ## 0.6.0 — `quickstart --demo`: the whole tour on your machine, no account
 
 An uninvited developer could not run the tour at all: a workspace needs an invite (no open signup, by ruling). A

package/README.md

@@ -9,8 +9,12 @@ is the two-minute tour, the sign-in and the token admin around it. Install, wrap
 ## The two-minute tour
 
 ```bash
+npx decidio                          # the short form: asks one question, then does the thing you picked
 npx @decidio/sdk quickstart          # against your workspace (you need an invite - request one below)
 npx @decidio/sdk quickstart --demo   # no invite yet? the same tour on this machine, against a local stand-in of the API
+# Not sure? The bare command asks: with no sign-in on this computer it asks whether you have an
+# invite (n → the local demo; y → sign in, then the tour or your own agent). Every answer prints
+# the command it stands for, so you never need the questions twice.
 ```
 
 One command, guided: it registers a fresh agent (key generated locally), gates a demo action
@@ -71,8 +75,8 @@ npx @decidio/sdk init --unique my-agent   # --unique appends a random suffix: co
 Every network command talks to the hosted sandbox by default (`verify` is offline) and announces its target host on
 stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another Decidio instead.
 
-`init` signs you into your workspace (email + password, or paste the sign-in link from your
-workspace email), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
+`init` signs you into your workspace (email + password, or the 8-character code the CLI emails you —
+type it where you asked), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
 is sent), registers the agent, mints its **floor-limited API token** (limited to the agent runtime — request authorization, poll status, report signed confirmation; it cannot administer the workspace or approve anything — and your workspace session never touches the agent's disk), and writes `.env`.
 Every later command that talks to Decidio reads `.env` from this directory automatically (`verify` is
 offline and never does). Re-running init for an
@@ -88,7 +92,7 @@ agent name — if it's already taken in your workspace, `init` stops cleanly and
 fresh one (or pass `--unique` to auto-append a random suffix — collision-proof for shared
 workspaces and CI). Interactive terminals sign in once (`npx @decidio/sdk login` — stored owner-only in your
 profile, bound to this terminal window, 30 days). Headless terminal (no prompts possible)? Export `DECIDIO_SESSION_TOKEN` first:
-request a sign-in link, then exchange its `?login=` value at `POST /demo/login-consume` — the
+request a sign-in link from the web app's sign-in screen, then exchange its `?login=` value at `POST /demo/login-consume` — the
 response's `token` is your session token (the CLI prints these exact instructions when it
 can't prompt). That session token is your workspace login, not the agent's credential: unset it
 before launching agent code from the same shell, because child processes inherit exported
@@ -137,8 +141,8 @@ the agent's floor-limited token — it cannot approve anything):
 
 ```bash
 npx @decidio/sdk approvals --mine        # see it pending (--mine narrows to THIS agent; the
-                                         # sandbox is one shared lab workspace, so the bare
-                                         # command lists every member's pending decisions)
+                                         # workspace is yours alone unless you invite others,
+                                         # so the bare command lists every pending decision in it)
 npx @decidio/sdk approvals approve <decisionId>
 ```
 
@@ -747,7 +751,7 @@ the next reader grades a promise, not a moving target:
 
 ## Using this for real?
 
-The hosted sandbox is synthetic and shared. Production workspaces are per-tenant, with your own
+The hosted sandbox is synthetic data in a workspace of your own. Production workspaces are per-tenant too, with your own
 issuer key and receipts that verify offline against it.
 
 [decidioai.com](https://decidioai.com) · [Developer docs](https://decidioai.com/developers/) · [Request access](https://decidioai.com/#early-access)

package/dist/cli.d.ts

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 export type ApprovalAnswer = "approve" | "reject" | "again";
 export declare function approvalAnswer(answer: unknown): ApprovalAnswer;
+/** The agent id `init` uses when none is given: this folder's name (or the package name), slugified. "my-agent" told a
+ *  tester nothing; the folder they are in is the agent they are building (founder ruling 2026-09-06). */
+export declare function defaultAgentId(dir?: string): string;
 /** `decidio-receipt-<id>.json`, with every character outside [A-Za-z0-9_-] escaped as `~` + hex code point, so two
  *  distinct decision ids can never share a file (first-run review of 0.4.1: dots were STRIPPED, `a.b` and `ab`
  *  collided). `~` is outside the allowed set, so the escape is unambiguous. Exported for the smokes. */

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync, openSync, writeSync, fsyncSync, closeSync, renameSync, mkdirSync, mkdtempSync, readdirSync, copyFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { homedir, tmpdir } from "node:os";
-import { join as joinPath, resolve as resolvePath, sep as pathSep } from "node:path";
+import { join as joinPath, resolve as resolvePath, sep as pathSep, basename } from "node:path";
 import { createServer } from "node:http";
 import { execFileSync, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
@@ -416,6 +416,7 @@ 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 brand = () => `${paint("38;5;178", "✦")} ${paint("38;5;29", bold("Decidio"))}`;
 const FRAME_WIDTH = 84;
 const visibleLength = (s) => s.replace(/\x1b\[[0-9;]*m|\x1b\]8;;[^\x1b]*\x1b\\/g, "").length;
 function frameWidth(rows) {
@@ -466,24 +467,42 @@ export function approvalAnswer(answer) {
         return "reject";
     return "again";
 }
+let sharedRl = null;
+let sharedRlOpen = false;
+function closeSharedRl() { if (sharedRlOpen) {
+    sharedRlOpen = false;
+    sharedRl?.close();
+} }
 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 });
+        if (!sharedRl || !sharedRlOpen) {
+            sharedRl = createInterface({ input: process.stdin, output: process.stderr, terminal: true, crlfDelay: Infinity });
+            sharedRlOpen = true;
+            sharedRl.once("close", () => { sharedRlOpen = false; });
+        }
+        const rl = sharedRl;
         currentRl = rl;
+        let restore = null;
         if (mute) {
             const anyRl = rl;
             const write = anyRl._writeToOutput?.bind(rl);
             anyRl._writeToOutput = (s) => { if (s.includes(question))
                 write?.(s); };
-        }
-        rl.once("close", () => { if (currentRl === rl)
-            currentRl = null; resolve(""); });
-        rl.question(question, (answer) => { resolve(answer.trim()); rl.close(); if (mute)
-            process.stderr.write("\n"); });
+            restore = () => { anyRl._writeToOutput = write; };
+        }
+        const onClose = () => { if (currentRl === rl)
+            currentRl = null; restore?.(); resolve(""); };
+        rl.once("close", onClose);
+        rl.question(question, (answer) => { rl.off("close", onClose); if (currentRl === rl)
+            currentRl = null; restore?.(); if (mute)
+            process.stderr.write("\n"); resolve(answer.trim()); });
     });
 }
+if (process.env.DECIDIO_DEBUG_INPUT && process.stdin.isTTY) {
+    process.stdin.on("data", (c) => { process.stderr.write(`[stdin ${Buffer.from(c).toString("hex")}]\n`); });
+}
 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];
@@ -566,29 +585,37 @@ async function loginFlow(purpose, emailArg) {
         }
         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 }) }, "");
+    const req = await api("/demo/login-link", { method: "POST", body: JSON.stringify({ email, code: true }) }, "");
     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`));
+    log(`  ✔ sign-in email sent to ${email} — it holds an 8-character code (single-use, 15 minutes). Check spam too.`);
+    log(dim(`    invite-only lab: an email arrives only for an invited address — not invited yet? request access: decidioai.com/#early-access`));
     log(dim(`    or see the whole story on this machine right now, no account: npx @decidio/sdk quickstart --demo`));
-    const pasted = await ask("  link or code: ");
-    if (!pasted) {
-        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) {
-        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;
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        const typed = await ask("  code from the email: ");
+        if (!typed) {
+            log("  ✘ nothing typed — re-run when you have the email.");
+            return null;
+        }
+        const m = typed.match(/[?&]login=([^&\s]+)/);
+        const isLink = !!m || /^[0-9a-f]{32,}$/i.test(typed);
+        const body = isLink ? { token: m ? decodeURIComponent(m[1]) : typed } : { token: "c." + typed.toUpperCase().replace(/[^0-9A-Z]/g, "").replace(/O/g, "0").replace(/[IL]/g, "1").slice(0, 8), email };
+        const r = await api("/demo/login-consume", { method: "POST", body: JSON.stringify(body) }, "");
+        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;
+        }
+        if (isLink) {
+            log(`  ✘ that link didn't work (${r.status})${r.body?.error ? ` — ${r.body.error}` : ""}. Sign-in links are single-use and expire in 15 minutes — request a fresh one and re-run.`);
+            return null;
+        }
+        if (attempt < 3)
+            log(`  ✘ that code didn't work — check the email and try again (${3 - attempt} ${3 - attempt === 1 ? "try" : "tries"} left)`);
     }
-    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.`);
+    log(`  ✘ three misses — that code is now dead. Re-run to get a fresh email.`);
     return null;
 }
 async function acquireSession(purpose) {
@@ -608,12 +635,95 @@ async function acquireSession(purpose) {
     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(`  or set DECIDIO_SESSION_TOKEN - or, with no account at all: npx @decidio/sdk quickstart --demo. 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);
 }
+export function defaultAgentId(dir = process.cwd()) {
+    let name = "";
+    try {
+        const pkg = JSON.parse(readFileSync(joinPath(dir, "package.json"), "utf8"));
+        if (typeof pkg?.name === "string")
+            name = pkg.name.replace(/^@[^/]+\//, "");
+    }
+    catch { }
+    if (!name)
+        name = basename(dir);
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+    return slug || "my-agent";
+}
+async function firstRunFork(signedInAs = null) {
+    const pick = async (prompt, ok) => {
+        let a = "";
+        for (let i = 0; i < 3 && !ok.test(a); i++)
+            a = (await ask(i === 0 ? "  › " : `   Please answer ${prompt}: `)).trim().toLowerCase();
+        return ok.test(a) ? a : "";
+    };
+    log("");
+    if (signedInAs !== null) {
+        log(`  Signed in${signedInAs ? ` as ${signedInAs}` : ""} on this computer.`);
+    }
+    else {
+        log(`  Do you have a Decidio invite?   ${dim("[y/n]")}`);
+        log(`    ${bold("n")}   the local demo on this machine, no account          ${dim("npx @decidio/sdk quickstart --demo")}`);
+        log(`    ${bold("y")}   sign in to your workspace                           ${dim("npx @decidio/sdk login")}`);
+        const a = await pick("y or n", /^[yn]$/);
+        if (!a) {
+            log(`  No answer — nothing was done. Run either command above when you are ready.`);
+            return { kind: "stop", code: 1 };
+        }
+        if (a === "n") {
+            log(`  → running: npx @decidio/sdk quickstart --demo`);
+            log("");
+            return { kind: "demo" };
+        }
+        log(`  → running: npx @decidio/sdk login`);
+        const token = await loginFlow("Signing in");
+        if (!token)
+            return { kind: "stop", code: 1 };
+    }
+    log("");
+    log(`  What next?   ${dim("[1/2/3]")}`);
+    log(`    ${bold("1")}   the two-minute tour against your workspace         ${dim("npx @decidio/sdk quickstart")}`);
+    log(`    ${bold("2")}   wire up your own agent now (register, token, .env)  ${dim("npx @decidio/sdk init <agentId>")}`);
+    log(`    ${bold("3")}   sign out of this computer                           ${dim("npx @decidio/sdk logout")}`);
+    const b = await pick("1, 2 or 3", /^[123]$/);
+    if (!b) {
+        log(`  No answer — you are signed in; run any command above when you are ready.`);
+        return { kind: "stop", code: 0 };
+    }
+    if (b === "1") {
+        log(`  → running: npx @decidio/sdk quickstart   ${dim("(signed in - it will not ask again)")}`);
+        log("");
+        return { kind: "tour" };
+    }
+    if (b === "3") {
+        log(`  → running: npx @decidio/sdk logout`);
+        log("");
+        return { kind: "logout" };
+    }
+    const here = readEnvFile();
+    if (["DECIDIO_AGENT_KEY", "DECIDIO_API_TOKEN"].some((k) => (here[k] ?? "").trim()) && here.DECIDIO_AGENT_ID) {
+        const tour = /^quickstart-/.test(here.DECIDIO_AGENT_ID);
+        log(`  This folder's .env already holds an agent (${tour ? "the tour's, " : ""}"${here.DECIDIO_AGENT_ID}"). A new agent here would overwrite its key.`);
+        log(`  Either: start in a new folder          ${dim("mkdir <name> && cd <name> && npx @decidio/sdk")}`);
+        if (tour)
+            log(`      or: clear the tour's agent first   ${dim("npx @decidio/sdk quickstart cleanup")}   then run this again`);
+        log(`      or: replace it, backing .env up     ${dim("npx @decidio/sdk init <name> --force")}`);
+        return { kind: "stop", code: 1 };
+    }
+    const def = defaultAgentId();
+    log(`  Your agent needs a name. It is how the workspace shows the request ("Requested by ${def.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")}")`);
+    log(`  and the key .env is written under. Any name works; Enter takes the folder's.`);
+    const typed = (await ask(`  agent id [${def}]: `)).trim();
+    const agentId = typed || def;
+    log(`  → running: npx @decidio/sdk init ${agentId}   ${dim("(next time, skip the questions: run that directly)")}`);
+    log("");
+    return { kind: "init", agentId };
+}
+const forkApplies = () => !!(process.stdin.isTTY && process.stdout.isTTY) && !process.env.DECIDIO_SESSION_TOKEN && !loadSession();
 async function cmdLogin(emailArg) {
     try {
         assertSafeTransport(API, true);
@@ -653,9 +763,8 @@ async function cmdInit(agentId, opts = {}) {
         err(`✘ this directory's .env already holds the key for a DIFFERENT agent ("${existingEnv.DECIDIO_AGENT_ID}").`);
         err(`  Registering "${agentId}" here would overwrite that key — and a private key that is`);
         err(`  overwritten is gone for good (it never left this machine). Nothing was written.`);
-        err(`  Pick one:`);
-        err(`    1. New directory (cleanest): mkdir ${agentId} && cd ${agentId} && npx @decidio/sdk init ${agentId}`);
-        err(`    2. Replace the old agent here, backing its .env up first: npx @decidio/sdk init ${agentId} --force`);
+        err(`  Either: a new directory (cleanest):   mkdir ${agentId} && cd ${agentId} && npx @decidio/sdk init ${agentId}`);
+        err(`      or: replace the old agent here, backing its .env up first:   npx @decidio/sdk init ${agentId} --force`);
         return 1;
     }
     const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
@@ -994,7 +1103,10 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
     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`;
+    const base = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, (c) => "~" + c.codePointAt(0).toString(16).padStart(2, "0"))}.json`;
+    if (DEMO_ORIGIN && DEMO_STAMP && existsSync(joinPath(DEMO_ORIGIN, base)))
+        return base.replace(/\.json$/, `.${DEMO_STAMP}.json`);
+    return base;
 }
 function writeReceiptFile(name, bytes, say = log) {
     if (existsSync(name)) {
@@ -1155,17 +1267,28 @@ function valuedOpt(args, flag) {
     const eq = args.find((x) => x.startsWith(flag + "="));
     return eq ? eq.slice(flag.length + 1) : undefined;
 }
+let DEMO_ORIGIN = null;
+let DEMO_STAMP = null;
 async function cmdQuickstart(opts = {}) {
     if (!opts.demo)
         return cmdQuickstartInner(opts);
+    if (opts.keepAgent) {
+        err(`✘ --keep-agent has nothing to keep under --demo: the demo's agent and token live in a temporary folder that is removed at the end (only the receipt stays).`);
+        err(`  Drop --keep-agent, or run the hosted tour (npx @decidio/sdk quickstart) where --keep-agent keeps a real agent + token.`);
+        return 2;
+    }
     const relayBase = SHELL_ENV.DECIDIO_DEMO_RELAY_URL === undefined ? "https://decidio-api.onrender.com" : (SHELL_ENV.DECIDIO_DEMO_RELAY_URL || null);
     const gate = await startDemoGate({ relayBase });
     enterDemo(gate.url);
     const origin = process.cwd();
     const work = mkdtempSync(joinPath(tmpdir(), "decidio-demo-"));
+    DEMO_ORIGIN = origin;
+    DEMO_STAMP = String(Date.now());
     process.chdir(work);
+    let code = 1;
+    let copyFailed = false;
     try {
-        return await cmdQuickstartInner(opts);
+        code = await cmdQuickstartInner(opts);
     }
     finally {
         process.chdir(origin);
@@ -1180,12 +1303,17 @@ async function cmdQuickstart(opts = {}) {
                 log(`  receipt kept here: ${target.slice(origin.length + 1)}   ${dim("(the demo's agent, token and files lived in a temporary folder, now removed)")}`);
             }
             catch (e) {
-                err(`  ⚠ could not copy the receipt into this folder (${e?.message ?? e}) — it is at ${joinPath(work, f)}`);
+                copyFailed = true;
+                err(`  ✘ could not copy the receipt into this folder (${e?.message ?? e}) — the temporary folder is KEPT so the receipt is not lost: ${joinPath(work, f)}`);
             }
         }
-        rmSync(work, { recursive: true, force: true });
+        if (!copyFailed)
+            rmSync(work, { recursive: true, force: true });
         await gate.close();
+        DEMO_ORIGIN = null;
+        DEMO_STAMP = null;
     }
+    return copyFailed ? (code || 1) : code;
 }
 async function cmdQuickstartInner(opts = {}) {
     const t0 = Date.now();
@@ -1194,9 +1322,9 @@ async function cmdQuickstartInner(opts = {}) {
         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(brand() + bold(" quickstart") + " — gate an action, route it to a human, execute on approval, hold the proof.");
     if (DEMO)
-        log(`  Target: LOCAL DEMO — an in-process stand-in for the Decidio API on this machine (${API}); nothing hosted, nothing kept`);
+        log(`  Target: LOCAL DEMO — an in-process stand-in for the Decidio API on this machine (${API}). Only the web/phone door touches a hosted relay (one word, no account); nothing is kept but the receipt`);
     else
         log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : dim("  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)")}`);
     hostAnnounced = true;
@@ -1458,26 +1586,52 @@ async function cmdQuickstartInner(opts = {}) {
             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`);
+            if (DEMO) {
+                log(`   Nothing executed and no receipt was written. Nothing is kept: the demo's agent, token and folder go now.`);
+                log(`   Re-run and answer y or n (or use the web page / QR).`);
+            }
+            else {
+                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);
+            currentRl?.close();
+            stdinReadAbandoned = true;
+            return 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`);
+            if (DEMO)
+                log(`   the demo ends here; nothing is kept (the demo's agent, token and folder go now). Re-run and answer within 5 minutes.`);
+            else {
+                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);
+            currentRl?.close();
+            stdinReadAbandoned = true;
+            return 3;
         }
     }
     else if (opts.autoApproveDemo) {
-        log("③ --auto-approve-demo: approving with your session credential. This is AUTOMATED authority");
+        log(`③ --auto-approve-demo: approving with ${DEMO ? "the demo's mock credential (no account is involved)" : "your session credential"}. This is AUTOMATED authority`);
         log("   (a flag you passed, not a human decision in the moment) — fine for CI, not the real story.");
     }
+    else if (DEMO) {
+        log("③ This terminal can't put a human in the loop, and an approval IS a human act — the demo stops here");
+        log("   rather than approve its own request. Nothing executed, no receipt was written, and nothing is kept:");
+        log("   the demo's agent, token and working folder go now (the stand-in API lives only in this process).");
+        log("");
+        log("   Re-run in an interactive terminal and answer y or n there, on the web page or by QR — or, for CI:");
+        log("     npx @decidio/sdk quickstart --demo --auto-approve-demo     (the tour approves itself under that explicit label)");
+        log("");
+        log("   (exit 3 = the demo stopped at the human moment; deliberately not reported as a completed tour.)");
+        stdinReadAbandoned = true;
+        return 3;
+    }
     else {
         log("③ This terminal can't put a human in the loop, and an approval IS a human act — the tour");
         log("   stops here rather than approve its own request. The decision is routed and waiting —");
@@ -1499,7 +1653,8 @@ async function cmdQuickstartInner(opts = {}) {
         log(`   or if you abandon the tour — remove them: npx @decidio/sdk quickstart cleanup`);
         log("");
         sessionReminder();
-        process.exit(3);
+        stdinReadAbandoned = true;
+        return 3;
     }
     const rejected = verdict === "reject";
     if (rejected) {
@@ -1644,7 +1799,7 @@ async function cmdQuickstartInner(opts = {}) {
         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("decided")}      ${decidedOutside ? "approved in the web app (or on your phone)" : opts.autoApproveDemo ? `approved by --auto-approve-demo (automated — the ${DEMO ? "receipt's reason says so" : "record's reason says so"})` : "approved by you, here"}`,
             `${bold("executed")}     your function ran once, AFTER approval`,
             `${bold("receipt")}      VALID — verified offline, pinned to ${DEMO ? "this demo's own key" : "your workspace issuer"} (④ above)`,
             dim("gated → routed to a human → approved → executed once → a receipt you can verify offline"),
@@ -1968,7 +2123,7 @@ function cmdDev(target, port) {
     }).listen(port, "127.0.0.1");
     return 0;
 }
-const USAGE = `decidio — the Decidio SDK command line
+const USAGE = `✦ Decidio — the 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.
@@ -1977,6 +2132,10 @@ const USAGE = `decidio — the Decidio SDK command line
 
       npx @decidio/sdk quickstart
 
+  With no sign-in on this computer it first asks ONE question - do you have an invite? - and, if you do,
+  what next: the tour, or wiring up your own agent. Every answer shows the command it stands for. The bare
+  npx @decidio/sdk on a terminal asks the same (skipping the invite question when you are signed in).
+
   It gates a demo action, routes it to YOU for approval, executes on your yes, and hands you a
   cryptographically verifiable receipt of the DECISION (execution evidence then accrues on the
   hosted record — the receipt seals who authorized what, not what ran afterward). Guided and
@@ -1995,16 +2154,18 @@ THE TOUR
   npx @decidio/sdk quickstart --auto-approve-demo   headless tour; cleans up after itself
   npx @decidio/sdk quickstart --demo   the same tour against a LOCAL stand-in of the API — no account needed; the
                                        web/phone door is a hosted demo page; the receipt is the one thing kept
-                                       (add --keep-agent to KEEP the tour agent + token)
+                                       (--keep-agent is refused here: nothing of the demo's can be kept)
 
 SIGN IN (once)
-  npx @decidio/sdk login [email]       sign in ONCE: the CLI emails you a link, you paste it; the sign-in
+  npx @decidio/sdk login [email]       sign in ONCE: the CLI emails you an 8-character code, you type it; the sign-in
                                        is kept on this computer 30 days, or until this terminal closes, logout, or cleanup
   npx @decidio/sdk logout              forget the stored sign-in on this computer (the token itself stays valid
                                        until it expires — there is no server-side revocation yet)
 
 YOUR AGENT AND ITS TOKENS
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
+                                       (agentId defaults to this folder's name; any name works - it is how the
+                                       workspace shows the request and the key .env is written under)
                                        --unique  append a random suffix (collision-proof samples)
                                        --force   replace a different agent already in this .env
                                                  (its .env is backed up first)
@@ -2037,7 +2198,8 @@ 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,
+  Update check: network commands (and the bare command on a terminal) 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 the way you installed - global, or in the
   project for a local install; under npx it prints the @latest form - 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
@@ -2092,7 +2254,8 @@ async function latestPublished() {
     }
 }
 async function updateGate(cmd, argv) {
-    if (!cmd || !GATED_CMDS.has(cmd) || SHELL_ENV.DECIDIO_NO_UPDATE_CHECK || SHELL_ENV.DECIDIO_UPDATE_REEXEC || VERSION === "unknown" || VERSION.includes("-"))
+    const gatedHere = cmd ? GATED_CMDS.has(cmd) : !!(process.stdin.isTTY && process.stdout.isTTY);
+    if (!gatedHere || SHELL_ENV.DECIDIO_NO_UPDATE_CHECK || SHELL_ENV.DECIDIO_UPDATE_REEXEC || VERSION === "unknown" || VERSION.includes("-"))
         return null;
     const latest = await latestPublished();
     if (!latest || !semverNewer(latest, VERSION))
@@ -2108,7 +2271,9 @@ async function updateGate(cmd, argv) {
         const cwd = norm(process.cwd());
         return cwd === norm(root) || cwd.startsWith(norm(root) + pathSep) ? root : null;
     })();
-    const upgradeCmd = underNpx ? `npx @decidio/sdk@latest ${argv.slice(2).join(" ")}` : localRoot ? "npm i @decidio/sdk@latest" : "npm i -g @decidio/sdk@latest";
+    const viaAlias = /[\\/]decidio$/.test(argv[1] ?? "");
+    const pkgName = viaAlias ? "decidio" : "@decidio/sdk";
+    const upgradeCmd = underNpx ? `npx ${pkgName}@latest ${argv.slice(2).join(" ")}` : localRoot ? `npm i ${pkgName}@latest` : `npm i -g ${pkgName}@latest`;
     const notice = `${latest} is available (you have ${VERSION}).`;
     if (!(process.stdin.isTTY && process.stdout.isTTY)) {
         err(`⚠ ${notice} Upgrade: ${upgradeCmd}`);
@@ -2132,7 +2297,7 @@ async function updateGate(cmd, argv) {
         return null;
     }
     log(`  upgrading: ${upgradeCmd}${localRoot ? ` (in ${localRoot})` : ""}`);
-    const up = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", localRoot ? ["i", "@decidio/sdk@latest"] : ["i", "-g", "@decidio/sdk@latest"], { stdio: "inherit", shell: process.platform === "win32", env: SHELL_ENV, ...(localRoot ? { cwd: localRoot } : {}) });
+    const up = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", localRoot ? ["i", `${pkgName}@latest`] : ["i", "-g", `${pkgName}@latest`], { stdio: "inherit", shell: process.platform === "win32", env: SHELL_ENV, ...(localRoot ? { cwd: localRoot } : {}) });
     if (up.status !== 0) {
         err(`✘ the upgrade did not complete (exit ${up.status ?? "?"}) — run it by hand: ${upgradeCmd}`);
         return 1;
@@ -2147,6 +2312,21 @@ async function main(argv) {
         log(VERSION);
         return 0;
     }
+    if (!cmd && process.stdin.isTTY && process.stdout.isTTY) {
+        const gatedBare = await updateGate(cmd, argv);
+        if (gatedBare !== null)
+            return gatedBare;
+        log(brand() + " — gate an action, route it to a human, execute on approval, hold the proof.   " + dim("(npx @decidio/sdk --help for every command)"));
+        const stored = process.env.DECIDIO_SESSION_TOKEN ? "" : loadSession()?.email ?? null;
+        const pick = await firstRunFork(process.env.DECIDIO_SESSION_TOKEN ? "" : stored);
+        if (pick.kind === "stop")
+            return pick.code;
+        if (pick.kind === "logout")
+            return cmdLogout();
+        if (pick.kind === "init")
+            return cmdInit(pick.agentId, {});
+        return cmdQuickstart({ demo: pick.kind === "demo" });
+    }
     if (!cmd || wantsHelp(cmd)) {
         log(USAGE);
         return 0;
@@ -2257,7 +2437,20 @@ async function main(argv) {
                     return 1;
                 return quickstartCleanup(session, envFile);
             }
-            return cmdQuickstart({ demo: argsIn.includes("--demo"), autoApproveDemo: argsIn.includes("--auto-approve-demo"), keepAgent: argsIn.includes("--keep-agent"), explain: argsIn.includes("--explain"), phone: valuedOpt(argsIn, "--phone") });
+            const qopts = { demo: argsIn.includes("--demo"), autoApproveDemo: argsIn.includes("--auto-approve-demo"), keepAgent: argsIn.includes("--keep-agent"), explain: argsIn.includes("--explain"), phone: valuedOpt(argsIn, "--phone") };
+            if (!qopts.demo && !qopts.autoApproveDemo && forkApplies()) {
+                log(brand() + bold(" quickstart") + " — gate an action, route it to a human, execute on approval, hold the proof.");
+                const pick = await firstRunFork();
+                if (pick.kind === "stop")
+                    return pick.code;
+                if (pick.kind === "logout")
+                    return cmdLogout();
+                if (pick.kind === "init")
+                    return cmdInit(pick.agentId, {});
+                if (pick.kind === "demo")
+                    qopts.demo = true;
+            }
+            return cmdQuickstart(qopts);
         }
         case "init": {
             const unique = argsIn.includes("--unique");
@@ -2270,7 +2463,7 @@ async function main(argv) {
             }
             const ddIdx = argsIn.indexOf("--");
             const nameArg = ddIdx >= 0 ? argsIn[ddIdx + 1] : argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
-            let name = nameArg ?? process.env.DECIDIO_AGENT_ID ?? "my-agent";
+            let name = nameArg ?? (process.env.DECIDIO_AGENT_ID || defaultAgentId());
             if (unique)
                 name = `${name}-${randomBytes(2).toString("hex")}`;
             return cmdInit(name, { force: argsIn.includes("--force"), expiresDays: expRaw ? Number(expRaw) : undefined });
@@ -2356,6 +2549,7 @@ const invokedAsProgram = (() => {
 })();
 if (invokedAsProgram)
     main(process.argv).then(async (code) => {
+        closeSharedRl();
         if (code !== 0)
             process.exitCode = code;
         if (stdinReadAbandoned) {

package/dist/demo-gate.js

@@ -35,6 +35,8 @@ export async function startDemoGate(opts = {}) {
     const issuerDid = "did:key:z" + b58(Buffer.concat([Buffer.from([0xed, 0x01]), issuerRaw]));
     const sealedAt = new Date().toISOString();
     let verdict = null;
+    let decidedBy = "the human at the terminal";
+    let lastReason = "quickstart";
     let relayCode = null;
     let relayOk = null;
     const relayFetch = async (path, init = {}) => {
@@ -58,7 +60,7 @@ export async function startDemoGate(opts = {}) {
         }
     };
     const issueReceipt = (kind) => {
-        const canonical = `{"accountableParty":"[PERSON_1]","action":"payInvoice","amount":"[AMOUNT_2]","recordKind":"${kind}","recordSeries":"local-demo"}`;
+        const canonical = jcsCanonicalize({ accountableParty: "[PERSON_1]", action: "payInvoice", amount: 86000, currency: "USD", decidedBy, reason: lastReason, recordKind: kind, recordSeries: "local-demo" });
         const contentHash = createHash("sha256").update(canonical, "utf8").digest("hex");
         const context = ["https://www.w3.org/ns/credentials/v2"];
         const doc = {
@@ -113,14 +115,21 @@ export async function startDemoGate(opts = {}) {
                 if (path.startsWith("/agent/status/")) {
                     if (!verdict && relayCode) {
                         const r = await relayFetch(`/demo/relay/${relayCode}`);
-                        if (r && (r.verdict === "approve" || r.verdict === "reject"))
+                        if (r && (r.verdict === "approve" || r.verdict === "reject")) {
                             verdict = r.verdict;
+                            decidedBy = "the demo page (web or phone), through the relay";
+                            lastReason = "decided on the demo page";
+                        }
                     }
                     return send(verdict === "reject" ? { state: "rejected", reason: "quickstart: rejected by the approver" } : { state: verdict === "approve" ? "approved" : "pending" });
                 }
                 if (/^\/api\/decisions\/[^/]+\/(approve|reject)$/.test(path)) {
                     const already = verdict !== null;
                     verdict = path.endsWith("/reject") ? "reject" : "approve";
+                    if (!already) {
+                        lastReason = typeof body?.reason === "string" && body.reason ? body.reason : "quickstart";
+                        decidedBy = /automated/i.test(lastReason) ? "automated: the --auto-approve-demo flag (not a human in the moment)" : "the human at the terminal";
+                    }
                     if (relayCode && !already)
                         void relayFetch(`/demo/relay/${relayCode}`, { method: "PUT", body: JSON.stringify({ verdict }) });
                     return send({ ok: true, decisionId: DECISION_ID, sealed: true, ...(already ? { alreadyResolved: true } : {}) });
@@ -156,6 +165,6 @@ export async function startDemoGate(opts = {}) {
         url: `http://127.0.0.1:${port}`,
         issuerDid,
         relayReachable: () => relayOk,
-        close: () => new Promise((r) => server.close(() => r())),
+        close: () => new Promise((r) => { server.closeAllConnections(); server.close(() => r()); }),
     };
 }

package/openapi.yaml

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

package/package.json

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