@decidio/sdk 0.1.12 → 0.2.1

package/README.md

@@ -90,8 +90,9 @@ const payInvoice = guard.protect(
   { mode: "blocking" },   // blocking = watch the whole loop live in one terminal sitting.
 );                        // Production agents use durable mode instead — see below.
 
-const result = await payInvoice({ id: "INV-2026-001", amount: 86_000 });
-console.log("executed after approval:", result);
+const { value, confirmation } = await payInvoice({ id: "INV-2026-001", amount: 86_000 });
+console.log("executed after approval:", value);
+console.log("Decidio recorded it as:", confirmation.evidenceTier);   // e.g. application_confirmed
 ```
 
 **4. Trigger it:**
@@ -200,7 +201,7 @@ That's the whole contract: gate → human decision → your execution → owned,
    - **proceed** — your function runs immediately (auto-approved under a named, versioned rule).
    - **route** — the action suspends (durable) or waits (blocking) for a human decision in Decidio's queue, then runs your function (or throws `DecidioRejectedError`).
    - **block** — the wrapper throws `DecidioBlockedError`; your function never runs.
-3. After your function runs, the wrapper reports the **real response it captured** back to Decidio, which records it as `application_confirmed` execution evidence (Decidio minimizes + tokenizes before storing — the immutable record never stores raw payloads).
+3. After your function runs, the wrapper reports the **real response it captured** back to Decidio (which minimizes + tokenizes before storing — the immutable record never stores raw payloads). The tier that report earns depends on what it can prove: `application_confirmed` when the agent has key material and signs the execution report, `agent_asserted` when it does not, and `execution_unconfirmed` when the reported value carries no usable evidence. The SDK tells you which it got; it never claims the top tier by default.
 
 Your agent executes its own action. **Decidio holds no write credentials for your system** — it authorizes the decision, records it, and (optionally) independently verifies it.
 
@@ -313,13 +314,42 @@ canonicalization preserves **value** semantics, not JavaScript object identity.
 pointing at the same object arrive as two equal objects, and mutating an argument inside your
 function does not affect the caller's copy.
 
-**What the SDK can and cannot promise about duplicates.** It prevents *concurrent* execution:
-an entry is claimed atomically before it runs, so two workers cannot both execute it and a
-duplicate signal finds nothing to replay. It cannot make an external side effect exactly-once —
-no client can. If your action succeeds and the process dies before the result is recorded,
-whether it ran is not knowable from this machine. So the contract is **at-least-once with
-honest recovery**, and your downstream action should be idempotent (the decision id makes a
-natural idempotency key).
+**What the SDK can and cannot promise about duplicates.** The guarantee, stated exactly:
+
+> Once invocation may have begun, the SDK never automatically invokes it again unless the
+> downstream system provides an idempotency guarantee or an operator explicitly reconciles it.
+
+It holds across processes and restarts, not just within one worker. Before your function is
+called the SDK writes a durable `invoking` marker to the pending store; from that moment no
+poll, no duplicate webhook, no fresh process and no worker cycle will call it again. Deletion of
+the parked row is cleanup, not the guarantee — a store whose `delete()` silently fails cannot
+cause a second execution.
+
+**Closing the last window yourself.** Pass `withContext: true` and your action receives an
+`ExecutionContext` as its first argument:
+
+```js
+const payInvoice = guard.protect(
+  async (ctx, invoice) => stripe.paymentIntents.create(
+    { amount: invoice.amount, currency: "usd" },
+    { idempotencyKey: ctx.idempotencyKey },   // ← stable across every attempt at this decision
+  ),
+  (invoice) => ({ action: "payInvoice", amount: invoice.amount }),
+  { withContext: true },
+);
+```
+
+`ctx` is `{ decisionId, attemptId, idempotencyKey }`. It is opt-in rather than inferred from your
+function's arity, because guessing wrong would hand a payment call a context object where it
+expected an invoice. `describe` still receives your arguments only — it describes the *request*,
+while the context describes the *execution*.
+
+It still cannot make an external side effect exactly-once — no client can. If your action
+succeeds and the process dies before the result is recorded, whether the downstream write
+committed is not knowable from this machine. The difference is what the SDK does about it: that
+decision becomes **`indeterminate`** and stops, rather than being retried into a duplicate
+payment. You settle it with `reconcile()` once you have looked downstream. Pass the decision id
+as your vendor's idempotency key and that window closes on their side too.
 
 Recovery is explicit rather than magical:
 
@@ -332,9 +362,12 @@ for (const item of await guard.resume.recover()) {
 // "parked"              → still waiting on a human; nothing has executed
 ```
 
-The report a worker sends is journalled *before* the first attempt, so a lost confirmation is
-recoverable; and because the journal holds no handler binding, replaying it can only re-send
-evidence — never re-run your function.
+The report a worker sends is written to the pending store's execution ledger *before* the first
+send attempt, so a lost confirmation is recoverable; and because that record holds no handler
+binding, replaying it can only re-send evidence — never re-run your function. The ledger lives in
+the store you configured, so two workers sharing one Redis or Postgres store can reconfirm each
+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`,
@@ -380,6 +413,10 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
 `npx @decidio/sdk <cmd>`:
 
 - `quickstart` — the guided two-minute tour (gate → approve → execute → proof)
+  - `--auto-approve-demo` approves the tour's own synthetic decision so it can run headless; it
+    then CLEANS UP the tour agent and token automatically. Pass `--keep-agent` to keep them.
+  - An interactive run keeps the agent by default and offers cleanup at the end;
+    `quickstart cleanup` works later too.
 - `init [agentId] [--unique] [--force] [--expires-days N]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries). Refuses to overwrite a *different* agent's key in this directory; `--force` backs the old `.env` up first.
 - `doctor` — config, connectivity, and what your current token can do
 - `approvals [--mine] [--json]` / `approvals approve|reject <id> [reason]` — the human side, from your terminal (the list is workspace-wide; `--mine` narrows it to this directory's agent)
@@ -392,7 +429,7 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
 The CLI's stream contract: **stdout carries results only** (safe to pipe — `--json` output is
 pure JSON); errors, usage shown on *error* paths, and the per-run target-host announcement go
 to **stderr**. Asked-for help (an explicit `--help`, or invoking the bare CLI) is itself a
-result and prints on stdout. Exit codes: 0 success · 1 failure or honest no-op · 2 usage error.
+result and prints on stdout. Exit codes: 0 success · 1 failure or honest no-op · 2 usage error · 3 `quickstart` stopped at the human moment (headless: the decision routed, but nothing executed and no receipt was written, so the run is deliberately not reported as a completed tour).
 
 Commands that administer your workspace (`init`, `approvals`, `receipt`) use a **session**
 sign-in held in memory for that run. What lands on disk in `.env`: the agent's floor-limited
@@ -431,6 +468,6 @@ your queue.
 ## 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).
-- **Confirmation integrity:** the wrapper runs in your process, so it captures the genuine API response — a materially stronger signal than an agent self-report, but it trusts the host. For high-assurance, Decidio can *independently* read the source back (`source_confirmed`) where it holds a read connection.
+- **Confirmation integrity:** the wrapper runs in your process, so it captures the genuine API response — a materially stronger signal than an agent self-report, but it trusts the host. For high-assurance, Decidio can *independently* read the source back (`independently_reconciled`) where it holds a read connection.
 - **Zero-code alternative:** an agent that speaks MCP (e.g. Claude on the web) can reach the same gate via Decidio's `request_approval` MCP tool with no code at all.
 - **API surface:** the agent-gate REST contract this SDK speaks is described in [`openapi.yaml`](./openapi.yaml), shipped in the package.

package/dist/adapters/_gate.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type EvidenceOutcome } from "../index.js";
 /** The ONLY authorization verdicts this SDK understands. A gate answer outside this set means
  *  the SDK does not understand the decision — and an answer you do not understand means NO. */
 export declare const AUTHORIZE_VERDICTS: readonly ["proceed", "route", "block"];
@@ -16,7 +16,13 @@ export interface GateAuth {
  *  fourth verdict) is the realistic trigger, and it must never mean "run it". */
 export declare function assertAuthorizeVerdict(auth: unknown, fallbackDecisionId?: string): GateAuth;
 export declare function gateAuthorize(config: GuardConfig, ctx: ApprovalContext): Promise<GateAuth>;
-export declare function gateConfirm(config: GuardConfig, decisionId: string, result: unknown): Promise<void>;
+/** Report an adapter-path execution and RETURN what Decidio recorded.
+ *
+ *  Two 0.2.0 changes, both closing the same gap. It applies the caller's `evidence` mapper — the
+ *  warning below tells you to use that option, and on every engine adapter it did nothing, because
+ *  the mapper never reached this function. And it RETURNS the outcome instead of swallowing it, so
+ *  an adapter can hand its caller the same confirmation the core path now does. */
+export declare function gateConfirm(config: GuardConfig, decisionId: string, result: unknown, evidence?: (r: any) => unknown): Promise<EvidenceOutcome>;
 /** Normalize a resume payload ({verdict} | "approved" | ...) to a verdict string. */
 export declare function verdictFrom(payload: any): string;
 /** Throw the right error for a non-approving verdict; return for approved/auto_approved. */

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 } from "../index.js";
+import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, readConfirmResponse, buildConfirmBody, decisionIdProblem } from "../index.js";
 export const AUTHORIZE_VERDICTS = ["proceed", "route", "block"];
 export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     const a = auth;
@@ -7,8 +7,9 @@ export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     if (!a || !AUTHORIZE_VERDICTS.includes(a.decision)) {
         throw new DecidioBlockedError(`unrecognised authorization verdict ${JSON.stringify(a?.decision ?? null)} — refusing to execute. The gate answers ${AUTHORIZE_VERDICTS.join(" | ")}; anything else means this SDK version does not understand the decision (upgrade @decidio/sdk), and an answer you do not understand is never permission.`, decisionId);
     }
-    if (typeof a.decisionId !== "string" || !a.decisionId) {
-        throw new DecidioBlockedError(`the gate answered "${a.decision}" with no usable decisionId (${JSON.stringify(a.decisionId ?? null)}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, decisionId);
+    const idProblem = decisionIdProblem(a.decisionId);
+    if (idProblem) {
+        throw new DecidioBlockedError(`the gate answered "${a.decision}" with no usable decisionId (${JSON.stringify(a.decisionId ?? null)} — ${idProblem}) — refusing to execute. Every authorized action must be addressable: without an id it cannot be polled, resumed, confirmed or audited.`, decisionId);
     }
     return a;
 }
@@ -40,19 +41,23 @@ export async function gateAuthorize(config, ctx) {
     }
     return assertAuthorizeVerdict(await res.json(), "unknown");
 }
-export async function gateConfirm(config, decisionId, result) {
+export async function gateConfirm(config, decisionId, result, evidence) {
     const f = config.fetchImpl ?? fetch;
+    const failed = (why, retryable = true) => ({
+        reportRecorded: false, executionConfirmed: false, confirmationRetryable: retryable, reportJournalled: false,
+        diagnostic: `your action RAN and Decidio does NOT have its execution report (${why}). Record the outcome from your own system; do NOT re-run the action.`,
+    });
     try {
         assertSafeTransport(config.apiUrl, carriesCredential(config));
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
-        return;
+        return failed(e.message, false);
     }
     let reported = null;
     let evidenceProblem;
     try {
-        reported = canonicalize(result ?? null, "result");
+        reported = canonicalize((evidence ? evidence(result) : result) ?? null, evidence ? "evidence(result)" : "result");
     }
     catch (e) {
         evidenceProblem = String(e?.message ?? e);
@@ -69,7 +74,7 @@ export async function gateConfirm(config, decisionId, result) {
         });
         if (!res.ok) {
             console.warn(`[decidio] confirm returned ${res.status} (action succeeded)`);
-            return;
+            return { ...failed(`HTTP ${res.status}`, res.status === 408 || res.status === 429 || res.status >= 500), evidenceError: evidenceProblem };
         }
         const ev = readConfirmResponse(await res.json().catch(() => null), { signed: !!requesterIdentity, capturedResponse: reported });
         if (!ev.reportRecorded)
@@ -78,9 +83,13 @@ export async function gateConfirm(config, decisionId, result) {
             console.warn(`[decidio] execution evidence for ${decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
         if (evidenceProblem)
             console.warn(`[decidio] ${decisionId}: the execution IS recorded, but with an empty captured response — see the evidence note above.`);
+        if (evidenceProblem)
+            ev.evidenceError = evidenceProblem;
+        return ev;
     }
     catch (e) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
+        return { ...failed(e.message), evidenceError: evidenceProblem };
     }
 }
 export function verdictFrom(payload) {

package/dist/adapters/langgraph.d.ts

@@ -11,7 +11,9 @@ import { type GuardConfig, type ApprovalContext } from "../index.js";
  * (This wiring doc ships in the .d.ts — the README points here.)
  */
 /** Gate `run()` behind Decidio inside a LangGraph node. */
-export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>): Promise<R>;
+export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>, opts?: {
+    evidence?: (r: R) => unknown;
+}): Promise<R>;
 /** Translate Decidio's signed resume webhook into the LangGraph resume Command. The host
  *  maps decisionId → thread_id and passes this to graph.invoke/stream. */
 export declare function decidioResumeCommand(body: {

package/dist/adapters/langgraph.js

@@ -1,7 +1,7 @@
 import { interrupt, Command } from "@langchain/langgraph";
 import { DecidioBlockedError } from "../index.js";
 import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict, checkEngineVersion } from "./_gate.js";
-export async function decidioGate(config, ctx, run) {
+export async function decidioGate(config, ctx, run, opts) {
     const auth = await gateAuthorize(config, ctx);
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
@@ -10,7 +10,7 @@ export async function decidioGate(config, ctx, run) {
         assertVerdict(verdictFrom(resumed), auth.decisionId, resumed?.reason);
     }
     const result = await run();
-    await gateConfirm(config, auth.decisionId, result);
+    await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     return result;
 }
 export function decidioResumeCommand(body) {

package/dist/adapters/openai.d.ts

@@ -1,4 +1,4 @@
-import type { GuardConfig, ApprovalContext } from "../index.js";
+import { type GuardConfig, type ApprovalContext } from "../index.js";
 type ToolApprovalItem = any;
 interface RunStateLike {
     getInterruptions(): ToolApprovalItem[];
@@ -41,6 +41,11 @@ export declare function gateInterruptions(config: GuardConfig, state: RunStateLi
     resolved: Resolved[];
     pending: Pending[];
 }>;
-/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString). */
+/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString).
+ *
+ *  VALIDATES BEFORE MUTATING. `else state.reject(item)` treated every unrecognised string as a
+ *  rejection, so a garbled payload, a version-skew verdict or an empty string became a rejection
+ *  that a caller could not tell apart from a human deciding no — and the RunState was already
+ *  mutated by the time anyone could look. The recognised set is exactly the one `resume` uses. */
 export declare function applyResume(state: RunStateLike, item: ToolApprovalItem, verdict: string): void;
 export {};

package/dist/adapters/openai.js

@@ -1,4 +1,5 @@
 import { gateAuthorize, checkEngineVersion } from "./_gate.js";
+import { DecidioBlockedError } from "../index.js";
 export async function gateInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
@@ -12,15 +13,22 @@ export async function gateInterruptions(config, state, describe) {
             state.reject(item);
             resolved.push({ item, verdict: "blocked", decisionId: auth.decisionId });
         }
-        else
+        else if (auth.decision === "route")
             pending.push({ item, decisionId: auth.decisionId });
+        else
+            throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)}`, auth.decisionId);
     }
     return { resolved, pending };
 }
 export function applyResume(state, item, verdict) {
-    if (verdict === "approved" || verdict === "auto_approved")
+    if (verdict === "approved" || verdict === "auto_approved") {
         state.approve(item);
-    else
+        return;
+    }
+    if (verdict === "rejected" || verdict === "blocked") {
         state.reject(item);
+        return;
+    }
+    throw new DecidioBlockedError(`unrecognised resume verdict ${JSON.stringify(verdict)} — refusing to apply it. This SDK understands approved / auto_approved / rejected / blocked; anything else is a version skew, and guessing would turn "I do not understand" into a decision. The RunState was NOT modified.`, "");
 }
 checkEngineVersion("openai");

package/dist/adapters/temporal.d.ts

@@ -21,11 +21,15 @@ export declare function installDecidioSignal(): Map<string, {
     verdict: string;
     reason?: string;
 }>;
-export interface DecidioGateOpts {
+export interface DecidioGateOpts<R = unknown> {
     authorize?: () => Promise<GateAuth>;
     confirm?: (decisionId: string, result: unknown) => Promise<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. */
+    evidence?: (result: R) => unknown;
 }
 export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>, verdicts: Map<string, {
     verdict: string;
     reason?: string;
-}>, opts?: DecidioGateOpts): Promise<R>;
+}>, opts?: DecidioGateOpts<R>): Promise<R>;

package/dist/adapters/temporal.js

@@ -22,6 +22,8 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     }
     const result = await run();
     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);
         if (!confirmWarned) {
             confirmWarned = true;
@@ -29,7 +31,7 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
         }
     }
     else {
-        await gateConfirm(config, auth.decisionId, result);
+        await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     }
     return result;
 }

package/dist/canonical.d.ts

@@ -15,4 +15,4 @@ export declare function canonicalize<T = JsonValue>(value: unknown, path?: strin
 export declare function canonicalizeArgs(args: readonly unknown[]): JsonValue[];
 /** RFC 8785-shaped canonical JSON of an already-canonical value — the exact bytes hashed for an
  *  execution report, so both languages produce the same digest. */
-export declare function canonicalJson(value: JsonValue): string;
+export declare function canonicalJson(value: JsonValue, path?: string): string;

package/dist/canonical.js

@@ -114,15 +114,19 @@ function deepFreeze(v) {
 export function canonicalizeArgs(args) {
     return args.map((a, i) => deepFreeze(walk(a, `args[${i}]`, new Set())));
 }
-export function canonicalJson(value) {
+export function canonicalJson(value, path = "canonicalJson(...)") {
     if (value === null)
         return "null";
     if (typeof value === "boolean" || typeof value === "number")
         return JSON.stringify(value);
-    if (typeof value === "string")
+    if (typeof value === "string") {
+        assertNoLoneSurrogate(value, path);
         return JSON.stringify(value);
+    }
     if (Array.isArray(value))
-        return `[${value.map(canonicalJson).join(",")}]`;
+        return `[${value.map((v, i) => canonicalJson(v, `${path}[${i}]`)).join(",")}]`;
     const keys = Object.keys(value).sort();
-    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+    for (const k of keys)
+        assertNoLoneSurrogate(k, `${path} key`);
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k], `${path}.${k}`)}`).join(",")}}`;
 }

package/dist/cli.js

@@ -258,6 +258,18 @@ async function cmdInit(agentId, opts = {}) {
     }
     const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
     const registerBody = JSON.stringify({ agentId, did: localDid, ...(sourceSystem ? { sourceSystem } : {}) });
+    let envPrepared = false;
+    const prepareEnvForWrite = () => {
+        if (envPrepared)
+            return;
+        envPrepared = true;
+        ensureGitignore();
+        if (opts.force && existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId) {
+            const backup = `.env.${existingEnv.DECIDIO_AGENT_ID.replace(/[^\w.-]/g, "_")}.bak`;
+            writeSecretFile(backup, readFileSync(ENV_PATH, "utf8"));
+            log(`✔ backed the previous agent's .env up to ${backup} (its key would otherwise be unrecoverable)`);
+        }
+    };
     let session = null;
     let r = await api("/api/agents/register", { method: "POST", body: registerBody });
     if (r.status === 401 || r.status === 403) {
@@ -288,6 +300,8 @@ async function cmdInit(agentId, opts = {}) {
         did = r.body?.did;
         privateKey = localKey;
         log(`✔ registered (did ${did}) — key generated locally; only the public half went to Decidio`);
+        prepareEnvForWrite();
+        upsertEnv({ DECIDIO_AGENT_ID: agentId, DECIDIO_AGENT_DID: did ?? localDid, DECIDIO_AGENT_KEY: localKey });
     }
     else {
         err(`✘ registration failed (${r.status}): ${JSON.stringify(r.body)}`);
@@ -310,7 +324,7 @@ async function cmdInit(agentId, opts = {}) {
         }
         else if (session) {
             err(`✘ could not mint the agent's API token (${mint.status}): ${JSON.stringify(mint.body)}`);
-            err(`  Without it the SDK has no runtime credential. Fix the cause above and re-run init — it's safe to repeat.`);
+            err(`  Without it the SDK has no runtime credential. The agent IS registered and its key is saved in ${ENV_PATH} — fix the cause above and re-run init; it will reuse that key and mint again.`);
             return 1;
         }
         else {
@@ -331,12 +345,7 @@ async function cmdInit(agentId, opts = {}) {
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     if (tokenJti)
         envOut.DECIDIO_TOKEN_JTI = tokenJti;
-    ensureGitignore();
-    if (opts.force && existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId) {
-        const backup = `.env.${existingEnv.DECIDIO_AGENT_ID.replace(/[^\w.-]/g, "_")}.bak`;
-        writeSecretFile(backup, readFileSync(ENV_PATH, "utf8"));
-        log(`✔ backed the previous agent's .env up to ${backup} (its key would otherwise be unrecoverable)`);
-    }
+    prepareEnvForWrite();
     upsertEnv(envOut);
     for (const [k, v] of Object.entries(envOut))
         process.env[k] = v;
@@ -358,8 +367,9 @@ async function cmdInit(agentId, opts = {}) {
     log(`       { mode: "blocking" },   // blocking = watch it happen live; durable is the production mode`);
     log(`     );`);
     log("");
-    log(`     const result = await payInvoice({ id: "INV-2026-001", amount: 86_000 });`);
-    log(`     console.log("executed after approval:", result);`);
+    log(`     const { value, confirmation } = await payInvoice({ id: "INV-2026-001", amount: 86_000 });`);
+    log(`     console.log("executed after approval:", value);`);
+    log(`     console.log("Decidio recorded it as:", confirmation.evidenceTier);`);
     log("");
     log("  2. Run it, approve it, watch it complete:");
     log("");
@@ -411,7 +421,7 @@ async function cmdDoctor() {
             if (typeof payload?.exp === "number") {
                 const msLeft = payload.exp * 1000 - Date.now();
                 const days = Math.floor((msLeft + 60_000) / 86_400_000);
-                const left = msLeft < 86_400_000 ? `${Math.max(1, Math.floor(msLeft / 3_600_000))} hour(s)` : `${days} day(s)`;
+                const left = msLeft < 86_400_000 ? `${Math.max(1, Math.floor(msLeft / 3_600_000))} hour(s)` : `${Math.round(msLeft / 86_400_000)} day(s)`;
                 const daysRounded = Math.round(msLeft / 86_400_000);
                 if (msLeft < 0)
                     line(false, `agent token: EXPIRED ${-days} day(s) ago — re-run \`npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}\` to mint a fresh one.`);
@@ -577,12 +587,18 @@ async function cmdReceipt(id, jsonMode = false) {
     const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
     const conf = detail.body?.record?.confirmation;
     const issuer = r.body?.issuer;
+    const resolved = r.body?.resolved;
     if (jsonMode) {
-        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed, issuer: issuer ?? null }, null, 2));
+        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed, issuer: issuer ?? null, ...(resolved ? { resolved } : {}) }, null, 2));
         return 0;
     }
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
+    if (resolved && Object.keys(resolved).length) {
+        log(`  Resolved for you (${Object.keys(resolved).length} field${Object.keys(resolved).length === 1 ? "" : "s"} your access covers — the FILE keeps the tokens, so it stays verifiable and safe to hand on):`);
+        for (const [tok, val] of Object.entries(resolved))
+            log(`    ${tok}  →  ${val}`);
+    }
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     if (issuer) {
         log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
@@ -656,6 +672,10 @@ async function cmdQuickstart(opts = {}) {
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
+    const envFile = readEnvFile().DECIDIO_AGENT_KEY ? ".env.quickstart" : ENV_PATH;
+    if (!assertNotTracked(envFile))
+        return 1;
+    ensureGitignore();
     let agentId = `quickstart-${randomBytes(5).toString("hex")}`;
     log(`① Registering agent "${agentId}"…`);
     const { did, privateKeyBase64 } = generateKeypair();
@@ -690,30 +710,36 @@ async function cmdQuickstart(opts = {}) {
         DECIDIO_WORKSPACE_ID: mint.body.workspaceId ?? "",
         ...(mint.body.jti ? { DECIDIO_TOKEN_JTI: mint.body.jti } : {}),
     };
-    let envFile = ENV_PATH;
-    if (readEnvFile().DECIDIO_AGENT_KEY) {
-        envFile = ".env.quickstart";
-        if (!assertNotTracked(envFile))
-            return 1;
-        ensureGitignore();
+    if (envFile !== ENV_PATH) {
         if (existsSync(envFile)) {
             const prev = readFileSync(envFile, "utf8");
             const prevId = prev.match(/^DECIDIO_AGENT_ID=(.+)$/m)?.[1];
+            const prevJti = prev.match(/^DECIDIO_TOKEN_JTI=(.+)$/m)?.[1];
             if (prevId && prevId !== agentId) {
-                const bak = `.env.quickstart.${prevId.replace(/[^\w.-]/g, "_")}.bak`;
-                writeSecretFile(bak, prev);
-                log(`  ✔ previous tour agent (${prevId}) backed up to ${bak} — its key would otherwise be unrecoverable (one backup PER agent: serial tours never clobber an earlier backup)`);
+                if (prevJti) {
+                    const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(prevJti)}`, { method: "DELETE" }, session);
+                    if (rv.status >= 200 && rv.status < 300)
+                        log(`  ✔ the previous tour agent (${prevId}) had its token REVOKED before this tour replaced it — no live credential is left behind`);
+                    else
+                        log(`  ⚠ could not revoke the previous tour's token (jti ${prevJti}, ${rv.status}) — revoke it by hand: npx @decidio/sdk tokens revoke ${prevJti}`);
+                }
+                else {
+                    log(`  ⚠ the previous tour file carried no revocation id, so its token (if any) must be revoked from your Decidio app.`);
+                }
             }
         }
         writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
         log(`  ✔ this directory already has an agent in .env — tour credentials went to ${envFile} (your agent is untouched)`);
     }
     else {
-        if (!assertNotTracked(ENV_PATH))
-            return 1;
-        ensureGitignore();
         upsertEnv(envOut);
     }
+    const failTour = async (code) => {
+        log("");
+        log("  The tour did not complete — cleaning up the credentials it created:");
+        await quickstartCleanup(session, envFile).catch(() => { });
+        return code;
+    };
     log(`  ✔ key generated locally (public half registered) · 7-day floor-limited token minted${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ""} · ${envFile} written`);
     log("");
     log(`② Gating a demo action — the tour runs this (blocking mode: watch it live):`);
@@ -740,15 +766,15 @@ async function cmdQuickstart(opts = {}) {
         err(`✘ this workspace's governed-action allowance is used up${earlyError.limit != null ? ` (${earlyError.limit} actions/hour on lab workspaces)` : ""}.`);
         err(`  Nothing was routed or executed — the cap is the sandbox protecting itself, not a fault${earlyError.resetAt ? `. It resets ${earlyError.resetAt}` : ""}.`);
         err(`  Re-run the tour after the reset (or talk to us about a production workspace).`);
-        return 1;
+        return failTour(1);
     }
     if (!decisionId && earlyError) {
         err(`✘ the gate refused before routing: ${earlyError?.message ?? earlyError}`);
-        return 1;
+        return failTour(1);
     }
     if (!decisionId) {
         err("✘ the gate did not route within 30s — check connectivity (npx @decidio/sdk doctor) and re-run.");
-        return 1;
+        return failTour(1);
     }
     log(`  ✔ $86,000 payInvoice ROUTED to a human (decision ${decisionId}) — this agent has no auto-approve rule,`);
     log(`    so deny-by-default sends everything to a person. Nothing executes until someone decides.`);
@@ -776,29 +802,35 @@ async function cmdQuickstart(opts = {}) {
         log("");
         log("   (exit 3 = the tour stopped at the human moment. Nothing executed and no receipt was");
         log("    written, so this run is deliberately not reported as a completed tour.)");
+        log("");
+        log(`   NOTE: this tour's credentials are still live in ${envFile} (a 7-day token + the agent's`);
+        log(`   key), because the decision above is still waiting for you. Once you have approved it —`);
+        log(`   or if you abandon the tour — remove them: npx @decidio/sdk quickstart cleanup`);
         process.exit(3);
     }
     const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
     if (!(ap.status >= 200 && ap.status < 300)) {
         err(`✘ approve failed (${ap.status}): ${JSON.stringify(ap.body)}`);
-        return 1;
+        return failTour(1);
     }
     log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
-    let result;
+    let done;
     try {
-        result = await running;
+        done = await running;
     }
     catch (e) {
         err(`✘ the gated call did not complete: ${e?.message ?? e}`);
-        return 1;
+        return failTour(1);
     }
-    log(`  ✔ your function executed AFTER approval: ${JSON.stringify(result)}`);
+    log(`  ✔ your function executed AFTER approval: ${JSON.stringify(done.value)}`);
+    if (done.confirmation?.evidenceTier)
+        log(`    …and the call itself told you what was recorded: confirmation.evidenceTier = ${done.confirmation.evidenceTier}`);
     log("");
     log("④ Downloading the sealed Authority Receipt and verifying it OFFLINE…");
     const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
     if (!(rec.status >= 200 && rec.status < 300) || !rec.body?.credential) {
         err(`✘ receipt fetch failed (${rec.status})`);
-        return 1;
+        return failTour(1);
     }
     const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
@@ -838,9 +870,8 @@ async function cmdQuickstart(opts = {}) {
         doCleanup = true;
         log(`\nAutomated run: cleaning the tour up (pass --keep-agent to keep the agent + token).`);
     }
-    if (doCleanup)
-        await quickstartCleanup(session, envFile);
-    return v.valid ? 0 : 1;
+    const cleanupCode = doCleanup ? await quickstartCleanup(session, envFile) : 0;
+    return v.valid ? (cleanupCode || 0) : 1;
 }
 async function quickstartCleanup(session, envFile) {
     const env = (() => {
@@ -1009,6 +1040,8 @@ const USAGE = `decidio — the Decidio SDK command line
                                        at the routed decision; --auto-approve-demo for CI, labeled
                                        automated; ends with a keep-or-cleanup choice)
   npx @decidio/sdk quickstart cleanup  revoke the tour's token + delete its local credentials
+  npx @decidio/sdk quickstart --auto-approve-demo   headless tour; cleans up after itself
+                                       (add --keep-agent to KEEP the tour agent + token)
   npx @decidio/sdk tokens list [--mine]   agent tokens with status (active/expired/REVOKED) by
                                        jti — token values are never re-shown; the list is
                                        workspace-wide, --mine narrows to this directory's agent

package/dist/errors.d.ts

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