@decidio/sdk 0.1.8 → 0.1.9

package/dist/cli.js

@@ -1,13 +1,32 @@
 #!/usr/bin/env node
+// @decidio/sdk CLI — the on-ramp. Run via `npx @decidio/sdk <cmd>` (or tsx in-repo).
+//   init [agentId]   sign in, register the agent, mint its API token, write .env
+//   doctor           check config + connectivity + durability readiness
+//   approvals        list pending agent approvals; `approvals approve|reject <id> [reason]`
+//   receipt <id>     download a sealed decision's Authority Receipt to a .json file
+//   dev [--target U] signal-only relay: forwards Decidio's webhook to your local agent URL
+//
+// TWO TOKEN KINDS, deliberately (self-serve design 2026-08-28): commands that ADMINISTER a
+// workspace (init's register+mint, approvals, receipt) need the owner's SESSION token — acquired
+// interactively per run or from DECIDIO_SESSION_TOKEN, held in memory, NEVER written to disk.
+// What lands in .env as DECIDIO_API_TOKEN is the floor-limited AGENT token the runtime SDK
+// needs (it can call /agent/* and nothing else). A session-capable secret must never live in
+// an agent host's .env — that was the pre-publish design's hole.
+//
+// MESSAGE DISCIPLINE (founder bar 2026-08-29, from the Codex acceptance run): every failure
+// tells the developer WHAT happened, WHY, and the EXACT next command. Every success says what
+// changed, where, and what to do next. No stack traces for expected failures; no green ✔ for a
+// no-op (the replay-approve bug: the server's idempotent alreadyResolved was reported as a
+// fresh success — an authority CLI may never dress a no-op as an action).
 import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync } from "node:fs";
-import { randomBytes, createHash } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
 import { generateKeypair } from "./signing.js";
 import { withApproval, DecidioRateLimitError } from "./index.js";
-import { verifyReceipt } from "@decidio/verify";
+import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
     try {
         return createRequire(import.meta.url)("../package.json").version;
@@ -16,33 +35,69 @@ const VERSION = (() => {
         return "unknown";
     }
 })();
+// ---- environment: load the CWD .env FIRST (Codex finding: init writes .env, but the next
+// command ignored it and pointed at localhost). Process env always wins — .env only fills gaps.
+// NEVER a crash: an unreadable .env (EPERM, EISDIR, a mangled volume) is that file's problem,
+// not this command's — warn on stderr and continue (round-9 catch: it was an unhandled Node
+// stack trace).
+let envWarned = false;
 function readEnvFile() {
     const out = {};
-    if (existsSync(".env"))
-        for (const line of readFileSync(".env", "utf8").split(/\r?\n/)) {
-            const m = line.match(/^\s*([A-Z_]+)=(.*)$/);
-            if (m)
-                out[m[1]] = m[2];
+    try {
+        if (existsSync(".env"))
+            for (const line of readFileSync(".env", "utf8").split(/\r?\n/)) {
+                const m = line.match(/^\s*([A-Z_]+)=(.*)$/);
+                if (m)
+                    out[m[1]] = m[2];
+            }
+    }
+    catch (e) {
+        if (!envWarned) {
+            envWarned = true;
+            console.error(`⚠ could not read .env (${e?.code ?? e?.message ?? e}) — continuing without it. Fix its permissions if you meant it to load.`);
         }
-    return out;
-}
-for (const [k, v] of Object.entries(readEnvFile())) {
-    if (k === "DECIDIO_SESSION_TOKEN") {
-        console.error("⚠ ignoring DECIDIO_SESSION_TOKEN found in .env — session tokens belong in your shell or CI secret store, never on disk. Remove that line; export it in the shell instead.");
-        continue;
     }
-    if (process.env[k] === undefined)
-        process.env[k] = v;
+    return out;
 }
+// OFFLINE commands never touch .env at all (round-9 catch: `verify` is cryptographically
+// offline and needs no credentials, yet the autoload coupled it to the directory's .env —
+// and the help text's "every command talks to the hosted sandbox" was wrong for it).
+const OFFLINE_CMD = ["verify", "--version", "-v", "-V", "version", "--help", "-h", "help", undefined].includes(process.argv[2]);
+if (!OFFLINE_CMD)
+    for (const [k, v] of Object.entries(readEnvFile())) {
+        // NEVER autoload the session token from disk: the whole design splits session (memory-only)
+        // from the floor-limited agent token (.env). Silently honoring a parked session token would
+        // reward exactly the credential-at-rest the split exists to prevent (guard catch 2026-08-29).
+        if (k === "DECIDIO_SESSION_TOKEN") {
+            console.error("⚠ ignoring DECIDIO_SESSION_TOKEN found in .env — session tokens belong in your shell or CI secret store, never on disk. Remove that line; export it in the shell instead.");
+            continue;
+        }
+        if (process.env[k] === undefined)
+            process.env[k] = v;
+    }
+// SANDBOX-FIRST (blind-review catch, founder-ruled): every command defaults to the hosted sandbox,
+// because that is the product people actually receive — the old localhost default was our own dev
+// environment leaking into the package, and it broke the tour's own follow-up commands the moment
+// cleanup removed .env. Explicit config (env or .env) always wins; the target host is announced on
+// stderr so no command ever talks to a server silently.
 const API = (process.env.DECIDIO_API_URL ?? "https://decidio-api.onrender.com").replace(/\/$/, "");
+// Token is read AT CALL TIME, not captured at import: init mints a fresh agent token mid-run and
+// its closing doctor must probe with THAT, not the pre-init env (round-3 Codex catch — the stale
+// capture made init's own doctor print "token: REJECTED" seconds after a successful mint).
 const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
+// Errors and usage guidance go to STDERR (blind-review catch: error text on stdout corrupts every
+// `--json | jq` pipeline — and any consumer of a CLI's stdout). Verdict output (verify's VALID/
+// INVALID lines) is the product and stays on stdout.
 const err = (...a) => console.error(...a);
+/** Fetch wrapper that turns transport failures into guidance instead of a stack trace. */
 let hostAnnounced = false;
 async function api(path, init = {}, bearer) {
     if (!hostAnnounced) {
         hostAnnounced = true;
+        // Once per process, on stderr: WHICH server this command talks to (sandbox-first means a
+        // missing config no longer fails loud, so the target must never be silent instead).
         err(`· decidio → ${API}${process.env.DECIDIO_API_URL ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
     }
     const auth = bearer ?? TOKEN();
@@ -72,13 +127,19 @@ async function api(path, init = {}, bearer) {
     }
     return { status: res.status, body };
 }
+/** Write a secrets file OWNER-ONLY (0600). `mode` applies on creation; an existing file keeps its
+ *  old permissions, so chmod as well. Best-effort: Windows ignores POSIX modes (its ACLs are
+ *  inherited from the directory), and a chmod failure must never lose the write. */
 function writeSecretFile(path, body) {
     writeFileSync(path, body, { mode: 0o600 });
     try {
         chmodSync(path, 0o600);
     }
-    catch { }
+    catch { /* restricted FS — the write itself stands */ }
     if (process.platform === "win32") {
+        // POSIX modes are a no-op on NTFS (round-8 verified the file kept inherited Modify ACLs).
+        // Do it the Windows way: strip inheritance, grant only the current user. Best-effort — a
+        // failure never loses the write, but it is SAID, not swallowed.
         try {
             execFileSync("icacls", [path, "/inheritance:r", "/grant:r", `${process.env.USERNAME ?? process.env.USER ?? ""}:F`], { stdio: "ignore" });
         }
@@ -88,12 +149,42 @@ function writeSecretFile(path, body) {
     }
 }
 function upsertEnv(updates) {
-    const cur = readEnvFile();
-    const merged = { ...cur, ...updates };
-    const body = Object.entries(merged).map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
-    writeSecretFile(ENV_PATH, body);
+    // Update IN PLACE, never rewrite (round-2 blind catch: the merge-and-rewrite dropped every
+    // comment and blank line — "# Production database — do not touch" vanished unrecoverably,
+    // since this file is gitignored). A user's line only changes when its KEY is being updated;
+    // everything else survives byte-for-byte; new keys append.
+    const remaining = { ...updates };
+    const updatedKeys = new Set();
+    const lines = [];
+    try {
+        if (existsSync(ENV_PATH))
+            for (const line of readFileSync(ENV_PATH, "utf8").split(/\r?\n/)) {
+                const m = line.match(/^\s*([A-Z_]+)=/);
+                // A hand-edited duplicate of an updated key is DROPPED, not kept (guard note: last-wins on
+                // the next read would resurrect the stale value — e.g. an old token — over the fresh one).
+                if (m && updatedKeys.has(m[1]))
+                    continue;
+                if (m && m[1] in remaining) {
+                    lines.push(`${m[1]}=${remaining[m[1]]}`);
+                    updatedKeys.add(m[1]);
+                    delete remaining[m[1]];
+                }
+                else
+                    lines.push(line);
+            }
+    }
+    catch { /* unreadable existing file: start fresh below — the write still lands */ }
+    while (lines.length && lines[lines.length - 1] === "")
+        lines.pop();
+    for (const [k, v] of Object.entries(remaining))
+        lines.push(`${k}=${v}`);
+    writeSecretFile(ENV_PATH, lines.join("\n") + "\n");
 }
+/** Keep secrets out of git without nagging: append the two entries to .gitignore when they're
+ *  not already covered. Creating the file in a non-git directory is harmless. */
 function ensureGitignore() {
+    // Every file this CLI may write that can hold a private key — including the `--force` backup
+    // (.env.<agent>.bak), which git's plain `.env` pattern does NOT match.
     const entries = [".env", ".env.quickstart", ".env.*.bak", ".decidio-pending/"];
     const existing = existsSync(".gitignore") ? readFileSync(".gitignore", "utf8") : "";
     const missing = entries.filter((e) => !existing.split(/\r?\n/).some((l) => l.trim() === e || l.trim() === e.replace(/\/$/, "")));
@@ -102,10 +193,12 @@ function ensureGitignore() {
     appendFileSync(".gitignore", (existing && !existing.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n");
     log(`✔ added ${missing.join(" + ")} to .gitignore (your agent key and parked actions stay out of git)`);
 }
+// ---- interactive input (session sign-in) ---------------------------------------------------
 function ask(question, mute = false) {
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
         if (mute) {
+            // Hide password echo: after the prompt renders, swallow subsequent output writes.
             const anyRl = rl;
             const write = anyRl._writeToOutput?.bind(rl);
             anyRl._writeToOutput = (s) => { if (s.includes(question))
@@ -115,20 +208,29 @@ function ask(question, mute = false) {
             process.stdout.write("\n"); resolve(answer.trim()); });
     });
 }
+/** Owner SESSION token, memory-only. Sources in order: DECIDIO_SESSION_TOKEN env, interactive
+ *  email+password (`/demo/login`), pasted sign-in link (`/demo/login-consume` — for the
+ *  password-less accounts the welcome flow creates). Never persisted. */
 async function acquireSession(purpose) {
+    // TRANSPORT CHECK FIRST — before ANY credential is selected, including one already in the
+    // environment. This guard used to sit after the DECIDIO_SESSION_TOKEN shortcut, so an
+    // env-supplied session token would ride plaintext http to a remote host without ever being
+    // checked. The rule is about the WIRE, so it cannot depend on where the credential came from.
     if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
         err(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
-        log(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
+        err(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
         return null;
     }
     if (process.env.DECIDIO_SESSION_TOKEN)
         return process.env.DECIDIO_SESSION_TOKEN;
     if (!process.stdin.isTTY) {
+        // WHOLE failure messages ride stderr (round-2 blind catch: the ✘ headline went to stderr
+        // while its remediation went to stdout — split mid-sentence for any consumer of either).
         err(`✘ ${purpose} needs a Decidio workspace sign-in, and this terminal can't prompt for one.`);
-        log(`  Fix: set DECIDIO_SESSION_TOKEN and re-run. To mint one:`);
-        log(`    1. Request a sign-in link from your workspace's sign-in screen (or use your welcome email).`);
-        log(`    2. POST its ?login= value — the response's "token" is your session token:`);
-        log(`       curl -X POST ${API}/demo/login-consume -H "content-type: application/json" -d '{"token":"<login value>"}'`);
+        err(`  Fix: set DECIDIO_SESSION_TOKEN and re-run. To mint one:`);
+        err(`    1. Request a sign-in link from your workspace's sign-in screen (or use your welcome email).`);
+        err(`    2. POST its ?login= value — the response's "token" is your session token:`);
+        err(`       curl -X POST ${API}/demo/login-consume -H "content-type: application/json" -d '{"token":"<login value>"}'`);
         return null;
     }
     log(`${purpose} needs your Decidio workspace sign-in (${API}).`);
@@ -160,21 +262,29 @@ async function acquireSession(purpose) {
     return null;
 }
 async function cmdInit(agentId, opts = {}) {
-    log(`Registering agent "${agentId}" with Decidio at ${API}…`);
+    err(`Registering agent "${agentId}" with Decidio at ${API}…`);
+    // CLIENT-SIDE KEYGEN: generate the Ed25519 keypair LOCALLY and register only the PUBLIC
+    // did:key. The private key NEVER crosses the wire — it goes straight to this host's env.
     const existingEnv = readEnvFile();
     const existingKey = existingEnv.DECIDIO_AGENT_KEY;
     const sourceSystem = process.env.DECIDIO_SOURCE_SYSTEM || existingEnv.DECIDIO_SOURCE_SYSTEM;
+    // NEVER silently orphan a different agent's key. Registering a NEW name in a directory that
+    // already holds another agent's key would overwrite it — and keys never leave the machine that
+    // made them, so that loss is irrecoverable (it strands the old agent in init's own 409 stop).
+    // Checked BEFORE registering, so a refusal leaves nothing behind server-side either.
     if (existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId && !opts.force) {
         err(`✘ this directory's .env already holds the key for a DIFFERENT agent ("${existingEnv.DECIDIO_AGENT_ID}").`);
-        log(`  Registering "${agentId}" here would overwrite that key — and a private key that is`);
-        log(`  overwritten is gone for good (it never left this machine). Nothing was written.`);
-        log(`  Pick one:`);
-        log(`    1. New directory (cleanest): mkdir ${agentId} && cd ${agentId} && npx @decidio/sdk init ${agentId}`);
-        log(`    2. Replace the old agent here, backing its .env up first: npx @decidio/sdk init ${agentId} --force`);
+        err(`  Registering "${agentId}" here would overwrite that key — and a private key that is`);
+        err(`  overwritten is gone for good (it never left this machine). Nothing was written.`);
+        err(`  Pick one:`);
+        err(`    1. New directory (cleanest): mkdir ${agentId} && cd ${agentId} && npx @decidio/sdk init ${agentId}`);
+        err(`    2. Replace the old agent here, backing its .env up first: npx @decidio/sdk init ${agentId} --force`);
         return 1;
     }
     const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
     const registerBody = JSON.stringify({ agentId, did: localDid, ...(sourceSystem ? { sourceSystem } : {}) });
+    // First try whatever bearer the env already carries (the local-dev / operator path — a static
+    // admin token, or dev-open auth). On 401/403 fall through to the self-serve session flow.
     let session = null;
     let r = await api("/api/agents/register", { method: "POST", body: registerBody });
     if (r.status === 401 || r.status === 403) {
@@ -185,6 +295,10 @@ async function cmdInit(agentId, opts = {}) {
     }
     let did, privateKey;
     if (r.status === 409) {
+        // Already registered to a server-held did. WITHOUT the original private key on this machine
+        // this is a HARD STOP, not a degraded continue (round-3 Codex catch: init used to write a
+        // keyless .env and print happy-path next steps — every request then routed unproven and
+        // execution evidence silently capped at agent_asserted).
         did = r.body?.did;
         if (existingKey) {
             log(`• "${agentId}" is already registered in this workspace (did ${did}) — reusing it with the DECIDIO_AGENT_KEY already in .env.`);
@@ -194,10 +308,10 @@ async function cmdInit(agentId, opts = {}) {
         else {
             const suggestion = `${agentId}-${randomBytes(2).toString("hex")}`;
             err(`✘ "${agentId}" is already registered in this workspace, and its private key is not on this machine`);
-            log(`  (keys never leave the machine that generated them — likely a previous run, or another directory).`);
-            log(`  Nothing was written. Two ways forward:`);
-            log(`    1. Fresh agent (most common): npx @decidio/sdk init ${suggestion}`);
-            log(`    2. Reuse "${agentId}": restore its original DECIDIO_AGENT_KEY into .env here, then re-run init.`);
+            err(`  (keys never leave the machine that generated them — likely a previous run, or another directory).`);
+            err(`  Nothing was written. Two ways forward:`);
+            err(`    1. Fresh agent (most common): npx @decidio/sdk init ${suggestion}`);
+            err(`    2. Reuse "${agentId}": restore its original DECIDIO_AGENT_KEY into .env here, then re-run init.`);
             return 1;
         }
     }
@@ -208,12 +322,18 @@ async function cmdInit(agentId, opts = {}) {
     }
     else {
         err(`✘ registration failed (${r.status}): ${JSON.stringify(r.body)}`);
-        log(`  Fix the cause above and re-run — init is safe to repeat.`);
+        err(`  Fix the cause above and re-run — init is safe to repeat.`);
         return 1;
     }
+    // Mint the runtime credential: the floor-limited AGENT token (can call /agent/* only). This is
+    // what .env gets — the session token stays in memory and dies with this process. On boxes
+    // without the tester-lab fence (plain local dev) the mint endpoint refuses; that's fine —
+    // local dev auths with its existing env and we say so instead of failing the init.
     let agentToken, workspaceId, tokenJti;
     const mintBearer = session ?? TOKEN();
     if (mintBearer) {
+        // Right-sized lifetime, not the server's year-long default: a CLI-minted credential should
+        // expire on the horizon of the work it was minted for (--expires-days to override).
         const expiresInDays = opts.expiresDays ?? 90;
         const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "sdk-cli", expiresInDays }) }, mintBearer);
         if (mint.status >= 200 && mint.status < 300 && mint.body?.token) {
@@ -221,10 +341,16 @@ async function cmdInit(agentId, opts = {}) {
             workspaceId = mint.body.workspaceId;
             tokenJti = mint.body.jti;
             log(`✔ minted the agent's API token — floor-limited: it can request authorization, poll status and report confirmation; it cannot administer the workspace or approve anything${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ` (${expiresInDays} days)`}`);
+            // The server keeps ONE active token per agent, so a re-mint REVOKES the previous one — an
+            // authority event the person triggering it must see, not discover later in tokens list
+            // (round-3 blind catch: a still-valid token silently died with no mention).
+            const superseded = Array.isArray(mint.body.supersededJtis) ? mint.body.supersededJtis : [];
+            for (const s of superseded)
+                log(`  • this replaces the agent's previous token (jti ${s}) — now REVOKED: the server keeps one active token per agent. Anything still using it will 401.`);
         }
         else if (session) {
             err(`✘ could not mint the agent's API token (${mint.status}): ${JSON.stringify(mint.body)}`);
-            log(`  Without it the SDK has no runtime credential. Fix the cause above and re-run init — it's safe to repeat.`);
+            err(`  Without it the SDK has no runtime credential. Fix the cause above and re-run init — it's safe to repeat.`);
             return 1;
         }
         else {
@@ -238,20 +364,28 @@ async function cmdInit(agentId, opts = {}) {
     if (did)
         envOut.DECIDIO_AGENT_DID = did;
     if (privateKey)
-        envOut.DECIDIO_AGENT_KEY = privateKey;
+        envOut.DECIDIO_AGENT_KEY = privateKey; // written locally; never left this host
     if (agentToken)
-        envOut.DECIDIO_API_TOKEN = agentToken;
+        envOut.DECIDIO_API_TOKEN = agentToken; // the FLOOR-LIMITED token — never the session
     if (workspaceId)
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
+    // Revocation metadata, not a secret — parity with the quickstart env (blind-review catch: the
+    // two files disagreed, and `tokens revoke` is unusable without the jti in hand).
     if (tokenJti)
         envOut.DECIDIO_TOKEN_JTI = tokenJti;
+    // IGNORE RULE BEFORE THE SECRET: writing .env first leaves a window (however short) where a
+    // private key sits in a repo with no ignore rule covering it.
     ensureGitignore();
     if (opts.force && existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId) {
+        // --force still must not DESTROY the old key: park it beside the new one, owner-only.
         const backup = `.env.${existingEnv.DECIDIO_AGENT_ID.replace(/[^\w.-]/g, "_")}.bak`;
         writeSecretFile(backup, readFileSync(ENV_PATH, "utf8"));
         log(`✔ backed the previous agent's .env up to ${backup} (its key would otherwise be unrecoverable)`);
     }
     upsertEnv(envOut);
+    // The closing doctor (and anything else this process does) must see what init just wrote —
+    // OVERWRITE process.env with the fresh values (round-3 Codex catch: doctor probed with the
+    // stale pre-init token and reported the mint it just watched as REJECTED).
     for (const [k, v] of Object.entries(envOut))
         process.env[k] = v;
     log(`✔ wrote ${ENV_PATH} (owner-only where the OS supports it) — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
@@ -286,63 +420,104 @@ async function cmdInit(agentId, opts = {}) {
 async function cmdDoctor() {
     const env = readEnvFile();
     let ok = true;
+    let warned = 0;
     const line = (good, label) => { log(`${good ? "✔" : "✘"} ${label}`); ok = ok && good; };
+    // Warnings COUNT in the summary (round-3 blind catch: "doctor: all green." directly under a ⚠
+    // line contradicts itself — green with a caveat must say so).
+    const warn = (label) => { warned++; log(`⚠ ${label}`); };
+    // An unset URL is a WORKING default (the hosted sandbox), not a failure — sandbox-first ruling.
     log(`✔ API URL: ${API}${(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL) ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
     line(!!(process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID), `agent id: ${process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID || "(unset — run: npx @decidio/sdk init <agent-name>)"}`);
+    // The webhook secret is OPERATOR-ONLY transport config — a missing one must never fail doctor
+    // (blind-review catch: doctor exited 1 immediately after the product's own successful
+    // quickstart, whose env rightly omits it). Informational either way.
     const secret = process.env.DECIDIO_WEBHOOK_SECRET || env.DECIDIO_WEBHOOK_SECRET;
     log(secret ? "✔ webhook secret: set — operator-only transport (inactive against the hosted sandbox; the poll worker guard.worker() is the self-serve resume path)"
         : "• webhook secret: not set — only needed for the operator resume-webhook transport; the poll worker guard.worker() is the self-serve resume path (init generates one)");
+    // Signing key — REQUIRED to be ELIGIBLE for auto-approve. Whether anything auto-approves is
+    // the workspace policy's call, not this key's (Codex finding: the old wording claimed
+    // "auto-approve is in effect" while deny-by-default routed everything).
     const signing = (process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY) && (process.env.DECIDIO_AGENT_DID || env.DECIDIO_AGENT_DID);
     if (signing)
         log("✔ signing key: set — the agent can prove its identity, making it ELIGIBLE for policy auto-approve. Whether a rule matches is your workspace policy's decision; with no matching rule every request routes to a human (deny-by-default).");
     else
-        log("⚠ signing key: MISSING (DECIDIO_AGENT_KEY/DID) — the agent can't prove identity, so EVERY request routes to a human. Run `npx @decidio/sdk init` to generate one.");
+        warn("signing key: MISSING (DECIDIO_AGENT_KEY/DID) — the agent can't prove identity, so EVERY request routes to a human. Run `npx @decidio/sdk init` to generate one.");
+    // Reachability and token role are SEPARATE checks (the old probe called any <500 green, so a
+    // wrong-kind token looked healthy). /api/health is unauthenticated truth about reachability;
+    // /api/records then classifies the token.
     const h = await api("/api/health", {}, "");
     line(h.status >= 200 && h.status < 300, `connectivity: API reachable (${h.status})`);
+    // EXPIRY BEFORE IT BITES: a right-sized token is only an improvement if its end is visible in
+    // advance — otherwise a production agent simply starts 401ing one day. Read `exp` out of the
+    // token's own payload (display only; the server remains the authority on validity).
     const tok = process.env.DECIDIO_API_TOKEN || env.DECIDIO_API_TOKEN;
+    // UNSET is its own diagnosis (round-3 blind catch: a bare directory probed the server with an
+    // EMPTY credential and told a first-run user their never-existent token was "invalid or
+    // expired"). Say what is true and stop — there is nothing to probe.
+    if (!tok) {
+        line(false, "agent token: NOT CONFIGURED — no DECIDIO_API_TOKEN in this directory's .env or your environment. Run `npx @decidio/sdk init <agent-name>` to register an agent and mint one.");
+        log(warned ? `\ndoctor: fix the ✘ items above, then re-run \`npx @decidio/sdk doctor\`. (${warned} warning${warned === 1 ? "" : "s"})` : "\ndoctor: fix the ✘ items above, then re-run `npx @decidio/sdk doctor`.");
+        return 1;
+    }
     if (tok) {
         try {
             const payload = JSON.parse(Buffer.from(tok.split(".")[1] ?? "", "base64url").toString("utf8"));
             if (typeof payload?.exp === "number") {
                 const msLeft = payload.exp * 1000 - Date.now();
-                const days = Math.floor(msLeft / 86_400_000);
+                // A minute of grace absorbs mint-to-doctor latency so a fresh 90-day token reads "90",
+                // matching the Python doctor (round-3 blind nit: 89 vs 90 for the same expiry).
+                const days = Math.floor((msLeft + 60_000) / 86_400_000);
+                // Under a day, days-precision reads as "0 day(s)" — which looks expired while ~23h remain
+                // (blind-review catch). Switch units instead of rounding away the truth.
                 const left = msLeft < 86_400_000 ? `${Math.max(1, Math.floor(msLeft / 3_600_000))} hour(s)` : `${days} day(s)`;
                 if (msLeft < 0)
                     line(false, `agent token: EXPIRED ${-days} day(s) ago — re-run \`npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}\` to mint a fresh one.`);
                 else if (days <= 14)
-                    log(`⚠ agent token: expires in ${left} — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
+                    warn(`agent token: expires in ${left} — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
                 else
                     log(`✔ agent token: valid for another ${days} days`);
             }
         }
-        catch { }
+        catch { /* not a JWT we can read — the scope probe below is the real check */ }
     }
     const rec = await api("/api/records");
     if (rec.status >= 200 && rec.status < 300)
         log("✔ token scope: session/admin (init, approvals and receipt work from this env)");
     else if (rec.status === 401) {
+        // A 401 off the agent floor could also mean an INVALID token (Codex catch: don't
+        // false-green expiry). Disambiguate with a floor probe: a valid agent token gets 404 for an
+        // unknown decision (authorized, not found); an invalid one gets 401 again. A rejection here
+        // flips the overall verdict — "all green" after a red line was round 3's other doctor bug.
         const probe = await api("/agent/status/doctor-scope-probe");
         if (probe.status === 404)
             log("✔ token scope: agent floor — correct for the runtime SDK (approvals/receipt will ask you to sign in)");
         else if (probe.status === 401)
             line(false, "token: REJECTED on the agent floor too — it's invalid or expired. Re-run `npx @decidio/sdk init` to mint a fresh one.");
         else
-            log(`⚠ token scope: agent-floor probe returned ${probe.status} — inconclusive`);
+            warn(`token scope: agent-floor probe returned ${probe.status} — inconclusive`);
     }
     else
-        log(`⚠ token scope: unexpected ${rec.status} from /api/records`);
-    log(ok ? "\ndoctor: all green." : "\ndoctor: fix the ✘ items above, then re-run `npx @decidio/sdk doctor`.");
+        warn(`token scope: unexpected ${rec.status} from /api/records`);
+    const warnNote = warned ? ` (${warned} warning${warned === 1 ? "" : "s"} above — working, worth a look)` : "";
+    log(ok ? `\ndoctor: all green.${warnNote}` : "\ndoctor: fix the ✘ items above, then re-run `npx @decidio/sdk doctor`.");
     return ok ? 0 : 1;
 }
 async function cmdApprovals(sub, id, reason, flags = {}) {
+    // Approvals are a HUMAN act on the workspace — session scope, never the agent token. If the
+    // env's token is agent-floor (401 on /api/*), sign in interactively; memory-only as always.
     const jsonMode = !!flags.json;
     const mineOnly = !!flags.mine;
     if (sub?.startsWith("--"))
         sub = undefined;
+    // USAGE BEFORE AUTH (round-8 catch): a malformed command must fail on its shape, not probe the
+    // network first — validation needs no credentials.
     if ((sub === "approve" || sub === "reject") && !id) {
         err(`usage: npx @decidio/sdk approvals ${sub} <decisionId> [reason]`);
         return 2;
     }
+    // --mine without an agent identity cannot mean anything — and quietly returning [] (exit 0)
+    // would tell a script "no pending work" when the truth is "misconfigured" (blind-review catch:
+    // it leaked "undefined" in human mode and lied with [] in JSON mode). Shape error, before auth.
     if (mineOnly && !process.env.DECIDIO_AGENT_ID) {
         err(`✘ --mine needs an agent identity, and there is no DECIDIO_AGENT_ID in this directory's .env or your environment.`);
         err(`  Run this from your agent's directory (where init wrote .env), or drop --mine for the workspace-wide list.`);
@@ -360,6 +535,9 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
     if (sub === "approve" || sub === "reject") {
         const r = await api(`/api/decisions/${encodeURIComponent(decisionArg)}/${sub === "approve" ? "approve" : "reject"}`, { method: "POST", body: JSON.stringify({ reason: reason ?? undefined }) }, bearer);
         if (r.status >= 200 && r.status < 300) {
+            // HONESTY over green checkmarks (Codex finding: the server resolves each decision exactly
+            // once and answers replays idempotently — a replay is a NO-OP and must read as one, never
+            // as a fresh approval). Non-zero exit so scripts can tell the difference.
             if (r.body?.alreadyResolved) {
                 log(`• ${id} was already resolved — nothing changed.`);
                 log(`  Decisions are single-use: a second ${sub} can never re-execute the action (that's the replay protection working).`);
@@ -388,6 +566,9 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
     }
     const cards = r.body?.cards ?? [];
     const pending = cards.filter((c) => c.isAgentRequest && c.status !== "sealed");
+    // FILTER FIRST, FORMAT SECOND (round-8 catch: --mine --json returned the UNFILTERED workspace
+    // list — and automation is exactly the consumer of the JSON form, so the human view and the
+    // machine view must be the same set).
     const myAgent = process.env.DECIDIO_AGENT_ID;
     const isMine = (c) => !!myAgent && typeof c.title === "string" && c.title.startsWith(`${myAgent}:`);
     const shown = mineOnly ? pending.filter(isMine) : pending;
@@ -419,6 +600,8 @@ async function cmdReceipt(id, jsonMode = false) {
         err("  Find decision ids via `npx @decidio/sdk approvals` or in your Decidio app.");
         return 2;
     }
+    // Receipts are workspace data — session scope, like approvals. (The record-detail /verify
+    // route carries the credential; the plain record route does not — Codex finding.)
     let bearer;
     let r = await api(`/api/records/${encodeURIComponent(id)}/verify`);
     if (r.status === 401 || r.status === 403) {
@@ -440,18 +623,28 @@ async function cmdReceipt(id, jsonMode = false) {
     const name = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     const nextBytes = JSON.stringify(r.body.credential, null, 2) + "\n";
     if (existsSync(name)) {
+        // Never silently overwrite an audit artifact (round-6 catch). Byte-identical is fine (receipts
+        // are immutable); a DIFFERENT file at the same name is a refusal.
         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;
         }
+        // In --json mode stdout is the JSON result ONLY — narrative rides stderr (stream contract).
         (jsonMode ? err : log)(`• ${name} already exists (byte-identical — receipts are immutable); leaving it in place.`);
     }
     else {
         writeFileSync(name, nextBytes);
         (jsonMode ? err : log)(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
     }
+    // The credential seals at DECISION time (immutable), so execution evidence that arrived later
+    // lives on the record — surface the CURRENT tier here so the reader doesn't need a second
+    // lookup to see it (Codex catch).
     const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
     const conf = detail.body?.record?.confirmation;
+    // The trust anchor, delivered over the AUTHENTICATED channel. Reading the issuer out of the
+    // receipt you are about to verify is circular; this value comes from the server's own verify
+    // response, so pinning it actually means something (round-7 catch: the guided flow sent people
+    // to an app panel they could not reach, leaving provenance uncompletable).
     const issuer = r.body?.issuer;
     if (jsonMode) {
         log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed, issuer: issuer ?? null }, null, 2));
@@ -459,6 +652,8 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
+    // Emit EXACTLY the deterministic command we document (round-4 catch: the README and this hint
+    // disagreed, and bare npx re-probes the registry) — the verifier ships INSIDE this package.
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     log(`    npx @decidio/sdk verify ${name}`);
     if (issuer) {
@@ -472,86 +667,16 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     return 0;
 }
-function parseReceiptStrict(text, file) {
-    const value = JSON.parse(text);
-    const stack = [];
-    let i = 0;
-    const readString = () => {
-        let out = "";
-        i++;
-        while (i < text.length) {
-            const ch = text[i];
-            if (ch === "\\") {
-                out += text[i] + text[i + 1];
-                i += 2;
-                continue;
-            }
-            if (ch === '"') {
-                i++;
-                return out;
-            }
-            out += ch;
-            i++;
-        }
-        return out;
-    };
-    while (i < text.length) {
-        const ch = text[i];
-        if (ch === '"') {
-            const s = readString();
-            let j = i;
-            while (j < text.length && /\s/.test(text[j]))
-                j++;
-            if (text[j] === ":" && stack.length > 0) {
-                const key = JSON.parse(`"${s}"`);
-                const top = stack[stack.length - 1];
-                if (top.has(key))
-                    throw new Error(`${file}: duplicate JSON key ${JSON.stringify(key)} — RFC 8785 requires duplicate-free input, and different parsers disagree on which value is real`);
-                top.add(key);
-            }
-            continue;
-        }
-        if (ch === "{")
-            stack.push(new Set());
-        else if (ch === "}")
-            stack.pop();
-        i++;
-    }
-    return value;
-}
-function chainOf(vcs, expectedIssuer) {
-    if (!vcs.length)
-        return { valid: false, length: 0, reason: "no receipts supplied" };
-    const issuers = [...new Set(vcs.map((v) => String(v?.issuer ?? "")))];
-    if (issuers.length > 1)
-        return { valid: false, length: 0, reason: `these receipts come from ${issuers.length} DIFFERENT issuers — a chain must be issued end to end by one issuer` };
-    let prev = null;
-    let anchor = "segment";
-    for (let i = 0; i < vcs.length; i++) {
-        const r = verifyReceiptDoor(vcs[i], expectedIssuer);
-        if (!r.valid)
-            return { valid: false, length: i, reason: `receipt ${i} (${r.recordId ?? "?"}) invalid: ${r.reason}` };
-        const cs = vcs[i]?.credentialSubject ?? {};
-        if (i === 0)
-            anchor = (cs.prevHash ?? null) === null ? "genesis" : "segment";
-        else if ((cs.prevHash ?? null) !== prev)
-            return { valid: false, length: i, reason: `receipt ${i} does not follow receipt ${i - 1} (prevHash mismatch)` };
-        prev = cs.contentHash;
-    }
-    return { valid: true, length: vcs.length, anchor };
-}
-function verifyReceiptDoor(vc, expectedIssuer) {
-    const res = verifyReceipt(vc, expectedIssuer);
-    if (!res.valid && res.reason === "issuer DID is not the expected issuer") {
-        const cs = vc?.credentialSubject ?? {};
-        const derive = (canonical, prevHash) => createHash("sha256").update((prevHash ?? "") + canonical).digest("hex");
-        const bound = typeof cs.recordCanonical === "string" && typeof cs.contentHash === "string"
-            && derive(cs.recordCanonical, typeof cs.prevHash === "string" ? cs.prevHash : null) === cs.contentHash;
-        return { ...res, contentBound: bound, recordId: typeof cs.recordId === "string" ? cs.recordId : res.recordId, reason: "issuer DID is not the expected issuer (the receipt itself may be internally consistent — it was just not issued by who you pinned)" };
-    }
-    return res;
-}
+// ---- verify (embedded) ----------------------------------------------------------------------
+// ONE implementation, all doors (0.1.9): the dependency floor now carries `runVerify`, so the
+// strict-parse / chain / wrong-issuer local copies this door carried since 0.1.4 are DELETED —
+// the sdk door and the standalone decidio-verify CLI are literally the same function, and the
+// conformance runner's third door keeps them honest. This CLI keeps only what is CLI-shaped:
+// flag grammar, I/O-vs-verdict separation, and usage.
 function cmdVerify(argsIn) {
+    // Positional parse mirroring the standalone decidio-verify CLI: --issuer in space AND `=` form
+    // (the `=` form silently dropped was the standalone's unpinned-VALID bug — one grammar, all
+    // doors). Unknown flags never reach here (main()'s strict table refuses them first).
     let expectedIssuer;
     const files = [];
     for (let i = 0; i < argsIn.length; i++) {
@@ -582,44 +707,30 @@ function cmdVerify(argsIn) {
         err("  Verifies Authority Receipts OFFLINE — signature, content binding, and (for several files) chain order.");
         return 2;
     }
-    const texts = [];
+    // An unreadable file is an I/O problem, not a cryptographic verdict (blind-review catch: a
+    // typo'd filename got the same "INVALID" a forged receipt gets).
+    const texts = new Map();
     for (const f of files) {
         try {
-            texts.push(readFileSync(f, "utf8"));
+            texts.set(f, readFileSync(f, "utf8"));
         }
         catch (e) {
             err(`✘ cannot read ${f}: ${e?.code === "ENOENT" ? "no such file" : e?.message ?? e} (nothing was verified)`);
             return 1;
         }
     }
-    let vcs;
-    try {
-        vcs = files.map((f, i) => parseReceiptStrict(texts[i], f));
-    }
-    catch (e) {
-        log(`✘ INVALID  ${String(e?.message ?? e)}`);
-        return 1;
-    }
-    let allOk = true;
-    vcs.forEach((vc, i) => {
-        const res = verifyReceiptDoor(vc, expectedIssuer);
-        allOk = allOk && res.valid;
-        log(`${res.valid ? "✔ VALID  " : "✘ INVALID"}  ${files[i]}`);
-        log(`    record: ${res.recordId ?? "?"}   issuer: ${res.issuer}${expectedIssuer ? "" : "  (unpinned — pass --issuer to bind to your workspace's DID)"}`);
-        log(`    content-bound: ${res.contentBound}${res.reason ? `   reason: ${res.reason}` : ""}`);
-    });
-    if (vcs.length > 1) {
-        const c = chainOf(vcs, expectedIssuer);
-        allOk = allOk && c.valid;
-        log(`\nchain: ${c.valid ? "✔ intact" : "✘ broken"} (${c.length}/${vcs.length})${c.valid ? (c.anchor === "segment" ? " — segment: ordering proven from the FIRST file forward; history before it is not covered by these receipts" : " — from genesis") : ""}${c.reason ? ` — ${c.reason}` : ""}`);
-    }
-    return allOk ? 0 : 1;
+    const { ok, lines } = runVerify(files, expectedIssuer, (f) => texts.get(f));
+    for (const l of lines)
+        log(l);
+    return ok ? 0 : 1;
 }
+// ---- quickstart (the guided two-minute tour) ------------------------------------------------
 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("");
+    // SIDE EFFECTS UP FRONT (round-8 ask): say what the tour creates before creating any of it.
     log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
     log("  write .env (or .env.quickstart) + .gitignore entries · create one synthetic decision");
     log("  and its sealed record (records are permanent by design). Cleanup offer at the end.");
@@ -627,6 +738,9 @@ async function cmdQuickstart(opts = {}) {
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
+    // 1. A collision-proof agent, registered fresh every run (round-4 ask: idempotent sample
+    //    registration). Key generated locally; floor-limited token minted; .env written so the
+    //    take-away snippet works in this directory afterward.
     const agentId = `quickstart-${randomBytes(2).toString("hex")}`;
     log(`① Registering agent "${agentId}" (fresh name each run — no collisions)…`);
     const { did, privateKeyBase64 } = generateKeypair();
@@ -635,27 +749,40 @@ async function cmdQuickstart(opts = {}) {
         err(`✘ registration failed (${reg.status}): ${JSON.stringify(reg.body)}`);
         return 1;
     }
+    // A tour credential should outlive the tour and not much else — 7 days, disclosed.
     const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "quickstart", expiresInDays: 7 }) }, session);
     if (!(mint.status >= 200 && mint.status < 300) || !mint.body?.token) {
         err(`✘ token mint failed (${mint.status}): ${JSON.stringify(mint.body)}`);
         return 1;
     }
+    // No webhook secret here (round-8 catch): the sandbox tour never uses the webhook transport,
+    // and inheriting the .env's existing secret duplicated one agent's secret into another's file.
+    // DECIDIO_TOKEN_JTI is revocation METADATA (not a secret) — it is what `quickstart cleanup`
+    // and `tokens revoke` need to kill the token later.
     const envOut = {
         DECIDIO_API_URL: API, DECIDIO_AGENT_ID: agentId, DECIDIO_AGENT_DID: reg.body?.did ?? did,
         DECIDIO_AGENT_KEY: privateKeyBase64, DECIDIO_API_TOKEN: mint.body.token,
         DECIDIO_WORKSPACE_ID: mint.body.workspaceId ?? "",
         ...(mint.body.jti ? { DECIDIO_TOKEN_JTI: mint.body.jti } : {}),
     };
+    // NEVER clobber a real agent's key (guard catch: keys never leave this machine — overwriting
+    // .env's DECIDIO_AGENT_KEY orphans that agent irrecoverably). A directory that already holds
+    // one gets a TOUR-SCOPED env file instead — through the SAME secure writer as .env (round-8
+    // catch: this path used plain writeFileSync).
     let envFile = ENV_PATH;
     if (readEnvFile().DECIDIO_AGENT_KEY) {
         envFile = ".env.quickstart";
         ensureGitignore();
+        // A THIRD tour in the same directory would otherwise overwrite the previous tour agent's
+        // private key — unrecoverable, same class as the .env clobber init refuses (blind-review
+        // catch). Same remedy: back the old file up first, owner-only.
         if (existsSync(envFile)) {
             const prev = readFileSync(envFile, "utf8");
             const prevId = prev.match(/^DECIDIO_AGENT_ID=(.+)$/m)?.[1];
             if (prevId && prevId !== agentId) {
-                writeSecretFile(".env.quickstart.bak", prev);
-                log(`  ✔ previous tour agent (${prevId}) backed up to .env.quickstart.bak — its key would otherwise be unrecoverable`);
+                const bak = `.env.quickstart.${prevId.replace(/[^\w.-]/g, "_")}.bak`;
+                writeSecretFile(bak, prev);
+                log(`  ✔ previous tour agent (${prevId}) backed up to ${bak} — its key would otherwise be unrecoverable (one backup PER agent: serial tours never clobber an earlier backup)`);
             }
         }
         writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
@@ -667,6 +794,9 @@ async function cmdQuickstart(opts = {}) {
     }
     log(`  ✔ key generated locally (public half registered) · 7-day floor-limited token minted${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ""} · ${envFile} written`);
     log("");
+    // 2. Gate a demo action. Show the ACTUAL wrap the tour runs (round-6 catch: the printed line
+    //    differed from the code — this tour uses blocking mode; the bare guard.protect default is
+    //    durable and needs a worker/webhook, which the README covers).
     log(`② Gating a demo action — the tour runs this (blocking mode: watch it live):`);
     log("");
     log(`     const payInvoice = guard.protect(payInvoiceRaw,`);
@@ -682,6 +812,9 @@ async function cmdQuickstart(opts = {}) {
     };
     const payInvoice = withApproval(async (inv) => ({ paid: true, id: inv.id }), (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }), cfg);
     const running = payInvoice({ id: "INV-2026-001", amount: 86_000 });
+    // An EARLY rejection (before routing) must be diagnosed as ITSELF, not as a routing timeout
+    // (round-2 blind catch: the sandbox's per-hour action cap surfaced here as "check
+    // connectivity", and doctor then corroborated the wrong suspect with "all green").
     let earlyError;
     running.catch((e) => { earlyError = e; });
     const waitStart = Date.now();
@@ -704,6 +837,10 @@ async function cmdQuickstart(opts = {}) {
     log(`  ✔ $86,000 payInvoice ROUTED to a human (decision ${decisionId}) — this agent has no auto-approve rule,`);
     log(`    so deny-by-default sends everything to a person. Nothing executes until someone decides.`);
     log("");
+    // 3. The human moment — and it must BE one. The tour's whole claim is "routes it to YOU,
+    //    executes on your yes"; a headless run that approves itself has no discrete yes (round-8
+    //    catch: "headless quickstart breaks the central story"). So headless STOPS here unless
+    //    --auto-approve-demo was passed explicitly, and that path is labeled automated authority.
     const interactive = process.stdin.isTTY;
     if (interactive) {
         await ask(`③ YOU are the approver. Press Enter to approve it here (or approve it in your Decidio queue first, then Enter): `);
@@ -721,6 +858,7 @@ async function cmdQuickstart(opts = {}) {
         log("   Then re-run the quickstart interactively to watch the whole loop — or, for CI, re-run");
         log("   with --auto-approve-demo to let the tour approve itself under that explicit label.");
         log(`   Tidy up this tour's agent + token any time: npx @decidio/sdk quickstart cleanup`);
+        // The blocking poll keeps the event loop alive; the tour is over, so leave cleanly.
         process.exit(0);
     }
     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);
@@ -729,6 +867,7 @@ async function cmdQuickstart(opts = {}) {
         return 1;
     }
     log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
+    // 4. The blocking wrapper wakes and runs the agent's own function.
     let result;
     try {
         result = await running;
@@ -739,6 +878,7 @@ async function cmdQuickstart(opts = {}) {
     }
     log(`  ✔ your function executed AFTER approval: ${JSON.stringify(result)}`);
     log("");
+    // 5. The proof: download the receipt and verify it offline, all in-process.
     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) {
@@ -747,6 +887,8 @@ async function cmdQuickstart(opts = {}) {
     }
     const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
+    // Verify PINNED to the issuer the server just told us over the authenticated channel — an
+    // unpinned VALID only proves self-consistency, and the tour should demonstrate the real thing.
     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}` : "; issuer unpinned"})`);
@@ -766,6 +908,9 @@ async function cmdQuickstart(opts = {}) {
     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")}  ·  Next: the README's 7-step quickstart (durable, workers, adapters).`);
+    // 6. Leave nothing behind unless asked to (round-8 ask: each tour left a live 7-day token and
+    //    local credentials with no cleanup path). Interactive: offer, default KEEP (they may want
+    //    to build on it). Automated (--auto-approve-demo): default CLEANUP unless --keep-agent.
     let doCleanup = false;
     if (interactive) {
         const answer = await ask(`\nKeep this agent for development? [Enter = keep · c + Enter = clean up now]: `);
@@ -781,6 +926,9 @@ async function cmdQuickstart(opts = {}) {
         await quickstartCleanup(session, envFile);
     return v.valid ? 0 : 1;
 }
+/** Revoke the tour's token and remove its local credential file. Honest about what remains:
+ *  sealed records are PERMANENT by design, and the agent's registration row stays (there is no
+ *  deregistration endpoint yet) — but with its token revoked and its key deleted it is inert. */
 async function quickstartCleanup(session, envFile) {
     const env = (() => {
         const out = {};
@@ -794,7 +942,9 @@ async function quickstartCleanup(session, envFile) {
     })();
     if (env.DECIDIO_TOKEN_JTI) {
         const rev = await api(`/api/workspace/agent-token/${encodeURIComponent(env.DECIDIO_TOKEN_JTI)}`, { method: "DELETE" }, session);
-        if (rev.status >= 200 && rev.status < 300)
+        if (rev.status >= 200 && rev.status < 300 && rev.body?.changed === false)
+            log(`  • token was already revoked (jti ${env.DECIDIO_TOKEN_JTI}) — nothing to do.`);
+        else if (rev.status >= 200 && rev.status < 300)
             log(`  ✔ token revoked (jti ${env.DECIDIO_TOKEN_JTI})`);
         else
             log(`  ⚠ token revoke returned ${rev.status} — it still expires on its own within 7 days. List tokens: npx @decidio/sdk tokens list`);
@@ -802,6 +952,10 @@ async function quickstartCleanup(session, envFile) {
     else {
         log(`  ⚠ no DECIDIO_TOKEN_JTI in ${envFile} (older tour) — revoke by hand: npx @decidio/sdk tokens list, then tokens revoke <jti>. It expires on its own within 7 days.`);
     }
+    // Remove ONLY what the tour wrote (guard catch: in a project directory the tour MERGES into an
+    // existing .env, so deleting the whole file would destroy the project's own variables — a
+    // cleanup must never remove anything it didn't create). The file itself goes only when nothing
+    // else lives in it.
     if (existsSync(envFile)) {
         const TOUR_KEYS = new Set(["DECIDIO_API_URL", "DECIDIO_AGENT_ID", "DECIDIO_AGENT_DID", "DECIDIO_AGENT_KEY", "DECIDIO_API_TOKEN", "DECIDIO_WORKSPACE_ID", "DECIDIO_TOKEN_JTI"]);
         const kept = readFileSync(envFile, "utf8").split(/\r?\n/).filter((line) => {
@@ -817,6 +971,9 @@ async function quickstartCleanup(session, envFile) {
             log(`  ✔ tour credentials removed from ${envFile} — its ${kept.length} other line${kept.length === 1 ? "" : "s"} untouched (the agent's local key is gone — the registered agent is now inert)`);
         }
     }
+    // HONEST ACCOUNTING includes the queue (blind-review catch: a headless-stopped tour leaves its
+    // routed decision pending in the SHARED workspace queue, and cleanup said nothing about it).
+    // Listing is a read; clearing it stays a human act — we print the command, we don't run it.
     const tourAgent = env.DECIDIO_AGENT_ID;
     if (tourAgent) {
         const cards = await api("/api/decisions/cards", {}, session);
@@ -830,9 +987,10 @@ async function quickstartCleanup(session, envFile) {
     log(`    and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap).`);
     return 0;
 }
-async function cmdTokens(sub, jti) {
+/** tokens list [--mine] / tokens revoke <jti> — the workspace's agent-token lifecycle. */
+async function cmdTokens(sub, jti, mineOnly = false) {
     if (sub !== "list" && sub !== "revoke") {
-        err("usage: npx @decidio/sdk tokens list");
+        err("usage: npx @decidio/sdk tokens list [--mine]");
         err("       npx @decidio/sdk tokens revoke <jti>");
         err("  Agent tokens are shown by jti (their revocation id) — the token VALUE is never shown again after minting.");
         return 2;
@@ -841,6 +999,14 @@ async function cmdTokens(sub, jti) {
         err("usage: npx @decidio/sdk tokens revoke <jti>   (find the jti with: npx @decidio/sdk tokens list)");
         return 2;
     }
+    // Same grammar and same shape-error as approvals --mine (round-9 catch: a first run in the
+    // SHARED sandbox listed 138 workspace-wide rows — accurate, documented, and still terrible
+    // isolation optics with no way to narrow).
+    if (mineOnly && !process.env.DECIDIO_AGENT_ID) {
+        err(`✘ --mine needs an agent identity, and there is no DECIDIO_AGENT_ID in this directory's .env or your environment.`);
+        err(`  Run this from your agent's directory (where init wrote .env), or drop --mine for the workspace-wide list.`);
+        return 2;
+    }
     let bearer;
     let r = await api("/api/workspace/agent-token");
     if (r.status === 401 || r.status === 403) {
@@ -854,6 +1020,9 @@ async function cmdTokens(sub, jti) {
     if (sub === "revoke") {
         const rev = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, bearer);
         if (rev.status >= 200 && rev.status < 300) {
+            // Replay honesty (blind-review catch + the SDK's own contract): revoking an already-revoked
+            // token changes nothing and must read as a no-op, not a fresh kill. The server says which
+            // via `changed`.
             if (rev.body?.changed === false) {
                 log(`• ${jti} was already revoked — nothing changed.`);
                 log(`  Revocation is permanent; there is no re-revoke. See it: npx @decidio/sdk tokens list`);
@@ -873,16 +1042,23 @@ async function cmdTokens(sub, jti) {
         err(`✘ could not list tokens (${r.status}): ${JSON.stringify(r.body).slice(0, 300)}`);
         return 1;
     }
-    const tokens = r.body?.tokens ?? r.body ?? [];
+    const all = r.body?.tokens ?? r.body ?? [];
+    const myAgent = process.env.DECIDIO_AGENT_ID;
+    const tokens = mineOnly ? all.filter((t) => t.agentId === myAgent) : all;
     if (!Array.isArray(tokens) || !tokens.length) {
-        log("No agent tokens in this workspace.");
+        log(mineOnly ? `No agent tokens for "${myAgent}"${all.length ? ` (${all.length} elsewhere in this workspace — drop --mine to see them)` : ""}.` : "No agent tokens in this workspace.");
         return 0;
     }
+    // Status is derived per row, revoked first — a list that showed revoked tokens as "Active" made
+    // the revocation audit surface unable to confirm its own revocations (blind-review catch).
     const status = (t) => t.revokedAt ? `REVOKED ${String(t.revokedAt).slice(0, 10)}`
         : (t.expiresAt && Date.parse(t.expiresAt) < Date.now()) ? "expired" : "active";
-    log(`Agent tokens (${tokens.length}):`);
+    log(`Agent tokens (${tokens.length}${mineOnly ? ` for "${myAgent}"` : ""})${!mineOnly && myAgent ? ` — workspace-wide (a shared workspace shows every member's agents; --mine narrows to this directory's agent, ${myAgent})` : ""}:`);
     for (const t of tokens)
         log(`  ${t.jti}  ${status(t)}  agent=${t.agentId ?? "?"}  label=${t.label ?? ""}  expires=${t.expiresAt ?? "?"}`);
+    // The governed-action allowance rides the same response — showing it here is what keeps the
+    // per-hour cap from ever being a surprise 429 (round-2 blind catch: the cap was undocumented
+    // and its refusal untyped).
     const al = r.body?.allowance;
     if (al?.limit != null)
         log(`\nGoverned-action allowance: ${al.remaining}/${al.limit} remaining this hour${al.resetAt ? ` (resets ${al.resetAt})` : ""}.`);
@@ -890,6 +1066,8 @@ async function cmdTokens(sub, jti) {
     return 0;
 }
 function cmdDev(target, port) {
+    // Signal-only relay: receive Decidio's webhook here (a stable URL) and forward it to
+    // your local agent's resume listener. Useful when the agent isn't directly reachable.
     log(`decidio dev relay on http://localhost:${port}/decidio/resume → forwarding to ${target}`);
     createServer((req, res) => {
         if (req.method !== "POST") {
@@ -921,16 +1099,18 @@ const USAGE = `decidio — the Decidio SDK command line
       npx @decidio/sdk quickstart
 
   It gates a demo action, routes it to YOU for approval, executes on your yes, and hands you a
-  cryptographically verifiable receipt. (Guided and explicit — this CLI never acts, signs you
-  in, or writes files unless you ask it to.)
+  cryptographically verifiable receipt of the DECISION (execution evidence then accrues on the
+  hosted record — the receipt seals who authorized what, not what ran afterward). Guided and
+  explicit — this CLI never acts, signs you in, or writes files unless you ask it to.
 
   npx @decidio/sdk quickstart          the guided two-minute tour: gate → approve → execute → proof
                                        (interactive: YOUR Enter is the approval. Headless it stops
                                        at the routed decision; --auto-approve-demo for CI, labeled
                                        automated; ends with a keep-or-cleanup choice)
   npx @decidio/sdk quickstart cleanup  revoke the tour's token + delete its local credentials
-  npx @decidio/sdk tokens list         agent tokens with status (active/expired/REVOKED) by jti —
-                                       token values are never re-shown
+  npx @decidio/sdk tokens list [--mine]   agent tokens with status (active/expired/REVOKED) by
+                                       jti — token values are never re-shown; the list is
+                                       workspace-wide, --mine narrows to this directory's agent
   npx @decidio/sdk tokens revoke <jti> kill a token now instead of waiting out its lifetime
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
                                        --unique  append a random suffix (collision-proof samples)
@@ -946,10 +1126,12 @@ const USAGE = `decidio — the Decidio SDK command line
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
   npx @decidio/sdk --version           print the CLI version
 
-Every command talks to the hosted sandbox (https://decidio-api.onrender.com) unless
-DECIDIO_API_URL says otherwise; the target host is announced on stderr each run.
+Every NETWORK command talks to the hosted sandbox (https://decidio-api.onrender.com) unless
+DECIDIO_API_URL says otherwise; the target host is announced on stderr each run. "verify" is
+fully offline — it touches no network and reads no .env.
 Exit codes: 0 success · 1 failure or honest no-op (e.g. replay refused) · 2 usage error.
-Errors and usage go to stderr; stdout carries results only (safe to pipe).
+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 (quickstart, durable resume, adapters).`;
 async function main(argv) {
     const [cmd, a, b, ...rest] = argv.slice(2);
@@ -966,6 +1148,9 @@ async function main(argv) {
         log(USAGE);
         return 0;
     }
+    // STRICT FLAGS (round-8 catch: `verify --strict` was silently ignored — a security CLI must
+    // fail closed on options it doesn't understand, BEFORE any auth or network). Each command
+    // whitelists its flags; anything else exits 2. Value-taking flags name themselves.
     const argsIn = argv.slice(3);
     const KNOWN = {
         quickstart: { flags: ["--auto-approve-demo", "--keep-agent"] },
@@ -974,7 +1159,7 @@ async function main(argv) {
         approvals: { flags: ["--json", "--mine"] },
         receipt: { flags: ["--json"] },
         verify: { flags: [], valued: ["--issuer"] },
-        tokens: { flags: [] },
+        tokens: { flags: ["--mine"] },
         dev: { flags: [], valued: ["--target", "--port"] },
     };
     const spec = KNOWN[cmd];
@@ -990,14 +1175,19 @@ async function main(argv) {
             if (valued.includes(a)) {
                 i++;
                 continue;
-            }
+            } // its value is consumed
             if (valued.some((v) => a.startsWith(v + "=")))
-                continue;
+                continue; // --flag=value form
             if (!spec.flags.includes(a)) {
                 err(`✘ unknown option "${a}" for \`${cmd}\` — refusing to guess (a flag you meant to matter must never be silently ignored).\n\n${USAGE}`);
                 return 2;
             }
         }
+        // POSITIONAL arity is part of the same contract (round-2 blind catch: `tokens revoke jti1
+        // jti2` revoked only the first and reported unqualified success — silent false success on a
+        // security control). Anything beyond what the command reads is refused, not dropped.
+        // approvals approve/reject take a free-text reason, so their tail is exempt; verify takes
+        // any number of files.
         const MAX_POS = { 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) {
@@ -1020,6 +1210,7 @@ async function main(argv) {
     switch (cmd) {
         case "quickstart": {
             if (argsIn.includes("cleanup")) {
+                // Standalone cleanup: prefer the tour-scoped file; fall back to a tour-created .env.
                 const envFile = existsSync(".env.quickstart") ? ".env.quickstart"
                     : (readEnvFile().DECIDIO_AGENT_ID ?? "").startsWith("quickstart-") ? ENV_PATH : undefined;
                 if (!envFile) {
@@ -1035,6 +1226,9 @@ async function main(argv) {
         }
         case "init": {
             const unique = argsIn.includes("--unique");
+            // BOTH forms (guard catch: the strict table's generic `=` allowance let --expires-days=30
+            // pass the gate while this parser read only the space form — a silently-ignored
+            // credential-LIFETIME flag, the exact class the verifier doors just fixed).
             const expIdx = argsIn.indexOf("--expires-days");
             const expEq = argsIn.find((x) => x.startsWith("--expires-days="));
             const expRaw = expIdx >= 0 ? argsIn[expIdx + 1] : expEq ? expEq.slice("--expires-days=".length) : undefined;
@@ -1057,7 +1251,7 @@ async function main(argv) {
         case "verify": return cmdVerify(argsIn);
         case "tokens": {
             const positional = argsIn.filter((x) => !x.startsWith("-"));
-            return cmdTokens(positional[0], positional[1]);
+            return cmdTokens(positional[0], positional[1], argsIn.includes("--mine"));
         }
         case "dev": {
             const flag = (name) => {
@@ -1068,6 +1262,8 @@ async function main(argv) {
                 return eq ? eq.slice(name.length + 1) : undefined;
             };
             const target = flag("--target") || process.env.DECIDIO_AGENT_RESUME_URL || "http://localhost:4100/decidio/resume";
+            // Validate on shape, before binding anything (blind-review catch: `--port abc` printed
+            // localhost:NaN and died with a raw internal error).
             const portRaw = flag("--port") || process.env.DECIDIO_DEV_PORT || "4099";
             if (!/^\d+$/.test(portRaw) || Number(portRaw) < 1 || Number(portRaw) > 65535) {
                 err(`✘ --port needs a number between 1 and 65535 (got "${portRaw}").`);
@@ -1080,7 +1276,14 @@ async function main(argv) {
             return cmdDev(target, Number(portRaw));
         }
         default:
-            err(`✘ unknown command "${cmd}"\n\n${USAGE}`);
+            // Exit 2, not 1: an unknown command is a USAGE error, and the help text promised that
+            // contract (round-8 catch).
+            // A flag in command position gets a NAMED fix, not just a refusal (round-3 blind nit:
+            // `--json approvals` earned "unknown command" with no hint that flags follow the command).
+            if (cmd.startsWith("-"))
+                err(`✘ unknown command "${cmd}" — flags go AFTER the command (e.g. npx @decidio/sdk approvals ${cmd}).\n\n${USAGE}`);
+            else
+                err(`✘ unknown command "${cmd}"\n\n${USAGE}`);
             return 2;
     }
 }