@decidio/sdk 0.3.3 → 0.3.5

package/README.md

@@ -57,6 +57,9 @@ npm install @decidio/sdk
 npx @decidio/sdk init --unique my-agent   # --unique appends a random suffix: collision-proof
 ```
 
+> Just ran `npx @decidio/sdk quickstart` in this directory and kept its agent? Its `.env` already
+> works — skip this step and continue at step 3.
+
 Every CLI command talks to the hosted sandbox by default and announces its target host on
 stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another Decidio instead.
 
@@ -230,7 +233,11 @@ Real approvals take minutes to days, and nobody keeps a terminal open for them.
 `mode: "blocking"` (durable is the default) and a routed action **suspends** instead of
 waiting: it parks its call arguments agent-side (`.decidio-pending/` by default — Decidio
 stores none of your downstream payload) and throws `DecidioSuspendedError`. The process may
-exit. Two ways the parked action resumes when a human decides:
+exit. **The parked payload is plaintext on the agent's disk:** the full call arguments and their
+signature sit in `.decidio-pending/` until the decision resolves — owner-only permissions where the
+OS supports it, gitignored by `init`, but not encrypted. Treat that directory as you treat the `.env`
+beside it; a custom `PendingStore` can encrypt at rest. Two ways the parked action resumes when a
+human decides:
 
 **The worker (self-serve — start here).** No inbound URL, no shared secrets, and it resumes work
 the current process never started. Here is a complete `agent.mjs` you can run:
@@ -421,11 +428,12 @@ the store you configured, so two workers sharing one Redis or Postgres store can
 other's work. (Through 0.1.x this was a separate local-filesystem journal, which meant two
 workers kept two disjoint journals and neither could. `reportDir` is accepted and ignored now.)
 
-**Parked arguments must be JSON-serializable.** A suspended action is signed and then written to
-disk as JSON, so values that don't survive `JSON.stringify` round-tripping — `Date`, `Map`,
-`undefined`, `NaN`, class instances with custom `toJSON` — come back changed and fail the
-integrity check on resume (a refusal, never a wrong execution). Pass plain data; rehydrate
-inside your function.
+**Parked arguments must be JSON-serializable — and that is checked BEFORE routing.** Values that
+do not survive JSON with their meaning intact — `Date`, `Map`, `undefined`, `NaN`, class instances,
+functions — are refused with `DecidioUnsafeArgumentsError` before any decision exists and before any
+network call (since 0.1.12): nothing is parked, nothing is routed. The parked payload is also
+signed, so a file edited on disk fails the integrity check on resume (a refusal, never a wrong
+execution). Pass plain data; rehydrate inside your function.
 
 **Payload integrity.** When a routed action is parked, the SDK signs its arguments (bound to the
 decision id) with your agent key; on resume it **refuses to execute** if the parked payload was
@@ -451,7 +459,7 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
 
 
 
-## The durable store is a revision chain (0.3.2)
+## The durable store is a revision chain (since 0.3.2)
 
 `FilePendingStore` keeps each decision's execution record as an **append-only revision chain** —
 `<id>.rev.1`, `<id>.rev.2`, … — and the head is the highest number. Every state change reads the
@@ -484,11 +492,19 @@ the store refuses to pick one.
 
 **Custom stores.** The `PendingStore` contract has said since 0.2.0 that every method must be atomic
 against concurrent callers. The shipped file store did not honor that until now; a custom store must.
-The deterministic two-process schedules that proved the defect live in
-`packages/conformance/acceptance.mjs` (criteria 7a, 7b and 7c): a denial landing while an invoker
-is paused between validating and publishing; two conflicting settlements from one head; and a denier
-paused while the approver publishes four revisions past it. A store that cannot pass them is not
-atomic, whatever its methods say.
+The deterministic two-process schedules that proved the defect live in the Decidio source
+repository's conformance suite (not part of this package): a denial landing while an invoker is
+paused between validating and publishing; two conflicting settlements from one head; and a denier
+paused while the approver publishes four revisions past it. A store that cannot pass those schedules
+is not atomic, whatever its methods say.
+
+**Sizing envelope.** Nothing deletes a revision, so each decision leaves a handful of small files (one
+per transition, typically four to six) and a head lookup lists the directory. That is comfortable for
+tens of thousands of decisions on a local disk; beyond that, or for any deployment that shares a store
+across hosts, use a transactional custom `PendingStore`. The tested envelope is a **single host on a local
+filesystem with hard links** — network, FUSE and multi-host volumes are outside it, and their link
+semantics have not been exercised. Never compact the directory while a worker runs; if compaction is
+ever wanted it is an offline job with every writer stopped.
 
 ## Reading a receipt
 
@@ -510,8 +526,9 @@ request was compared to and did not clear, not a limit that was applied to it. R
 `requested_amount` as the ask, the other two as ceilings.
 
 **`firedRules` is what the policy engine actually matched — for any verdict.** It is not an
-auto-approve indicator: a **blocked** request carries the deny-by-default backstop rule here, so
-non-empty does not mean "approved" and empty does not mean "blocked". The field that states the
+auto-approve indicator: a request **blocked by the universal backstop** (no active policy governs
+agents at all) carries that backstop rule here, so non-empty does not mean "approved" and empty does
+not mean "blocked". The field that states the
 disposition is `authority.result`; `firedRules` tells you which named, versioned rules produced it.
 
 **`payloadSchemaUri` is a `urn:`, not a URL.** It is content-addressed —
@@ -541,8 +558,10 @@ verdict, reason?)` is now REQUIRED — it writes the tombstone that makes a deni
 permanently unclaimable, and a store that cannot record a denial cannot uphold the guarantee, so
 this is refused at construction rather than deep inside a resolve. `delete` also takes an optional
 owning attempt (`delete(id, attemptId?)`) so a superseded attempt cannot clean up the live one's
-payload, and `settle` takes `workerStopped`. The shipped stores show the shape, and
-`packages/conformance/vectors/ownership.json` is the corpus your store should pass.
+payload, and `settle` takes `workerStopped`. The shipped stores show the shape; the ownership
+corpus that pins these rules (claim fencing, terminal denial, advance-only transitions, settle
+preconditions) lives in the Decidio source repository and is not part of this package — the rules
+themselves are the ones stated above.
 
 **`recover()` now throws instead of returning `[]`** when the ledger cannot be read
 (`DecidioRecoveryUnavailableError`). `[]` and "I cannot tell you what you owe" are the same value
@@ -581,8 +600,9 @@ that fits every other confirm error.
 
 - **Engine adapters are BETA.** They share the core's gate semantics — the verdict allow-list,
   the canonical argument model, the transport rule and evidence handling are ONE implementation,
-  and a conformance matrix runs the same malformed-verdict, unsafe-argument and plaintext-transport
-  battery against every door. What is *not* yet verified is the engine integration itself: those
+  and a conformance matrix runs the same malformed-verdict, unsafe-argument, plaintext-transport and
+  malformed-description (blank action, negative amount) battery against every door. What is *not* yet
+  verified is the engine integration itself: those
   paths are exercised against structural mocks, not live LangGraph/Temporal/Inngest/OpenAI
   runtimes. Use the core path for production until that changes. Each adapter is bound through its
   own `@decidio/sdk/<engine>` subpath (they need the engine handle at call time); no engine at all?
@@ -631,7 +651,7 @@ manager for production.
 
 ## Errors
 
-- `DecidioBlockedError` — policy blocked the action (incl. the universal deny-by-default backstop).
+- `DecidioBlockedError` — policy blocked the action: a named block rule, or the universal backstop that fires when NO active policy governs agents at all (fail closed, no human involved). Distinct from routing-by-default — with an active policy and no matching auto-approve rule, a request is not blocked, it is ROUTED to a person.
 - `DecidioRejectedError` — a human rejected the routed action.
 - `DecidioSuspendedError` — (durable mode) the action was routed and is parked for async approval; the process may exit and resume later. Not a failure.
 - `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); the decision stays open in Decidio, nothing executed locally.

package/dist/adapters/_gate.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, readConfirmResponse, buildConfirmBody, decisionIdProblem } from "../index.js";
+import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, assertDescribed, readConfirmResponse, buildConfirmBody, decisionIdProblem } from "../index.js";
 export const AUTHORIZE_VERDICTS = ["proceed", "route", "block"];
 export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     const a = auth;
@@ -15,6 +15,7 @@ export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
 }
 export async function gateAuthorize(config, ctx) {
     ctx = canonicalize(ctx, "describe(...)");
+    assertDescribed(ctx);
     assertSafeTransport(config.apiUrl, carriesCredential(config));
     const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;

package/dist/adapters/openai.d.ts

@@ -15,7 +15,7 @@ interface RunStateLike {
  * park the serialized state agent-side on `route`, resume on Decidio's approval.
  *
  * const state = result.state;                       // or RunState from the run
- * const { resolved, pending } = await gateInterruptions(config, state, describe);
+ * const { resolved, pending } = await authorizeInterruptions(config, state, describe);
  * if (pending.length) { await store.put(decisionId, state.toString()); return; }  // suspend
  * result = await run(agent, state);                 // all resolved → resume
  * // on Decidio approval webhook: state = await RunState.fromString(agent, parked);

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);
     }
@@ -123,14 +149,79 @@ 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();
@@ -180,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)
@@ -319,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)}`);
@@ -356,6 +464,8 @@ async function cmdInit(agentId, opts = {}) {
     try {
         prepareEnvForWrite();
         upsertEnv(envOut);
+        if (tokenJti)
+            journalRetire(tokenJti, "persisted");
     }
     catch (e) {
         if (agentToken && tokenJti)
@@ -404,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;
@@ -422,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.");
@@ -729,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,
@@ -741,8 +886,8 @@ 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));
@@ -767,6 +912,8 @@ async function cmdQuickstart(opts = {}) {
         }
         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)
@@ -780,6 +927,8 @@ async function cmdQuickstart(opts = {}) {
     else {
         try {
             upsertEnv(envOut);
+            if (mint.body.jti)
+                journalRetire(mint.body.jti, "persisted");
         }
         catch (e) {
             if (mint.body?.jti)
@@ -832,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) {
@@ -913,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) {
@@ -932,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) {
@@ -970,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:`);
@@ -978,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() !== "";
         });
@@ -1004,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) {
@@ -1036,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;
         }
@@ -1151,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;
@@ -1230,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/index.d.ts

@@ -103,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));
@@ -142,12 +150,7 @@ export function withApproval(fn, describe, config, opts) {
         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;
-        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;

package/dist/resume.d.ts

@@ -450,7 +450,10 @@ export declare class DecidioSuspendedError extends Error {
 /** `indeterminate` (0.2.0): the handler was INVOKED and then threw. Whether the downstream
  *  effect committed is not knowable from here, so the action is never retried automatically —
  *  it waits for reconcile(). Callers that switch exhaustively on this union must handle it. */
-export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate";
+/** `already_resolved` (0.3.5): this resume signal LOST the transition race to an earlier, final answer
+ *  (a denial, or an execution that already ran) — `reason` names which. It used to read `unknown`,
+ *  which is the word for "not ours"; safety was right and the diagnosis was not (prodsec V033-06). */
+export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved";
 /** The states a durable action can actually be in — every one of them nameable, including the
  *  one nobody likes. */
 export type RecoveryState = 
@@ -472,7 +475,9 @@ export type RecoveryState =
  *  and must never be retried automatically. */
  | "indeterminate"
 /** Executed, result captured, report not yet accepted by Decidio. Safe to `reconfirm`. */
- | "executed_unreported";
+ | "executed_unreported"
+/** a parked row whose payload is gone: cannot execute, not awaiting anyone (0.3.5) */
+ | "orphaned_state";
 export interface RecoveryItem {
     decisionId: string;
     action?: string;

package/dist/resume.js

@@ -1037,7 +1037,7 @@ export function createDecidioResume(opts) {
                     refuseOnce(decisionId, claim.state === "discarded"
                         ? `[decidio] REFUSING to execute ${decisionId}: it was DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}) and that answer is final. Nothing ran. A denial cannot be reconciled or retried — if this action should now proceed, it needs a NEW request and a new approval.`
                         : `[decidio] REFUSING to execute ${decisionId}: its durable state is ${claim.state} — invocation already began, so re-running it could duplicate a committed effect. Inspect it with guard.resume.recover(); settle it with guard.resume.reconcile("${decisionId}", …).`, claim.state === "discarded" ? " (This prints once. The decision is closed — no action is needed.)" : undefined);
-                    return finish({ status: claim.state === "indeterminate" ? "indeterminate" : "unknown", decisionId, action: pending.action, reason: claim.reason });
+                    return finish({ status: claim.state === "indeterminate" ? "indeterminate" : "already_resolved", decisionId, action: pending.action, reason: claim.state === "discarded" ? `this decision was already DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}); that answer is final and this signal lost the race to it` : `this decision already ran (durable state ${claim.state}); this signal lost the race to it` });
                 }
                 return { status: "unknown", decisionId };
             }
@@ -1269,7 +1269,12 @@ export function createDecidioResume(opts) {
                             guidance: `"${a}" was claimed at ${r.at} by attempt ${r.attemptId ?? "(unknown)"} which never reached the invocation boundary — the handler provably did not run, and nothing will retry it on its own. Release it: guard.resume.reconcile("${r.decisionId}", { outcome: "not_committed", reason: "claimed but never invoked" }).` });
                         break;
                     case "parked":
-                        items.push({ decisionId: r.decisionId, action: r.action, state: "parked", guidance: `"${a}" is parked awaiting a human decision. Nothing has executed.` });
+                        if (!(await ctrl.store.get(r.decisionId))) {
+                            items.push({ decisionId: r.decisionId, action: r.action, state: "orphaned_state", guidance: `"${a}" is recorded as parked but its payload is gone, so nothing can execute it — an orphaned row (usually a legacy denial whose state was never written), not work awaiting a human. Nothing will run. It needs no action; remove its revision files if you want the listing clean.` });
+                        }
+                        else {
+                            items.push({ decisionId: r.decisionId, action: r.action, state: "parked", guidance: `"${a}" is parked awaiting a human decision. Nothing has executed.` });
+                        }
                         break;
                     case "discarded":
                         if (r.executionDespiteDenial) {

package/dist/signing.d.ts

@@ -74,6 +74,10 @@ export declare function assertJsonSafe(value: unknown, path?: string): void;
  *  rule is about the WIRE, not which credential (the interactive sign-in enforced this for
  *  session tokens while agent-token requests sailed through). localhost/127.0.0.1/[::1] stay
  *  allowed for local dev; https always allowed. Throws before anything is sent. */
+/** The URL as it may be ECHOED in a refusal: userinfo masked. The SDK treats URL userinfo as a credential
+ *  (it is refused as one), so no refusal may print it - every branch of assertSafeTransport echoes through
+ *  this, not the raw string (invariant-guard, 0.3.5). */
+export declare function redactUrl(u: string): string;
 export declare function assertSafeTransport(url: string, hasCredential: boolean): void;
 /** The ONE answer to "does this request carry a credential worth protecting?" (A6, 0.1.12).
  *  A signed identity proof is a credential too: sending it over remote plaintext disclosed

package/dist/signing.js

@@ -106,7 +106,17 @@ export function assertJsonSafe(value, path = "args") {
     };
     walk(value, path);
 }
+export function redactUrl(u) { return u.replace(/\/\/[^/@]*@/, "//***@"); }
 export function assertSafeTransport(url, hasCredential) {
+    if (typeof url !== "string") {
+        throw new Error(`[decidio] the gate URL is ${url === null ? "null" : typeof url}, not a string, so there is no host to send to. Decidio needs a full https URL (or http://localhost for local dev). Nothing was sent.`);
+    }
+    for (const ch of url) {
+        const cp = ch.codePointAt(0);
+        if (cp <= 0x20 || (cp >= 0x7f && cp <= 0x9f) || cp === 0xfeff) {
+            throw new Error(`[decidio] the gate URL ${JSON.stringify(redactUrl(url))} contains whitespace or a control character (U+${cp.toString(16).toUpperCase().padStart(4, "0")}) - a validator and a transport can read such a spelling differently, so it is refused as written. Remove it. Nothing was sent.`);
+        }
+    }
     let u;
     try {
         u = new URL(url);
@@ -114,9 +124,9 @@ export function assertSafeTransport(url, hasCredential) {
     catch {
         const spelled = url.replace(/[\t\r\n]/g, "").replace(/^[\s\u0000-\u001f\u0085\ufeff]+/, "");
         if (/^http:/i.test(spelled)) {
-            throw new Error(`[decidio] refusing to ${hasCredential ? "send credentials" : "send a request"} over plaintext http to ${JSON.stringify(url)} — that is not a complete absolute URL, so where the request would actually connect is undefined (the path is appended to it, which can turn it into a remote host). Set a full https URL, or http://localhost for local dev. Nothing was sent.`);
+            throw new Error(`[decidio] refusing to ${hasCredential ? "send credentials" : "send a request"} over plaintext http to ${JSON.stringify(redactUrl(url))} — that is not a complete absolute URL, so where the request would actually connect is undefined (the path is appended to it, which can turn it into a remote host). Set a full https URL, or http://localhost for local dev. Nothing was sent.`);
         }
-        throw new Error(`[decidio] the gate URL ${JSON.stringify(url)} is not an absolute URL, so there is no host to send to — where a request would actually connect depends entirely on whichever transport resolves it. Decidio needs a full https URL (or http://localhost for local dev). Nothing was sent.`);
+        throw new Error(`[decidio] the gate URL ${JSON.stringify(redactUrl(url))} is not an absolute URL, so there is no host to send to — where a request would actually connect depends entirely on whichever transport resolves it. Decidio needs a full https URL (or http://localhost for local dev). Nothing was sent.`);
     }
     if (u.protocol !== "http:" && u.protocol !== "https:") {
         throw new Error(`[decidio] the gate URL uses the ${u.protocol.replace(":", "")} scheme, which is not a Decidio endpoint — use https (or http://localhost for local dev). Nothing was sent.`);
@@ -125,14 +135,14 @@ export function assertSafeTransport(url, hasCredential) {
         throw new Error(`[decidio] the gate URL carries credentials in the URL itself (${u.protocol}//user:***@${u.host}). Decidio authenticates with a bearer token; remove the user:password from the URL. Nothing was sent.`);
     }
     if (u.hostname === "") {
-        throw new Error(`[decidio] the gate URL ${JSON.stringify(url)} has no host — there is nowhere for the request to go. Decidio needs a full https URL (or http://localhost for local dev). Nothing was sent.`);
+        throw new Error(`[decidio] the gate URL ${JSON.stringify(redactUrl(url))} has no host — there is nowhere for the request to go. Decidio needs a full https URL (or http://localhost for local dev). Nothing was sent.`);
     }
     {
         const spelled = url.replace(/[\t\r\n]/g, "").replace(/^[\s\u0000-\u001f\u0085\ufeff]+/, "").toLowerCase();
         const origin = `${u.protocol}//${u.host}`.toLowerCase();
         const next = spelled.charAt(origin.length);
         if (!spelled.startsWith(origin) || (next !== "" && next !== "/" && next !== "?" && next !== "#" && next !== ":")) {
-            throw new Error(`[decidio] the gate URL ${JSON.stringify(url)} is not written in canonical form — this parser reads it as ${origin}, but the raw spelling is what a transport receives, and a parser that normalizes differently can read it as another host entirely. Write it as ${origin}. Nothing was sent.`);
+            throw new Error(`[decidio] the gate URL ${JSON.stringify(redactUrl(url))} is not written in canonical form — this parser reads it as ${origin}, but the raw spelling is what a transport receives, and a parser that normalizes differently can read it as another host entirely. Write it as ${origin}. Nothing was sent.`);
         }
     }
     if (u.protocol !== "http:")

package/package.json

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