@decidio/sdk 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog — @decidio/sdk
+
+Release notes for the client SDK. The Python package `decidio` ships the same changes under the same
+version (the two are conformance-locked twins). Each entry names what changed, what a reader must do
+on upgrade, and what proved it.
+
+## 0.4.0 — the scope statement
+
+- **README: "What 0.4 does not yet claim" and "Compatibility and support."** The stability promise is
+  stated: what is stable, what is Beta (the engine adapters), what is deprecated and kept until 1.0
+  (`protectBestEffort`, `gateInterruptions`), and the five things reviewers keep finding that only
+  product decisions close (trust-on-first-use issuer DID, the unshipped schema, the unshipped
+  conformance suites, provenance and the repository link). 1.0.0 follows user-acceptance testing.
+- **The tour fails closed on an unpinned check.** If the API omits the issuer DID, the tour used to warn
+  and still report success; it now fails and cleans up.
+- **The tour's preflight names everything it writes**, including `.decidio-token-journal` and
+  `.decidio-pending/`.
+- **`--` ends option parsing on all three verifier doors**, so a receipt saved under a dash-leading
+  name can be verified.
+- **The token recovery journal treats corruption as uncertainty, never absence** (prodsec retest of
+  0.3.5). Every row is parsed and schema-checked before any mint; a row that cannot be trusted refuses
+  `init` and `quickstart`, turns `doctor` red and makes `quickstart cleanup` exit non-zero - the bytes are
+  left as found. Appends are framed (a delimiter first if the previous row lost its newline, a schema
+  version, a write loop before the fsync), so a torn row stays discoverable.
+- **A resume signal that finds the decision `invoking` answers `indeterminate`**, not `already_resolved`
+  with "already ran": the action may still be running, may have crashed before any effect, or may have
+  finished without reporting. `already_resolved` is reserved for the final states.
+- **Temporal (Beta): a custom `confirm` may return the gate's confirm outcome** (validated with
+  `readConfirmResponse`) and it becomes the step's confirmation instead of being discarded.
+- **Transport: every refusal redacts URL userinfo**, including the opaque `scheme:user:secret@` spelling,
+  and Unicode space and format characters (NBSP, ideographic space, zero-width space, …) are refused in
+  both runtimes from one explicit list. Four cases joined the shared transport corpus.
+- **This file ships** in the tarball (and in the Python sdist), as a deliberate publish-boundary line.
+
+## 0.3.5 — the retest residuals
+
+- **Transport:** any control character or whitespace anywhere in the URL is refused before anything is
+  sent; refusals echo a redacted spelling (URL userinfo is a credential).
+- **Credential lifecycle:** the quickstart inspects a previous `.env.quickstart` before minting; secret
+  files are written temp + fsync + rename; **the token recovery journal** (`.decidio-token-journal`,
+  owner-only, append-only) records every minted token id before the credential file exists and retires
+  it on a durable write or any proven revoke. Credential creation fails closed if the journal cannot be
+  written. `quickstart cleanup` sweeps it; `doctor` lists outstanding entries.
+- **Verifiers (all three doors):** the `verificationMethod` must be the issuer's exact `did:key` method
+  identifier, and `created` must be a real calendar date-time. Correctly signed receipts naming a
+  nonexistent method fragment or an impossible time are now INVALID.
+- **Adapter gate:** the same describe validation as the core (a blank action or negative amount is
+  refused before signing or posting).
+- **Outcomes:** a resume signal that lost the race to a final answer is `already_resolved`; a parked row
+  whose payload is gone is `orphaned_state`.
+- Upgrade: no action. Custom stores are unaffected.
+
+## 0.3.4 — first-run consistency
+
+- Tour and README pointers, routing-by-default vs the universal-backstop block named as two states, the
+  stale "unsafe values park and fail on resume" paragraph corrected, cleanup discloses the durable
+  store, help never loads `.env` (and only when usage will actually print), adapter headers current.
+- Upgrade: no action.
+
+## 0.3.2 / 0.3.3 — the transition itself is atomic (COORDINATED UPGRADE)
+
+- **The shipped file stores are an append-only revision chain** (`<key>.rev.<N>`), published with a
+  hard link that refuses an existing name: exactly one writer wins each transition, and a loser
+  re-validates against what actually happened. This closed the pre-0.3.2 race in which a denial could
+  be written and returned and the denied action still run.
+- **Upgrade — read this if a directory is shared by more than one worker:** the first 0.3.2+ store
+  migrates the older marker layout one way. **Stop every older worker that shares the directory before
+  the first 0.3.2+ process starts**, then upgrade them together. An older worker writing into an
+  upgraded directory leaves a marker beside the chain, and that decision reads as unreadable by design.
+  Nothing deletes a revision; each decision keeps a handful of small files (see the README's sizing
+  envelope).
+- 0.3.3: one snapshot of `describe()`'s answer for signing and posting; the shared id grammar at every
+  exported resume door; a compensating revoke when a minted token's credential file fails to write;
+  `reconfirm()` on a reported decision tells the truth about confirmation.
+
+## 0.3.1
+
+- The verifier says what it proves (canonical signed claims, not exact bytes); proof options
+  (`proofPurpose`, `verificationMethod`, `created`) are part of the claim on every door; duplicate
+  `--issuer` flags are refused everywhere; orphaned token ids survive every replacement.
+
+## 0.3.0
+
+- A claim that gates nothing: `reportRecorded` and `executionConfirmed` are distinct, honest booleans.
+  A denial is final on every path. The decision-id grammar is defined server-side and mirrored here.
+- Upgrade for custom stores: `markDiscarded` is required (a hard construction failure without it).
+
+## 0.2.x
+
+- The execution state machine (`parked → claimed_preinvoke → invoking → executed_unreported |
+  indeterminate → reported`), `reconcile()`, `ExecutionContext` with a stable idempotency key, and the
+  composite return (`{ value, decisionId, confirmation }`) with `protectBestEffort` keeping the old shape.

package/README.md

@@ -57,13 +57,17 @@ 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.
 
 `init` signs you into your workspace (email + password, or paste the sign-in link from your
 workspace email), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
 is sent), registers the agent, mints its **floor-limited API token** (limited to the agent runtime — request authorization, poll status, report signed confirmation; it cannot administer the workspace or approve anything — and your workspace session never touches the agent's disk), and writes `.env`.
-Every later command reads `.env` from this directory automatically. Re-running init for an
+Every later command that talks to Decidio reads `.env` from this directory automatically (`verify` is
+offline and never does). Re-running init for an
 agent that already has a token REPLACES it — the server keeps one active token per agent, so
 the previous one is revoked and init says so.
 
@@ -230,7 +234,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 +429,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 +460,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 +493,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 +527,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 +559,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 +601,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 +652,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.
@@ -657,6 +678,45 @@ Every error raised after a decision exists carries the `decisionId`, so a suspen
 timed-out action is always findable in
 your queue.
 
+## What 0.4 does not yet claim
+
+The retest that graded 0.3.3 *A- for the core and the shipped stores* and the first-run reviews of
+0.3.3 and 0.3.5 agree on what is left, and none of it is a defect a patch release closes. Stated here so
+the next reader grades a promise, not a moving target:
+
+- **Engine adapters are Beta and outside the stability promise.** They pass the same conformance
+  battery as the core against structural mocks; no live LangGraph/Temporal/Inngest/OpenAI restart suite
+  exists yet. Use the core path for production until it does.
+- **The issuer DID is trust on first use.** The tour and `receipt` print your workspace's issuer DID
+  from the same authenticated response that carries the receipt. Pinned verification is only as strong
+  as where you keep that DID: record it through a channel you trust independently (your app's
+  record-verify panel today; a published well-known location is on the roadmap).
+- **Verification is cryptographic, not schema validation.** `VALID` means the issuer's key signed these
+  canonical claims; the sealed-payload schema the receipt names by hash is not shipped, so a
+  structurally odd but correctly signed document is not refused on shape. Shipping the schema is on
+  the roadmap.
+- **The conformance suites are not in the package.** The deterministic two-process schedules that
+  prove the durable store, and the corpus every door is held to, live in the Decidio source repository.
+  A customer cannot rerun them from this tarball; a public conformance kit is on the roadmap.
+- **No provenance attestation, no repository link.** The source repository is private; npm refuses
+  provenance for private repositories, and a link that 404s is worse than none. Registry signatures and
+  lockfile integrity are what you can check today.
+
+## Compatibility and support
+
+- **Stable in 0.4:** `guard.protect` / `withApproval` and their options; the durable resume
+  controller (`createDecidioResume`: `park`, `resolve`, `reconcile`, `reconfirm`, `recover`, the worker
+  and both webhook handlers); the `PendingStore` contract and both shipped stores, including the on-disk
+  revision-chain layout; `EvidenceOutcome` (a root export) and `ResumeStatus` / `RecoveryState` (on the
+  `@decidio/sdk/resume` subpath), additive growth only; the error classes; the CLI's commands, flags and exit codes; the receipt verifier's verdict and
+  reasons. Changes to any of these announce themselves in the changelog first.
+- **Beta:** the engine adapters (above).
+- **Deprecated, kept until 1.0:** `protectBestEffort` (the value-only shape) and the old adapter
+  name `gateInterruptions`. They will be removed in 1.0.0, not before.
+- **Versioning:** 0.x minor releases may still carry deliberate breaking cleanups, announced in the
+  changelog with the upgrade step. 1.0.0 follows user-acceptance testing of this release and freezes the
+  surface above.
+
 ## Notes
 
 - **Framework-agnostic:** it wraps at the tool-call boundary, so it works with any agent runtime (LangGraph, OpenAI Agents SDK, CrewAI, a raw tool loop) and any action (Salesforce, M365, SAP, a DB write).

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/adapters/temporal.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext, type ProtectedExecution } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 /**
  * @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
@@ -23,7 +23,10 @@ export declare function installDecidioSignal(): Map<string, {
 }>;
 export interface DecidioGateOpts<R = unknown> {
     authorize?: () => Promise<GateAuth>;
-    confirm?: (decisionId: string, result: unknown) => Promise<void>;
+    /** Reports through YOUR activity. Return the gate's confirm response body (validated with
+     *  `readConfirmResponse`) and it becomes the outcome; return nothing and the outcome says the SDK could
+     *  not read back what Decidio recorded (prodsec V035-03: a returned outcome used to be discarded). */
+    confirm?: (decisionId: string, result: unknown) => Promise<EvidenceOutcome | void>;
     /** Map your action's return value to the evidence Decidio records — the same option the core
      *  path takes. Every adapter's stderr note named it and no adapter accepted one, so on this
      *  path the advice could not be followed. */

package/dist/adapters/temporal.js

@@ -25,12 +25,13 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     if (opts.confirm) {
         if (opts.evidence)
             console.warn("[decidio] temporal: `evidence` is ignored when you supply `confirm` — your callback owns the report, so map the result inside it. Remove one of the two to make the intent clear.");
-        await opts.confirm(auth.decisionId, result);
-        confirmation = {
+        const returned = await opts.confirm(auth.decisionId, result);
+        const usable = !!returned && typeof returned === "object" && typeof returned.reportRecorded === "boolean";
+        confirmation = usable ? returned : {
             reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: false,
             diagnostic: "your own `confirm` callback reported this execution, so this SDK cannot read back what Decidio recorded. Check the record, or return the gate's response body from your activity and validate it with readConfirmResponse.",
         };
-        if (!confirmWarned) {
+        if (!usable && !confirmWarned) {
             confirmWarned = true;
             console.warn(`[decidio] temporal: a custom \`confirm\` reports through your own activity, so this SDK cannot read back the evidence tier Decidio recorded. Check the record (or return the gate's response body from your activity and validate it with readConfirmResponse) if you need to know whether the execution was CONFIRMED, not merely reported.`);
         }

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,137 @@ 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";
+const JOURNAL_SCHEMA = 1;
+const JOURNAL_EVENTS = new Set(["probe", "minted", "retired"]);
+function journalAppend(entry) {
+    const fresh = !existsSync(JOURNAL_PATH);
+    const row = Buffer.from(JSON.stringify({ v: JOURNAL_SCHEMA, ...entry, at: new Date().toISOString() }) + "\n", "utf8");
+    const fd = openSync(JOURNAL_PATH, "a", 0o600);
+    try {
+        if (!fresh) {
+            const st = readFileSync(JOURNAL_PATH);
+            if (st.length && st[st.length - 1] !== 0x0a) {
+                let w = 0;
+                const nl = Buffer.from("\n");
+                while (w < nl.length)
+                    w += writeSync(fd, nl, w);
+            }
+        }
+        let written = 0;
+        while (written < row.length)
+            written += writeSync(fd, row, written);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (fresh) {
+        try {
+            chmodSync(JOURNAL_PATH, 0o600);
+        }
+        catch { }
+        hardenFile(JOURNAL_PATH);
+    }
+}
+function journalRowProblem(e) {
+    if (!e || typeof e !== "object" || Array.isArray(e))
+        return "not a JSON object";
+    if (e.v !== undefined && e.v !== JOURNAL_SCHEMA)
+        return `schema version ${JSON.stringify(e.v)} is not ${JOURNAL_SCHEMA}`;
+    if (typeof e.event !== "string" || !JOURNAL_EVENTS.has(e.event))
+        return `unknown event ${JSON.stringify(e.event ?? null)}`;
+    if (e.event !== "probe" && (typeof e.jti !== "string" || !e.jti.trim()))
+        return `${e.event} row without a string jti`;
+    if (e.event === "retired" && e.how !== "persisted" && e.how !== "revoked")
+        return `retired row with how=${JSON.stringify(e.how ?? null)}`;
+    return null;
+}
+class JournalCorruptError extends Error {
+    line;
+    why;
+    constructor(line, why) {
+        super(`${JOURNAL_PATH} line ${line}: ${why}`);
+        this.line = line;
+        this.why = why;
+        this.name = "JournalCorruptError";
+    }
+}
+function journalRows() {
+    if (!existsSync(JOURNAL_PATH))
+        return [];
+    const rows = [];
+    const lines = readFileSync(JOURNAL_PATH, "utf8").split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            throw new JournalCorruptError(i + 1, "not valid JSON (a torn or hand-edited row)");
+        }
+        const why = journalRowProblem(e);
+        if (why)
+            throw new JournalCorruptError(i + 1, why);
+        rows.push(e);
+    }
+    return rows;
+}
+const REFUSE_MINT_CORRUPT_JOURNAL = (e) => `✘ the token recovery journal cannot be trusted (${e.message}) - it may hold the id of a token that is still live. Refusing to mint on top of uncertain history. Inspect the file, revoke anything it names (npx @decidio/sdk tokens list --mine), and repair or move it aside; every byte is left as found. Nothing was minted.`;
+function journalProbe() {
+    try {
+        journalRows();
+    }
+    catch (e) {
+        return `CORRUPT: ${e?.message ?? e}`;
+    }
+    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() {
+    const minted = new Map();
+    for (const e of journalRows()) {
+        if (e.event === "minted")
+            minted.set(e.jti, { jti: e.jti, agentId: e.agentId, label: e.label, apiUrl: e.apiUrl, at: e.at });
+        if (e.event === "retired")
+            minted.delete(e.jti);
+    }
+    return [...minted.values()];
+}
+const REFUSE_MINT_NO_JOURNAL = (why) => why.startsWith("CORRUPT: ")
+    ? REFUSE_MINT_CORRUPT_JOURNAL(new Error(why.slice("CORRUPT: ".length)))
+    : `✘ 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 +329,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 +468,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 +522,8 @@ async function cmdInit(agentId, opts = {}) {
     try {
         prepareEnvForWrite();
         upsertEnv(envOut);
+        if (tokenJti)
+            journalRetire(tokenJti, "persisted");
     }
     catch (e) {
         if (agentToken && tokenJti)
@@ -404,6 +572,17 @@ async function cmdDoctor() {
     let warned = 0;
     const line = (good, label) => { log(`${good ? "✔" : "✘"} ${label}`); ok = ok && good; };
     const warn = (label) => { warned++; log(`⚠ ${label}`); };
+    let journalItems = [];
+    try {
+        journalItems = journalOutstanding();
+    }
+    catch (e) {
+        line(false, `token recovery journal: ${e?.message ?? e} — it may hold the id of a live token, and this directory cannot mint until it is repaired or moved aside (every byte is left as found).`);
+    }
+    for (const j of journalItems) {
+        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 +601,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.");
@@ -641,6 +820,10 @@ function cmdVerify(argsIn) {
     const files = [];
     for (let i = 0; i < argsIn.length; i++) {
         const a = argsIn[i];
+        if (a === "--") {
+            files.push(...argsIn.slice(i + 1));
+            break;
+        }
         if (a === "--issuer") {
             const v = argsIn[i + 1];
             if (v === undefined || v === "" || v.startsWith("-")) {
@@ -696,8 +879,10 @@ async function cmdQuickstart(opts = {}) {
     log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : "  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)"}`);
     log("");
     log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
-    log("  write .env (or .env.quickstart) + .gitignore entries · create one synthetic decision");
-    log("  and its sealed record (records are permanent by design). Cleanup offer at the end.");
+    log("  write .env (or .env.quickstart), .decidio-token-journal (revocation ids, no secrets) and .gitignore");
+    log("  entries (incl. .decidio-pending/, the durable store your real agent will use) · save the receipt");
+    log("  as decidio-receipt-<id>.json here (public; it stays) · create one synthetic decision and its");
+    log("  sealed record (records are permanent by design). Cleanup offer at the end.");
     log("");
     const session = await acquireSession("The quickstart");
     if (!session)
@@ -729,11 +914,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 +950,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 +976,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 +991,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 +1045,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) {
@@ -892,11 +1107,17 @@ async function cmdQuickstart(opts = {}) {
     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}` : ""})`);
+    if (!v.valid) {
+        err(`  ✘ the receipt did not verify (${v.reason ?? "no reason given"}) — the tour did not complete.`);
+        return failTour(1);
+    }
     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}`);
+        err(`  ✘ the tour does not count an UNPINNED check as success.`);
+        return failTour(1);
     }
     if (issuer)
         log(`    Keep that DID: it is your trust anchor — npx @decidio/sdk verify --issuer ${issuer} <receipt.json>`);
@@ -913,7 +1134,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 +1156,55 @@ 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 = [];
+    let outstanding = [];
+    try {
+        outstanding = journalOutstanding();
+    }
+    catch (e) {
+        err(`✘ the token recovery journal cannot be trusted (${e?.message ?? e}). It may hold the id of a live token, so this cleanup cannot claim nothing is owed. Every byte is left as found: inspect ${JOURNAL_PATH}, revoke anything it names (npx @decidio/sdk tokens list --mine), then repair or move it aside and re-run.`);
+        return 1;
+    }
+    for (const j of outstanding) {
+        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 +1235,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 +1246,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 +1281,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 +1319,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 +1436,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 +1514,15 @@ 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
+                        : (() => { try {
+                            return journalOutstanding().length ? ".env.quickstart" : undefined;
+                        }
+                        catch {
+                            return ".env.quickstart";
+                        } })();
                 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");
@@ -1251,7 +1541,8 @@ async function main(argv) {
                 err("✘ --expires-days needs a positive whole number of days (e.g. --expires-days 30).");
                 return 2;
             }
-            const nameArg = argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
+            const ddIdx = argsIn.indexOf("--");
+            const nameArg = ddIdx >= 0 ? argsIn[ddIdx + 1] : argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
             let name = nameArg ?? process.env.DECIDIO_AGENT_ID ?? "my-agent";
             if (unique)
                 name = `${name}-${randomBytes(2).toString("hex")}`;

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.d.ts

@@ -35,6 +35,8 @@ export type GateStepOutcome<R> = {
     status: "executed" | "rejected" | "blocked";
     decisionId: string;
     value?: R;
+    /** Always present when `status` is "executed" (the step confirms before it returns); optional in the type
+     *  because the other statuses carry none. */
     confirmation?: EvidenceOutcome;
 };
 /**

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,12 @@ 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, an execution that already ran, or a report already recorded) — `reason` names which. It used
+ *  to read `unknown`, the word for "not ours" (prodsec V033-06). An `invoking` row is NOT final and answers
+ *  `indeterminate` (prodsec V035-02). Both members are additive: an exhaustive switch over this union
+ *  gains a case per release, which the changelog announces. */
+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 +477,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,12 @@ 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 });
+                    if (claim.state === "invoking" || claim.state === "indeterminate") {
+                        return finish({ status: "indeterminate", decisionId, action: pending.action, reason: claim.state === "invoking"
+                                ? `this decision is in durable state invoking: its action may still be running, may have crashed before any effect, or may have finished without reporting - it may or may not have run. Nothing will retry it; check the worker and the downstream system, then settle it with reconcile("${decisionId}", …).`
+                                : claim.reason });
+                    }
+                    return finish({ status: "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 +1274,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,14 @@ 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;
+/** Unicode SPACE and FORMAT characters a URL must never contain: the Zs/Zl/Zp separators (NBSP, ideographic
+ *  space, …) and the zero-width formats. Spelled as an explicit list in BOTH runtimes so the answers cannot
+ *  drift with a library's notion of whitespace (Python's urlsplit strips a leading NBSP; WHATWG does not). */
+export declare const URL_UNICODE_SPACE: RegExp;
 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,20 @@ export function assertJsonSafe(value, path = "args") {
     };
     walk(value, path);
 }
+export function redactUrl(u) {
+    return u.replace(/\/\/[^/?#]*@/, "//***@").replace(/^([^/?#@:]*:)(?!\/\/)[\/\\]*[^/?#]*@/, "$1***@");
+}
+export const URL_UNICODE_SPACE = /[\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\u200b-\u200d\u2060]/;
 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 || URL_UNICODE_SPACE.test(ch)) {
+            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 +127,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 +138,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.4.0",
   "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",
@@ -40,6 +40,7 @@
     "dist",
     "openapi.yaml",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -82,7 +83,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.4.0"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {