@decidio/sdk 0.2.2 → 0.3.3

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,8 +148,12 @@ 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
+**What VALID means — and what it does not.** A pinned `VALID` proves the receipt's **claims** were
+sealed by your workspace's issuer and that none of them has changed since. Not its *bytes*: the
+signature covers the record's canonical form (JCS), so reformatting the file — reindenting it,
+minifying it, reordering keys — still verifies, and should, because none of that alters a claim.
+If you need byte-for-byte custody, hash the file and keep that hash yourself; this proves the
+content, which is what an auditor is asking about. 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
@@ -382,10 +390,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
@@ -420,6 +448,135 @@ 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.
 
+
+
+
+## The durable store is a revision chain (0.3.2)
+
+`FilePendingStore` keeps each decision's execution record as an **append-only revision chain** —
+`<id>.rev.1`, `<id>.rev.2`, … — and the head is the highest number. Every state change reads the
+head, validates against exactly that record, writes the successor to a temp file, and publishes it
+with `link()` to the next revision number. `link()` fails if that name already exists, so **exactly
+one writer wins each revision**, with no lock, no timeout and no daemon — on any volume that
+supports hard links (NTFS, ext4, APFS, XFS; not FAT/exFAT, and not every network or FUSE mount —
+on those every write fails closed rather than silently degrading). A loser re-reads the new head
+and validates again — against what actually happened, not a snapshot. **No revision file is ever
+deleted:** a name that could be reused is a race that could be lost, so the chain is genuinely
+append-only and a decision's whole history stays readable in place.
+
+This replaced the 0.2/0.3 one-marker-per-state layout after an external retest showed why it had to:
+that layout made a transition in three separate steps (read the markers, write the new one, sweep
+the weaker ones), so a process holding `claimed_preinvoke` could validate its snapshot, lose to a
+second process that durably wrote *and returned* a denial, then write `invoking` anyway — and its
+sweep deleted the tombstone. The SDK reported a denial as final and ran the denied action. Every
+*sequential* schedule was safe; the window was inside one transition. The chain has no such window:
+nothing ever deletes the head, and the rule that refuses a denied decision now runs against the
+denial that just landed.
+
+**Upgrading.** A directory in the older layout is migrated once, at the first construction of a
+0.3.2 store: each decision's markers become the head of a fresh chain and the markers are removed.
+Corrupt markers are left exactly as found and the decision reads as unreadable until a person
+inspects it. **Stop every older worker that shares the directory BEFORE the first 0.3.2 process
+constructs its store, then upgrade them together.** The one-time migration reads the markers it
+finds and removes exactly those; an older SDK still writing leaves a marker beside a chain, and
+that decision is then *unreadable* by design — neither reading can be trusted over the other, so
+the store refuses to pick one.
+
+**Custom stores.** The `PendingStore` contract has said since 0.2.0 that every method must be atomic
+against concurrent callers. The shipped file store did not honor that until now; a custom store must.
+The deterministic two-process schedules that proved the defect live in
+`packages/conformance/acceptance.mjs` (criteria 7a, 7b and 7c): a denial landing while an invoker
+is paused between validating and publishing; two conflicting settlements from one head; and a denier
+paused while the approver publishes four revisions past it. A store that cannot pass them is not
+atomic, whatever its methods say.
+
+## Reading a receipt
+
+The cryptography is only half the evidence. These are the fields that an outside reader has
+actually misread on a first run, and what each one means.
+
+**`ratified: yes` next to `deciders: 0` is not a contradiction.** `deciders` is the list of people
+nominated **in advance** to decide. When an agent's request is *routed* rather than pre-assigned,
+that list is empty — nobody was nominated, because the request had not happened yet. The person who
+actually decided is the **ratifier** (`ratifiedBy`). So a receipt for a human-approved action reads
+`deciders: 0, ratified: yes`, and the human is recorded, in the field named for the role they
+played. The verifier prints this explanation whenever the pair appears.
+
+**`appliedLimits` is what the request was MEASURED AGAINST, not a rule that fired.** It holds up to
+three entries, and only those that have a value: `requested_amount` (the amount actually asked for),
+`auto_approve_threshold` and `hard_cap` (the ceilings on the agent's own token). So a decision routed
+to a human because *no rule matched* can still list an `auto_approve_threshold` — that is the bar the
+request was compared to and did not clear, not a limit that was applied to it. Read
+`requested_amount` as the ask, the other two as ceilings.
+
+**`firedRules` is what the policy engine actually matched — for any verdict.** It is not an
+auto-approve indicator: a **blocked** request carries the deny-by-default backstop rule here, so
+non-empty does not mean "approved" and empty does not mean "blocked". The field that states the
+disposition is `authority.result`; `firedRules` tells you which named, versioned rules produced it.
+
+**`payloadSchemaUri` is a `urn:`, not a URL.** It is content-addressed —
+`urn:decidio:sealed-payload:1:sha256:<hash>` — so it *identifies* the exact schema the record was
+sealed under and pins it against substitution. It does not locate a document, and nothing will
+resolve it. (Shipping the schema alongside the verifier so you can check the hash yourself is on
+the roadmap; today the URN is an identifier only, and this note exists so it does not look broken.)
+
+**`prevHash` proves a pointer, not an ancestry.** A non-null `prevHash` shows this record was
+sealed after a specific predecessor, but a single-file verification cannot check that predecessor
+exists or is what it claims. Verify a chain (`verify a.json b.json c.json`) when the sequence
+matters.
+
+**Pinning is trust-on-first-use.** The first time you fetch a receipt, the record *and* the issuer
+DID arrive in the same authenticated response — so that first check trusts the connection, not the
+key. What pinning buys is everything afterwards: record the DID once, out of band if you can, and
+every later verification is checked against a key you chose rather than one you were handed. The
+verifier says so on every unpinned run.
+
+## 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,
@@ -430,6 +587,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
@@ -495,3 +663,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/_gate.js

@@ -14,7 +14,7 @@ export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     return a;
 }
 export async function gateAuthorize(config, ctx) {
-    canonicalize(ctx, "describe(...)");
+    ctx = canonicalize(ctx, "describe(...)");
     assertSafeTransport(config.apiUrl, carriesCredential(config));
     const f = config.fetchImpl ?? fetch;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;

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,22 +114,22 @@ 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.`);
-        }
+    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 effectiveUser() {
-    try {
-        return userInfo().username;
-    }
-    catch {
-        return process.env.USERNAME ?? process.env.USER ?? "";
+async function revokeFreshMint(jti, bearer, writeError, target) {
+    err(`✘ could not write ${target} (${writeError?.message ?? writeError}). The token minted a moment ago (jti ${jti}) is LIVE until revoked - revoking it now.`);
+    const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(jti)}`, { method: "DELETE" }, bearer);
+    if (rv.status >= 200 && rv.status < 300) {
+        err(`  ✔ the token minted a moment ago (jti ${jti}) was REVOKED again, so nothing live was left behind. Fix the cause above and re-run - it will mint a fresh one.`);
+        return true;
     }
+    err(`  ⚠ the token minted a moment ago (jti ${jti}) is LIVE and could NOT be revoked (${rv.status}). Revoke it by hand, or re-run init - the server keeps one active token per agent, so a fresh mint supersedes it:`);
+    err(`    npx @decidio/sdk tokens revoke ${jti}`);
+    err(`    npx @decidio/sdk tokens list --mine`);
+    return false;
 }
 function upsertEnv(updates) {
     const remaining = { ...updates };
@@ -345,8 +353,19 @@ async function cmdInit(agentId, opts = {}) {
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
     if (tokenJti)
         envOut.DECIDIO_TOKEN_JTI = tokenJti;
-    prepareEnvForWrite();
-    upsertEnv(envOut);
+    try {
+        prepareEnvForWrite();
+        upsertEnv(envOut);
+    }
+    catch (e) {
+        if (agentToken && tokenJti)
+            await revokeFreshMint(tokenJti, mintBearer, e, ENV_PATH);
+        else if (agentToken)
+            err(`✘ could not write ${ENV_PATH} (${e?.message ?? e}). The token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+        else
+            err(`✘ could not write ${ENV_PATH} (${e?.message ?? e}). No token was minted this run.`);
+        return 1;
+    }
     for (const [k, v] of Object.entries(envOut))
         process.env[k] = v;
     log(`✔ wrote ${ENV_PATH} (owner-only where the OS supports it) — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
@@ -601,10 +620,13 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     if (issuer) {
+        log(`  Record your workspace's issuer DID — copy this line, and pin it forever:`);
+        log(``);
+        log(`${issuer}`);
+        log(``);
+        log(`  Then verify, pinned to it (the same DID, inline — copy from the line above, not this one,`);
+        log(`  which your terminal may wrap):`);
         log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
-        log(`  That pins the check to your workspace's issuer DID (read from the authenticated`);
-        log(`  response above — record it once, then pin it forever):`);
-        log(`    ${issuer}`);
         log(`  Without --issuer the verifier proves the receipt is internally consistent, but NOT who`);
         log(`  issued it; it says so in its output.`);
     }
@@ -625,6 +647,10 @@ function cmdVerify(argsIn) {
                 err("✘ --issuer needs a did:key value (a bare or EMPTY --issuer must not silently verify unpinned).");
                 return 2;
             }
+            if (expectedIssuer !== undefined && expectedIssuer !== v) {
+                err(`✘ --issuer given twice with different values (${expectedIssuer} then ${v}) — refusing to choose which one you meant to pin to.`);
+                return 2;
+            }
             expectedIssuer = v;
             i++;
         }
@@ -634,6 +660,10 @@ function cmdVerify(argsIn) {
                 err("✘ --issuer needs a did:key value.");
                 return 2;
             }
+            if (expectedIssuer !== undefined && expectedIssuer !== v) {
+                err(`✘ --issuer given twice with different values (${expectedIssuer} then ${v}) — refusing to choose which one you meant to pin to.`);
+                return 2;
+            }
             expectedIssuer = v;
         }
         else if (!a.startsWith("-")) {
@@ -715,24 +745,49 @@ async function cmdQuickstart(opts = {}) {
             const prev = readFileSync(envFile, "utf8");
             const prevId = prev.match(/^DECIDIO_AGENT_ID=(.+)$/m)?.[1];
             const prevJti = prev.match(/^DECIDIO_TOKEN_JTI=(.+)$/m)?.[1];
+            const carried = new Set((prev.match(/^DECIDIO_ORPHANED_TOKEN_JTI=(.+)$/m)?.[1] ?? "").split(",").map((s) => s.trim()).filter(Boolean));
             if (prevId && prevId !== agentId) {
                 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 {
+                        carried.add(prevJti);
+                        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.`);
                 }
             }
+            if (carried.size) {
+                envOut.DECIDIO_ORPHANED_TOKEN_JTI = [...carried].join(",");
+                log(`  • ${carried.size} orphaned token id(s) from earlier replacements carried forward — \`quickstart cleanup\` will retry them.`);
+            }
+        }
+        try {
+            writeSecretFile(envFile, Object.entries(envOut).map(([k, v]) => `${k}=${v}`).join("\n") + "\n");
+        }
+        catch (e) {
+            if (mint.body?.jti)
+                await revokeFreshMint(mint.body.jti, session, e, envFile);
+            else
+                err(`✘ could not write ${envFile} (${e?.message ?? e}). The tour token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+            return 1;
         }
-        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 {
-        upsertEnv(envOut);
+        try {
+            upsertEnv(envOut);
+        }
+        catch (e) {
+            if (mint.body?.jti)
+                await revokeFreshMint(mint.body.jti, session, e, envFile);
+            else
+                err(`✘ could not write ${envFile} (${e?.message ?? e}). The tour token minted a moment ago is LIVE and the server returned no revocation id - find and revoke it: npx @decidio/sdk tokens list --mine`);
+            return 1;
+        }
     }
     const failTour = async (code) => {
         log("");
@@ -859,6 +914,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 +940,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 +979,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;
 }