@decidio/sdk 0.3.5 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog — @decidio/sdk
+
+Release notes for the client SDK. The Python package `decidio` ships the same changes under the same
+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
+  stated: what is stable, what is Beta (the engine adapters), what is deprecated and kept until 1.0
+  (`protectBestEffort`, `gateInterruptions`), and the five things reviewers keep finding that only
+  product decisions close (trust-on-first-use issuer DID, the unshipped schema, the unshipped
+  conformance suites, provenance and the repository link). 1.0.0 follows user-acceptance testing.
+- **The tour fails closed on an unpinned check.** If the API omits the issuer DID, the tour used to warn
+  and still report success; it now fails and cleans up.
+- **The tour's preflight names everything it writes**, including `.decidio-token-journal` and
+  `.decidio-pending/`.
+- **`--` ends option parsing on all three verifier doors**, so a receipt saved under a dash-leading
+  name can be verified.
+- **The token recovery journal treats corruption as uncertainty, never absence** (prodsec retest of
+  0.3.5). Every row is parsed and schema-checked before any mint; a row that cannot be trusted refuses
+  `init` and `quickstart`, turns `doctor` red and makes `quickstart cleanup` exit non-zero - the bytes are
+  left as found. Appends are framed (a delimiter first if the previous row lost its newline, a schema
+  version, a write loop before the fsync), so a torn row stays discoverable.
+- **A resume signal that finds the decision `invoking` answers `indeterminate`**, not `already_resolved`
+  with "already ran": the action may still be running, may have crashed before any effect, or may have
+  finished without reporting. `already_resolved` is reserved for the final states.
+- **Temporal (Beta): a custom `confirm` may return the gate's confirm outcome** (validated with
+  `readConfirmResponse`) and it becomes the step's confirmation instead of being discarded.
+- **Transport: every refusal redacts URL userinfo**, including the opaque `scheme:user:secret@` spelling,
+  and Unicode space and format characters (NBSP, ideographic space, zero-width space, …) are refused in
+  both runtimes from one explicit list. Four cases joined the shared transport corpus.
+- **This file ships** in the tarball (and in the Python sdist), as a deliberate publish-boundary line.
+
+## 0.3.5 — the retest residuals
+
+- **Transport:** any control character or whitespace anywhere in the URL is refused before anything is
+  sent; refusals echo a redacted spelling (URL userinfo is a credential).
+- **Credential lifecycle:** the quickstart inspects a previous `.env.quickstart` before minting; secret
+  files are written temp + fsync + rename; **the token recovery journal** (`.decidio-token-journal`,
+  owner-only, append-only) records every minted token id before the credential file exists and retires
+  it on a durable write or any proven revoke. Credential creation fails closed if the journal cannot be
+  written. `quickstart cleanup` sweeps it; `doctor` lists outstanding entries.
+- **Verifiers (all three doors):** the `verificationMethod` must be the issuer's exact `did:key` method
+  identifier, and `created` must be a real calendar date-time. Correctly signed receipts naming a
+  nonexistent method fragment or an impossible time are now INVALID.
+- **Adapter gate:** the same describe validation as the core (a blank action or negative amount is
+  refused before signing or posting).
+- **Outcomes:** a resume signal that lost the race to a final answer is `already_resolved`; a parked row
+  whose payload is gone is `orphaned_state`.
+- Upgrade: no action. Custom stores are unaffected.
+
+## 0.3.4 — first-run consistency
+
+- Tour and README pointers, routing-by-default vs the universal-backstop block named as two states, the
+  stale "unsafe values park and fail on resume" paragraph corrected, cleanup discloses the durable
+  store, help never loads `.env` (and only when usage will actually print), adapter headers current.
+- Upgrade: no action.
+
+## 0.3.2 / 0.3.3 — the transition itself is atomic (COORDINATED UPGRADE)
+
+- **The shipped file stores are an append-only revision chain** (`<key>.rev.<N>`), published with a
+  hard link that refuses an existing name: exactly one writer wins each transition, and a loser
+  re-validates against what actually happened. This closed the pre-0.3.2 race in which a denial could
+  be written and returned and the denied action still run.
+- **Upgrade — read this if a directory is shared by more than one worker:** the first 0.3.2+ store
+  migrates the older marker layout one way. **Stop every older worker that shares the directory before
+  the first 0.3.2+ process starts**, then upgrade them together. An older worker writing into an
+  upgraded directory leaves a marker beside the chain, and that decision reads as unreadable by design.
+  Nothing deletes a revision; each decision keeps a handful of small files (see the README's sizing
+  envelope).
+- 0.3.3: one snapshot of `describe()`'s answer for signing and posting; the shared id grammar at every
+  exported resume door; a compensating revoke when a minted token's credential file fails to write;
+  `reconfirm()` on a reported decision tells the truth about confirmation.
+
+## 0.3.1
+
+- The verifier says what it proves (canonical signed claims, not exact bytes); proof options
+  (`proofPurpose`, `verificationMethod`, `created`) are part of the claim on every door; duplicate
+  `--issuer` flags are refused everywhere; orphaned token ids survive every replacement.
+
+## 0.3.0
+
+- A claim that gates nothing: `reportRecorded` and `executionConfirmed` are distinct, honest booleans.
+  A denial is final on every path. The decision-id grammar is defined server-side and mirrored here.
+- Upgrade for custom stores: `markDiscarded` is required (a hard construction failure without it).
+
+## 0.2.x
+
+- The execution state machine (`parked → claimed_preinvoke → invoking → executed_unreported |
+  indeterminate → reported`), `reconcile()`, `ExecutionContext` with a stable idempotency key, and the
+  composite return (`{ value, decisionId, confirmation }`) with `protectBestEffort` keeping the old shape.

package/README.md

@@ -66,7 +66,8 @@ stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another De
 `init` signs you into your workspace (email + password, or paste the sign-in link from your
 workspace email), generates the agent's Ed25519 keypair **locally** (only the public `did:key`
 is sent), registers the agent, mints its **floor-limited API token** (limited to the agent runtime — request authorization, poll status, report signed confirmation; it cannot administer the workspace or approve anything — and your workspace session never touches the agent's disk), and writes `.env`.
-Every later command reads `.env` from this directory automatically. Re-running init for an
+Every later command that talks to Decidio reads `.env` from this directory automatically (`verify` is
+offline and never does). Re-running init for an
 agent that already has a token REPLACES it — the server keeps one active token per agent, so
 the previous one is revoked and init says so.
 
@@ -80,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`:
 
@@ -677,6 +681,45 @@ Every error raised after a decision exists carries the `decisionId`, so a suspen
 timed-out action is always findable in
 your queue.
 
+## What 0.4 does not yet claim
+
+The retest that graded 0.3.3 *A- for the core and the shipped stores* and the first-run reviews of
+0.3.3 and 0.3.5 agree on what is left, and none of it is a defect a patch release closes. Stated here so
+the next reader grades a promise, not a moving target:
+
+- **Engine adapters are Beta and outside the stability promise.** They pass the same conformance
+  battery as the core against structural mocks; no live LangGraph/Temporal/Inngest/OpenAI restart suite
+  exists yet. Use the core path for production until it does.
+- **The issuer DID is trust on first use.** The tour and `receipt` print your workspace's issuer DID
+  from the same authenticated response that carries the receipt. Pinned verification is only as strong
+  as where you keep that DID: record it through a channel you trust independently (your app's
+  record-verify panel today; a published well-known location is on the roadmap).
+- **Verification is cryptographic, not schema validation.** `VALID` means the issuer's key signed these
+  canonical claims; the sealed-payload schema the receipt names by hash is not shipped, so a
+  structurally odd but correctly signed document is not refused on shape. Shipping the schema is on
+  the roadmap.
+- **The conformance suites are not in the package.** The deterministic two-process schedules that
+  prove the durable store, and the corpus every door is held to, live in the Decidio source repository.
+  A customer cannot rerun them from this tarball; a public conformance kit is on the roadmap.
+- **No provenance attestation, no repository link.** The source repository is private; npm refuses
+  provenance for private repositories, and a link that 404s is worse than none. Registry signatures and
+  lockfile integrity are what you can check today.
+
+## Compatibility and support
+
+- **Stable in 0.4:** `guard.protect` / `withApproval` and their options; the durable resume
+  controller (`createDecidioResume`: `park`, `resolve`, `reconcile`, `reconfirm`, `recover`, the worker
+  and both webhook handlers); the `PendingStore` contract and both shipped stores, including the on-disk
+  revision-chain layout; `EvidenceOutcome` (a root export) and `ResumeStatus` / `RecoveryState` (on the
+  `@decidio/sdk/resume` subpath), additive growth only; the error classes; the CLI's commands, flags and exit codes; the receipt verifier's verdict and
+  reasons. Changes to any of these announce themselves in the changelog first.
+- **Beta:** the engine adapters (above).
+- **Deprecated, kept until 1.0:** `protectBestEffort` (the value-only shape) and the old adapter
+  name `gateInterruptions`. They will be removed in 1.0.0, not before.
+- **Versioning:** 0.x minor releases may still carry deliberate breaking cleanups, announced in the
+  changelog with the upgrade step. 1.0.0 follows user-acceptance testing of this release and freezes the
+  surface above.
+
 ## Notes
 
 - **Framework-agnostic:** it wraps at the tool-call boundary, so it works with any agent runtime (LangGraph, OpenAI Agents SDK, CrewAI, a raw tool loop) and any action (Salesforce, M365, SAP, a DB write).

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/adapters/temporal.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext, type ProtectedExecution } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type ProtectedExecution, type EvidenceOutcome } from "../index.js";
 import { type GateAuth } from "./_gate.js";
 /**
  * @decidio/sdk/temporal — durable suspend via Temporal's native `condition()` + a
@@ -23,7 +23,10 @@ export declare function installDecidioSignal(): Map<string, {
 }>;
 export interface DecidioGateOpts<R = unknown> {
     authorize?: () => Promise<GateAuth>;
-    confirm?: (decisionId: string, result: unknown) => Promise<void>;
+    /** Reports through YOUR activity. Return the gate's confirm response body (validated with
+     *  `readConfirmResponse`) and it becomes the outcome; return nothing and the outcome says the SDK could
+     *  not read back what Decidio recorded (prodsec V035-03: a returned outcome used to be discarded). */
+    confirm?: (decisionId: string, result: unknown) => Promise<EvidenceOutcome | void>;
     /** Map your action's return value to the evidence Decidio records — the same option the core
      *  path takes. Every adapter's stderr note named it and no adapter accepted one, so on this
      *  path the advice could not be followed. */

package/dist/adapters/temporal.js

@@ -25,12 +25,13 @@ export async function decidioGate(config, ctx, run, verdicts, opts = {}) {
     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 = {
+        const returned = await opts.confirm(auth.decisionId, result);
+        const usable = !!returned && typeof returned === "object" && typeof returned.reportRecorded === "boolean";
+        confirmation = usable ? returned : {
             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) {
+        if (!usable && !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.`);
         }

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 {
@@ -168,11 +170,25 @@ async function revokeFreshMint(jti, bearer, writeError, target) {
     return false;
 }
 const JOURNAL_PATH = ".decidio-token-journal";
+const JOURNAL_SCHEMA = 1;
+const JOURNAL_EVENTS = new Set(["probe", "minted", "retired"]);
 function journalAppend(entry) {
     const fresh = !existsSync(JOURNAL_PATH);
+    const row = Buffer.from(JSON.stringify({ v: JOURNAL_SCHEMA, ...entry, at: new Date().toISOString() }) + "\n", "utf8");
     const fd = openSync(JOURNAL_PATH, "a", 0o600);
     try {
-        writeSync(fd, JSON.stringify({ ...entry, at: new Date().toISOString() }) + "\n");
+        if (!fresh) {
+            const st = readFileSync(JOURNAL_PATH);
+            if (st.length && st[st.length - 1] !== 0x0a) {
+                let w = 0;
+                const nl = Buffer.from("\n");
+                while (w < nl.length)
+                    w += writeSync(fd, nl, w);
+            }
+        }
+        let written = 0;
+        while (written < row.length)
+            written += writeSync(fd, row, written);
         fsyncSync(fd);
     }
     finally {
@@ -186,7 +202,86 @@ function journalAppend(entry) {
         hardenFile(JOURNAL_PATH);
     }
 }
+function journalRowProblem(e) {
+    if (!e || typeof e !== "object" || Array.isArray(e))
+        return "not a JSON object";
+    if (e.v !== undefined && e.v !== JOURNAL_SCHEMA)
+        return `schema version ${JSON.stringify(e.v)} is not ${JOURNAL_SCHEMA}`;
+    if (typeof e.event !== "string" || !JOURNAL_EVENTS.has(e.event))
+        return `unknown event ${JSON.stringify(e.event ?? null)}`;
+    if (e.event !== "probe" && (typeof e.jti !== "string" || !e.jti.trim()))
+        return `${e.event} row without a string jti`;
+    if (e.event === "retired" && e.how !== "persisted" && e.how !== "revoked")
+        return `retired row with how=${JSON.stringify(e.how ?? null)}`;
+    return null;
+}
+class JournalCorruptError extends Error {
+    line;
+    why;
+    constructor(line, why) {
+        super(`${JOURNAL_PATH} line ${line}: ${why}`);
+        this.line = line;
+        this.why = why;
+        this.name = "JournalCorruptError";
+    }
+}
+function journalRows() {
+    if (!existsSync(JOURNAL_PATH))
+        return [];
+    const rows = [];
+    const lines = readFileSync(JOURNAL_PATH, "utf8").split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            throw new JournalCorruptError(i + 1, "not valid JSON (a torn or hand-edited row)");
+        }
+        const why = journalRowProblem(e);
+        if (why)
+            throw new JournalCorruptError(i + 1, why);
+        rows.push(e);
+    }
+    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 {
+        journalRows();
+    }
+    catch (e) {
+        return `CORRUPT: ${e?.message ?? e}`;
+    }
     try {
         journalAppend({ event: "probe" });
         return null;
@@ -201,27 +296,23 @@ function journalRetire(jti, how) { try {
 }
 catch { } }
 function journalOutstanding() {
-    if (!existsSync(JOURNAL_PATH))
-        return [];
     const minted = new Map();
-    for (const line of readFileSync(JOURNAL_PATH, "utf8").split(/\r?\n/)) {
-        if (!line.trim())
-            continue;
-        let e;
-        try {
-            e = JSON.parse(line);
-        }
-        catch {
-            continue;
-        }
-        if (e?.event === "minted" && typeof e.jti === "string")
+    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" && typeof e.jti === "string")
+        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()];
 }
-const REFUSE_MINT_NO_JOURNAL = (why) => `✘ could not write the token recovery journal (${JOURNAL_PATH}: ${why}) - refusing to mint a credential this directory cannot record a revocation handle for. Fix the directory's permissions or free space and re-run. Nothing was minted.`;
+const REFUSE_MINT_NO_JOURNAL = (why) => why.startsWith("CORRUPT: ")
+    ? REFUSE_MINT_CORRUPT_JOURNAL(new Error(why.slice("CORRUPT: ".length)))
+    : `✘ could not write the token recovery journal (${JOURNAL_PATH}: ${why}) - refusing to mint a credential this directory cannot record a revocation handle for. Fix the directory's permissions or free space and re-run. Nothing was minted.`;
 function upsertEnv(updates) {
     const remaining = { ...updates };
     const updatedKeys = new Set();
@@ -279,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) {
@@ -288,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) {
@@ -514,15 +618,19 @@ async function cmdDoctor() {
     let warned = 0;
     const line = (good, label) => { log(`${good ? "✔" : "✘"} ${label}`); ok = ok && good; };
     const warn = (label) => { warned++; log(`⚠ ${label}`); };
-    let journalRows = [];
+    let journalItems = [];
     try {
-        journalRows = journalOutstanding();
+        journalItems = journalOutstanding();
     }
     catch (e) {
-        warn(`token recovery journal (${JOURNAL_PATH}) could not be read (${e?.message ?? e}) — it may hold live token ids; fix its permissions and re-run doctor.`);
+        line(false, `token recovery journal: ${e?.message ?? e} — it may hold the id of a live token, and this directory cannot mint until it is repaired or moved aside (every byte is left as found).`);
     }
-    for (const j of journalRows) {
+    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)"}`);
@@ -762,6 +870,10 @@ function cmdVerify(argsIn) {
     const files = [];
     for (let i = 0; i < argsIn.length; i++) {
         const a = argsIn[i];
+        if (a === "--") {
+            files.push(...argsIn.slice(i + 1));
+            break;
+        }
         if (a === "--issuer") {
             const v = argsIn[i + 1];
             if (v === undefined || v === "" || v.startsWith("-")) {
@@ -817,8 +929,11 @@ async function cmdQuickstart(opts = {}) {
     log(`  Target: ${API}${process.env.DECIDIO_API_URL ? "" : "  (the hosted synthetic sandbox — set DECIDIO_API_URL to use your own)"}`);
     log("");
     log("  This tour will: register one synthetic agent · mint a 7-DAY floor-limited token ·");
-    log("  write .env (or .env.quickstart) + .gitignore entries · create one synthetic decision");
-    log("  and its sealed record (records are permanent by design). Cleanup offer at the end.");
+    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 (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)
@@ -847,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;
@@ -894,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}`);
@@ -986,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");
@@ -1014,61 +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);
+    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")}`);
     }
-    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);
+    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`);
     }
-    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 (!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}`);
-    }
-    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]: `);
@@ -1081,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 = (() => {
@@ -1101,7 +1294,27 @@ async function quickstartCleanup(session, envFile) {
     })();
     let journalRevoked = 0;
     const journalStuck = [];
-    for (const j of journalOutstanding()) {
+    let outstanding = [];
+    let heldElsewhere = [];
+    let unheld = [];
+    let journalReconciled = 0;
+    try {
+        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);
             err(`  ⚠ journalled token ${j.jti} was minted against ${j.apiUrl}, not ${API} — revoke it there: DECIDIO_API_URL=${j.apiUrl} npx @decidio/sdk tokens revoke ${j.jti}`);
@@ -1110,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);
@@ -1131,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.`);
@@ -1146,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)
@@ -1160,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:`);
@@ -1203,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`);
@@ -1280,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") {
@@ -1437,7 +1672,12 @@ async function main(argv) {
             if (argsIn.includes("cleanup")) {
                 const envFile = existsSync(".env.quickstart") ? ".env.quickstart"
                     : (readEnvFile().DECIDIO_AGENT_ID ?? "").startsWith("quickstart-") ? ENV_PATH
-                        : journalOutstanding().length ? ".env.quickstart" : undefined;
+                        : (() => { try {
+                            return (journalOwed().length || journalUnheld().length) ? ".env.quickstart" : undefined;
+                        }
+                        catch {
+                            return ".env.quickstart";
+                        } })();
                 if (!envFile) {
                     log("Nothing to clean up here: no .env.quickstart, .env doesn't belong to a quickstart agent, and the token recovery journal owes nothing.");
                     return 0;
@@ -1458,7 +1698,8 @@ async function main(argv) {
                 err("✘ --expires-days needs a positive whole number of days (e.g. --expires-days 30).");
                 return 2;
             }
-            const nameArg = argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
+            const ddIdx = argsIn.indexOf("--");
+            const nameArg = ddIdx >= 0 ? argsIn[ddIdx + 1] : argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
             let name = nameArg ?? process.env.DECIDIO_AGENT_ID ?? "my-agent";
             if (unique)
                 name = `${name}-${randomBytes(2).toString("hex")}`;
@@ -1530,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,11 +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;
-    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

@@ -450,10 +450,18 @@ export declare class DecidioSuspendedError extends Error {
 /** `indeterminate` (0.2.0): the handler was INVOKED and then threw. Whether the downstream
  *  effect committed is not knowable from here, so the action is never retried automatically —
  *  it waits for reconcile(). Callers that switch exhaustively on this union must handle it. */
-/** `already_resolved` (0.3.5): this resume signal LOST the transition race to an earlier, final answer
- *  (a denial, or an execution that already ran) — `reason` names which. It used to read `unknown`,
- *  which is the word for "not ours"; safety was right and the diagnosis was not (prodsec V033-06). */
-export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown" | "indeterminate" | "already_resolved";
+/** `already_resolved` (0.3.5): this resume signal LOST the transition race to an earlier, FINAL answer
+ *  (a denial, an execution that already ran, or a report already recorded) — `reason` names which. It used
+ *  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. */
+/** `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,10 +1046,15 @@ 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);
-                    return finish({ status: claim.state === "indeterminate" ? "indeterminate" : "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` });
+                        : `[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}", …).`
+                                : claim.reason });
+                    }
+                    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);
@@ -1047,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/dist/signing.d.ts

@@ -78,6 +78,10 @@ export declare function assertJsonSafe(value: unknown, path?: string): void;
  *  (it is refused as one), so no refusal may print it - every branch of assertSafeTransport echoes through
  *  this, not the raw string (invariant-guard, 0.3.5). */
 export declare function redactUrl(u: string): string;
+/** Unicode SPACE and FORMAT characters a URL must never contain: the Zs/Zl/Zp separators (NBSP, ideographic
+ *  space, …) and the zero-width formats. Spelled as an explicit list in BOTH runtimes so the answers cannot
+ *  drift with a library's notion of whitespace (Python's urlsplit strips a leading NBSP; WHATWG does not). */
+export declare const URL_UNICODE_SPACE: RegExp;
 export declare function assertSafeTransport(url: string, hasCredential: boolean): void;
 /** The ONE answer to "does this request carry a credential worth protecting?" (A6, 0.1.12).
  *  A signed identity proof is a credential too: sending it over remote plaintext disclosed

package/dist/signing.js

@@ -106,14 +106,17 @@ export function assertJsonSafe(value, path = "args") {
     };
     walk(value, path);
 }
-export function redactUrl(u) { return u.replace(/\/\/[^/@]*@/, "//***@"); }
+export function redactUrl(u) {
+    return u.replace(/\/\/[^/?#]*@/, "//***@").replace(/^([^/?#@:]*:)(?!\/\/)[\/\\]*[^/?#]*@/, "$1***@");
+}
+export const URL_UNICODE_SPACE = /[\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\u200b-\u200d\u2060]/;
 export function assertSafeTransport(url, hasCredential) {
     if (typeof url !== "string") {
         throw new Error(`[decidio] the gate URL is ${url === null ? "null" : typeof url}, not a string, so there is no host to send to. Decidio needs a full https URL (or http://localhost for local dev). Nothing was sent.`);
     }
     for (const ch of url) {
         const cp = ch.codePointAt(0);
-        if (cp <= 0x20 || (cp >= 0x7f && cp <= 0x9f) || cp === 0xfeff) {
+        if (cp <= 0x20 || (cp >= 0x7f && cp <= 0x9f) || cp === 0xfeff || URL_UNICODE_SPACE.test(ch)) {
             throw new Error(`[decidio] the gate URL ${JSON.stringify(redactUrl(url))} contains whitespace or a control character (U+${cp.toString(16).toUpperCase().padStart(4, "0")}) - a validator and a transport can read such a spelling differently, so it is refused as written. Remove it. Nothing was sent.`);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.3.5",
+  "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",
@@ -40,6 +40,7 @@
     "dist",
     "openapi.yaml",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
@@ -82,7 +83,7 @@
     "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.3.5"
+    "@decidio/verify": "0.4.1"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {