@decidio/sdk 0.1.10 → 0.1.12

package/dist/cli.js

@@ -6,8 +6,8 @@ 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 { generateKeypair, assertSafeTransport } from "./signing.js";
+import { withApproval, DecidioRateLimitError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
     try {
@@ -18,6 +18,7 @@ const VERSION = (() => {
     }
 })();
 let envWarned = false;
+let envUnreadable = false;
 function readEnvFile() {
     const out = {};
     try {
@@ -29,9 +30,10 @@ function readEnvFile() {
             }
     }
     catch (e) {
+        envUnreadable = true;
         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.`);
+            console.error(`⚠ could not read .env (${e?.code ?? e?.message ?? e}).`);
         }
     }
     return out;
@@ -58,10 +60,20 @@ async function api(path, init = {}, bearer) {
         err(`· decidio → ${API}${process.env.DECIDIO_API_URL ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
     }
     const auth = bearer ?? TOKEN();
-    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.`);
+    if (auth && envUnreadable && !process.env.DECIDIO_API_URL) {
+        err(`✘ .env exists here but could not be read, so the target Decidio is unknown — refusing to send credentials to a guessed host (${API}).`);
+        err(`  Fix the file's permissions, or set DECIDIO_API_URL explicitly for this command. 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 {
         res = await fetch(API + path, { ...init, headers: { "content-type": "application/json", ...(auth ? { authorization: `Bearer ${auth}` } : {}), ...(init.headers ?? {}) } });
@@ -137,6 +149,28 @@ function upsertEnv(updates) {
         lines.push(`${k}=${v}`);
     writeSecretFile(ENV_PATH, lines.join("\n") + "\n");
 }
+function isTrackedByGit(path) {
+    try {
+        execFileSync("git", ["ls-files", "--error-unmatch", path], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function assertNotTracked(path) {
+    if (!isTrackedByGit(path))
+        return true;
+    err(`✘ ${path} is ALREADY TRACKED by git — refusing to write the agent's private key into it.`);
+    err(`  A .gitignore entry does not untrack a file: the next \`git add -A\` would commit`);
+    err(`  DECIDIO_AGENT_KEY and DECIDIO_API_TOKEN into permanent history. Nothing was written.`);
+    err(`  Fix it, then re-run:`);
+    err(`    git rm --cached ${path}        # stop tracking it (keeps your local copy)`);
+    err(`    git commit -m "stop tracking ${path}"`);
+    err(`  If it has ALREADY been committed with secrets in it, rotate them — history rewriting`);
+    err(`  alone does not un-leak a key that was pushed.`);
+    return false;
+}
 function ensureGitignore() {
     const entries = [".env", ".env.quickstart", ".env.*.bak", ".decidio-pending/"];
     const existing = existsSync(".gitignore") ? readFileSync(".gitignore", "utf8") : "";
@@ -144,7 +178,7 @@ function ensureGitignore() {
     if (!missing.length)
         return;
     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)`);
+    log(`✔ added ${missing.join(" + ")} to .gitignore (new secret files here will not be committed)`);
 }
 function ask(question, mute = false) {
     return new Promise((resolve) => {
@@ -160,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;
@@ -204,6 +241,8 @@ async function acquireSession(purpose) {
     return null;
 }
 async function cmdInit(agentId, opts = {}) {
+    if (!assertNotTracked(ENV_PATH))
+        return 1;
     err(`Registering agent "${agentId}" with Decidio at ${API}…`);
     const existingEnv = readEnvFile();
     const existingKey = existingEnv.DECIDIO_AGENT_KEY;
@@ -342,8 +381,20 @@ async function cmdDoctor() {
     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)");
     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).");
+    if (signing) {
+        const storedDid = (process.env.DECIDIO_AGENT_DID || env.DECIDIO_AGENT_DID);
+        let derived;
+        try {
+            derived = didFromPrivateKey((process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY));
+        }
+        catch { }
+        if (!derived)
+            line(false, "signing key: PRESENT BUT UNREADABLE — DECIDIO_AGENT_KEY is not a valid Ed25519 private key. Re-run `npx @decidio/sdk init` (its public half is what Decidio registered).");
+        else if (derived !== storedDid)
+            line(false, `signing key: DOES NOT MATCH this agent's DID — the key here derives ${derived}, but .env registers ${storedDid}. Signed requests will not be recognised as this agent (auto-approve and application_confirmed evidence will both fail). Restore the original key, or re-run \`npx @decidio/sdk init\` to register a fresh one.`);
+        else
+            log("✔ signing key: set and MATCHES the registered DID — 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
         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.");
     const h = await api("/api/health", {}, "");
@@ -361,12 +412,13 @@ async function cmdDoctor() {
                 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 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: valid for another ${days} days`);
+                    log(`✔ agent token: unexpired for another ${daysRounded} days (validity is decided by the server — see the token-scope check below)`);
             }
         }
         catch { }
@@ -396,6 +448,11 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
         sub = undefined;
     if ((sub === "approve" || sub === "reject") && !id) {
         err(`usage: npx @decidio/sdk approvals ${sub} <decisionId> [reason]`);
+        err(`       npx @decidio/sdk approvals ${sub} <decisionId> --reason "text with -dashes"`);
+        return 2;
+    }
+    if ((sub === "approve" || sub === "reject") && (flags.json || flags.mine)) {
+        err(`✘ ${flags.json ? "--json" : "--mine"} applies to \`approvals\` (the list), not to ${sub} — refusing to ignore a flag you meant to matter.`);
         return 2;
     }
     if (mineOnly && !process.env.DECIDIO_AGENT_ID) {
@@ -422,8 +479,18 @@ async function cmdApprovals(sub, id, reason, flags = {}) {
                 return 1;
             }
             log(`✔ ${sub === "approve" ? "approved" : "rejected"} ${id}${r.body?.resumeSignal ? ` — agent signalled (${r.body.resumeSignal.ok ? "ok" : r.body.resumeSignal.error})` : ""}`);
-            if (sub === "approve")
-                log(`  The agent's function runs next — a blocking call resumes now; a durable one when its worker or resume route picks this up.`);
+            if (reason) {
+                log(`  reason sent verbatim: ${JSON.stringify(reason)}`);
+                log(`  (it seals immutably; personal or sensitive values are tokenized at rest, so the`);
+                log(`   stored text can differ — see exactly what was kept: npx @decidio/sdk receipt ${id})`);
+            }
+            if (sub === "approve") {
+                log(`  What happens next depends on how the agent is waiting:`);
+                log(`    • durable (the production mode): its worker or resume route picks this up and executes.`);
+                log(`    • blocking, still running: it resumes now.`);
+                log(`    • blocking, already timed out or exited: NOTHING executes — that process is gone, and this`);
+                log(`      approval resolved the RECORD only. Re-run the action to request again.`);
+            }
             else
                 log(`  The agent's action will NOT run; the rejection seals as a verifiable record.`);
             log(`  Download the receipt: npx @decidio/sdk receipt ${id}`);
@@ -517,11 +584,13 @@ 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)" : ""}.`);
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
-    log(`    npx @decidio/sdk verify ${name}`);
     if (issuer) {
-        log(`  Your workspace's issuer DID (from the authenticated response — record it once, then pin it forever):`);
-        log(`    ${issuer}`);
         log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
+        log(`  That pins the check to your workspace's issuer DID (read from the authenticated`);
+        log(`  response above — record it once, then pin it forever):`);
+        log(`    ${issuer}`);
+        log(`  Without --issuer the verifier proves the receipt is internally consistent, but NOT who`);
+        log(`  issued it; it says so in its output.`);
     }
     else {
         log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
@@ -536,8 +605,8 @@ function cmdVerify(argsIn) {
         const a = argsIn[i];
         if (a === "--issuer") {
             const v = argsIn[i + 1];
-            if (v === undefined || v.startsWith("-")) {
-                err("✘ --issuer needs a did:key value.");
+            if (v === undefined || v === "" || v.startsWith("-")) {
+                err("✘ --issuer needs a did:key value (a bare or EMPTY --issuer must not silently verify unpinned).");
                 return 2;
             }
             expectedIssuer = v;
@@ -587,12 +656,27 @@ 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)…`);
+    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);
@@ -609,6 +693,8 @@ async function cmdQuickstart(opts = {}) {
     let envFile = ENV_PATH;
     if (readEnvFile().DECIDIO_AGENT_KEY) {
         envFile = ".env.quickstart";
+        if (!assertNotTracked(envFile))
+            return 1;
         ensureGitignore();
         if (existsSync(envFile)) {
             const prev = readFileSync(envFile, "utf8");
@@ -623,6 +709,8 @@ async function cmdQuickstart(opts = {}) {
         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);
     }
@@ -685,7 +773,10 @@ 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.)");
+        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)) {
@@ -713,7 +804,13 @@ async function cmdQuickstart(opts = {}) {
     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);
@@ -762,11 +859,20 @@ async function quickstartCleanup(session, envFile) {
             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`);
+        else {
+            err(`✘ token revoke returned ${rev.status} — the tour's token is STILL LIVE (it would expire on its own within 7 days).`);
+            err(`  Nothing was deleted: ${envFile} still holds the jti so you can retry. Run \`npx @decidio/sdk quickstart cleanup\` again, or revoke it directly:`);
+            err(`    npx @decidio/sdk tokens revoke ${env.DECIDIO_TOKEN_JTI}`);
+            return 1;
+        }
     }
     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"]);
@@ -916,6 +1022,12 @@ 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, 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)
   npx @decidio/sdk verify [--issuer <did>] <receipt.json> [more...]   verify receipts OFFLINE
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
@@ -924,7 +1036,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
@@ -949,7 +1063,7 @@ async function main(argv) {
         quickstart: { flags: ["--auto-approve-demo", "--keep-agent"] },
         init: { flags: ["--unique", "--force"], valued: ["--expires-days"] },
         doctor: { flags: [] },
-        approvals: { flags: ["--json", "--mine"] },
+        approvals: { flags: ["--json", "--mine"], valued: ["--reason"] },
         receipt: { flags: ["--json"] },
         verify: { flags: [], valued: ["--issuer"] },
         tokens: { flags: ["--mine"] },
@@ -961,6 +1075,17 @@ async function main(argv) {
         const positionals = [];
         for (let i = 0; i < argsIn.length; i++) {
             const a = argsIn[i];
+            if (a === "--") {
+                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;
@@ -1028,8 +1153,35 @@ async function main(argv) {
         }
         case "doctor": return cmdDoctor();
         case "approvals": {
-            const positional = argsIn.filter((x) => !x.startsWith("-"));
-            return cmdApprovals(positional[0], positional[1], positional.slice(2).join(" ") || undefined, { json: argsIn.includes("--json"), mine: argsIn.includes("--mine") });
+            const dashdash = argsIn.indexOf("--");
+            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) {
+                const after = head.indexOf(id) + 1;
+                const rest = head.slice(after).filter((x) => x !== "--json" && x !== "--mine");
+                reason = rest.length ? rest.join(" ") : undefined;
+            }
+            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"));
         case "verify": return cmdVerify(argsIn);

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/** 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;
+    body?: unknown | undefined;
+    readonly retryable: boolean;
+    constructor(status: number, endpoint: string, body?: unknown | undefined);
+}

package/dist/errors.js

@@ -0,0 +1,18 @@
+export class DecidioHttpError extends Error {
+    status;
+    endpoint;
+    body;
+    retryable;
+    constructor(status, endpoint, body) {
+        const terminal = status === 401 || status === 403;
+        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.`));
+        this.status = status;
+        this.endpoint = endpoint;
+        this.body = body;
+        this.name = "DecidioHttpError";
+        this.retryable = !terminal;
+    }
+}

package/dist/evidence.d.ts

@@ -0,0 +1,45 @@
+/** Every tier the gate can record, weakest to strongest. Mirrors the server's enum exactly; an
+ *  answer outside this list means this SDK version does not understand the record, and an answer
+ *  we do not understand is never treated as evidence. */
+export declare const EVIDENCE_TIERS: readonly ["pending", "execution_unconfirmed", "agent_asserted", "sensor_observed", "application_confirmed", "independently_reconciled"];
+export type EvidenceTier = (typeof EVIDENCE_TIERS)[number];
+export interface EvidenceOutcome {
+    /** Decidio accepted the report and named the tier it recorded. */
+    reportRecorded: boolean;
+    /** The tier Decidio recorded, verbatim. */
+    evidenceTier?: EvidenceTier;
+    /** The recorded tier attests a committed execution. */
+    executionConfirmed: boolean;
+    /** 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;
+}
+/** 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
+ *  (`id` / `recordId` / `Id`), and must not explicitly deny success (`success: false` /
+ *  `ok: false`). An id with no success field is treated as a commit; a response with neither is
+ *  honestly `execution_unconfirmed`. */
+export declare function describeTierGap(capturedResponse: unknown): string;
+/** Read the gate's confirm response and say precisely what happened. Fail-closed: an unknown or
+ *  missing tier is NOT a recorded report. */
+export declare function readConfirmResponse(body: unknown, opts: {
+    signed: boolean;
+    capturedResponse?: unknown;
+    journalled?: boolean;
+}): EvidenceOutcome;
+import { type RequesterIdentity } from "./signing.js";
+/** Minimal identity a confirm body needs. */
+export interface ReportIdentity {
+    agentId: string;
+    agentKey?: string;
+    agentDid?: string;
+    workspaceId?: string;
+}
+/** The ONE confirm request shape, shared by every door (inline, durable resume, adapters).
+ *  Carries the identity proof (who is reporting) AND — when a key is configured — a signed,
+ *  decision-bound ExecutionReport over the canonical response digest (what was reported). */
+export declare function buildConfirmBody(cfg: ReportIdentity, decisionId: string, canonicalResult: unknown, requesterIdentity?: RequesterIdentity, source?: string): Record<string, unknown>;

package/dist/evidence.js

@@ -0,0 +1,65 @@
+export const EVIDENCE_TIERS = [
+    "pending",
+    "execution_unconfirmed",
+    "agent_asserted",
+    "sensor_observed",
+    "application_confirmed",
+    "independently_reconciled",
+];
+const CONFIRMING = ["sensor_observed", "application_confirmed", "independently_reconciled"];
+export function describeTierGap(capturedResponse) {
+    const r = (capturedResponse ?? {});
+    const id = r.id ?? r.recordId ?? r.Id ?? null;
+    const denied = r.success === false || r.ok === false;
+    if (denied) {
+        return "your protected function reported success: false (or ok: false), so Decidio recorded the execution as UNCONFIRMED — that is the response saying the downstream write did not commit. If it did commit, return a truthy success flag.";
+    }
+    if (id == null) {
+        return "your protected function's return value carried no record id (`id`, `recordId` or `Id`), so Decidio has no evidence that the downstream write committed and honestly recorded the execution as UNCONFIRMED. Return the source system's identifiers (e.g. `{ id, success }` or `{ recordId, ok }`), or map them with the `evidence` option, to earn application_confirmed.";
+    }
+    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
+        ? "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}` };
+    }
+    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}` };
+    }
+    const executionConfirmed = CONFIRMING.includes(tier);
+    const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed };
+    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 (!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";
+export function buildConfirmBody(cfg, decisionId, canonicalResult, requesterIdentity, source = "wrapper") {
+    const executionReport = (cfg.agentKey && cfg.agentDid)
+        ? signExecutionReport(cfg.agentKey, {
+            decisionId, agentId: cfg.agentId, did: cfg.agentDid, workspaceId: cfg.workspaceId,
+            source, resultDigest: resultDigest(canonicalResult ?? null),
+        })
+        : undefined;
+    return {
+        decisionId,
+        capturedResponse: canonicalResult ?? null,
+        source,
+        ...(requesterIdentity ? { requesterIdentity } : {}),
+        ...(executionReport ? { executionReport } : {}),
+    };
+}

package/dist/guard.d.ts

@@ -21,7 +21,12 @@ export interface GuardFacadeConfig {
 }
 export interface ProtectOptions {
     /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest)
-     *  live in @decidio/sdk subpaths and take the engine handle. */
+     *  live in @decidio/sdk subpaths and take the engine handle.
+     *
+     *  BETA: the engine adapters share the core's gate semantics (verdict allow-list, canonical
+     *  arguments, transport rule and evidence handling are one implementation, conformance-tested
+     *  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";
     /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
@@ -37,16 +42,30 @@ export interface ProtectOptions {
     pollTimeoutMs?: number;
     /** Blocking-mode poll interval in ms (default 3000). */
     pollIntervalMs?: number;
+    /** Map YOUR function's natural return value to the evidence Decidio records. The gate awards
+     *  its strongest wrapper tier (application_confirmed) only for a committed record id plus a
+     *  success indication, so instead of forcing your API into magic field names:
+     *  `evidence: (r) => ({ recordId: r.transactionId, success: r.status === "committed" })`. */
+    evidence?: (result: any) => unknown;
 }
 export declare class Guard {
     config: GuardFacadeConfig;
-    resume?: ResumeController;
+    private _resume?;
     constructor(config: GuardFacadeConfig, resume?: ResumeController);
+    /** The recovery surface — `guard.resume.recover()` / `.reconfirm(id)`. BUILT ON FIRST ACCESS,
+     *  because the process that needs to recover is usually a COLD one that never made the original
+     *  call, so nothing has lazily constructed the controller yet. As a plain field this read was
+     *  `undefined` there and the documented recovery loop crashed on the exact path it exists for.
+     *  Unconfigured still fails loud (naming DECIDIO_API_URL), never silently. */
+    get resume(): ResumeController;
+    /** Kept writable: hosts that construct their own controller (custom store, injected fetch)
+     *  assign it here, and `new Guard(cfg, controller)` must stay equivalent to that assignment. */
+    set resume(r: ResumeController);
     static fromEnv(): 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)`. */