@decidio/sdk 0.1.5 → 0.1.6

package/README.md

@@ -192,8 +192,21 @@ also allow-list resume hosts (default-deny). That's operator territory: if you r
 Decidio (or we run a pilot with you), the webhook is set up then. Against the hosted sandbox,
 use the worker — a webhook secret your server never learned would (correctly) fail closed.
 
-Either way, re-execution is **single-use** — the parked entry is claimed on completion, so a
-duplicate signal can't double-write.
+Either way, re-execution is **single-use on the happy path**: the parked entry is claimed before
+execution and deleted on success, so a duplicate signal finds nothing to replay. Honest edge — if
+your action succeeds but the process dies *before* the entry is cleared, the claim can be retried
+(robust crash-recovery of stale claims is on the roadmap), so make your downstream action
+idempotent if you need exactly-once under crashes.
+
+**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
+modified, its signature stripped, or the file swapped into another decision's slot. That defends
+against tampering by anything lacking your agent's key — note a *fully compromised agent host*
+can bypass the guard entirely (it holds both the key and the function), so the durable guarantee
+that closes that gap is server-sealed argument binding, auditable in the receipt itself, which is
+on the roadmap. **Upgrading from ≤0.1.5:** entries parked by an older version carry no signature
+and are refused once your agent has a key — drain pending approvals before upgrading, or delete
+the parked files and re-run those actions.
 
 ### Already on a durable engine? Use its native wait
 

package/dist/adapters/_gate.d.ts

@@ -7,7 +7,5 @@ export interface GateAuth {
 }
 export declare function gateAuthorize(config: GuardConfig, ctx: ApprovalContext): Promise<GateAuth>;
 export declare function gateConfirm(config: GuardConfig, decisionId: string, result: unknown): Promise<void>;
-/** 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. */
 export declare function assertVerdict(verdict: string, decisionId: string, reason?: string): void;

package/dist/adapters/_gate.js

@@ -1,15 +1,7 @@
-// Shared adapter gate logic (TS) — the thin-adapter rule in code. Every engine adapter
-// reuses these gate calls + verdict handling; only the suspend/resume translation
-// differs. Pure/testable so the offline smoke covers our logic; the engine-primitive
-// call in each adapter is a thin one-liner verified by typecheck against real types.
 import { DecidioBlockedError, DecidioRejectedError, signBoundProof, signConfirm } from "../index.js";
 export async function gateAuthorize(config, ctx) {
     const f = config.fetchImpl ?? fetch;
-    // Fall back to the resume controller's URL (matches the core wrapper) so an adapter
-    // decision carries a callback URL even when only resume.resumeUrl was set.
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
-    // Sign the bound identity proof like the core wrapper, so an adapter-path agent can PROVE
-    // its identity and auto-approve (not just route). No key → unsigned → server routes.
     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;
@@ -29,10 +21,7 @@ export async function gateAuthorize(config, ctx) {
 export async function gateConfirm(config, decisionId, result) {
     const f = config.fetchImpl ?? fetch;
     try {
-        // Sign the confirm too (bound to {action:"confirm", scope:decisionId}) so the adapter path
-        // earns application_confirmed; without a key the server caps it at agent_asserted.
         const requesterIdentity = signConfirm(decisionId, config);
-        // Same no-silent-downgrade rule as the inline wrap (guard equivalent-path catch).
         if (!requesterIdentity)
             console.warn(`[decidio] execution evidence for ${decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID to earn application_confirmed.`);
         const res = await f(config.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
@@ -40,8 +29,6 @@ export async function gateConfirm(config, decisionId, result) {
             headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
             body: JSON.stringify({ decisionId, capturedResponse: result ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
         });
-        // fetch only rejects on network error — surface a non-2xx (auth/500) too. Best-effort:
-        // log, don't throw (the action already happened).
         if (!res.ok)
             console.warn(`[decidio] confirm returned ${res.status} (action succeeded)`);
     }
@@ -49,11 +36,9 @@ export async function gateConfirm(config, decisionId, result) {
         console.warn(`[decidio] confirm failed (action succeeded): ${e.message}`);
     }
 }
-/** Normalize a resume payload ({verdict} | "approved" | ...) to a verdict string. */
 export function verdictFrom(payload) {
     return (payload && typeof payload === "object" ? payload.verdict : payload) ?? "";
 }
-/** Throw the right error for a non-approving verdict; return for approved/auto_approved. */
 export function assertVerdict(verdict, decisionId, reason) {
     if (verdict === "approved" || verdict === "auto_approved")
         return;

package/dist/adapters/langgraph.d.ts

@@ -1,9 +1,6 @@
 import { Command } from "@langchain/langgraph";
 import { type GuardConfig, type ApprovalContext } from "../index.js";
-/** Gate `run()` behind Decidio inside a LangGraph node. */
 export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>): 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: {
     verdict?: string;
     reason?: string;

package/dist/adapters/langgraph.js

@@ -1,19 +1,11 @@
-// @decidio/sdk/langgraph — durable suspend via LangGraph's native `interrupt()`.
-// `interrupt` finds the running graph itself (no handle needed), so the gate drops into
-// a node: authorize → on route, interrupt() durably pauses (the checkpointer persists;
-// the process can die) → on resume (Command(resume={verdict})) run the agent's own
-// action + confirm. Decidio is the approval system; the host bridges its webhook to the
-// graph resume (decidioResumeCommand). Requires @langchain/langgraph (optional peer dep).
 import { interrupt, Command } from "@langchain/langgraph";
 import { DecidioBlockedError } from "../index.js";
 import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict } from "./_gate.js";
-/** Gate `run()` behind Decidio inside a LangGraph node. */
 export async function decidioGate(config, ctx, run) {
     const auth = await gateAuthorize(config, ctx);
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
-        // Durable pause. On resume, interrupt() returns the Command(resume=...) payload.
         const resumed = interrupt({ decidio: { decisionId: auth.decisionId, action: ctx.action, amount: ctx.amount, scope: ctx.scope } });
         assertVerdict(verdictFrom(resumed), auth.decisionId, resumed?.reason);
     }
@@ -21,8 +13,6 @@ export async function decidioGate(config, ctx, run) {
     await gateConfirm(config, auth.decisionId, result);
     return result;
 }
-/** 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 function decidioResumeCommand(body) {
     return new Command({ resume: { verdict: body.verdict, reason: body.reason } });
 }

package/dist/adapters/openai.d.ts

@@ -14,13 +14,9 @@ export interface Pending {
     item: ToolApprovalItem;
     decisionId: string;
 }
-/** Ask Decidio for each pending tool-approval on a RunState.
- *  proceed → state.approve(item); block → state.reject(item); route → pending (a human
- *  decides via Decidio; the host parks state.toString() + resumes via applyResume). */
 export declare function gateInterruptions(config: GuardConfig, state: RunStateLike, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<{
     resolved: Resolved[];
     pending: Pending[];
 }>;
-/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString). */
 export declare function applyResume(state: RunStateLike, item: ToolApprovalItem, verdict: string): void;
 export {};

package/dist/adapters/openai.js

@@ -1,23 +1,4 @@
-// @decidio/sdk/openai — gate OpenAI Agents SDK tool-approval interruptions through
-// Decidio, with durable suspend via the SDK's native RunState serialization.
-//
-// The Agents loop surfaces tool approvals on the RunState (state.getInterruptions());
-// you state.approve(item)/reject(item) then resume with run(agent, state). RunState
-// serializes (state.toString() / RunState.fromString(agent, s)) — that's the durability:
-// 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);
-//   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);
-//   //   applyResume(state, item, verdict); result = await run(agent, state);
-//
-// Duck-typed on the state/item (no hard @openai/agents import) so it stays thin.
 import { gateAuthorize } from "./_gate.js";
-/** Ask Decidio for each pending tool-approval on a RunState.
- *  proceed → state.approve(item); block → state.reject(item); route → pending (a human
- *  decides via Decidio; the host parks state.toString() + resumes via applyResume). */
 export async function gateInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
@@ -36,7 +17,6 @@ export async function gateInterruptions(config, state, describe) {
     }
     return { resolved, pending };
 }
-/** Apply a Decidio verdict to a resumed RunState (after RunState.fromString). */
 export function applyResume(state, item, verdict) {
     if (verdict === "approved" || verdict === "auto_approved")
         state.approve(item);

package/dist/adapters/temporal.d.ts

@@ -1,7 +1,6 @@
 import { type GuardConfig, type ApprovalContext } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 export declare const decidioResumeSignal: import("@temporalio/workflow").SignalDefinition<[string, string, (string | undefined)?]>;
-/** Call inside the workflow to wire the resume signal; returns the verdict store. */
 export declare function installDecidioSignal(): Map<string, {
     verdict: string;
     reason?: string;

package/dist/adapters/temporal.js

@@ -1,19 +1,7 @@
-// @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
-// Decidio resume signal. Strongest durability (the workflow survives worker restarts for
-// days); the agent's action runs on resume. Requires @temporalio/workflow (optional peer).
-//
-// Inside your workflow:
-//   const verdicts = installDecidioSignal();                 // wires the resume signal
-//   const out = await decidioGate(config, ctx, () => createOpp(o), verdicts, {
-//     authorize: () => executeActivity(authorizeActivity, ...),   // HTTP belongs in activities
-//     confirm:   (id, r) => executeActivity(confirmActivity, ...),
-//   });
-// Decidio's webhook bridges to: handle.signal(decidioResumeSignal, decisionId, verdict, reason)
 import { condition, defineSignal, setHandler } from "@temporalio/workflow";
 import { DecidioBlockedError } from "../index.js";
 import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict } from "./_gate.js";
 export const decidioResumeSignal = defineSignal("decidioResume");
-/** Call inside the workflow to wire the resume signal; returns the verdict store. */
 export function installDecidioSignal() {
     const verdicts = new Map();
     setHandler(decidioResumeSignal, (decisionId, verdict, reason) => { verdicts.set(decisionId, { verdict, reason }); });
@@ -24,7 +12,7 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
-        await condition(() => verdicts.has(auth.decisionId)); // durable wait on the signal
+        await condition(() => verdicts.has(auth.decisionId));
         const v = verdicts.get(auth.decisionId);
         assertVerdict(verdictFrom(v), auth.decisionId, v.reason);
     }

package/dist/cli.js

@@ -1,23 +1,4 @@
 #!/usr/bin/env node
-// @decidio/sdk CLI — the on-ramp. Run via `npx @decidio/sdk <cmd>` (or tsx in-repo).
-//   init [agentId]   sign in, register the agent, mint its API token, write .env
-//   doctor           check config + connectivity + durability readiness
-//   approvals        list pending agent approvals; `approvals approve|reject <id> [reason]`
-//   receipt <id>     download a sealed decision's Authority Receipt to a .json file
-//   dev [--target U] signal-only relay: forwards Decidio's webhook to your local agent URL
-//
-// TWO TOKEN KINDS, deliberately (self-serve design 2026-08-28): commands that ADMINISTER a
-// workspace (init's register+mint, approvals, receipt) need the owner's SESSION token — acquired
-// interactively per run or from DECIDIO_SESSION_TOKEN, held in memory, NEVER written to disk.
-// What lands in .env as DECIDIO_API_TOKEN is the floor-limited AGENT token the runtime SDK
-// needs (it can call /agent/* and nothing else). A session-capable secret must never live in
-// an agent host's .env — that was the pre-publish design's hole.
-//
-// MESSAGE DISCIPLINE (founder bar 2026-08-29, from the Codex acceptance run): every failure
-// tells the developer WHAT happened, WHY, and the EXACT next command. Every success says what
-// changed, where, and what to do next. No stack traces for expected failures; no green ✔ for a
-// no-op (the replay-approve bug: the server's idempotent alreadyResolved was reported as a
-// fresh success — an authority CLI may never dress a no-op as an action).
 import { readFileSync, writeFileSync, existsSync, appendFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
@@ -34,8 +15,6 @@ const VERSION = (() => {
         return "unknown";
     }
 })();
-// ---- environment: load the CWD .env FIRST (Codex finding: init writes .env, but the next
-// command ignored it and pointed at localhost). Process env always wins — .env only fills gaps.
 function readEnvFile() {
     const out = {};
     if (existsSync(".env"))
@@ -47,9 +26,6 @@ function readEnvFile() {
     return out;
 }
 for (const [k, v] of Object.entries(readEnvFile())) {
-    // NEVER autoload the session token from disk: the whole design splits session (memory-only)
-    // from the floor-limited agent token (.env). Silently honoring a parked session token would
-    // reward exactly the credential-at-rest the split exists to prevent (guard catch 2026-08-29).
     if (k === "DECIDIO_SESSION_TOKEN") {
         console.log("⚠ ignoring DECIDIO_SESSION_TOKEN found in .env — session tokens belong in your shell or CI secret store, never on disk. Remove that line; export it in the shell instead.");
         continue;
@@ -57,17 +33,11 @@ for (const [k, v] of Object.entries(readEnvFile())) {
     if (process.env[k] === undefined)
         process.env[k] = v;
 }
-// `quickstart` is the zero-config guided tour: with no DECIDIO_API_URL anywhere it targets the
-// hosted sandbox (and says so); every other command keeps the localhost dev default.
 const IS_QUICKSTART = process.argv[2] === "quickstart";
 const API = (process.env.DECIDIO_API_URL ?? (IS_QUICKSTART ? "https://decidio-api.onrender.com" : "http://localhost:4000")).replace(/\/$/, "");
-// Token is read AT CALL TIME, not captured at import: init mints a fresh agent token mid-run and
-// its closing doctor must probe with THAT, not the pre-init env (round-3 Codex catch — the stale
-// capture made init's own doctor print "token: REJECTED" seconds after a successful mint).
 const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
-/** Fetch wrapper that turns transport failures into guidance instead of a stack trace. */
 async function api(path, init = {}, bearer) {
     const auth = bearer ?? TOKEN();
     let res;
@@ -102,10 +72,8 @@ function upsertEnv(updates) {
     const body = Object.entries(merged).map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
     writeFileSync(ENV_PATH, body);
 }
-/** Keep secrets out of git without nagging: append the two entries to .gitignore when they're
- *  not already covered. Creating the file in a non-git directory is harmless. */
 function ensureGitignore() {
-    const entries = [".env", ".decidio-pending/"];
+    const entries = [".env", ".env.quickstart", ".decidio-pending/"];
     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)
@@ -113,12 +81,10 @@ function ensureGitignore() {
     appendFileSync(".gitignore", (existing && !existing.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n");
     log(`✔ added ${missing.join(" + ")} to .gitignore (your agent key and parked actions stay out of git)`);
 }
-// ---- interactive input (session sign-in) ---------------------------------------------------
 function ask(question, mute = false) {
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
         if (mute) {
-            // Hide password echo: after the prompt renders, swallow subsequent output writes.
             const anyRl = rl;
             const write = anyRl._writeToOutput?.bind(rl);
             anyRl._writeToOutput = (s) => { if (s.includes(question))
@@ -128,14 +94,9 @@ function ask(question, mute = false) {
             process.stdout.write("\n"); resolve(answer.trim()); });
     });
 }
-/** Owner SESSION token, memory-only. Sources in order: DECIDIO_SESSION_TOKEN env, interactive
- *  email+password (`/demo/login`), pasted sign-in link (`/demo/login-consume` — for the
- *  password-less accounts the welcome flow creates). Never persisted. */
 async function acquireSession(purpose) {
     if (process.env.DECIDIO_SESSION_TOKEN)
         return process.env.DECIDIO_SESSION_TOKEN;
-    // Same rule the server applies to resume URLs: credentials never ride plaintext http to a
-    // non-loopback host. Refuse before prompting, not after collecting a password.
     if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
         log(`✘ refusing to send sign-in credentials over plaintext http to ${API}.`);
         log(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
@@ -179,14 +140,10 @@ async function acquireSession(purpose) {
 }
 async function cmdInit(agentId) {
     log(`Registering agent "${agentId}" with Decidio at ${API}…`);
-    // CLIENT-SIDE KEYGEN: generate the Ed25519 keypair LOCALLY and register only the PUBLIC
-    // did:key. The private key NEVER crosses the wire — it goes straight to this host's env.
     const existingKey = readEnvFile().DECIDIO_AGENT_KEY;
     const sourceSystem = process.env.DECIDIO_SOURCE_SYSTEM || readEnvFile().DECIDIO_SOURCE_SYSTEM;
     const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
     const registerBody = JSON.stringify({ agentId, did: localDid, ...(sourceSystem ? { sourceSystem } : {}) });
-    // First try whatever bearer the env already carries (the local-dev / operator path — a static
-    // admin token, or dev-open auth). On 401/403 fall through to the self-serve session flow.
     let session = null;
     let r = await api("/api/agents/register", { method: "POST", body: registerBody });
     if (r.status === 401 || r.status === 403) {
@@ -197,10 +154,6 @@ async function cmdInit(agentId) {
     }
     let did, privateKey;
     if (r.status === 409) {
-        // Already registered to a server-held did. WITHOUT the original private key on this machine
-        // this is a HARD STOP, not a degraded continue (round-3 Codex catch: init used to write a
-        // keyless .env and print happy-path next steps — every request then routed unproven and
-        // execution evidence silently capped at agent_asserted).
         did = r.body?.did;
         if (existingKey) {
             log(`• "${agentId}" is already registered in this workspace (did ${did}) — reusing it with the DECIDIO_AGENT_KEY already in .env.`);
@@ -227,10 +180,6 @@ async function cmdInit(agentId) {
         log(`  Fix the cause above and re-run — init is safe to repeat.`);
         return 1;
     }
-    // Mint the runtime credential: the floor-limited AGENT token (can call /agent/* only). This is
-    // what .env gets — the session token stays in memory and dies with this process. On boxes
-    // without the tester-lab fence (plain local dev) the mint endpoint refuses; that's fine —
-    // local dev auths with its existing env and we say so instead of failing the init.
     let agentToken, workspaceId;
     const mintBearer = session ?? TOKEN();
     if (mintBearer) {
@@ -256,15 +205,12 @@ async function cmdInit(agentId) {
     if (did)
         envOut.DECIDIO_AGENT_DID = did;
     if (privateKey)
-        envOut.DECIDIO_AGENT_KEY = privateKey; // written locally; never left this host
+        envOut.DECIDIO_AGENT_KEY = privateKey;
     if (agentToken)
-        envOut.DECIDIO_API_TOKEN = agentToken; // the FLOOR-LIMITED token — never the session
+        envOut.DECIDIO_API_TOKEN = agentToken;
     if (workspaceId)
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     upsertEnv(envOut);
-    // The closing doctor (and anything else this process does) must see what init just wrote —
-    // OVERWRITE process.env with the fresh values (round-3 Codex catch: doctor probed with the
-    // stale pre-init token and reported the mint it just watched as REJECTED).
     for (const [k, v] of Object.entries(envOut))
         process.env[k] = v;
     log(`✔ wrote ${ENV_PATH} — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
@@ -305,27 +251,17 @@ async function cmdDoctor() {
     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;
     line(!!secret, secret ? "webhook secret: set — operator-only transport (inactive against the hosted sandbox; the poll worker guard.worker() is the self-serve resume path)" : "webhook secret: MISSING — the resume webhook (operator deployments) would fail closed; init generates one");
-    // Signing key — REQUIRED to be ELIGIBLE for auto-approve. Whether anything auto-approves is
-    // the workspace policy's call, not this key's (Codex finding: the old wording claimed
-    // "auto-approve is in effect" while deny-by-default routed everything).
     const signing = (process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY) && (process.env.DECIDIO_AGENT_DID || env.DECIDIO_AGENT_DID);
     if (signing)
         log("✔ signing key: set — the agent can prove its identity, making it ELIGIBLE for policy auto-approve. Whether a rule matches is your workspace policy's decision; with no matching rule every request routes to a human (deny-by-default).");
     else
         log("⚠ 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.");
-    // Reachability and token role are SEPARATE checks (the old probe called any <500 green, so a
-    // wrong-kind token looked healthy). /api/health is unauthenticated truth about reachability;
-    // /api/records then classifies the token.
     const h = await api("/api/health", {}, "");
     line(h.status >= 200 && h.status < 300, `connectivity: API reachable (${h.status})`);
     const rec = await api("/api/records");
     if (rec.status >= 200 && rec.status < 300)
         log("✔ token scope: session/admin (init, approvals and receipt work from this env)");
     else if (rec.status === 401) {
-        // A 401 off the agent floor could also mean an INVALID token (Codex catch: don't
-        // false-green expiry). Disambiguate with a floor probe: a valid agent token gets 404 for an
-        // unknown decision (authorized, not found); an invalid one gets 401 again. A rejection here
-        // flips the overall verdict — "all green" after a red line was round 3's other doctor bug.
         const probe = await api("/agent/status/doctor-scope-probe");
         if (probe.status === 404)
             log("✔ token scope: agent floor — correct for the runtime SDK (approvals/receipt will ask you to sign in)");
@@ -340,8 +276,6 @@ async function cmdDoctor() {
     return ok ? 0 : 1;
 }
 async function cmdApprovals(sub, id, reason) {
-    // Approvals are a HUMAN act on the workspace — session scope, never the agent token. If the
-    // env's token is agent-floor (401 on /api/*), sign in interactively; memory-only as always.
     const jsonMode = sub === "--json";
     if (jsonMode)
         sub = undefined;
@@ -360,9 +294,6 @@ async function cmdApprovals(sub, id, reason) {
         }
         const r = await api(`/api/decisions/${encodeURIComponent(id)}/${sub === "approve" ? "approve" : "reject"}`, { method: "POST", body: JSON.stringify({ reason: reason ?? undefined }) }, bearer);
         if (r.status >= 200 && r.status < 300) {
-            // HONESTY over green checkmarks (Codex finding: the server resolves each decision exactly
-            // once and answers replays idempotently — a replay is a NO-OP and must read as one, never
-            // as a fresh approval). Non-zero exit so scripts can tell the difference.
             if (r.body?.alreadyResolved) {
                 log(`• ${id} was already resolved — nothing changed.`);
                 log(`  Decisions are single-use: a second ${sub} can never re-execute the action (that's the replay protection working).`);
@@ -392,7 +323,6 @@ async function cmdApprovals(sub, id, reason) {
     const cards = r.body?.cards ?? [];
     const pending = cards.filter((c) => c.isAgentRequest && c.status !== "sealed");
     if (jsonMode) {
-        // Stable machine output (round-3 ask): agents scripting the queue parse this, not prose.
         log(JSON.stringify(pending.map((c) => ({ decisionId: c.id, action: c.agentRequest?.action ?? null, amount: c.agentRequest?.amount ?? null, title: c.title ?? null })), null, 2));
         return 0;
     }
@@ -418,8 +348,6 @@ async function cmdReceipt(id, jsonMode = false) {
         log("  Find decision ids via `npx @decidio/sdk approvals` or in your Decidio app.");
         return 2;
     }
-    // Receipts are workspace data — session scope, like approvals. (The record-detail /verify
-    // route carries the credential; the plain record route does not — Codex finding.)
     let bearer;
     let r = await api(`/api/records/${encodeURIComponent(id)}/verify`);
     if (r.status === 401 || r.status === 403) {
@@ -439,11 +367,18 @@ async function cmdReceipt(id, jsonMode = false) {
         return 1;
     }
     const name = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
-    writeFileSync(name, JSON.stringify(r.body.credential, null, 2) + "\n");
-    log(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
-    // The credential seals at DECISION time (immutable), so execution evidence that arrived later
-    // lives on the record — surface the CURRENT tier here so the reader doesn't need a second
-    // lookup to see it (Codex catch).
+    const nextBytes = JSON.stringify(r.body.credential, null, 2) + "\n";
+    if (existsSync(name)) {
+        if (readFileSync(name, "utf8") !== nextBytes) {
+            log(`✘ ${name} already exists with DIFFERENT bytes — refusing to overwrite an audit artifact. Move it aside or delete it, then re-run.`);
+            return 1;
+        }
+        log(`• ${name} already exists (byte-identical — receipts are immutable); leaving it in place.`);
+    }
+    else {
+        writeFileSync(name, nextBytes);
+        log(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
+    }
     const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
     const conf = detail.body?.record?.confirmation;
     if (jsonMode) {
@@ -452,19 +387,12 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
-    // Emit EXACTLY the deterministic command we document (round-4 catch: the README and this hint
-    // disagreed, and bare npx re-probes the registry) — the verifier ships INSIDE this package.
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     log(`    npx @decidio/sdk verify ${name}`);
     log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
     log(`    npx @decidio/sdk verify --issuer <did:key:...> ${name}`);
     return 0;
 }
-// ---- verify (embedded) ----------------------------------------------------------------------
-/** Duplicate-key-refusing parse — the SAME semantics as the decidio-verify CLI (RFC 8785 §3.1:
- *  duplicate keys make different parsers disagree on which value is real; refuse instead).
- *  Conformance-locked: the cross-language runner asserts this door refuses the same vectors for
- *  the same reasons as decidio-verify and python -m decidio.verify. */
 function parseReceiptStrict(text, file) {
     const value = JSON.parse(text);
     const stack = [];
@@ -514,6 +442,10 @@ function parseReceiptStrict(text, file) {
 }
 function cmdVerify(argsIn) {
     const issIdx = argsIn.indexOf("--issuer");
+    if (issIdx >= 0 && (argsIn[issIdx + 1] === undefined || argsIn[issIdx + 1].startsWith("--"))) {
+        log("✘ --issuer needs a did:key value.");
+        return 2;
+    }
     const expectedIssuer = issIdx >= 0 ? argsIn[issIdx + 1] : undefined;
     const files = argsIn.filter((a, i) => !a.startsWith("--") && !(issIdx >= 0 && i === issIdx + 1));
     if (!files.length) {
@@ -544,7 +476,6 @@ function cmdVerify(argsIn) {
     }
     return allOk ? 0 : 1;
 }
-// ---- quickstart (the guided two-minute tour) ------------------------------------------------
 async function cmdQuickstart() {
     const t0 = Date.now();
     log("Decidio quickstart — gate an action, route it to a human, execute on approval, hold the proof.");
@@ -553,9 +484,6 @@ async function cmdQuickstart() {
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
-    // 1. A collision-proof agent, registered fresh every run (round-4 ask: idempotent sample
-    //    registration). Key generated locally; floor-limited token minted; .env written so the
-    //    take-away snippet works in this directory afterward.
     const agentId = `quickstart-${randomBytes(2).toString("hex")}`;
     log(`① Registering agent "${agentId}" (fresh name each run — no collisions)…`);
     const { did, privateKeyBase64 } = generateKeypair();
@@ -574,9 +502,6 @@ async function cmdQuickstart() {
         DECIDIO_AGENT_KEY: privateKeyBase64, DECIDIO_API_TOKEN: mint.body.token,
         DECIDIO_WORKSPACE_ID: mint.body.workspaceId ?? "", DECIDIO_WEBHOOK_SECRET: readEnvFile().DECIDIO_WEBHOOK_SECRET || randomBytes(32).toString("hex"),
     };
-    // NEVER clobber a real agent's key (guard catch: keys never leave this machine — overwriting
-    // .env's DECIDIO_AGENT_KEY orphans that agent irrecoverably). A directory that already holds
-    // one gets a TOUR-SCOPED env file instead.
     let envFile = ENV_PATH;
     if (readEnvFile().DECIDIO_AGENT_KEY) {
         envFile = ".env.quickstart";
@@ -589,11 +514,11 @@ async function cmdQuickstart() {
     ensureGitignore();
     log(`  ✔ key generated locally (public half registered) · floor-limited token minted · ${envFile} written`);
     log("");
-    // 2. Gate a demo action — the same one line you'd wrap your real function with.
-    log(`② Gating a demo action with ONE line — guard.protect(payInvoice, …):`);
+    log(`② Gating a demo action — the tour runs this (blocking mode: watch it live):`);
     log("");
     log(`     const payInvoice = guard.protect(payInvoiceRaw,`);
-    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }));`);
+    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }),`);
+    log(`       { mode: "blocking" });   // your real agent typically omits this — durable + a worker`);
     log("");
     let decisionId = "";
     const cfg = {
@@ -615,7 +540,6 @@ async function cmdQuickstart() {
     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("");
-    // 3. The human moment — approve right here, or from the Decidio app.
     if (process.stdin.isTTY) {
         await ask(`③ YOU are the approver. Press Enter to approve it here (or approve it in your Decidio queue first, then Enter): `);
     }
@@ -628,7 +552,6 @@ async function cmdQuickstart() {
         return 1;
     }
     log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
-    // 4. The blocking wrapper wakes and runs the agent's own function.
     let result;
     try {
         result = await running;
@@ -639,7 +562,6 @@ async function cmdQuickstart() {
     }
     log(`  ✔ your function executed AFTER approval: ${JSON.stringify(result)}`);
     log("");
-    // 5. The proof: download the receipt and verify it offline, all in-process.
     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) {
@@ -649,25 +571,24 @@ async function cmdQuickstart() {
     const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
     const v = verifyReceipt(rec.body.credential, undefined);
-    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding verified with NO network, no Decidio account)`);
+    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline; issuer UNPINNED — bind it with: npx @decidio/sdk verify --issuer <your workspace DID>)`);
     const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
     const tier = detail.body?.record?.confirmation?.status;
     if (tier)
-        log(`  ✔ execution evidence on the record: ${tier} — the wrapper's report was cryptographically bound to this agent`);
+        log(`  ✔ execution evidence on the record: ${tier} — the wrapper's signed report. (The receipt seals the DECISION; execution evidence accrues on the record — see the README.)`);
     log("");
     const secs = Math.round((Date.now() - t0) / 1000);
-    log(`Done in ${secs}s: gated → routed to a human → approved → executed once → sealed, verifiable proof in your hands.`);
+    log(`Done in ${secs}s: gated → routed to a human → approved → your function executed once → an authority-decision receipt you can verify offline.`);
     log("");
     log("Take it to your real agent — the .env here already works:");
     log(`  import { guard } from "@decidio/sdk";`);
     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("Next: the README's 7-step quickstart (durable mode, workers, adapters) · your queue at your Decidio app.");
+    log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}  ·  Next: the README's 7-step quickstart (durable, workers, adapters).`);
     return v.valid ? 0 : 1;
 }
 function cmdDev(target, port) {
-    // Signal-only relay: receive Decidio's webhook here (a stable URL) and forward it to
-    // your local agent's resume listener. Useful when the agent isn't directly reachable.
     log(`decidio dev relay on http://localhost:${port}/decidio/resume → forwarding to ${target}`);
     createServer((req, res) => {
         if (req.method !== "POST") {

package/dist/guard.d.ts

@@ -8,22 +8,14 @@ export interface GuardFacadeConfig {
     resumeUrl?: string;
     webhookSecret?: string;
     pendingDir?: string;
-    /** Local signing key (DECIDIO_AGENT_KEY) + public did (DECIDIO_AGENT_DID), from `init`.
-     *  When present the gate authorizes against a PROVEN identity, not a claimed label. */
     agentKey?: string;
     agentDid?: string;
-    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID). Bound into the signed proof (D-B3.6)
-     *  so a captured proof can't be replayed in another tenant. */
     workspaceId?: string;
-    /** Base URL of the Decidio app (DECIDIO_APP_URL) — used to deep-link a routed decision. */
     appUrl?: string;
     fetchImpl?: typeof fetch;
 }
 export interface ProtectOptions {
-    /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest/mcp)
-     *  live in @decidio/sdk/adapters and take the engine handle. */
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest" | "mcp";
-    /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
 }
 export declare class Guard {
@@ -31,13 +23,8 @@ export declare class Guard {
     resume?: ResumeController;
     constructor(config: GuardFacadeConfig, resume?: ResumeController);
     static fromEnv(): Guard;
-    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
     resumeHandler(): import("http").RequestListener;
-    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
     resumeFetchHandler(): (req: Request) => Promise<Response>;
-    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
-     *  any parked approval — so a suspended action survives a process restart. One line at startup.
-     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
     worker(opts?: {
         intervalMs?: number;
         timeoutMs?: number;
@@ -48,5 +35,4 @@ export declare class Guard {
     private ensureResume;
     protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
 }
-/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export declare const guard: Guard;