@decidio/sdk 0.1.11 → 0.2.0

package/dist/cli.js

@@ -6,7 +6,7 @@ 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 { generateKeypair, assertSafeTransport } from "./signing.js";
 import { withApproval, DecidioRateLimitError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
@@ -65,9 +65,14 @@ async function api(path, init = {}, bearer) {
         err(`  Fix the file's permissions, or set DECIDIO_API_URL explicitly for this command. Nothing was sent.`);
         process.exit(1);
     }
-    if (auth && /^http:[/][/]/i.test(API) && !/^http:[/][/](localhost|127.0.0.1|.::1.)([:/]|$)/i.test(API)) {
-        err(`✘ refusing to send credentials over plaintext http to ${API} — use https, or localhost for local dev. Nothing was sent.`);
-        process.exit(1);
+    if (auth) {
+        try {
+            assertSafeTransport(API, true);
+        }
+        catch (e) {
+            err(`✘ ${String(e?.message ?? e).replace(/^\[decidio\] /, "")}`);
+            process.exit(1);
+        }
     }
     let res;
     try {
@@ -189,7 +194,10 @@ function ask(question, mute = false) {
     });
 }
 async function acquireSession(purpose) {
-    if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
+    try {
+        assertSafeTransport(API, true);
+    }
+    catch {
         err(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
         err(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
         return null;
@@ -250,6 +258,18 @@ async function cmdInit(agentId, opts = {}) {
     }
     const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
     const registerBody = JSON.stringify({ agentId, did: localDid, ...(sourceSystem ? { sourceSystem } : {}) });
+    let envPrepared = false;
+    const prepareEnvForWrite = () => {
+        if (envPrepared)
+            return;
+        envPrepared = true;
+        ensureGitignore();
+        if (opts.force && existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId) {
+            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)`);
+        }
+    };
     let session = null;
     let r = await api("/api/agents/register", { method: "POST", body: registerBody });
     if (r.status === 401 || r.status === 403) {
@@ -280,6 +300,8 @@ async function cmdInit(agentId, opts = {}) {
         did = r.body?.did;
         privateKey = localKey;
         log(`✔ registered (did ${did}) — key generated locally; only the public half went to Decidio`);
+        prepareEnvForWrite();
+        upsertEnv({ DECIDIO_AGENT_ID: agentId, DECIDIO_AGENT_DID: did ?? localDid, DECIDIO_AGENT_KEY: localKey });
     }
     else {
         err(`✘ registration failed (${r.status}): ${JSON.stringify(r.body)}`);
@@ -302,7 +324,7 @@ async function cmdInit(agentId, opts = {}) {
         }
         else if (session) {
             err(`✘ could not mint the agent's API token (${mint.status}): ${JSON.stringify(mint.body)}`);
-            err(`  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. The agent IS registered and its key is saved in ${ENV_PATH} — fix the cause above and re-run init; it will reuse that key and mint again.`);
             return 1;
         }
         else {
@@ -323,12 +345,7 @@ async function cmdInit(agentId, opts = {}) {
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     if (tokenJti)
         envOut.DECIDIO_TOKEN_JTI = tokenJti;
-    ensureGitignore();
-    if (opts.force && existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId) {
-        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)`);
-    }
+    prepareEnvForWrite();
     upsertEnv(envOut);
     for (const [k, v] of Object.entries(envOut))
         process.env[k] = v;
@@ -350,8 +367,9 @@ async function cmdInit(agentId, opts = {}) {
     log(`       { mode: "blocking" },   // blocking = watch it happen live; durable is the production mode`);
     log(`     );`);
     log("");
-    log(`     const result = await payInvoice({ id: "INV-2026-001", amount: 86_000 });`);
-    log(`     console.log("executed after approval:", result);`);
+    log(`     const { value, confirmation } = await payInvoice({ id: "INV-2026-001", amount: 86_000 });`);
+    log(`     console.log("executed after approval:", value);`);
+    log(`     console.log("Decidio recorded it as:", confirmation.evidenceTier);`);
     log("");
     log("  2. Run it, approve it, watch it complete:");
     log("");
@@ -403,13 +421,14 @@ async function cmdDoctor() {
             if (typeof payload?.exp === "number") {
                 const msLeft = payload.exp * 1000 - Date.now();
                 const days = Math.floor((msLeft + 60_000) / 86_400_000);
-                const left = msLeft < 86_400_000 ? `${Math.max(1, Math.floor(msLeft / 3_600_000))} hour(s)` : `${days} day(s)`;
+                const left = msLeft < 86_400_000 ? `${Math.max(1, Math.floor(msLeft / 3_600_000))} hour(s)` : `${Math.round(msLeft / 86_400_000)} day(s)`;
+                const daysRounded = Math.round(msLeft / 86_400_000);
                 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)
                     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: unexpired for another ${days} days (validity is decided by the server — see the token-scope check below)`);
+                    log(`✔ agent token: unexpired for another ${daysRounded} days (validity is decided by the server — see the token-scope check below)`);
             }
         }
         catch { }
@@ -568,12 +587,18 @@ async function cmdReceipt(id, jsonMode = false) {
     const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
     const conf = detail.body?.record?.confirmation;
     const issuer = r.body?.issuer;
+    const resolved = r.body?.resolved;
     if (jsonMode) {
-        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed, issuer: issuer ?? null }, null, 2));
+        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed, issuer: issuer ?? null, ...(resolved ? { resolved } : {}) }, null, 2));
         return 0;
     }
     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)" : ""}.`);
+    if (resolved && Object.keys(resolved).length) {
+        log(`  Resolved for you (${Object.keys(resolved).length} field${Object.keys(resolved).length === 1 ? "" : "s"} your access covers — the FILE keeps the tokens, so it stays verifiable and safe to hand on):`);
+        for (const [tok, val] of Object.entries(resolved))
+            log(`    ${tok}  →  ${val}`);
+    }
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     if (issuer) {
         log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
@@ -647,12 +672,31 @@ async function cmdQuickstart(opts = {}) {
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
-    const agentId = `quickstart-${randomBytes(2).toString("hex")}`;
-    log(`① Registering agent "${agentId}" (fresh name each run — no collisions)…`);
+    const envFile = readEnvFile().DECIDIO_AGENT_KEY ? ".env.quickstart" : ENV_PATH;
+    if (!assertNotTracked(envFile))
+        return 1;
+    ensureGitignore();
+    let agentId = `quickstart-${randomBytes(5).toString("hex")}`;
+    log(`① Registering agent "${agentId}"…`);
     const { did, privateKeyBase64 } = generateKeypair();
-    const reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
+    let reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
+    for (let attempt = 0; reg.status === 409 && attempt < 3; attempt++) {
+        agentId = `quickstart-${randomBytes(5).toString("hex")}`;
+        reg = await api("/api/agents/register", { method: "POST", body: JSON.stringify({ agentId, did }) }, session);
+        if (reg.status >= 200 && reg.status < 300)
+            log(`  (that name was taken — using "${agentId}" instead)`);
+    }
     if (!(reg.status >= 200 && reg.status < 300)) {
-        err(`✘ registration failed (${reg.status}): ${JSON.stringify(reg.body)}`);
+        err(`✘ could not register the tour's agent (${reg.status}): ${JSON.stringify(reg.body)}`);
+        if (reg.status === 409) {
+            err(`  Every generated name collided, which should be almost impossible — something is likely`);
+            err(`  wrong with this workspace's agent list rather than with your setup.`);
+            err(`  See what is registered: npx @decidio/sdk tokens list`);
+        }
+        else {
+            err(`  Check the target and your sign-in, then re-run: npx @decidio/sdk doctor`);
+        }
+        err(`  Nothing was written to this directory.`);
         return 1;
     }
     const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "quickstart", expiresInDays: 7 }) }, session);
@@ -666,30 +710,36 @@ async function cmdQuickstart(opts = {}) {
         DECIDIO_WORKSPACE_ID: mint.body.workspaceId ?? "",
         ...(mint.body.jti ? { DECIDIO_TOKEN_JTI: mint.body.jti } : {}),
     };
-    let envFile = ENV_PATH;
-    if (readEnvFile().DECIDIO_AGENT_KEY) {
-        envFile = ".env.quickstart";
-        if (!assertNotTracked(envFile))
-            return 1;
-        ensureGitignore();
+    if (envFile !== ENV_PATH) {
         if (existsSync(envFile)) {
             const prev = readFileSync(envFile, "utf8");
             const prevId = prev.match(/^DECIDIO_AGENT_ID=(.+)$/m)?.[1];
+            const prevJti = prev.match(/^DECIDIO_TOKEN_JTI=(.+)$/m)?.[1];
             if (prevId && prevId !== agentId) {
-                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)`);
+                if (prevJti) {
+                    const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(prevJti)}`, { method: "DELETE" }, session);
+                    if (rv.status >= 200 && rv.status < 300)
+                        log(`  ✔ the previous tour agent (${prevId}) had its token REVOKED before this tour replaced it — no live credential is left behind`);
+                    else
+                        log(`  ⚠ could not revoke the previous tour's token (jti ${prevJti}, ${rv.status}) — revoke it by hand: npx @decidio/sdk tokens revoke ${prevJti}`);
+                }
+                else {
+                    log(`  ⚠ the previous tour file carried no revocation id, so its token (if any) must be revoked from your Decidio app.`);
+                }
             }
         }
         writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
         log(`  ✔ this directory already has an agent in .env — tour credentials went to ${envFile} (your agent is untouched)`);
     }
     else {
-        if (!assertNotTracked(ENV_PATH))
-            return 1;
-        ensureGitignore();
         upsertEnv(envOut);
     }
+    const failTour = async (code) => {
+        log("");
+        log("  The tour did not complete — cleaning up the credentials it created:");
+        await quickstartCleanup(session, envFile).catch(() => { });
+        return code;
+    };
     log(`  ✔ key generated locally (public half registered) · 7-day floor-limited token minted${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ""} · ${envFile} written`);
     log("");
     log(`② Gating a demo action — the tour runs this (blocking mode: watch it live):`);
@@ -716,15 +766,15 @@ async function cmdQuickstart(opts = {}) {
         err(`✘ this workspace's governed-action allowance is used up${earlyError.limit != null ? ` (${earlyError.limit} actions/hour on lab workspaces)` : ""}.`);
         err(`  Nothing was routed or executed — the cap is the sandbox protecting itself, not a fault${earlyError.resetAt ? `. It resets ${earlyError.resetAt}` : ""}.`);
         err(`  Re-run the tour after the reset (or talk to us about a production workspace).`);
-        return 1;
+        return failTour(1);
     }
     if (!decisionId && earlyError) {
         err(`✘ the gate refused before routing: ${earlyError?.message ?? earlyError}`);
-        return 1;
+        return failTour(1);
     }
     if (!decisionId) {
         err("✘ the gate did not route within 30s — check connectivity (npx @decidio/sdk doctor) and re-run.");
-        return 1;
+        return failTour(1);
     }
     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.`);
@@ -749,35 +799,50 @@ 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`);
-        process.exit(0);
+        log("");
+        log("   (exit 3 = the tour stopped at the human moment. Nothing executed and no receipt was");
+        log("    written, so this run is deliberately not reported as a completed tour.)");
+        log("");
+        log(`   NOTE: this tour's credentials are still live in ${envFile} (a 7-day token + the agent's`);
+        log(`   key), because the decision above is still waiting for you. Once you have approved it —`);
+        log(`   or if you abandon the tour — remove them: npx @decidio/sdk quickstart cleanup`);
+        process.exit(3);
     }
     const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
     if (!(ap.status >= 200 && ap.status < 300)) {
         err(`✘ approve failed (${ap.status}): ${JSON.stringify(ap.body)}`);
-        return 1;
+        return failTour(1);
     }
     log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
-    let result;
+    let done;
     try {
-        result = await running;
+        done = await running;
     }
     catch (e) {
         err(`✘ the gated call did not complete: ${e?.message ?? e}`);
-        return 1;
+        return failTour(1);
     }
-    log(`  ✔ your function executed AFTER approval: ${JSON.stringify(result)}`);
+    log(`  ✔ your function executed AFTER approval: ${JSON.stringify(done.value)}`);
+    if (done.confirmation?.evidenceTier)
+        log(`    …and the call itself told you what was recorded: confirmation.evidenceTier = ${done.confirmation.evidenceTier}`);
     log("");
     log("④ Downloading the sealed Authority Receipt and verifying it OFFLINE…");
     const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
     if (!(rec.status >= 200 && rec.status < 300) || !rec.body?.credential) {
         err(`✘ receipt fetch failed (${rec.status})`);
-        return 1;
+        return failTour(1);
     }
     const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
     const issuer = rec.body?.issuer;
     const v = verifyReceipt(rec.body.credential, issuer);
-    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : "; issuer unpinned"})`);
+    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : ""})`);
+    if (!issuer) {
+        err(`  ⚠ the server did not return an issuer DID, so this check ran UNPINNED — it proves the`);
+        err(`    receipt is internally consistent, NOT who issued it (a self-signed forgery also passes).`);
+        err(`    Get your workspace's issuer DID from the app's record-verify panel, then re-check:`);
+        err(`      npx @decidio/sdk verify --issuer <did:key:...> ${fname}`);
+    }
     if (issuer)
         log(`    Keep that DID: it is your trust anchor — npx @decidio/sdk verify --issuer ${issuer} <receipt.json>`);
     const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
@@ -805,9 +870,8 @@ async function cmdQuickstart(opts = {}) {
         doCleanup = true;
         log(`\nAutomated run: cleaning the tour up (pass --keep-agent to keep the agent + token).`);
     }
-    if (doCleanup)
-        await quickstartCleanup(session, envFile);
-    return v.valid ? 0 : 1;
+    const cleanupCode = doCleanup ? await quickstartCleanup(session, envFile) : 0;
+    return v.valid ? (cleanupCode || 0) : 1;
 }
 async function quickstartCleanup(session, envFile) {
     const env = (() => {
@@ -834,7 +898,12 @@ 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.`);
+        err(`✘ no DECIDIO_TOKEN_JTI in ${envFile} (older tour) — this tour's token is STILL LIVE and this`);
+        err(`  command cannot revoke it. Nothing was deleted. Find and revoke it, then re-run cleanup:`);
+        err(`    npx @decidio/sdk tokens list`);
+        err(`    npx @decidio/sdk tokens revoke <jti>`);
+        err(`  (it also expires on its own within 7 days)`);
+        return 1;
     }
     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"]);
@@ -971,6 +1040,8 @@ const USAGE = `decidio — the Decidio SDK command line
                                        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 quickstart --auto-approve-demo   headless tour; cleans up after itself
+                                       (add --keep-agent to KEEP the tour agent + token)
   npx @decidio/sdk tokens list [--mine]   agent tokens with status (active/expired/REVOKED) by
                                        jti — token values are never re-shown; the list is
                                        workspace-wide, --mine narrows to this directory's agent
@@ -984,8 +1055,10 @@ const USAGE = `decidio — the Decidio SDK command line
   npx @decidio/sdk approvals [--json] [--mine]   list pending agent approvals
   npx @decidio/sdk approvals approve <id> [reason]
   npx @decidio/sdk approvals reject <id> [reason]
-                                       the reason is FREE TEXT and is sealed verbatim. If it
-                                       starts with a dash, put it after -- or use --reason:
+                                       the reason is FREE TEXT, sent exactly as typed. It seals
+                                       immutably; personal or sensitive values are tokenized at
+                                       rest, so the STORED text can differ (see: receipt <id>).
+                                       If it starts with a dash, put it after -- or use --reason:
                                          ... approve <id> -- "-50% cut, per the board"
                                          ... approve <id> --reason "-50% cut, per the board"
   npx @decidio/sdk receipt <id>        download a sealed decision's Authority Receipt (.json)
@@ -996,7 +1069,9 @@ const USAGE = `decidio — the Decidio SDK command line
 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.
+Exit codes: 0 success · 1 failure or honest no-op (e.g. replay refused) · 2 usage error ·
+3 quickstart stopped at the human moment (headless: routed, but nothing executed and no
+receipt written — pass --auto-approve-demo for a run that completes unattended).
 Errors, and usage shown on ERROR paths, go to stderr; stdout carries results only (safe to
 pipe). Asked-for help — including this bare invocation — IS a result, so it prints here.
 Docs: the README that shipped with this package — node_modules/@decidio/sdk/README.md
@@ -1037,6 +1112,13 @@ async function main(argv) {
                 positionals.push(...argsIn.slice(i + 1));
                 break;
             }
+            const inFreeTextTail = cmd === "approvals"
+                && (positionals[0] === "approve" || positionals[0] === "reject")
+                && positionals.length >= 2;
+            if (!inFreeTextTail && a.startsWith("-") && !a.startsWith("--")) {
+                err(`✘ unknown option "${a}" for \`${cmd}\` — refusing to guess (a flag you meant to matter must never be silently ignored). Short flags are not supported; use the long form.\n\n${USAGE}`);
+                return 2;
+            }
             if (!a.startsWith("--")) {
                 positionals.push(a);
                 continue;
@@ -1108,12 +1190,15 @@ async function main(argv) {
             const head = dashdash >= 0 ? argsIn.slice(0, dashdash) : argsIn;
             const literal = dashdash >= 0 ? argsIn.slice(dashdash + 1) : [];
             const rIdx = head.indexOf("--reason");
+            const rEq = head.find((x) => x.startsWith("--reason="));
             const flagless = head.filter((x, i) => !x.startsWith("-") && !(rIdx >= 0 && i === rIdx + 1));
             const sub = flagless[0];
             const id = flagless[1];
             let reason;
             if (rIdx >= 0)
                 reason = head[rIdx + 1];
+            else if (rEq !== undefined)
+                reason = rEq.slice("--reason=".length);
             else if (literal.length)
                 reason = literal.join(" ");
             else if (sub && id) {
@@ -1121,10 +1206,14 @@ async function main(argv) {
                 const rest = head.slice(after).filter((x) => x !== "--json" && x !== "--mine");
                 reason = rest.length ? rest.join(" ") : undefined;
             }
-            if (rIdx >= 0 && (reason === undefined || reason.startsWith("-"))) {
+            if ((rIdx >= 0 || rEq !== undefined) && (reason === undefined || reason === "" || (rIdx >= 0 && reason.startsWith("--")))) {
                 err(`✘ --reason needs the text to record (quote it if it contains spaces): npx @decidio/sdk approvals ${sub ?? "approve"} <id> --reason "over budget -50% cut required"`);
                 return 2;
             }
+            if (reason !== undefined && sub !== "approve" && sub !== "reject") {
+                err(`✘ --reason only applies to approve/reject (a sealed reason needs a decision to seal onto): npx @decidio/sdk approvals approve <id> --reason "..."`);
+                return 2;
+            }
             return cmdApprovals(sub, id, reason, { json: head.includes("--json"), mine: head.includes("--mine") });
         }
         case "receipt": return cmdReceipt(argsIn.find((x) => !x.startsWith("-")), argsIn.includes("--json"));

package/dist/errors.d.ts

@@ -1,8 +1,3 @@
-/** A gate response this SDK could not accept, carrying what a caller needs to BRANCH on rather
- *  than a stringified body they would have to parse. `status` is the HTTP status; `retryable`
- *  distinguishes a terminal refusal (401/403 — a credential problem no retry fixes) from a
- *  transient one (5xx, 429). Every long-running agent hits the terminal case eventually: an
- *  agent token expires, or `init` is re-run and revokes it. */
 export declare class DecidioHttpError extends Error {
     status: number;
     endpoint: string;
@@ -10,3 +5,15 @@ export declare class DecidioHttpError extends Error {
     readonly retryable: boolean;
     constructor(status: number, endpoint: string, body?: unknown | undefined);
 }
+/** ONE rule for what counts as a usable decision id, returning a REASON rather than throwing, so
+ *  every door can apply the same check and raise its own error type. (`resume.ts` cannot import
+ *  `index.ts`, which is why the check was copy-pasted into four places and drifted.)
+ *
+ *  All four copies tested truthiness only, so `"   "` passed every one of them: the blocking path
+ *  would poll `/agent/status/%20%20%20`, the durable path would park under a whitespace key, and
+ *  the confirmation would attest a decision nobody can look up. Control characters are refused for
+ *  the same reason a reason-string is sanitised — an id goes into a URL path, a filename and an
+ *  audit line. Nothing is silently trimmed: an id that needs trimming is not the id the server
+ *  sent, and quietly rewriting an identifier is how two systems end up disagreeing about which
+ *  decision they mean. */
+export declare function decisionIdProblem(raw: unknown): string | null;

package/dist/errors.js

@@ -1,18 +1,50 @@
+const RETRYABLE_STATUS = (status) => status === 408 || status === 429 || (status >= 500 && status !== 501);
+function sideEffectNote(endpoint) {
+    if (endpoint.startsWith("/agent/confirm")) {
+        return " Your action ALREADY RAN — only its report failed. Do NOT re-run it.";
+    }
+    if (endpoint.startsWith("/agent/status")) {
+        return " This call is a read, so it changed nothing; the decision itself is unaffected.";
+    }
+    return " Nothing was routed or executed.";
+}
 export class DecidioHttpError extends Error {
     status;
     endpoint;
     body;
     retryable;
     constructor(status, endpoint, body) {
-        const terminal = status === 401 || status === 403;
+        const credential = status === 401 || status === 403;
+        const retryable = !credential && RETRYABLE_STATUS(status);
         super(`[decidio] ${endpoint} refused this call (HTTP ${status})` +
-            (terminal
-                ? ` — the credential was rejected. The agent token may have expired or been revoked (re-running \`init\` for the same agent revokes the previous one). Mint a fresh one: npx @decidio/sdk init <agent-name>, then restart this process. Nothing was routed or executed.`
-                : ` — this looks transient; retrying is safe (a retry creates a NEW request and can never double-execute). Nothing was routed or executed.`));
+            (credential
+                ? ` — the credential was rejected. The agent token may have expired or been revoked (re-running \`init\` for the same agent revokes the previous one). Mint a fresh one: npx @decidio/sdk init <agent-name>, then restart this process.`
+                : retryable
+                    ? ` — this looks transient; retrying is safe (a retry creates a NEW request and can never double-execute).`
+                    : ` — the server refused the request itself, so retrying it unchanged will fail the same way. Fix the request (or the decision it names) first.`) +
+            sideEffectNote(endpoint));
         this.status = status;
         this.endpoint = endpoint;
         this.body = body;
         this.name = "DecidioHttpError";
-        this.retryable = !terminal;
+        this.retryable = retryable;
+    }
+}
+export function decisionIdProblem(raw) {
+    if (typeof raw !== "string")
+        return `it is ${raw === null ? "null" : typeof raw}, not a string`;
+    if (raw.length === 0)
+        return "it is empty";
+    if (raw.trim().length === 0)
+        return "it is only whitespace";
+    if (raw !== raw.trim())
+        return "it has leading or trailing whitespace (ids are used verbatim in URLs, filenames and audit lines — this SDK will not silently trim one)";
+    for (const ch of raw) {
+        const cp = ch.codePointAt(0);
+        if (cp < 0x20 || cp === 0x7f)
+            return "it contains control characters";
     }
+    if (raw.length > 256)
+        return `it is ${raw.length} characters long (limit 256)`;
+    return null;
 }

package/dist/evidence.d.ts

@@ -13,6 +13,29 @@ export interface EvidenceOutcome {
     /** Present when the outcome is worth explaining (why a signed report did not confirm, or why
      *  a report was not recorded at all) — always actionable, never a shrug. */
     diagnostic?: string;
+    /** Present when the gate reported on the SIGNED execution report: whether the attestation
+     *  proof VERIFIED (C3, 0.1.12 — this field used to be read off the wire and discarded, so a
+     *  failed attestation was invisible to every client door). */
+    executionReportVerified?: boolean;
+    /** WHY the attestation did not verify, verbatim from the gate (unknown did, expired proof,
+     *  burnt nonce, payload mismatch). It was folded into `diagnostic` prose and nowhere else, so a
+     *  caller who wanted to BRANCH on the reason — retry vs re-register vs alert — had to regex an
+     *  English sentence. Same rule as the typed HTTP errors: give callers the fact, not a string to
+     *  parse. */
+    executionReportReason?: string;
+    /** Whether re-sending this report could succeed. False for a refusal the server will repeat
+     *  (an unrecognised tier, a denied success flag); true for a transport or availability failure.
+     *  Undefined when the report WAS recorded and there is nothing to retry. */
+    confirmationRetryable?: boolean;
+    /** Whether the reported value reached durable storage, so `reconfirm()` can re-send it. On the
+     *  inline path this is false by construction — nothing is parked — which is exactly why an
+     *  inline caller needs to see the outcome at the call site rather than in a log line. */
+    reportJournalled?: boolean;
+    /** Set when the caller's `evidence` mapper (or the canonical model) rejected the return value,
+     *  so an EMPTY captured response was reported. The execution is recorded; its evidence is not.
+     *  This was previously a console.warn and nothing else — invisible to the code that could
+     *  actually fix it. */
+    evidenceError?: string;
 }
 /** The SERVER's rule for `application_confirmed`, restated here exactly as implemented so this
  *  explanation can never drift from it: the captured response must carry a RECORD ID

package/dist/evidence.js

@@ -20,23 +20,34 @@ export function describeTierGap(capturedResponse) {
     return "the report was accepted but the gate recorded a weaker tier — check that this agent's registration and signing key still match (`npx @decidio/sdk doctor`).";
 }
 export function readConfirmResponse(body, opts) {
-    const retry = opts.journalled
+    const journalled = opts.journalled ?? false;
+    const retry = journalled
         ? "re-send the report with `guard.resume.reconfirm(decisionId)` once connectivity or the service is healthy."
         : "this path journalled no report, so there is nothing to re-send from here — record the outcome from your own system, or run the action through `guard.protect`'s durable mode, where reports ARE journalled and `reconfirm` can replay them.";
     const b = body;
     if (!b || b.ok !== true || typeof b.confirmation !== "string") {
-        return { reportRecorded: false, executionConfirmed: false, diagnostic: `the gate answered 2xx but named no evidence tier — the execution report is NOT recorded. Your action DID run; ${retry}` };
+        return { reportRecorded: false, executionConfirmed: false, confirmationRetryable: true, reportJournalled: journalled, diagnostic: `the gate answered 2xx but named no evidence tier — the execution report is NOT recorded. Your action DID run; ${retry}` };
     }
     const tier = b.confirmation;
     if (!EVIDENCE_TIERS.includes(tier)) {
-        return { reportRecorded: false, executionConfirmed: false, diagnostic: `the gate reported an evidence tier this SDK does not recognise (${JSON.stringify(tier)}) — refusing to treat it as evidence. Upgrade @decidio/sdk; your action DID run, and ${retry}` };
+        return { reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: journalled, diagnostic: `the gate reported an evidence tier this SDK does not recognise (${JSON.stringify(tier)}) — refusing to treat it as evidence. Upgrade @decidio/sdk; your action DID run, and ${retry}` };
     }
     const executionConfirmed = CONFIRMING.includes(tier);
-    const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed };
+    const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed, reportJournalled: journalled };
     if (!executionConfirmed && opts.signed)
         outcome.diagnostic = describeTierGap(opts.capturedResponse);
     else if (!executionConfirmed)
         outcome.diagnostic = "no signing key is configured, so the gate capped this report at an unproven agent assertion. Run `npx @decidio/sdk init` to generate the agent's key and earn a confirming tier.";
+    const rpt = body?.executionReport;
+    if (rpt && typeof rpt === "object" && typeof rpt.verified === "boolean") {
+        outcome.executionReportVerified = rpt.verified;
+        if (typeof rpt.reason === "string" && rpt.reason)
+            outcome.executionReportReason = rpt.reason;
+        if (!rpt.verified) {
+            const why = typeof rpt.reason === "string" && rpt.reason ? ` (${rpt.reason})` : "";
+            outcome.diagnostic = `${outcome.diagnostic ? outcome.diagnostic + " " : ""}The signed execution report did NOT verify${why} — the report was recorded without a proven attestation. Check the agent's key/DID/registration (npx @decidio/sdk doctor).`;
+        }
+    }
     return outcome;
 }
 import { signExecutionReport, resultDigest } from "./signing.js";

package/dist/guard.d.ts

@@ -1,4 +1,4 @@
-import { type ApprovalContext } from "./index.js";
+import { type ApprovalContext, type ProtectedExecution } from "./index.js";
 import { type ResumeController, type ResumeOutcome } from "./resume.js";
 export interface GuardFacadeConfig {
     apiUrl: string;
@@ -28,6 +28,12 @@ export interface ProtectOptions {
      *  across every door), but their ENGINE integration is verified against structural mocks, not
      *  live engines. Use the core path for production until that changes. */
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest";
+    /** Hand the action an `ExecutionContext` as its FIRST argument: `{ decisionId, attemptId,
+     *  idempotencyKey }`. Pass `idempotencyKey` to your downstream API and the one window this SDK
+     *  cannot close — the vendor committing twice — closes on their side. Opt-in by design: arity
+     *  inspection would have to guess, and guessing wrong hands a payment call a context object
+     *  where it expected an invoice. */
+    withContext?: boolean;
     /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
     /** The action name this wrapper produces, declared UP FRONT so the resume registry is populated
@@ -65,7 +71,7 @@ export declare class Guard {
     /** Register a raw fn under its action name so a COLD process (one that never made the original
      *  call) can resume it. Call this at startup beside `guard.worker()` — or pass
      *  `{ action }` to `protect(...)`, which does it for you at wrap time. */
-    register(action: string, fn: (...a: any[]) => Promise<any>): void;
+    register(action: string, fn: (...a: any[]) => Promise<any>, evidence?: (result: any) => unknown): void;
     /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
     resumeHandler(): import("http").RequestListener;
     /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
@@ -84,7 +90,18 @@ export declare class Guard {
     /** Throws when the facade has no gate URL — at USE time, not import time, so `import { guard }`
      *  stays safe in envless contexts. */
     private assertConfigured;
-    protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
+    /** Wrap a function so every call is authorized, recorded and — in 0.2.0 — REPORTED BACK.
+     *
+     *  Returns `{ value, decisionId, confirmation }`, not the bare value. Through 0.1.x it returned
+     *  `R` and the confirmation outcome went to a console warning, so the one thing a caller of an
+     *  authority SDK could not do was find out what Decidio recorded. If you genuinely do not need
+     *  it, `protectBestEffort` keeps the old shape. */
+    protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<ProtectedExecution<R>>;
+    /** @deprecated The 0.1.x shape: resolves to your function's value alone and DISCARDS what
+     *  Decidio recorded. Kept because a caller who truly does not care should not have to
+     *  destructure — but "the report was not recorded" and "the execution could not be attested"
+     *  become invisible again, which is the gap 0.2.0 exists to close. Prefer `protect`. */
+    protectBestEffort<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
 }
 /** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export declare const guard: Guard;

package/dist/guard.js

@@ -24,7 +24,7 @@ export class Guard {
             appUrl: process.env.DECIDIO_APP_URL,
         });
     }
-    register(action, fn) { this.ensureResume().register(action, fn); }
+    register(action, fn, evidence) { this.ensureResume().register(action, fn, evidence); }
     resumeHandler() { return this.ensureResume().webhookHandler(); }
     resumeFetchHandler() { return this.ensureResume().fetchHandler(); }
     worker(opts) {
@@ -68,14 +68,16 @@ export class Guard {
                 `(pollTimeoutMs), and when it does, the decision stays OPEN in Decidio while this process stops waiting: ` +
                 `a later approval cannot resume it. Only safe for short, watched approvals — omit mode:"blocking" for ` +
                 `durable async resume on real (minutes-to-days) approvals.`);
-            return withApproval(fn, describe, base, opts?.evidence ? { evidence: opts.evidence } : undefined);
+            return withApproval(fn, describe, base, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
         }
         const resume = this.ensureResume();
         if (opts?.action)
-            resume.register(opts.action, fn);
-        if (opts?.evidence)
-            resume.evidence = opts.evidence;
-        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, opts?.evidence ? { evidence: opts.evidence } : undefined);
+            resume.register(opts.action, fn, opts?.evidence, opts?.withContext);
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume }, { ...(opts?.evidence ? { evidence: opts.evidence } : {}), ...(opts?.withContext ? { withContext: true } : {}) });
+    }
+    protectBestEffort(fn, describe, opts) {
+        const wrapped = this.protect(fn, describe, opts);
+        return async (...a) => (await wrapped(...a)).value;
     }
 }
 export const guard = Guard.fromEnv();