@decidio/sdk 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,56 @@ Release notes for the client SDK. The Python package `decidio` ships the same ch
 version (the two are conformance-locked twins). Each entry names what changed, what a reader must do
 on upgrade, and what proved it.
 
+## 0.4.1 — "no" means no
+
+Two first-run defects found by an outside engineer within sixteen minutes of installing 0.4.0. Both were
+in the CLI's own tour and cleanup, not in the SDK's gate, ledger or verifier; both are fixed in both
+languages, and the two blind spots that let them ship are now test axes.
+
+- **The tour's approval prompt is a question.** "Press Enter to approve" accepted ANY completed line —
+  the literal `no` included — as approval, because the answer was never read. Now `y` approves, `n`
+  REJECTS (the tour rehearses the rejection half: the request is refused, your function does not run, and
+  the tour says so), and anything else asks again; three non-answers stop the tour with the decision still
+  pending (exit 3) rather than guess. The rule is one pure function, `approvalAnswer`, driven by a shared
+  corpus (`packages/conformance/vectors/consent-answers.json`) in both languages, and the interactive
+  branch itself is exercised under a real terminal on the Linux gate. The automated `--auto-approve-demo`
+  path is unchanged and still labeled as automated authority.
+- **A lost `.env` no longer loses the token.** 0.3.5's recovery journal retired a token id the moment its
+  credential file was written, so moving or deleting `.env` afterwards left `quickstart cleanup` saying the
+  journal owed nothing over a live seven-day token. Only a revocation retires a journal entry now. Cleanup
+  revokes tour tokens from the journal even when the credential file is gone, and still revokes a token
+  whose credential file never landed (the double fault the journal was built for). It never revokes an
+  `init` token that DID land: one a credential file here holds is named and left alone; one that was written
+  to a file no longer found here is named with the `tokens revoke` command (it may simply live elsewhere);
+  `doctor` shows a held token as live-and-held. **Upgrading from 0.3.5/0.4.0:** rows those versions retired as `persisted` count as
+  outstanding again. A tour you already cleaned up will show in `doctor` until you run
+  `npx @decidio/sdk quickstart cleanup` once, which reports the token as already revoked and retires the row.
+- **Truth and disclosure.** The failure text after a refused registration no longer claims nothing was
+  written (the `.gitignore` entries were); the preflight discloses the five-minute wait for your answer and
+  that receipts are shareable but carry business metadata; cleanup names the retained journal; the
+  worker's "prints once" is "once per worker process"; the tour tells you to unset `DECIDIO_SESSION_TOKEN`
+  before launching agent code from the same shell.
+- **`dev --target` obeys the wire rule:** the relay refuses a remote plaintext `http://` target, since the
+  forwarded body is signed resume material.
+- **A race loser says so** (prodsec retest of 0.4.0, V040-01). A resume signal that finds the pre-invocation
+  claim held by another live attempt, or loses the invocation-boundary race to one, answers the new additive
+  status `lost_race` (it did nothing; the winner reports). It used to read `unknown` — the word for "not
+  ours" — and `no_handler` although the handler was registered. A boundary loss to a DENIAL is final and
+  answers `already_resolved` with the denial named; a store fault at the boundary answers `lost_race` with
+  "nothing ran … a later signal may retry". A signal that arrives after the entry was consumed now consults
+  the ledger: already ran or denied → `already_resolved`; in flight → `indeterminate`; a claim held by another
+  attempt → `lost_race`; only a decision with no record at all is `unknown`. Exhaustive switches over the
+  status union gain one case.
+- **Adapter declarations aligned** (V040-02): the Temporal compatibility floor checked at bind time is now the
+  same `>=1.9 <2` the package declares; the peer-dependency comment says what the manifest does (optional
+  peers, checked at bind time); the Inngest step outcome is a discriminated union, so `confirmation` is
+  statically present when `status` is `"executed"`. Adapters stay Beta; real-engine evidence (V040-03) and
+  provenance metadata (V040-04) remain open and disclosed.
+- Deliberately not changed, recorded in the backlog for a product decision: per-subcommand `--help`, the
+  tour showing the exact call it makes (`withApproval` in blocking mode rather than the `guard.protect`
+  line it prints as the takeaway), dot-stripping in receipt filenames, and a shared no-overwrite receipt
+  writer for the tour.
+
 ## 0.4.0 — the scope statement
 
 - **README: "What 0.4 does not yet claim" and "Compatibility and support."** The stability promise is

package/README.md

@@ -81,7 +81,10 @@ fresh one (or pass `--unique` to auto-append a random suffix — collision-proof
 workspaces and CI). Headless terminal (no prompts possible)? Export `DECIDIO_SESSION_TOKEN` first:
 request a sign-in link, then exchange its `?login=` value at `POST /demo/login-consume` — the
 response's `token` is your session token (the CLI prints these exact instructions when it
-can't prompt).
+can't prompt). That session token is your workspace login, not the agent's credential: unset it
+before launching agent code from the same shell, because child processes inherit exported
+variables. In the tour's human step, `y` approves and `n` rejects — the rejection half is worth
+watching once: the request is refused and your function does not run.
 
 **3. Protect one function** — save this as `quickstart.mjs`:
 

package/dist/adapters/_gate.d.ts

@@ -27,12 +27,12 @@ export declare function gateConfirm(config: GuardConfig, decisionId: string, res
 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;
-/** Engine versions these adapters are written and tested against. Peer dependencies are
- *  deliberately NOT declared: declaring them made npm resolve four engine ecosystems into ~211MB
- *  of cache metadata for every consumer, including the majority who use none of them. The
- *  compatibility contract lives here instead, and it is CHECKED at bind time — a mismatch names
- *  the version it found, the range it wants, the beta status and the exact remediation, rather
- *  than failing somewhere deep in the engine later. */
+/** Engine versions these adapters are written and tested against. The two engines that ARE declared in
+ *  package.json are declared as OPTIONAL peers (peerDependenciesMeta), so a consumer who uses none of them
+ *  installs nothing extra; Inngest and the OpenAI Agents SDK are not declared at all. Either way the
+ *  contract is CHECKED here at bind time — a mismatch names the version it found, the range it wants, the
+ *  beta status and the exact remediation, rather than failing somewhere deep in the engine later. These
+ *  ranges and package.json's peer ranges are the SAME numbers (prodsec V040-02: they had drifted). */
 export declare const ENGINE_RANGES: Record<string, {
     pkg: string;
     min: string;

package/dist/adapters/_gate.js

@@ -105,7 +105,7 @@ export function assertVerdict(verdict, decisionId, reason) {
 }
 export const ENGINE_RANGES = {
     langgraph: { pkg: "@langchain/langgraph", min: "0.2.0", lessThan: "2.0.0" },
-    temporal: { pkg: "@temporalio/workflow", min: "1.0.0", lessThan: "2.0.0" },
+    temporal: { pkg: "@temporalio/workflow", min: "1.9.0", lessThan: "2.0.0" },
     openai: { pkg: "@openai/agents", min: "0.0.1", lessThan: "2.0.0" },
     inngest: { pkg: "inngest", min: "3.0.0", lessThan: "4.0.0" },
 };

package/dist/cli.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+export type ApprovalAnswer = "approve" | "reject" | "again";
+export declare function approvalAnswer(answer: unknown): ApprovalAnswer;

package/dist/cli.js

@@ -4,10 +4,12 @@ import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
+import { pathToFileURL as toFileUrl, fileURLToPath as fromFileUrl } from "node:url";
+import { realpathSync as realPath } from "node:fs";
 import { createRequire } from "node:module";
 import { generateKeypair, assertSafeTransport } from "./signing.js";
 import { hardenFile } from "./resume.js";
-import { withApproval, DecidioRateLimitError, didFromPrivateKey } from "./index.js";
+import { withApproval, DecidioRateLimitError, DecidioRejectedError, didFromPrivateKey } from "./index.js";
 import { verifyReceipt, runVerify } from "@decidio/verify";
 const VERSION = (() => {
     try {
@@ -246,6 +248,32 @@ function journalRows() {
     }
     return rows;
 }
+function credentialJtisOnDisk() {
+    const out = new Set();
+    for (const f of [".env", ".env.quickstart"]) {
+        if (!existsSync(f))
+            continue;
+        let text = "";
+        try {
+            text = readFileSync(f, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const m of text.matchAll(/^\s*DECIDIO_(?:ORPHANED_)?TOKEN_JTI=(.+)$/gm))
+            for (const j of m[1].split(","))
+                if (j.trim())
+                    out.add(j.trim());
+    }
+    return out;
+}
+function journalOwed() {
+    return journalOutstanding().filter((j) => j.label === "quickstart" || !j.persisted);
+}
+function journalUnheld() {
+    const held = credentialJtisOnDisk();
+    return journalOutstanding().filter((j) => j.label !== "quickstart" && j.persisted && !held.has(j.jti));
+}
 const REFUSE_MINT_CORRUPT_JOURNAL = (e) => `✘ the token recovery journal cannot be trusted (${e.message}) - it may hold the id of a token that is still live. Refusing to mint on top of uncertain history. Inspect the file, revoke anything it names (npx @decidio/sdk tokens list --mine), and repair or move it aside; every byte is left as found. Nothing was minted.`;
 function journalProbe() {
     try {
@@ -272,7 +300,12 @@ function journalOutstanding() {
     for (const e of journalRows()) {
         if (e.event === "minted")
             minted.set(e.jti, { jti: e.jti, agentId: e.agentId, label: e.label, apiUrl: e.apiUrl, at: e.at });
-        if (e.event === "retired")
+        if (e.event === "retired" && e.how === "persisted") {
+            const m = minted.get(e.jti);
+            if (m)
+                m.persisted = true;
+        }
+        if (e.event === "retired" && e.how === "revoked")
             minted.delete(e.jti);
     }
     return [...minted.values()];
@@ -337,7 +370,19 @@ function ensureGitignore() {
     appendFileSync(".gitignore", (existing && !existing.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n");
     log(`✔ added ${missing.join(" + ")} to .gitignore (new secret files here will not be committed)`);
 }
+const APPROVE_WORDS = new Set(["y", "yes", "approve", "approved"]);
+const REJECT_WORDS = new Set(["n", "no", "reject", "rejected", "deny", "denied"]);
+export function approvalAnswer(answer) {
+    const a = String(answer ?? "").trim().toLowerCase();
+    if (APPROVE_WORDS.has(a))
+        return "approve";
+    if (REJECT_WORDS.has(a))
+        return "reject";
+    return "again";
+}
 function ask(question, mute = false) {
+    if (process.stdin.readableEnded || process.stdin.destroyed)
+        return Promise.resolve("");
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
         if (mute) {
@@ -346,8 +391,9 @@ function ask(question, mute = false) {
             anyRl._writeToOutput = (s) => { if (s.includes(question))
                 write?.(s); };
         }
-        rl.question(question, (answer) => { rl.close(); if (mute)
-            process.stderr.write("\n"); resolve(answer.trim()); });
+        rl.once("close", () => resolve(""));
+        rl.question(question, (answer) => { resolve(answer.trim()); rl.close(); if (mute)
+            process.stderr.write("\n"); });
     });
 }
 async function acquireSession(purpose) {
@@ -581,6 +627,10 @@ async function cmdDoctor() {
     }
     for (const j of journalItems) {
         const where = j.apiUrl && j.apiUrl !== API ? `DECIDIO_API_URL=${j.apiUrl} ` : "";
+        if (j.jti === env.DECIDIO_TOKEN_JTI) {
+            line(true, `token recovery journal: jti ${j.jti} is live and held by ${ENV_PATH} — it retires only when revoked (npx @decidio/sdk tokens revoke ${j.jti}; a tour token: quickstart cleanup).`);
+            continue;
+        }
         warn(`token recovery journal: jti ${j.jti} (${j.label ?? "token"}, agent ${j.agentId ?? "?"}, minted ${j.at ?? "?"} against ${j.apiUrl ?? API}) has no recorded revocation in this directory's journal — it may still be live. Revoke it, or confirm it is gone: ${where}npx @decidio/sdk quickstart cleanup   (or: ${where}npx @decidio/sdk tokens revoke ${j.jti})`);
     }
     log(`✔ API URL: ${API}${(process.env.DECIDIO_API_URL || env.DECIDIO_API_URL) ? "" : "  (default: the hosted sandbox — set DECIDIO_API_URL to point elsewhere)"}`);
@@ -881,8 +931,9 @@ async function cmdQuickstart(opts = {}) {
     log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
     log("  write .env (or .env.quickstart), .decidio-token-journal (revocation ids, no secrets) and .gitignore");
     log("  entries (incl. .decidio-pending/, the durable store your real agent will use) · save the receipt");
-    log("  as decidio-receipt-<id>.json here (public; it stays) · create one synthetic decision and its");
-    log("  sealed record (records are permanent by design). Cleanup offer at the end.");
+    log("  as decidio-receipt-<id>.json here (shareable: action, amount, policy, the human's reason - no secrets; it stays)");
+    log("  · create one synthetic decision and its sealed record (records are permanent by design) · wait up to");
+    log("  5 minutes for your y (approve) or n (reject) at the human step. Cleanup offer at the end.");
     log("");
     const session = await acquireSession("The quickstart");
     if (!session)
@@ -911,7 +962,7 @@ async function cmdQuickstart(opts = {}) {
         else {
             err(`  Check the target and your sign-in, then re-run: npx @decidio/sdk doctor`);
         }
-        err(`  Nothing was written to this directory.`);
+        err(`  No credential was written to this directory (the only write so far is the .gitignore entries above, which are safe to keep).`);
         return 1;
     }
     let prevTourFile = null;
@@ -958,8 +1009,10 @@ async function cmdQuickstart(opts = {}) {
             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)
+                    if (rv.status >= 200 && rv.status < 300) {
+                        journalRetire(prevJti, "revoked");
                         log(`  ✔ the previous tour agent (${prevId}) had its token REVOKED before this tour replaced it — no live credential is left behind`);
+                    }
                     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}`);
@@ -1050,8 +1103,26 @@ async function cmdQuickstart(opts = {}) {
     log(`    Nothing executes until someone decides.`);
     log("");
     const interactive = process.stdin.isTTY;
+    let verdict = "approve";
     if (interactive) {
-        await ask(`③ YOU are the approver. Press Enter to approve it here (or approve it in your Decidio queue first, then Enter): `);
+        verdict = "again";
+        for (let attempt = 0; attempt < 3 && verdict === "again"; attempt++) {
+            const answer = await ask(attempt === 0
+                ? `③ YOU are the approver. Type y to approve or n to reject, then Enter (or decide it in your Decidio queue first, then answer here the same way): `
+                : `   Please answer y (approve) or n (reject): `);
+            verdict = approvalAnswer(answer);
+            if (process.stdin.readableEnded || process.stdin.destroyed) {
+                verdict = "again";
+                break;
+            }
+        }
+        if (verdict === "again") {
+            log(`③ No decision was made (no y or n answer), so the tour stops here rather than guess.`);
+            log(`   The request is still ROUTED and waiting in your queue - approve or reject it there, or re-run the tour.`);
+            log(`   NOTE: this tour's credentials are still live in ${envFile} (a 7-day token + the agent's key). Once you`);
+            log(`   have decided - or if you abandon the tour - remove them: npx @decidio/sdk quickstart cleanup`);
+            process.exit(3);
+        }
     }
     else if (opts.autoApproveDemo) {
         log("③ --auto-approve-demo: approving with your session credential. This is AUTOMATED authority");
@@ -1078,67 +1149,119 @@ async function cmdQuickstart(opts = {}) {
         log(`   or if you abandon the tour — remove them: npx @decidio/sdk quickstart cleanup`);
         process.exit(3);
     }
-    const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
-    if (!(ap.status >= 200 && ap.status < 300)) {
-        err(`✘ approve failed (${ap.status}): ${JSON.stringify(ap.body)}`);
-        return failTour(1);
-    }
-    log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
-    let done;
-    try {
-        done = await running;
-    }
-    catch (e) {
-        err(`✘ the gated call did not complete: ${e?.message ?? e}`);
-        return failTour(1);
-    }
-    log(`  ✔ your function executed AFTER approval: ${JSON.stringify(done.value)}`);
-    if (done.confirmation?.evidenceTier)
-        log(`    …and the call itself told you what was recorded: confirmation.evidenceTier = ${done.confirmation.evidenceTier}`);
-    log("");
-    log("④ Downloading the sealed Authority Receipt and verifying it OFFLINE…");
-    const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
-    if (!(rec.status >= 200 && rec.status < 300) || !rec.body?.credential) {
-        err(`✘ receipt fetch failed (${rec.status})`);
-        return failTour(1);
-    }
-    const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
-    writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
-    const issuer = rec.body?.issuer;
-    const v = verifyReceipt(rec.body.credential, issuer);
-    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : ""})`);
-    if (!v.valid) {
-        err(`  ✘ the receipt did not verify (${v.reason ?? "no reason given"}) — the tour did not complete.`);
-        return failTour(1);
+    const rejected = verdict === "reject";
+    if (rejected) {
+        const rj = await api(`/api/decisions/${encodeURIComponent(decisionId)}/reject`, { method: "POST", body: JSON.stringify({ reason: "quickstart: rejected by the approver" }) }, session);
+        if (!(rj.status >= 200 && rj.status < 300)) {
+            err(`✘ reject failed (${rj.status}): ${JSON.stringify(rj.body)}`);
+            return failTour(1);
+        }
+        const decidedInApp = rj.body?.alreadyResolved === true;
+        log(decidedInApp ? `  • this decision was already decided from your app — the tour follows that decision` : `  ✔ rejected`);
+        let leaked;
+        let refused;
+        try {
+            leaked = await running;
+        }
+        catch (e) {
+            refused = e;
+        }
+        if (refused === undefined && !decidedInApp) {
+            err(`✘ the gated function RAN after the rejection (it returned ${JSON.stringify(leaked)}) — this is a defect, not a tour. Please report it: decidioai.com/#early-access`);
+            return failTour(1);
+        }
+        const ranOnAppApproval = refused === undefined;
+        if (ranOnAppApproval) {
+            log(`  ✔ your app APPROVED it first, so that decision stood and your function ran: ${JSON.stringify(leaked)}. Re-run the tour to watch a rejection.`);
+        }
+        else if (refused instanceof DecidioRejectedError) {
+            log(`  ✔ your function did NOT run — the wrapper refused: ${refused.message}`);
+            log(`    That is the product: a human said no, and nothing happened.${rj.body?.sealed === true ? " The denial is sealed on the record, as an approval would be." : ""}`);
+        }
+        else {
+            err(`✘ the gated call ended with an error rather than a clean refusal: ${refused?.message ?? refused} — nothing ran, but the tour did not complete.`);
+            return failTour(1);
+        }
+        log("");
+        const secsR = Math.round((Date.now() - t0) / 1000);
+        log(ranOnAppApproval
+            ? `Done in ${secsR}s: gated → routed to a human → decided in your app (approved) → your function ran once.`
+            : `Done in ${secsR}s: gated → routed to a human → REJECTED → your function never ran.`);
+        if (!ranOnAppApproval)
+            log(`Re-run the tour and answer y to watch the approval half, with its offline-verifiable receipt.`);
+        log("");
+        log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}`);
     }
-    if (!issuer) {
-        err(`  ⚠ the server did not return an issuer DID, so this check ran UNPINNED — it proves the`);
-        err(`    receipt is internally consistent, NOT who issued it (a self-signed forgery also passes).`);
-        err(`    Get your workspace's issuer DID from the app's record-verify panel, then re-check:`);
-        err(`      npx @decidio/sdk verify --issuer <did:key:...> ${fname}`);
-        err(`  ✘ the tour does not count an UNPINNED check as success.`);
-        return failTour(1);
+    else {
+        const ap = await api(`/api/decisions/${encodeURIComponent(decisionId)}/approve`, { method: "POST", body: JSON.stringify({ reason: opts.autoApproveDemo && !interactive ? "quickstart --auto-approve-demo (automated)" : "quickstart" }) }, session);
+        if (!(ap.status >= 200 && ap.status < 300)) {
+            err(`✘ approve failed (${ap.status}): ${JSON.stringify(ap.body)}`);
+            return failTour(1);
+        }
+        log(`  ✔ approved${ap.body?.alreadyResolved ? " (already decided from your app — the tour follows that decision)" : ""}`);
+        let done;
+        try {
+            done = await running;
+        }
+        catch (e) {
+            if (e instanceof DecidioRejectedError) {
+                err(`✘ it was REJECTED from your app before this tour's approval landed — your function did NOT run (that is the product). Re-run the tour to watch the approval half.`);
+                return failTour(1);
+            }
+            err(`✘ the gated call did not complete: ${e?.message ?? e}`);
+            return failTour(1);
+        }
+        log(`  ✔ your function executed AFTER approval: ${JSON.stringify(done.value)}`);
+        if (done.confirmation?.evidenceTier)
+            log(`    …and the call itself told you what was recorded: confirmation.evidenceTier = ${done.confirmation.evidenceTier}`);
+        log("");
+        log("④ Downloading the sealed Authority Receipt and verifying it OFFLINE…");
+        const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
+        if (!(rec.status >= 200 && rec.status < 300) || !rec.body?.credential) {
+            err(`✘ receipt fetch failed (${rec.status})`);
+            return failTour(1);
+        }
+        const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
+        writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
+        const issuer = rec.body?.issuer;
+        const v = verifyReceipt(rec.body.credential, issuer);
+        log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : ""})`);
+        if (!v.valid) {
+            err(`  ✘ the receipt did not verify (${v.reason ?? "no reason given"}) — the tour did not complete.`);
+            return failTour(1);
+        }
+        if (!issuer) {
+            err(`  ⚠ the server did not return an issuer DID, so this check ran UNPINNED — it proves the`);
+            err(`    receipt is internally consistent, NOT who issued it (a self-signed forgery also passes).`);
+            err(`    Get your workspace's issuer DID from the app's record-verify panel, then re-check:`);
+            err(`      npx @decidio/sdk verify --issuer <did:key:...> ${fname}`);
+            err(`  ✘ the tour does not count an UNPINNED check as success.`);
+            return failTour(1);
+        }
+        if (issuer)
+            log(`    Keep that DID: it is your trust anchor — npx @decidio/sdk verify --issuer ${issuer} <receipt.json>`);
+        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 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 → 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(`Before launching agent code from THIS shell, unset DECIDIO_SESSION_TOKEN if you exported it: child processes`);
+        log(`inherit exported variables, and that credential is your workspace login, not the agent's.`);
+        log("");
+        log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}`);
+        log(`Next: the README section "Production mode: durable async resume" (the worker; the engine adapters follow it).`);
+        log(`The README's seven-step quickstart is this same blocking flow in your own code - if you keep this agent, its .env`);
+        log(`already works here, so skip that flow's init step.`);
+        log(`Built by OmniTwin — decidioai.com  ·  Putting this in front of real approvals? decidioai.com/#early-access`);
     }
-    if (issuer)
-        log(`    Keep that DID: it is your trust anchor — npx @decidio/sdk verify --issuer ${issuer} <receipt.json>`);
-    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 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 → 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(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}`);
-    log(`Next: the README section "Production mode: durable async resume" (the worker; the engine adapters follow it).`);
-    log(`The README's seven-step quickstart is this same blocking flow in your own code - if you keep this agent, its .env`);
-    log(`already works here, so skip that flow's init step.`);
-    log(`Built by OmniTwin — decidioai.com  ·  Putting this in front of real approvals? decidioai.com/#early-access`);
     let doCleanup = false;
     if (interactive) {
         const answer = await ask(`\nKeep this agent for development? [Enter = keep · c + Enter = clean up now]: `);
@@ -1151,7 +1274,7 @@ async function cmdQuickstart(opts = {}) {
         log(`\nAutomated run: cleaning the tour up (pass --keep-agent to keep the agent + token).`);
     }
     const cleanupCode = doCleanup ? await quickstartCleanup(session, envFile) : 0;
-    return v.valid ? (cleanupCode || 0) : 1;
+    return cleanupCode || 0;
 }
 async function quickstartCleanup(session, envFile) {
     const env = (() => {
@@ -1172,13 +1295,25 @@ async function quickstartCleanup(session, envFile) {
     let journalRevoked = 0;
     const journalStuck = [];
     let outstanding = [];
+    let heldElsewhere = [];
+    let unheld = [];
+    let journalReconciled = 0;
     try {
-        outstanding = journalOutstanding();
+        const ownIds = new Set([env.DECIDIO_TOKEN_JTI, ...(env.DECIDIO_ORPHANED_TOKEN_JTI ?? "").split(",").map((s) => s.trim())].filter(Boolean));
+        outstanding = journalOwed().filter((j) => !ownIds.has(j.jti));
+        unheld = journalUnheld();
+        const owedIds = new Set(outstanding.map((j) => j.jti));
+        const unheldIds = new Set(unheld.map((j) => j.jti));
+        heldElsewhere = journalOutstanding().filter((j) => !owedIds.has(j.jti) && !unheldIds.has(j.jti) && !ownIds.has(j.jti));
     }
     catch (e) {
         err(`✘ the token recovery journal cannot be trusted (${e?.message ?? e}). It may hold the id of a live token, so this cleanup cannot claim nothing is owed. Every byte is left as found: inspect ${JOURNAL_PATH}, revoke anything it names (npx @decidio/sdk tokens list --mine), then repair or move it aside and re-run.`);
         return 1;
     }
+    for (const j of heldElsewhere)
+        log(`  • journalled token ${j.jti} (${j.label ?? "token"}) is live and still held by a credential file here — not a tour token, left alone (revoke it yourself: npx @decidio/sdk tokens revoke ${j.jti})`);
+    for (const j of unheld)
+        err(`  ⚠ journalled token ${j.jti} (${j.label ?? "token"}) is live: it was written to a credential file that is no longer here — not a tour token, so this cleanup will not revoke it. If it is yours and lost, revoke it: npx @decidio/sdk tokens revoke ${j.jti}`);
     for (const j of outstanding) {
         if (j.apiUrl && j.apiUrl !== API) {
             journalStuck.push(j.jti);
@@ -1188,11 +1323,14 @@ async function quickstartCleanup(session, envFile) {
         const rv = await api(`/api/workspace/agent-token/${encodeURIComponent(j.jti)}`, { method: "DELETE" }, session);
         if (rv.status >= 200 && rv.status < 300) {
             journalRetire(j.jti, "revoked");
-            journalRevoked++;
-            if (rv.body?.changed === false)
+            if (rv.body?.changed === false) {
+                journalReconciled++;
                 log(`  • journalled token ${j.jti} was already revoked — retiring its journal entry.`);
-            else
-                log(`  ✔ journalled token revoked (jti ${j.jti}${j.label ? `, ${j.label}` : ""}) — its credential file never landed, so this was its only handle`);
+            }
+            else {
+                journalRevoked++;
+                log(`  ✔ journalled token revoked (jti ${j.jti}${j.label ? `, ${j.label}` : ""}) — from the journal: ${j.persisted ? "its credential file is gone" : "its credential file never landed"}, so the journal was the handle`);
+            }
         }
         else {
             journalStuck.push(j.jti);
@@ -1209,8 +1347,10 @@ async function quickstartCleanup(session, envFile) {
     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)
+        if (rv.status >= 200 && rv.status < 300) {
+            journalRetire(jti, "revoked");
             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.`);
@@ -1224,6 +1364,8 @@ async function quickstartCleanup(session, envFile) {
     }
     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)
+            journalRetire(env.DECIDIO_TOKEN_JTI, "revoked");
         if (rev.status >= 200 && rev.status < 300 && rev.body?.changed === false)
             log(`  • token was already revoked (jti ${env.DECIDIO_TOKEN_JTI}) — nothing to do.`);
         else if (rev.status >= 200 && rev.status < 300)
@@ -1238,6 +1380,12 @@ async function quickstartCleanup(session, envFile) {
     else if (journalRevoked > 0 && !existsSync(envFile) || (journalRevoked > 0 && Object.keys(env).length === 0)) {
         log(`  • no credential file to clean: the journal sweep revoked ${journalRevoked} token(s) this directory owed.`);
     }
+    else if (!existsSync(envFile)) {
+        if (unheld.length)
+            err(`  • no credential file here (${envFile} is already gone); the journal names ${unheld.length} live token(s) this cleanup will not revoke (above).`);
+        else
+            log(`  • no credential file here (${envFile} is already gone) and the token recovery journal owes nothing further${journalReconciled ? ` (${journalReconciled} already-revoked row(s) reconciled)` : ""}.`);
+    }
     else {
         err(`✘ no DECIDIO_TOKEN_JTI in ${envFile} (older tour) — this tour's token is STILL LIVE and this`);
         err(`  command cannot revoke it. Nothing was deleted. Find and revoke it, then re-run cleanup:`);
@@ -1281,6 +1429,8 @@ async function quickstartCleanup(session, envFile) {
     }
     log(`  • What remains, by design: the sealed decision record (records are permanent — that is the product)`);
     log(`    and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap).`);
+    if (existsSync(JOURNAL_PATH))
+        log(`  • Also kept: ${JOURNAL_PATH} — the ids and timestamps of what this directory minted and revoked (no secrets). Gitignored; owner-only where the OS supports it.`);
     if (existsSync(".decidio-pending")) {
         log(`  • Also kept: .decidio-pending/ — this agent's own execution ledger: whatever this agent parked (call arguments,`);
         log(`    execution evidence; never credentials, by design). Gitignored; owner-only where the OS supports it. If nothing is`);
@@ -1358,6 +1508,13 @@ async function cmdTokens(sub, jti, mineOnly = false) {
     return 0;
 }
 function cmdDev(target, port) {
+    try {
+        assertSafeTransport(target, true);
+    }
+    catch (e) {
+        err(`✘ dev relay refused: ${e?.message ?? e}`);
+        return 2;
+    }
     log(`decidio dev relay on http://localhost:${port}/decidio/resume → forwarding to ${target}`);
     createServer((req, res) => {
         if (req.method !== "POST") {
@@ -1516,7 +1673,7 @@ async function main(argv) {
                 const envFile = existsSync(".env.quickstart") ? ".env.quickstart"
                     : (readEnvFile().DECIDIO_AGENT_ID ?? "").startsWith("quickstart-") ? ENV_PATH
                         : (() => { try {
-                            return journalOutstanding().length ? ".env.quickstart" : undefined;
+                            return (journalOwed().length || journalUnheld().length) ? ".env.quickstart" : undefined;
                         }
                         catch {
                             return ".env.quickstart";
@@ -1614,5 +1771,19 @@ async function main(argv) {
             return 2;
     }
 }
-main(process.argv).then((code) => { if (code !== 0)
-    process.exitCode = code; }).catch((e) => { console.error(`✘ unexpected error: ${e?.message ?? e}`); process.exit(1); });
+const invokedAsProgram = (() => {
+    const entry = process.argv[1];
+    if (!entry)
+        return true;
+    if (/(^|[\\/])(cli\.(js|mjs|ts)|decidio(\.cmd|\.ps1)?)$/i.test(entry))
+        return true;
+    try {
+        return toFileUrl(realPath(entry)).href === toFileUrl(realPath(fromFileUrl(import.meta.url))).href;
+    }
+    catch {
+        return true;
+    }
+})();
+if (invokedAsProgram)
+    main(process.argv).then((code) => { if (code !== 0)
+        process.exitCode = code; }).catch((e) => { console.error(`✘ unexpected error: ${e?.message ?? e}`); process.exit(1); });

package/dist/inngest.d.ts

@@ -31,13 +31,21 @@ export interface InngestClientLike {
  *  `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";
+export type GateStepOutcome<R> = 
+/** The action ran: the value AND what Decidio recorded (the step confirms before it returns). Encoded in the
+ *  type, not only in prose (prodsec V040-02): narrow on `status` and `confirmation` is there. */
+{
+    status: "executed";
     decisionId: string;
-    value?: R;
-    /** Always present when `status` is "executed" (the step confirms before it returns); optional in the type
-     *  because the other statuses carry none. */
-    confirmation?: EvidenceOutcome;
+    value: R;
+    confirmation: EvidenceOutcome;
+}
+/** The action never ran — a human said no, or a rule blocked it — so there is nothing to confirm. */
+ | {
+    status: "rejected" | "blocked";
+    decisionId: string;
+    value?: undefined;
+    confirmation?: undefined;
 };
 /**
  * Gate an action INSIDE an Inngest function, with durable suspend on routing.

package/dist/resume.d.ts

@@ -455,7 +455,13 @@ export declare class DecidioSuspendedError extends Error {
  *  to read `unknown`, the word for "not ours" (prodsec V033-06). An `invoking` row is NOT final and answers
  *  `indeterminate` (prodsec V035-02). Both members are additive: an exhaustive switch over this union
  *  gains a case per release, which the changelog announces. */
-export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved";
+/** `lost_race` (0.4.1): this signal lost a durable transition race to ANOTHER ATTEMPT that is still in flight
+ *  (it holds the pre-invocation claim, or crossed the invocation boundary first), or the boundary could not be
+ *  recorded at all - and it did NOTHING. Nothing ran on this signal; the winner reports, or the entry stays
+ *  parked for a later signal. It used to read `unknown` (the word for "not ours") for the claim loser and
+ *  `no_handler` for the boundary loser although a handler was registered (prodsec V040-01). A loss to a FINAL
+ *  answer (a denial, an execution) stays `already_resolved`. Additive, like the two above. */
+export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved" | "lost_race";
 /** The states a durable action can actually be in — every one of them nameable, including the
  *  one nobody likes. */
 export type RecoveryState = 

package/dist/resume.js

@@ -951,7 +951,7 @@ export function createDecidioResume(opts) {
         if (refusalWarned.has(decisionId))
             return;
         refusalWarned.add(decisionId);
-        console.error(msg + (tail ?? " (This prints once — the entry stays parked until you act.)"));
+        console.error(msg + (tail ?? " (This prints once per worker process — the entry stays parked until you act.)"));
     };
     const ctrl = {
         ...opts,
@@ -991,8 +991,18 @@ export function createDecidioResume(opts) {
             if (idProblem)
                 return { status: "unknown", decisionId: String(decisionId ?? ""), reason: `not a decision id this SDK will act on (${idProblem})` };
             const pending = await ctrl.store.get(decisionId);
-            if (!pending)
+            if (!pending) {
+                const head = await ctrl.store.getExecution(decisionId).catch(() => undefined);
+                if (head?.state === "discarded")
+                    return { status: "already_resolved", decisionId, reason: `this decision was DENIED (${head.verdict ?? "rejected"}); that answer is final and this signal did nothing` };
+                if (head?.state === "executed_unreported" || head?.state === "reported")
+                    return { status: "already_resolved", decisionId, reason: `this decision already ran (durable state ${head.state}); this signal arrived after it and did nothing` };
+                if (head?.state === "invoking" || head?.state === "indeterminate")
+                    return { status: "indeterminate", decisionId, reason: `this decision is in durable state ${head.state}: its action may still be running or may have finished without reporting - it may or may not have run. Nothing will retry it; check the worker and the downstream system, then settle it with reconcile("${decisionId}", …).` };
+                if (head?.state === "claimed_preinvoke")
+                    return { status: "lost_race", decisionId, reason: `another attempt holds the pre-invocation claim on this decision; this signal did nothing. If that attempt is alive it will report; if it died, recover() lists the decision and reconcile() can settle it` };
                 return { status: "unknown", decisionId };
+            }
             if (verdict === "rejected" || verdict === "blocked") {
                 await ctrl.store.markDiscarded(decisionId, verdict, reason);
                 await ctrl.store.delete(decisionId);
@@ -1036,7 +1046,7 @@ export function createDecidioResume(opts) {
                 if (claim.state && NON_REPLAYABLE.includes(claim.state)) {
                     refuseOnce(decisionId, claim.state === "discarded"
                         ? `[decidio] REFUSING to execute ${decisionId}: it was DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}) and that answer is final. Nothing ran. A denial cannot be reconciled or retried — if this action should now proceed, it needs a NEW request and a new approval.`
-                        : `[decidio] REFUSING to execute ${decisionId}: its durable state is ${claim.state} — invocation already began, so re-running it could duplicate a committed effect. Inspect it with guard.resume.recover(); settle it with guard.resume.reconcile("${decisionId}", …).`, claim.state === "discarded" ? " (This prints once. The decision is closed — no action is needed.)" : undefined);
+                        : `[decidio] REFUSING to execute ${decisionId}: its durable state is ${claim.state} — invocation already began, so re-running it could duplicate a committed effect. Inspect it with guard.resume.recover(); settle it with guard.resume.reconcile("${decisionId}", …).`, claim.state === "discarded" ? " (This prints once per worker process. The decision is closed — no action is needed.)" : undefined);
                     if (claim.state === "invoking" || claim.state === "indeterminate") {
                         return finish({ status: "indeterminate", decisionId, action: pending.action, reason: claim.state === "invoking"
                                 ? `this decision is in durable state invoking: its action may still be running, may have crashed before any effect, or may have finished without reporting - it may or may not have run. Nothing will retry it; check the worker and the downstream system, then settle it with reconcile("${decisionId}", …).`
@@ -1044,7 +1054,7 @@ export function createDecidioResume(opts) {
                     }
                     return finish({ status: "already_resolved", decisionId, action: pending.action, reason: claim.state === "discarded" ? `this decision was already DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}); that answer is final and this signal lost the race to it` : `this decision already ran (durable state ${claim.state}); this signal lost the race to it` });
                 }
-                return { status: "unknown", decisionId };
+                return finish({ status: "lost_race", decisionId, action: pending.action, reason: `another attempt holds the pre-invocation claim on this decision (durable state ${claim.state}); this signal lost the race and did nothing. If that attempt is alive it will report; if it died, recover() lists the decision and reconcile() can settle it` });
             }
             try {
                 await ctrl.store.markInvoking(decisionId, attemptId);
@@ -1052,7 +1062,14 @@ export function createDecidioResume(opts) {
             catch (e) {
                 await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
                 console.error(`[decidio] ${decisionId}: could not record the invocation boundary (${e?.message ?? e}) — refusing to run the action rather than run it unrecorded.`);
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "could not durably record the invocation boundary" });
+                const head = await ctrl.store.getExecution(decisionId).catch(() => undefined);
+                if (head?.state === "discarded")
+                    return finish({ status: "already_resolved", decisionId, action: pending.action, reason: `this decision was DENIED (${head.verdict ?? "rejected"}) while this signal was about to invoke; that answer is final and nothing ran` });
+                if (head?.state === "executed_unreported" || head?.state === "reported")
+                    return finish({ status: "already_resolved", decisionId, action: pending.action, reason: `this decision already ran (durable state ${head.state}); this signal lost the race to it and did nothing` });
+                if (head?.state === "invoking" || head?.state === "indeterminate")
+                    return finish({ status: "lost_race", decisionId, action: pending.action, reason: `another attempt crossed the invocation boundary first (durable state ${head.state}); this signal did nothing - the winner reports, or reconcile() settles it` });
+                return finish({ status: "lost_race", decisionId, action: pending.action, reason: `could not durably record the invocation boundary (${e?.message ?? e}); nothing ran, the entry stays parked, and a later signal may retry` });
             }
             let result;
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",
@@ -83,7 +83,7 @@
     "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.4.0"
+    "@decidio/verify": "0.4.1"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {