@decidio/sdk 0.2.1 → 0.3.0

package/README.md

@@ -2,6 +2,8 @@
 
 One line to put a human-or-policy approval gate in front of any AI-agent action — and get a signed, verifiable Authority Receipt for every decision, with execution evidence accruing on the record.
 
+`@decidio/sdk` is the client for Decidio — the system of record for enterprise authority, from OmniTwin Technologies.
+
 ## The two-minute tour
 
 ```bash
@@ -21,15 +23,17 @@ prints the approve command and exits rather than approve its own request (CI can
 
 ## Quickstart — seven steps to your first sealed receipt
 
-Under 30 minutes, no help needed. You'll need Node 20.6+, a terminal, and a Decidio workspace
-(request one at [decidioai.com](https://decidioai.com/#early-access) — the hosted sandbox is
-synthetic data, safe to experiment in — and it is ONE SHARED workspace: workspace-wide views
-like `tokens list` or `approvals` show every lab member's agents and decisions there, which is
-the shared-lab boundary working as designed; production workspaces are per-tenant). Lab
-workspaces have a **governed-action allowance**
-(currently 30 actions/hour); hitting it raises a typed `DecidioRateLimitError` naming the limit
-and reset time — nothing is routed or executed — and `tokens list` shows your remaining
-allowance any time.
+Under 30 minutes, no help needed. You'll need Node 20.6+ and a terminal.
+
+**You'll need a Decidio workspace.** → Request one at [decidioai.com](https://decidioai.com/#early-access)
+
+The hosted sandbox is synthetic data, safe to experiment in. Note it is ONE SHARED workspace:
+workspace-wide views like `tokens list` or `approvals` show every lab member's agents and
+decisions — the shared-lab boundary working as designed. Production workspaces are per-tenant.
+
+Lab workspaces have a **governed-action allowance** (currently 30 actions/hour); hitting it raises
+a typed `DecidioRateLimitError` naming the limit and reset time — nothing is routed or executed —
+and `tokens list` shows your remaining allowance any time.
 
 **PowerShell users** — the equivalents for every Bash idiom used below:
 
@@ -144,6 +148,17 @@ evidence is yours, not ours. To also prove *who* issued it, pin your workspace's
 record verify panel — or simply read it off the `receipt` command's output, which prints your
 workspace's issuer DID from the authenticated response so you never have to hunt for it).
 
+**What VALID means — and what it does not.** A pinned `VALID` proves the receipt's bytes were
+sealed by your workspace's issuer and are unaltered since. It does **not** prove the approved
+action ran. Execution is confirmed *after* the seal, and a sealed record is immutable, so the
+receipt's own `authority.result` and `confirmation.status` are a snapshot taken at seal time — a
+receipt for an approved-but-never-executed action verifies `VALID`, correctly. The verifier now
+prints those fields under `as sealed`, plus a note saying exactly this, so the distinction is on
+screen rather than left to inference. The check is **cryptographic, not semantic**: it does not
+evaluate business rules, timestamp plausibility, revocation, or whether a later record superseded
+this one. For current execution status, ask the issuer (`npx @decidio/sdk receipt <decisionId>`
+reports the live evidence tier).
+
 One receipt proves itself. Pass several files and their **ordering** is verified too — in
 **seal order** (each receipt's `prevHash` links to its predecessor's `contentHash`), which is
 the order decisions were *sealed*, not the order of their displayed decision numbers (two
@@ -255,8 +270,21 @@ catch (e) { console.log(e.name); }   // DecidioSuspendedError — expected, not
 ```
 
 Run `node --env-file=.env agent.mjs`, then `node --env-file=.env submit.mjs` once, approve from
-another terminal, and the running worker executes it. Now kill the worker, restart it, and
-approve: it still executes — and restarting created no second request. **If you can't declare the name at wrap time** (a dynamic
+another terminal, and the running worker executes it.
+
+To see recovery, the approval has to be waiting while nothing is running — so submit a **second**
+request with the worker stopped:
+
+1. Stop the worker (Ctrl-C).
+2. `node --env-file=.env submit.mjs` again — it parks; nothing is running to pick it up.
+3. Approve it from the other terminal. It stays parked, approved and unexecuted.
+4. Start the worker again: it executes that request exactly once, and restarting created no
+   duplicate.
+
+Step 2 is the one that is easy to skip: by the time you restart, the first request has already
+executed, so without a second submission there is nothing left to approve.
+
+**If you can't declare the name at wrap time** (a dynamic
 `describe`), register the raw function explicitly at startup instead —
 `guard.register("payInvoice", payInvoiceRaw)` — before calling `guard.worker()`. Without one of
 those two, a cold worker has an empty registry and reports `no_handler` (the parked action is
@@ -358,10 +386,30 @@ for (const item of await guard.resume.recover()) {
   console.log(item.state, item.decisionId, item.guidance);
 }
 // "executed_unreported" → guard.resume.reconfirm(id) re-sends the saved report (never re-runs)
-// "indeterminate"       → a process died mid-flight; reconcile downstream, do NOT blind-retry
+// "indeterminate"       → no outcome was recorded; check downstream, then reconcile. Never blind-retry
 // "parked"              → still waiting on a human; nothing has executed
 ```
 
+Two things `reconcile()` will refuse, because both would undo an authority decision rather than
+record one. **It refuses by returning, not by throwing** — check `reportRecorded`, and read
+`diagnostic` to see why:
+
+```js
+// A denial is final. There is no outcome to record — nothing ran — so neither outcome is accepted.
+const r = await guard.resume.reconcile(deniedId, { outcome: "not_committed" });
+r.reportRecorded;   // false — r.diagnostic says the decision was DENIED
+
+// A decision that is still `invoking` may be running the action at this moment. Releasing it would
+// let a second worker run the same approved action, so it takes an explicit assertion — from you,
+// after you have checked. Nothing here can see another machine's process table, so this is your
+// judgement, and it is stamped into the ledger as such.
+await guard.resume.reconcile(id, { outcome: "not_committed", reason: "…" });   // refused while invoking
+await guard.resume.reconcile(id, { outcome: "not_committed", reason: "…", workerStopped: true });  // released
+```
+
+`indeterminate` needs no such flag: the handler has already returned or thrown, so nothing is in
+flight — only the downstream result is unknown.
+
 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
@@ -396,6 +444,53 @@ imports none of them — install the engine you use alongside the SDK (`npm i in
 for engines you don't. Each adapter's shipped `.d.ts` header documents its wiring; `npx
 @decidio/sdk quickstart` is the fastest runnable end-to-end.
 
+
+## Upgrading from 0.2.x to 0.3.0
+
+0.3.0 is a breaking release. Every item below changes behaviour a 0.2.x caller may depend on, so
+none of it is left to be discovered at runtime.
+
+**If you wrote a custom `PendingStore`, it will fail to construct.** `markDiscarded(decisionId,
+verdict, reason?)` is now REQUIRED — it writes the tombstone that makes a denied decision
+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.
+
+**`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
+to a caller and mean opposite things, so a script reading `if (!(await recover()).length)` treated
+a permissions change as proof that nothing was outstanding. Wrap the call if you poll it.
+
+**`reconcile()` refuses two things it used to allow.** A DENIED decision cannot be reconciled on
+either outcome, and releasing a decision that is still `invoking` takes an explicit
+`workerStopped: true` — that is the one state where the handler may be running right now, and
+releasing it hands one approved action to two live workers. It refuses by RETURNING, not throwing:
+check `reportRecorded` and read `diagnostic`.
+
+**The adapters return a different shape.** `decidioGate` (LangGraph, Temporal) returns
+`ProtectedExecution` — `{ value, decisionId, confirmation }` — instead of the bare value.
+`decidioGateStep` (Inngest) renames `result` to `value` and carries `confirmation`.
+`gateInterruptions` is now `authorizeInterruptions` and returns `confirmationSupported: false`
+(the old name remains as a deprecated alias). Read `.value` where you previously read the result.
+
+**The transport rule refuses URLs it used to accept.** A gate URL must now be absolute and either
+https or an exact loopback host, whatever credentials the config holds. A relative or scheme-less
+`apiUrl` throws at startup — it used to pass on the reasoning that the shipped transport rejects
+it, which says nothing about a custom `fetchImpl`.
+
+**Decision ids are shape-checked.** Letters, digits, dot, dash and underscore, starting with a
+letter or digit, at most 128 characters, never trimmed. The server enforces the same grammar (it
+had none before 0.3.0, which is why the SDK was the stricter of the two). Ids Decidio issues are
+well inside it.
+
+**`/agent/confirm` can answer 409.** `TERMINALLY_DENIED` means a human refused the decision and
+your action appears to have run anyway; `NOT_AUTHORIZED` means there is no approved, sealed
+decision for evidence to attach to. Neither is a report failure and neither is retryable — the SDK
+raises `DecidioHttpError` with advice that says so, rather than the "only its report failed" note
+that fits every other confirm error.
+
 ## Engine adapters (BETA) — and Python too
 
 - **Engine adapters are BETA.** They share the core's gate semantics — the verdict allow-list,
@@ -406,6 +501,17 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
   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?
   The worker/webhook resume is the universal path and is not beta.
+- **One result shape on every door (0.3.0, breaking).** `decidioGate` (LangGraph, Temporal) and
+  `decidioGateStep` (Inngest) now return `{ value, decisionId, confirmation }` — the same
+  `ProtectedExecution` the core path returns. They used to hand back the bare value and discard what
+  Decidio recorded, so "it ran and was recorded" and "it ran and Decidio does not know" were the
+  same return value to a caller. Inngest keeps its `status`, because its durable path can end in
+  `rejected` or `blocked` without ever calling your action; its value field is `value`, not
+  `result`.
+  The OpenAI door is the exception and now says so: it was renamed `gateInterruptions` →
+  `authorizeInterruptions` and returns `confirmationSupported: false`. The OpenAI runtime executes
+  the tool itself, so this SDK never sees the return value and has nothing to attest — and an
+  ABSENT confirmation must not look like a failed one. The old name remains as a deprecated alias.
 - **Python twin:** `pip install decidio` exposes the identical `guard.protect` (plus the `@guard.approve` decorator, adapters, and the offline verifier); a conformance suite asserts both languages emit an identical request + receipt.
 
 ## CLI
@@ -421,7 +527,7 @@ for engines you don't. Each adapter's shipped `.d.ts` header documents its wirin
 - `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)
 - `receipt <id>` — download a sealed decision's Authority Receipt to a `.json` file
-- `verify [--issuer <did>] <file>...` — verify receipts offline (the canonical verifier; the standalone `@decidio/verify` package is the same implementation, for auditors who want zero Decidio dependency — the sdk's embedded copy is pinned to the previous release, so message wording may trail it one version; verdicts and semantics are conformance-locked identical). Unknown flags are refused, never ignored. Fully offline AND fully decoupled: it touches no network and reads no `.env` — a receipt verifies identically from an empty directory.
+- `verify [--issuer <did>] <file>...` — verify receipts offline (the canonical verifier; the standalone `@decidio/verify` package is the same implementation, for auditors who want zero Decidio dependency — the sdk depends on the verifier released alongside it, at the same version). Unknown flags are refused, never ignored. Fully offline AND fully decoupled: it touches no network and reads no `.env` — a receipt verifies identically from an empty directory.
 - `tokens list [--mine]` / `tokens revoke <jti>` — see and kill agent tokens (values are never re-shown; the jti is the revocation handle). Each row carries its status — `active`, `expired`, or `REVOKED <date>` — so the list confirms the revocations it performs; re-revoking is an honest no-op (exit 1). The list is workspace-wide (a shared workspace shows every member's agents); `--mine` narrows to this directory's agent
 - `quickstart cleanup` — revoke the tour's token and delete its local credentials. What stays, honestly: sealed records (permanent by design) and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap)
 - `dev [--target URL]` — local relay for the resume webhook (operator setups)
@@ -471,3 +577,12 @@ your queue.
 - **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.
+
+## Using this for real?
+
+The hosted sandbox is synthetic and shared. Production workspaces are per-tenant, with your own
+issuer key and receipts that verify offline against it.
+
+[decidioai.com](https://decidioai.com) · [Developer docs](https://decidioai.com/developers/) · [Request access](https://decidioai.com/#early-access)
+
+Built by OmniTwin Technologies.

package/dist/adapters/langgraph.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "@langchain/langgraph";
-import { type GuardConfig, type ApprovalContext } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution } from "../index.js";
 /**
  * @decidio/sdk/langgraph — durable suspend via LangGraph's native `interrupt()`.
  * `interrupt` finds the running graph itself (no handle needed), so the gate drops into
@@ -13,7 +13,7 @@ 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>, opts?: {
     evidence?: (r: R) => unknown;
-}): Promise<R>;
+}): Promise<ProtectedExecution<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

@@ -10,8 +10,8 @@ export async function decidioGate(config, ctx, run, opts) {
         assertVerdict(verdictFrom(resumed), auth.decisionId, resumed?.reason);
     }
     const result = await run();
-    await gateConfirm(config, auth.decisionId, result, opts?.evidence);
-    return result;
+    const confirmation = await gateConfirm(config, auth.decisionId, result, opts?.evidence);
+    return { value: result, decisionId: auth.decisionId, confirmation };
 }
 export function decidioResumeCommand(body) {
     return new Command({ resume: { verdict: body.verdict, reason: body.reason } });

package/dist/adapters/openai.d.ts

@@ -34,13 +34,23 @@ 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<{
+/** THIS DOOR AUTHORIZES; IT DOES NOT CONFIRM. Named `gateInterruptions` it looked like the other
+ *  `decidioGate*` functions, which all run the action and report what happened. This one cannot:
+ *  the OpenAI Agents runtime executes the tool itself, so the SDK never sees the return value and
+ *  has nothing to attest. Every other adapter now returns a `confirmation`; this one deliberately
+ *  returns `confirmationSupported: false` instead of an empty one, because an absent confirmation
+ *  and a failed confirmation must not look alike.
+ *
+ *  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 authorizeInterruptions(config: GuardConfig, state: RunStateLike, describe: (item: ToolApprovalItem) => ApprovalContext): Promise<{
     resolved: Resolved[];
     pending: Pending[];
+    confirmationSupported: false;
 }>;
+/** @deprecated Renamed to `authorizeInterruptions` in 0.3.0 — the old name read like the other
+ *  `decidioGate*` doors, which execute and confirm. This one only ever authorized. */
+export declare const gateInterruptions: typeof authorizeInterruptions;
 /** Apply a Decidio verdict to a resumed RunState (after RunState.fromString).
  *
  *  VALIDATES BEFORE MUTATING. `else state.reject(item)` treated every unrecognised string as a

package/dist/adapters/openai.js

@@ -1,6 +1,6 @@
 import { gateAuthorize, checkEngineVersion } from "./_gate.js";
 import { DecidioBlockedError } from "../index.js";
-export async function gateInterruptions(config, state, describe) {
+export async function authorizeInterruptions(config, state, describe) {
     const resolved = [];
     const pending = [];
     for (const item of state.getInterruptions()) {
@@ -18,8 +18,9 @@ export async function gateInterruptions(config, state, describe) {
         else
             throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)}`, auth.decisionId);
     }
-    return { resolved, pending };
+    return { resolved, pending, confirmationSupported: false };
 }
+export const gateInterruptions = authorizeInterruptions;
 export function applyResume(state, item, verdict) {
     if (verdict === "approved" || verdict === "auto_approved") {
         state.approve(item);

package/dist/adapters/temporal.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 /**
  * @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
@@ -32,4 +32,4 @@ export interface DecidioGateOpts<R = unknown> {
 export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>, verdicts: Map<string, {
     verdict: string;
     reason?: string;
-}>, opts?: DecidioGateOpts<R>): Promise<R>;
+}>, opts?: DecidioGateOpts<R>): Promise<ProtectedExecution<R>>;

package/dist/adapters/temporal.js

@@ -21,18 +21,23 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
         throw new DecidioBlockedError(`unhandled authorization verdict ${JSON.stringify(auth.decision)} — refusing to execute`, auth.decisionId);
     }
     const result = await run();
+    let confirmation;
     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 = {
+            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) {
             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.`);
         }
     }
     else {
-        await gateConfirm(config, auth.decisionId, result, opts?.evidence);
+        confirmation = await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     }
-    return result;
+    return { value: result, decisionId: auth.decisionId, confirmation };
 }
 checkEngineVersion("temporal");

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { userInfo } from "node:os";
 import { createServer } from "node:http";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
 import { generateKeypair, assertSafeTransport } from "./signing.js";
+import { hardenFile } from "./resume.js";
 import { withApproval, DecidioRateLimitError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
@@ -39,6 +39,14 @@ function readEnvFile() {
     return out;
 }
 const OFFLINE_CMD = ["verify", "--version", "-v", "-V", "version", "--help", "-h", "help", undefined].includes(process.argv[2]);
+if (!OFFLINE_CMD) {
+    readEnvFile();
+    if (envUnreadable) {
+        console.error(`✘ .env exists here but could not be read, so this command cannot know what is already configured in this directory.`);
+        console.error(`  Treating it as empty would risk overwriting an agent key that cannot be recovered. Fix the file's permissions (or move it aside) and run the command again. Nothing was changed.`);
+        process.exit(1);
+    }
+}
 if (!OFFLINE_CMD)
     for (const [k, v] of Object.entries(readEnvFile())) {
         if (k === "DECIDIO_SESSION_TOKEN") {
@@ -106,21 +114,9 @@ function writeSecretFile(path, body) {
         chmodSync(path, 0o600);
     }
     catch { }
-    if (process.platform === "win32") {
-        try {
-            execFileSync("icacls", [path, "/inheritance:r", "/grant:r", `${effectiveUser()}:F`], { stdio: "ignore" });
-        }
-        catch {
-            console.warn(`⚠ could not restrict ${path} to owner-only on this Windows volume — it keeps the directory's inherited permissions. For production, move these values to a secret manager.`);
-        }
-    }
-}
-function effectiveUser() {
-    try {
-        return userInfo().username;
-    }
-    catch {
-        return process.env.USERNAME ?? process.env.USER ?? "";
+    const why = hardenFile(path);
+    if (why) {
+        console.warn(`⚠ could not restrict ${path} to owner-only on this Windows volume (${why}) — it keeps the directory's inherited permissions. For production, move these values to a secret manager.`);
     }
 }
 function upsertEnv(updates) {
@@ -720,8 +716,11 @@ async function cmdQuickstart(opts = {}) {
                     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 {
+                        const carried = [...(prev.match(/^DECIDIO_ORPHANED_TOKEN_JTI=(.+)$/m)?.[1] ?? "").split(",").filter(Boolean), prevJti];
+                        envOut.DECIDIO_ORPHANED_TOKEN_JTI = [...new Set(carried)].join(",");
+                        log(`  ⚠ could not revoke the previous tour's token (jti ${prevJti}, ${rv.status}) — it is still LIVE. Its id is kept in ${envFile} as DECIDIO_ORPHANED_TOKEN_JTI, and \`quickstart cleanup\` will retry it; or revoke it by hand: npx @decidio/sdk tokens revoke ${prevJti}`);
+                    }
                 }
                 else {
                     log(`  ⚠ the previous tour file carried no revocation id, so its token (if any) must be revoked from your Decidio app.`);
@@ -859,6 +858,7 @@ async function cmdQuickstart(opts = {}) {
     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(`Built by OmniTwin — decidioai.com  ·  Putting this in front of real approvals? decidioai.com/#early-access`);
     let doCleanup = false;
     if (interactive) {
         const answer = await ask(`\nKeep this agent for development? [Enter = keep · c + Enter = clean up now]: `);
@@ -884,6 +884,23 @@ async function quickstartCleanup(session, envFile) {
             }
         return out;
     })();
+    const orphans = (env.DECIDIO_ORPHANED_TOKEN_JTI ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const stillOrphaned = [];
+    for (const jti of orphans) {
+        const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, session);
+        if (rv.status >= 200 && rv.status < 300)
+            log(`  ✔ orphaned token revoked (jti ${jti}) — it had survived an earlier replace`);
+        else {
+            stillOrphaned.push(jti);
+            err(`  ⚠ orphaned token ${jti} could NOT be revoked (${rv.status}) — it is still live.`);
+        }
+    }
+    if (stillOrphaned.length) {
+        err(`✘ ${stillOrphaned.length} orphaned token(s) are STILL LIVE and could not be revoked. Nothing was deleted; ${envFile} keeps their ids so you can retry:`);
+        for (const jti of stillOrphaned)
+            err(`    npx @decidio/sdk tokens revoke ${jti}`);
+        return 1;
+    }
     if (env.DECIDIO_TOKEN_JTI) {
         const rev = await api(`/api/workspace/agent-token/${encodeURIComponent(env.DECIDIO_TOKEN_JTI)}`, { method: "DELETE" }, session);
         if (rev.status >= 200 && rev.status < 300 && rev.body?.changed === false)
@@ -906,7 +923,7 @@ async function quickstartCleanup(session, envFile) {
         return 1;
     }
     if (existsSync(envFile)) {
-        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"]);
+        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 m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)=/);
             return m ? !TOUR_KEYS.has(m[1]) : line.trim() !== "";

package/dist/errors.js

@@ -1,6 +1,12 @@
 const RETRYABLE_STATUS = (status) => status === 408 || status === 429 || (status >= 500 && status !== 501);
-function sideEffectNote(endpoint) {
+function sideEffectNote(endpoint, code) {
     if (endpoint.startsWith("/agent/confirm")) {
+        if (code === "TERMINALLY_DENIED") {
+            return " A human DENIED this decision, and your action appears to have run anyway. Decidio recorded the refusal and will NOT attach execution evidence to a denied decision. Do NOT re-run it — investigate why the action executed without an approval.";
+        }
+        if (code === "NOT_AUTHORIZED") {
+            return " This decision is not an approved, sealed decision, so no execution evidence can attach to it yet. If your action already ran, it ran WITHOUT authority — do NOT re-run it; investigate. If you are confirming early, wait for the approval and confirm then.";
+        }
         return " Your action ALREADY RAN — only its report failed. Do NOT re-run it.";
     }
     if (endpoint.startsWith("/agent/status")) {
@@ -22,7 +28,7 @@ export class DecidioHttpError extends Error {
                 : retryable
                     ? ` — 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));
+            sideEffectNote(endpoint, typeof body?.code === "string" ? body.code : undefined));
         this.status = status;
         this.endpoint = endpoint;
         this.body = body;
@@ -44,7 +50,9 @@ export function decisionIdProblem(raw) {
         if (cp < 0x20 || cp === 0x7f)
             return "it contains control characters";
     }
-    if (raw.length > 256)
-        return `it is ${raw.length} characters long (limit 256)`;
+    if (raw.length > 128)
+        return `it is ${raw.length} characters long (limit 128)`;
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(raw))
+        return "it is not letters, digits, dot, dash or underscore starting with a letter or digit (an opaque id needs nothing else, and every other character is a way to make two different strings look like the same decision)";
     return null;
 }

package/dist/evidence.js

@@ -32,20 +32,22 @@ export function readConfirmResponse(body, opts) {
     if (!EVIDENCE_TIERS.includes(tier)) {
         return { reportRecorded: false, executionConfirmed: false, confirmationRetryable: false, reportJournalled: journalled, diagnostic: `the gate reported an evidence tier this SDK does not recognise (${JSON.stringify(tier)}) — refusing to treat it as evidence. Upgrade @decidio/sdk; your action DID run, and ${retry}` };
     }
-    const executionConfirmed = CONFIRMING.includes(tier);
+    const rpt = body?.executionReport;
+    const hasVerdict = !!rpt && typeof rpt === "object" && typeof rpt.verified === "boolean";
+    const proofExplicitlyFailed = hasVerdict && rpt.verified === false;
+    const executionConfirmed = CONFIRMING.includes(tier) && !proofExplicitlyFailed;
     const outcome = { reportRecorded: true, evidenceTier: tier, executionConfirmed, reportJournalled: journalled };
-    if (!executionConfirmed && opts.signed)
+    if (!executionConfirmed && !proofExplicitlyFailed && opts.signed)
         outcome.diagnostic = describeTierGap(opts.capturedResponse);
-    else if (!executionConfirmed)
+    else if (!executionConfirmed && !proofExplicitlyFailed)
         outcome.diagnostic = "no signing key is configured, so the gate capped this report at an unproven agent assertion. Run `npx @decidio/sdk init` to generate the agent's key and earn a confirming tier.";
-    const rpt = body?.executionReport;
-    if (rpt && typeof rpt === "object" && typeof rpt.verified === "boolean") {
+    if (hasVerdict) {
         outcome.executionReportVerified = rpt.verified;
         if (typeof rpt.reason === "string" && rpt.reason)
             outcome.executionReportReason = rpt.reason;
-        if (!rpt.verified) {
+        if (proofExplicitlyFailed) {
             const why = typeof rpt.reason === "string" && rpt.reason ? ` (${rpt.reason})` : "";
-            outcome.diagnostic = `${outcome.diagnostic ? outcome.diagnostic + " " : ""}The signed execution report did NOT verify${why} — the report was recorded without a proven attestation. Check the agent's key/DID/registration (npx @decidio/sdk doctor).`;
+            outcome.diagnostic = `the signed execution report did NOT verify${why}, so this is NOT a confirmed execution — the gate reported tier "${tier}", and this SDK refuses to read an unproven attestation as confirmation. Your action DID run; check the agent's key/DID/registration (npx @decidio/sdk doctor), then ${retry}`;
         }
     }
     return outcome;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { ResumeController } from "./resume.js";
 import { type EvidenceOutcome } from "./evidence.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export type { PendingAction, PendingStore, ResumeController, ResumeOutcome } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export type { GuardFacadeConfig, ProtectOptions } from "./guard.js";

package/dist/index.js

@@ -2,7 +2,7 @@ import { DecidioSuspendedError } from "./resume.js";
 import { signBoundProof, signConfirm, assertSafeTransport, carriesCredential } from "./signing.js";
 import { canonicalize, canonicalizeArgs } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
-export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
+export { DecidioSuspendedError, DecidioDeniedError, DecidioRecoveryUnavailableError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
 export { DecidioHttpError, decisionIdProblem } from "./errors.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";

package/dist/inngest.d.ts

@@ -1,6 +1,6 @@
 import type { RequestListener } from "node:http";
 import { verifyResumeSignature } from "./resume.js";
-import type { GuardConfig, ApprovalContext } from "./index.js";
+import type { GuardConfig, ApprovalContext, EvidenceOutcome } from "./index.js";
 /** The Inngest event Decidio's verdict is translated into. The waiting function
  *  correlates on `data.decisionId`. */
 export declare const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
@@ -24,10 +24,18 @@ export interface InngestClientLike {
         data: Record<string, any>;
     }): Promise<unknown>;
 }
+/** ONE RESULT SHAPE ACROSS EVERY DOOR (F-008), with the one field this door genuinely needs on
+ *  top of it. `status` stays because Inngest's durable path can legitimately end in `rejected` or
+ *  `blocked` without ever calling your action — the other adapters signal that by throwing. What
+ *  changed: the value is `value` (not `result`) so it reads the same as every other door, and
+ *  `confirmation` is CARRIED rather than discarded. It used to be thrown away inside the confirm
+ *  step, which made "it ran and Decidio recorded it" and "it ran and Decidio does not know"
+ *  indistinguishable to the caller. */
 export type GateStepOutcome<R> = {
     status: "executed" | "rejected" | "blocked";
     decisionId: string;
-    result?: R;
+    value?: R;
+    confirmation?: EvidenceOutcome;
 };
 /**
  * Gate an action INSIDE an Inngest function, with durable suspend on routing.

package/dist/inngest.js

@@ -22,8 +22,8 @@ export async function decidioGateStep(args) {
             return { status: "blocked", decisionId: auth.decisionId };
     }
     const result = await step.run("agent-action", args.run);
-    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result, args.evidence); return true; });
-    return { status: "executed", decisionId: auth.decisionId, result };
+    const confirmation = await step.run("decidio-confirm", async () => gateConfirm(config, auth.decisionId, result, args.evidence));
+    return { status: "executed", decisionId: auth.decisionId, value: result, confirmation };
 }
 export function createInngestResumeBridge(opts) {
     const secret = opts.webhookSecret ?? "";