@decidio/sdk 0.3.0 → 0.3.5

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync, openSync, writeSync, fsyncSync, closeSync, renameSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { execFileSync } from "node:child_process";
@@ -38,7 +38,10 @@ function readEnvFile() {
     }
     return out;
 }
-const OFFLINE_CMD = ["verify", "--version", "-v", "-V", "version", "--help", "-h", "help", undefined].includes(process.argv[2]);
+const wantsHelp = (s) => s === "help" || s === "--help" || s === "-h";
+const ARGV_TAIL = process.argv.slice(2);
+const OFFLINE_CMD = ["verify", "--version", "-v", "-V", "version", undefined].includes(ARGV_TAIL[0])
+    || wantsHelp(ARGV_TAIL[0]) || wantsHelp(ARGV_TAIL[1]);
 if (!OFFLINE_CMD) {
     readEnvFile();
     if (envUnreadable) {
@@ -109,7 +112,30 @@ async function api(path, init = {}, bearer) {
     return { status: res.status, body };
 }
 function writeSecretFile(path, body) {
-    writeFileSync(path, body, { mode: 0o600 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    const fd = openSync(tmp, "w", 0o600);
+    try {
+        writeSync(fd, body);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        chmodSync(tmp, 0o600);
+    }
+    catch { }
+    hardenFile(tmp);
+    try {
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch { }
+        throw e;
+    }
     try {
         chmodSync(path, 0o600);
     }
@@ -119,6 +145,83 @@ function writeSecretFile(path, body) {
         console.warn(`⚠ could not restrict ${path} to owner-only on this Windows volume (${why}) — it keeps the directory's inherited permissions. For production, move these values to a secret manager.`);
     }
 }
+async function revokeFreshMint(jti, bearer, writeError, target) {
+    err(`✘ could not write ${target} (${writeError?.message ?? writeError}). The token minted a moment ago (jti ${jti}) is LIVE until revoked - revoking it now.`);
+    const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, bearer);
+    if (rv.status >= 200 && rv.status < 300) {
+        journalRetire(jti, "revoked");
+        err(`  ✔ the token minted a moment ago (jti ${jti}) was REVOKED again, so nothing live was left behind. Fix the cause above and re-run - it will mint a fresh one.`);
+        return true;
+    }
+    let known = false;
+    try {
+        known = journalOutstanding().some((j) => j.jti === jti);
+    }
+    catch { }
+    if (known)
+        err(`  Its id is kept in ${JOURNAL_PATH} (owner-only, append-only) until it is revoked - \`quickstart cleanup\` retries it, and \`doctor\` names it.`);
+    else
+        err(`  Its id is NOT recorded anywhere but this terminal (the journal write is what failed) - write it down now and revoke it by hand.`);
+    err(`  ⚠ the token minted a moment ago (jti ${jti}) is LIVE and could NOT be revoked (${rv.status}). Revoke it by hand, or re-run init - the server keeps one active token per agent, so a fresh mint supersedes it:`);
+    err(`    npx @decidio/sdk tokens revoke ${jti}`);
+    err(`    npx @decidio/sdk tokens list --mine`);
+    return false;
+}
+const JOURNAL_PATH = ".decidio-token-journal";
+function journalAppend(entry) {
+    const fresh = !existsSync(JOURNAL_PATH);
+    const fd = openSync(JOURNAL_PATH, "a", 0o600);
+    try {
+        writeSync(fd, JSON.stringify({ ...entry, at: new Date().toISOString() }) + "\n");
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (fresh) {
+        try {
+            chmodSync(JOURNAL_PATH, 0o600);
+        }
+        catch { }
+        hardenFile(JOURNAL_PATH);
+    }
+}
+function journalProbe() {
+    try {
+        journalAppend({ event: "probe" });
+        return null;
+    }
+    catch (e) {
+        return String(e?.message ?? e);
+    }
+}
+function journalMinted(jti, agentId, label) { journalAppend({ event: "minted", jti, agentId, label, apiUrl: API }); }
+function journalRetire(jti, how) { try {
+    journalAppend({ event: "retired", jti, how });
+}
+catch { } }
+function journalOutstanding() {
+    if (!existsSync(JOURNAL_PATH))
+        return [];
+    const minted = new Map();
+    for (const line of readFileSync(JOURNAL_PATH, "utf8").split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (e?.event === "minted" && typeof e.jti === "string")
+            minted.set(e.jti, { jti: e.jti, agentId: e.agentId, label: e.label, apiUrl: e.apiUrl, at: e.at });
+        if (e?.event === "retired" && typeof e.jti === "string")
+            minted.delete(e.jti);
+    }
+    return [...minted.values()];
+}
+const REFUSE_MINT_NO_JOURNAL = (why) => `✘ could not write the token recovery journal (${JOURNAL_PATH}: ${why}) - refusing to mint a credential this directory cannot record a revocation handle for. Fix the directory's permissions or free space and re-run. Nothing was minted.`;
 function upsertEnv(updates) {
     const remaining = { ...updates };
     const updatedKeys = new Set();
@@ -168,7 +271,7 @@ function assertNotTracked(path) {
     return false;
 }
 function ensureGitignore() {
-    const entries = [".env", ".env.quickstart", ".env.*.bak", ".decidio-pending/"];
+    const entries = [".env", ".env.quickstart", ".env.*.bak", ".env.*.tmp", ".decidio-pending/", ".decidio-token-journal"];
     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(/\/$/, "")));
     if (!missing.length)
@@ -307,16 +410,33 @@ async function cmdInit(agentId, opts = {}) {
     let agentToken, workspaceId, tokenJti;
     const mintBearer = session ?? TOKEN();
     if (mintBearer) {
+        ensureGitignore();
+        const noJournal = journalProbe();
+        if (noJournal) {
+            err(REFUSE_MINT_NO_JOURNAL(noJournal));
+            return 1;
+        }
         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) {
             agentToken = mint.body.token;
             workspaceId = mint.body.workspaceId;
             tokenJti = mint.body.jti;
+            if (tokenJti) {
+                try {
+                    journalMinted(tokenJti, agentId, "sdk-cli");
+                }
+                catch (e) {
+                    await revokeFreshMint(tokenJti, mintBearer, e, JOURNAL_PATH);
+                    return 1;
+                }
+            }
             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)`}`);
             const superseded = Array.isArray(mint.body.supersededJtis) ? mint.body.supersededJtis : [];
-            for (const s of superseded)
+            for (const s of superseded) {
+                journalRetire(s, "revoked");
                 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)}`);
@@ -341,8 +461,21 @@ async function cmdInit(agentId, opts = {}) {
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     if (tokenJti)
         envOut.DECIDIO_TOKEN_JTI = tokenJti;
-    prepareEnvForWrite();
-    upsertEnv(envOut);
+    try {
+        prepareEnvForWrite();
+        upsertEnv(envOut);
+        if (tokenJti)
+            journalRetire(tokenJti, "persisted");
+    }
+    catch (e) {
+        if (agentToken && tokenJti)
+            await revokeFreshMint(tokenJti, mintBearer, e, ENV_PATH);
+        else if (agentToken)
+            err(`✘ could not write ${ENV_PATH} (${e?.message ?? e}). The token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+        else
+            err(`✘ could not write ${ENV_PATH} (${e?.message ?? e}). No token was minted this run.`);
+        return 1;
+    }
     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)`);
@@ -381,6 +514,17 @@ async function cmdDoctor() {
     let warned = 0;
     const line = (good, label) => { log(`${good ? "✔" : "✘"} ${label}`); ok = ok && good; };
     const warn = (label) => { warned++; log(`⚠ ${label}`); };
+    let journalRows = [];
+    try {
+        journalRows = journalOutstanding();
+    }
+    catch (e) {
+        warn(`token recovery journal (${JOURNAL_PATH}) could not be read (${e?.message ?? e}) — it may hold live token ids; fix its permissions and re-run doctor.`);
+    }
+    for (const j of journalRows) {
+        const where = j.apiUrl && j.apiUrl !== API ? `DECIDIO_API_URL=${j.apiUrl} ` : "";
+        warn(`token recovery journal: jti ${j.jti} (${j.label ?? "token"}, agent ${j.agentId ?? "?"}, minted ${j.at ?? "?"} against ${j.apiUrl ?? API}) has no recorded revocation in this directory's journal — it may still be live. Revoke it, or confirm it is gone: ${where}npx @decidio/sdk quickstart cleanup   (or: ${where}npx @decidio/sdk tokens revoke ${j.jti})`);
+    }
     log(`✔ API URL: ${API}${(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL) ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
     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>)"}`);
     const secret = process.env.DECIDIO_WEBHOOK_SECRET || env.DECIDIO_WEBHOOK_SECRET;
@@ -399,7 +543,7 @@ async function cmdDoctor() {
         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).");
+            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 (routing-by-default - a block is different: a named rule, or the universal backstop when no active policy governs agents at all).");
     }
     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.");
@@ -597,10 +741,13 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     if (issuer) {
+        log(`  Record your workspace's issuer DID — copy this line, and pin it forever:`);
+        log(``);
+        log(`${issuer}`);
+        log(``);
+        log(`  Then verify, pinned to it (the same DID, inline — copy from the line above, not this one,`);
+        log(`  which your terminal may wrap):`);
         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.`);
     }
@@ -621,6 +768,10 @@ function cmdVerify(argsIn) {
                 err("✘ --issuer needs a did:key value (a bare or EMPTY --issuer must not silently verify unpinned).");
                 return 2;
             }
+            if (expectedIssuer !== undefined && expectedIssuer !== v) {
+                err(`✘ --issuer given twice with different values (${expectedIssuer} then ${v}) — refusing to choose which one you meant to pin to.`);
+                return 2;
+            }
             expectedIssuer = v;
             i++;
         }
@@ -630,6 +781,10 @@ function cmdVerify(argsIn) {
                 err("✘ --issuer needs a did:key value.");
                 return 2;
             }
+            if (expectedIssuer !== undefined && expectedIssuer !== v) {
+                err(`✘ --issuer given twice with different values (${expectedIssuer} then ${v}) — refusing to choose which one you meant to pin to.`);
+                return 2;
+            }
             expectedIssuer = v;
         }
         else if (!a.startsWith("-")) {
@@ -695,11 +850,35 @@ async function cmdQuickstart(opts = {}) {
         err(`  Nothing was written to this directory.`);
         return 1;
     }
+    let prevTourFile = null;
+    if (envFile !== ENV_PATH && existsSync(envFile)) {
+        try {
+            prevTourFile = readFileSync(envFile, "utf8");
+        }
+        catch (e) {
+            err(`✘ ${envFile} exists but could not be read (${e?.message ?? e}) - a previous tour's credentials may be in it, and this tour would have to replace it. Refusing to mint a new token on top of a file this command cannot read: fix its permissions or move it aside, then re-run. Nothing was minted.`);
+            return 1;
+        }
+    }
+    const noJournal = journalProbe();
+    if (noJournal) {
+        err(REFUSE_MINT_NO_JOURNAL(noJournal));
+        return 1;
+    }
     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;
     }
+    if (mint.body.jti) {
+        try {
+            journalMinted(mint.body.jti, agentId, "quickstart");
+        }
+        catch (e) {
+            await revokeFreshMint(mint.body.jti, session, e, JOURNAL_PATH);
+            return 1;
+        }
+    }
     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,
@@ -707,18 +886,18 @@ async function cmdQuickstart(opts = {}) {
         ...(mint.body.jti ? { DECIDIO_TOKEN_JTI: mint.body.jti } : {}),
     };
     if (envFile !== ENV_PATH) {
-        if (existsSync(envFile)) {
-            const prev = readFileSync(envFile, "utf8");
+        if (prevTourFile !== null) {
+            const prev = prevTourFile;
             const prevId = prev.match(/^DECIDIO_AGENT_ID=(.+)$/m)?.[1];
             const prevJti = prev.match(/^DECIDIO_TOKEN_JTI=(.+)$/m)?.[1];
+            const carried = new Set((prev.match(/^DECIDIO_ORPHANED_TOKEN_JTI=(.+)$/m)?.[1] ?? "").split(",").map((s) => s.trim()).filter(Boolean));
             if (prevId && prevId !== agentId) {
                 if (prevJti) {
                     const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(prevJti)}`, { method: "DELETE" }, session);
                     if (rv.status >= 200 && rv.status < 300)
                         log(`  ✔ the previous tour agent (${prevId}) had its token REVOKED before this tour replaced it — no live credential is left behind`);
                     else {
-                        const carried = [...(prev.match(/^DECIDIO_ORPHANED_TOKEN_JTI=(.+)$/m)?.[1] ?? "").split(",").filter(Boolean), prevJti];
-                        envOut.DECIDIO_ORPHANED_TOKEN_JTI = [...new Set(carried)].join(",");
+                        carried.add(prevJti);
                         log(`  ⚠ could not revoke the previous tour's token (jti ${prevJti}, ${rv.status}) — it is still LIVE. Its id is kept in ${envFile} as DECIDIO_ORPHANED_TOKEN_JTI, and \`quickstart cleanup\` will retry it; or revoke it by hand: npx @decidio/sdk tokens revoke ${prevJti}`);
                     }
                 }
@@ -726,12 +905,38 @@ async function cmdQuickstart(opts = {}) {
                     log(`  ⚠ the previous tour file carried no revocation id, so its token (if any) must be revoked from your Decidio app.`);
                 }
             }
+            if (carried.size) {
+                envOut.DECIDIO_ORPHANED_TOKEN_JTI = [...carried].join(",");
+                log(`  • ${carried.size} orphaned token id(s) from earlier replacements carried forward — \`quickstart cleanup\` will retry them.`);
+            }
+        }
+        try {
+            writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
+            if (mint.body.jti)
+                journalRetire(mint.body.jti, "persisted");
+        }
+        catch (e) {
+            if (mint.body?.jti)
+                await revokeFreshMint(mint.body.jti, session, e, envFile);
+            else
+                err(`✘ could not write ${envFile} (${e?.message ?? e}). The tour token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+            return 1;
         }
-        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 {
-        upsertEnv(envOut);
+        try {
+            upsertEnv(envOut);
+            if (mint.body.jti)
+                journalRetire(mint.body.jti, "persisted");
+        }
+        catch (e) {
+            if (mint.body?.jti)
+                await revokeFreshMint(mint.body.jti, session, e, envFile);
+            else
+                err(`✘ could not write ${envFile} (${e?.message ?? e}). The tour token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+            return 1;
+        }
     }
     const failTour = async (code) => {
         log("");
@@ -776,7 +981,9 @@ async function cmdQuickstart(opts = {}) {
         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.`);
+    log(`    so the policy ROUTES it to a person (routing-by-default). That is distinct from a BLOCK, which no human can`);
+    log(`    override: a block is a named rule, or the universal backstop when no active policy governs agents at all.`);
+    log(`    Nothing executes until someone decides.`);
     log("");
     const interactive = process.stdin.isTTY;
     if (interactive) {
@@ -857,7 +1064,10 @@ async function cmdQuickstart(opts = {}) {
     log(`  const doIt = guard.protect(doItRaw, (a) => ({ action: "yourAction", amount: a.amount, scope: "YourScope" }));`);
     log(`  // production is DURABLE mode (default) + one worker: guard.worker();  // README has the full pattern`);
     log("");
-    log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}  ·  Next: the README's 7-step quickstart (durable, workers, adapters).`);
+    log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}`);
+    log(`Next: the README section "Production mode: durable async resume" (the worker; the engine adapters follow it).`);
+    log(`The README's seven-step quickstart is this same blocking flow in your own code - if you keep this agent, its .env`);
+    log(`already works here, so skip that flow's init step.`);
     log(`Built by OmniTwin — decidioai.com  ·  Putting this in front of real approvals? decidioai.com/#early-access`);
     let doCleanup = false;
     if (interactive) {
@@ -876,14 +1086,47 @@ async function cmdQuickstart(opts = {}) {
 async function quickstartCleanup(session, envFile) {
     const env = (() => {
         const out = {};
-        if (existsSync(envFile))
-            for (const line of readFileSync(envFile, "utf8").split(/\r?\n/)) {
-                const m = line.match(/^\s*([A-Z_]+)=(.*)$/);
-                if (m)
-                    out[m[1]] = m[2];
-            }
+        try {
+            if (existsSync(envFile))
+                for (const line of readFileSync(envFile, "utf8").split(/\r?\n/)) {
+                    const m = line.match(/^\s*([A-Z_]+)=(.*)$/);
+                    if (m)
+                        out[m[1]] = m[2];
+                }
+        }
+        catch (e) {
+            err(`  ⚠ ${envFile} could not be read (${e?.message ?? e}) - sweeping the token recovery journal instead.`);
+        }
         return out;
     })();
+    let journalRevoked = 0;
+    const journalStuck = [];
+    for (const j of journalOutstanding()) {
+        if (j.apiUrl && j.apiUrl !== API) {
+            journalStuck.push(j.jti);
+            err(`  ⚠ journalled token ${j.jti} was minted against ${j.apiUrl}, not ${API} — revoke it there: DECIDIO_API_URL=${j.apiUrl} npx @decidio/sdk tokens revoke ${j.jti}`);
+            continue;
+        }
+        const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(j.jti)}`, { method: "DELETE" }, session);
+        if (rv.status >= 200 && rv.status < 300) {
+            journalRetire(j.jti, "revoked");
+            journalRevoked++;
+            if (rv.body?.changed === false)
+                log(`  • journalled token ${j.jti} was already revoked — retiring its journal entry.`);
+            else
+                log(`  ✔ journalled token revoked (jti ${j.jti}${j.label ? `, ${j.label}` : ""}) — its credential file never landed, so this was its only handle`);
+        }
+        else {
+            journalStuck.push(j.jti);
+            err(`  ⚠ journalled token ${j.jti} could NOT be revoked (${rv.status}) — it is still live; its id stays in ${JOURNAL_PATH}.`);
+        }
+    }
+    if (journalStuck.length) {
+        err(`✘ ${journalStuck.length} journalled token(s) are STILL LIVE and could not be revoked. Nothing was deleted; retry, or revoke by hand:`);
+        for (const jti of journalStuck)
+            err(`    npx @decidio/sdk tokens revoke ${jti}`);
+        return 1;
+    }
     const orphans = (env.DECIDIO_ORPHANED_TOKEN_JTI ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     const stillOrphaned = [];
     for (const jti of orphans) {
@@ -914,6 +1157,9 @@ async function quickstartCleanup(session, envFile) {
             return 1;
         }
     }
+    else if (journalRevoked > 0 && !existsSync(envFile) || (journalRevoked > 0 && Object.keys(env).length === 0)) {
+        log(`  • no credential file to clean: the journal sweep revoked ${journalRevoked} token(s) this directory owed.`);
+    }
     else {
         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:`);
@@ -922,9 +1168,18 @@ async function quickstartCleanup(session, envFile) {
         err(`  (it also expires on its own within 7 days)`);
         return 1;
     }
+    let envRaw = null;
     if (existsSync(envFile)) {
+        try {
+            envRaw = readFileSync(envFile, "utf8");
+        }
+        catch (e) {
+            err(`  ⚠ ${envFile} could not be read (${e?.message ?? e}) — left as it is; remove it by hand once it is readable.`);
+        }
+    }
+    if (envRaw !== null) {
         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", "DECIDIO_ORPHANED_TOKEN_JTI"]);
-        const kept = readFileSync(envFile, "utf8").split(/\r?\n/).filter((line) => {
+        const kept = envRaw.split(/\r?\n/).filter((line) => {
             const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)=/);
             return m ? !TOUR_KEYS.has(m[1]) : line.trim() !== "";
         });
@@ -948,6 +1203,12 @@ async function quickstartCleanup(session, envFile) {
     }
     log(`  • What remains, by design: the sealed decision record (records are permanent — that is the product)`);
     log(`    and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap).`);
+    if (existsSync(".decidio-pending")) {
+        log(`  • Also kept: .decidio-pending/ — this agent's own execution ledger: whatever this agent parked (call arguments,`);
+        log(`    execution evidence; never credentials, by design). Gitignored; owner-only where the OS supports it. If nothing is`);
+        log(`    pending and you do not want the history, remove it:`);
+        log(`      ${process.platform === "win32" ? "Remove-Item -Recurse .decidio-pending" : "rm -r .decidio-pending"}`);
+    }
     return 0;
 }
 async function cmdTokens(sub, jti, mineOnly = false) {
@@ -980,10 +1241,12 @@ async function cmdTokens(sub, jti, mineOnly = false) {
         const rev = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, bearer);
         if (rev.status >= 200 && rev.status < 300) {
             if (rev.body?.changed === false) {
+                journalRetire(jti, "revoked");
                 log(`• ${jti} was already revoked — nothing changed.`);
                 log(`  Revocation is permanent; there is no re-revoke. See it: npx @decidio/sdk tokens list`);
                 return 1;
             }
+            journalRetire(jti, "revoked");
             log(`✔ revoked ${jti} — the token is dead now (its agent stays registered; mint a new one with init).`);
             return 0;
         }
@@ -1095,7 +1358,6 @@ Docs: the README that shipped with this package — node_modules/@decidio/sdk/RE
 (quickstart, durable resume, workers, adapters).`;
 async function main(argv) {
     const [cmd, a, b, ...rest] = argv.slice(2);
-    const wantsHelp = (s) => s === "help" || s === "--help" || s === "-h";
     if (cmd === "--version" || cmd === "-v" || cmd === "-V" || cmd === "version") {
         log(VERSION);
         return 0;
@@ -1174,9 +1436,10 @@ async function main(argv) {
         case "quickstart": {
             if (argsIn.includes("cleanup")) {
                 const envFile = existsSync(".env.quickstart") ? ".env.quickstart"
-                    : (readEnvFile().DECIDIO_AGENT_ID ?? "").startsWith("quickstart-") ? ENV_PATH : undefined;
+                    : (readEnvFile().DECIDIO_AGENT_ID ?? "").startsWith("quickstart-") ? ENV_PATH
+                        : journalOutstanding().length ? ".env.quickstart" : undefined;
                 if (!envFile) {
-                    log("Nothing to clean up here: no .env.quickstart, and .env doesn't belong to a quickstart agent.");
+                    log("Nothing to clean up here: no .env.quickstart, .env doesn't belong to a quickstart agent, and the token recovery journal owes nothing.");
                     return 0;
                 }
                 const session = await acquireSession("Cleaning the quickstart up");

package/dist/errors.js

@@ -26,7 +26,11 @@ export class DecidioHttpError extends Error {
             (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).`
+                    ? (/\/agent\/confirm/.test(endpoint)
+                        ? ` — this looks transient. Your action ALREADY RAN; do NOT re-run it — only its report failed to land, and the door's own note says whether a report was kept to re-send.`
+                        : /\/agent\/status/.test(endpoint)
+                            ? ` — this looks transient; polling again is safe (a status read changes nothing).`
+                            : ` — 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, typeof body?.code === "string" ? body.code : undefined));
         this.status = status;

package/dist/evidence.d.ts

@@ -3,6 +3,15 @@
  *  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];
+/** Whether a recorded tier attests a COMMITTED execution - the same set the live reader uses, so a
+ *  tombstone that kept only the tier can still answer the question honestly (retest V030-07). */
+export declare function tierConfirms(tier: string | undefined | null): boolean;
+/** The tier a `reported` tombstone records. The server caps a confirming tier whose proof failed to
+ *  `execution_unconfirmed` (apps/api agent-confirm.ts, lint-locked CONFIRM-TRUTH), so a body that
+ *  says otherwise is one the current server cannot emit; the tombstone applies the same rule, so
+ *  reconfirm() - which derives from the tier - can never answer "confirmed" where resolve() answered
+ *  "not confirmed" over the same record (invariant-guard, 0.3.3). Every other tier is stored verbatim. */
+export declare function tombstoneTier(ev: EvidenceOutcome): string;
 export interface EvidenceOutcome {
     /** Decidio accepted the report and named the tier it recorded. */
     reportRecorded: boolean;

package/dist/evidence.js

@@ -7,6 +7,10 @@ export const EVIDENCE_TIERS = [
     "independently_reconciled",
 ];
 const CONFIRMING = ["sensor_observed", "application_confirmed", "independently_reconciled"];
+export function tierConfirms(tier) { return typeof tier === "string" && CONFIRMING.includes(tier); }
+export function tombstoneTier(ev) {
+    return ev.executionReportVerified === false && tierConfirms(ev.evidenceTier) ? "execution_unconfirmed" : (ev.evidenceTier ?? "recorded");
+}
 export function describeTierGap(capturedResponse) {
     const r = (capturedResponse ?? {});
     const id = r.id ?? r.recordId ?? r.Id ?? null;
@@ -47,7 +51,7 @@ export function readConfirmResponse(body, opts) {
             outcome.executionReportReason = rpt.reason;
         if (proofExplicitlyFailed) {
             const why = typeof rpt.reason === "string" && rpt.reason ? ` (${rpt.reason})` : "";
-            outcome.diagnostic = `the signed execution report did NOT verify${why}, so this is NOT a confirmed execution — the gate reported tier "${tier}", and this SDK refuses to read an unproven attestation as confirmation. Your action DID run; check the agent's key/DID/registration (npx @decidio/sdk doctor), then ${retry}`;
+            outcome.diagnostic = `the signed execution report did NOT verify${why}, so this is NOT a confirmed execution — the gate reported tier "${tier}", and this SDK refuses to read an unproven attestation as confirmation. Your action DID run and the report IS recorded at that tier - there is nothing to re-send, and re-sending would not change the verdict; the record stands as unverified. Check the agent's key/DID/registration (npx @decidio/sdk doctor) so the NEXT execution verifies.`;
         }
     }
     return outcome;

package/dist/index.d.ts

@@ -12,7 +12,10 @@ export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS
 export type { EvidenceOutcome, EvidenceTier } from "./evidence.js";
 export type { RequesterIdentity } from "./signing.js";
 export interface GuardConfig {
-    /** Base URL of the Decidio gate, e.g. "https://api.decidio.io". */
+    /** Base URL of the Decidio gate. The hosted sandbox is "https://decidio-api.onrender.com",
+     *  which is also the default when this is unset; a self-hosted deployment is your own origin.
+     *  (This example named a host the product does not use — it shipped in the .d.ts, so it was the
+     *  first URL a typing-aware editor suggested to anyone configuring the SDK.) */
     apiUrl: string;
     /** The agent identity registered with Decidio (onboarding wizard), e.g. "salesforce/SalesforceBot". */
     agentId: string;
@@ -100,6 +103,11 @@ export declare class DecidioNetworkError extends Error {
     code: string | undefined;
     constructor(endpoint: string, op: string, code: string | undefined, cause: unknown);
 }
+/** THE ONE DESCRIBE VALIDATION (prodsec V033-05). The core wrapper refused a blank `action` and a
+ *  negative / non-finite `amount` before routing; the adapter gate canonicalized and posted them, so
+ *  every engine door reached the mock authorization path with a request the core would have refused.
+ *  Exported so `adapters/_gate.ts` calls the same function rather than a second copy that can drift. */
+export declare function assertDescribed(ctx: ApprovalContext): void;
 /**
  * Wrap an async action behind the Decidio gate. `describe` extracts the approval
  * context (action, amount, scope) from the call arguments. Returns a function with

package/dist/index.js

@@ -78,6 +78,14 @@ async function reach(f, url, op, init) {
         throw new DecidioNetworkError(url, op, e?.cause?.code ?? e?.code, e);
     }
 }
+export function assertDescribed(ctx) {
+    if (typeof ctx?.action !== "string" || ctx.action.trim().length === 0) {
+        throw new Error(`[decidio] describe(...) must return an \`action\` string naming what is being asked (got ${JSON.stringify(ctx?.action ?? null)}). Nothing was routed or executed.`);
+    }
+    if (typeof ctx.amount !== "number" || !Number.isFinite(ctx.amount) || ctx.amount < 0) {
+        throw new Error(`[decidio] describe(...) must return a finite, non-negative \`amount\` — the policy decides on it, so a request without one is not a request Decidio can rule on (got ${JSON.stringify(ctx.amount ?? null)}). Use 0 for an action with no monetary value. Nothing was routed or executed.`);
+    }
+}
 async function post(cfg, path, body) {
     const f = cfg.fetchImpl ?? fetch;
     assertSafeTransport(cfg.apiUrl, carriesCredential(cfg));
@@ -138,16 +146,11 @@ export function withApproval(fn, describe, config, opts) {
             }
             throw e;
         }
+        ctx = canonicalize(ctx, "describe(...)");
         const requesterIdentity = (config.agentKey && config.agentDid)
             ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
             : undefined;
-        canonicalize(ctx, "describe(...)");
-        if (typeof ctx?.action !== "string" || ctx.action.trim().length === 0) {
-            throw new Error(`[decidio] describe(...) must return an \`action\` string naming what is being asked (got ${JSON.stringify(ctx?.action ?? null)}). Nothing was routed or executed.`);
-        }
-        if (typeof ctx.amount !== "number" || !Number.isFinite(ctx.amount) || ctx.amount < 0) {
-            throw new Error(`[decidio] describe(...) must return a finite, non-negative \`amount\` — the policy decides on it, so a request without one is not a request Decidio can rule on (got ${JSON.stringify(ctx.amount ?? null)}). Use 0 for an action with no monetary value. Nothing was routed or executed.`);
-        }
+        assertDescribed(ctx);
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,

package/dist/inngest.js

@@ -28,6 +28,8 @@ export async function decidioGateStep(args) {
 export function createInngestResumeBridge(opts) {
     const secret = opts.webhookSecret ?? "";
     const eventName = opts.eventName ?? DECIDIO_RESUME_EVENT;
+    if (!secret && opts.allowUnsigned)
+        console.warn("[decidio] inngest resume bridge: allowUnsigned=true and no webhookSecret — resume signals are NOT authenticated; anyone who can reach this endpoint can emit a resume event. Development only.");
     return (req, res) => {
         if (req.method !== "POST") {
             res.statusCode = 405;