@decidio/sdk 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,81 @@ 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.5.0 — `verify` pins by default
+
+**Breaking, on purpose (founder ruling 2026-09-04, after the prodsec review of 0.4.3).** Every CLI verify door - `npx
+@decidio/sdk verify`, the standalone `decidio-verify`, `python -m decidio verify` and `python -m decidio.verify` -
+now REFUSES to run without `--issuer <did:key>` (exit 2, with the remedy printed). An unpinned VALID only proves the
+file agrees with itself: the reviewer forged a self-signed "wire all funds" receipt and the exit code said yes. Scripts
+trust exit status, not warnings, so the safe check is now the default and the structural check is a named choice:
+`--allow-unpinned` runs it, and its verdict carries the UNPINNED warning as before. `--allow-unpinned` together with
+`--issuer` is refused as ambiguous, like a disagreeing repeated pin.
+
+- **What to change:** add `--issuer <your workspace DID>` to any scripted verify (the `receipt` command prints the
+  DID; the app's record-verify panel shows it), or `--allow-unpinned` where you genuinely want structure only.
+- **Unchanged:** the LIBRARY (`verifyReceipt(vc)` / `verify_receipt(vc)`) still verifies unpinned when no issuer is
+  passed - a caller reads `issuer` in the result and decides; the CLIs are what scripts trust blindly.
+- Vectors in all three suites: the refusal (exit 2, names `--issuer` and `--allow-unpinned`), the named unpinned run
+  reaching a verdict, both flags refused together. The usage pages, both READMEs and the `receipt` command's hint
+  say the new rule; the live selftest names its one unpinned run.
+- **The sealed payload names two fields for what they are (schemaVersion 2).** `deciders` → `nominatedDeciders` (the
+  people nominated IN ADVANCE; the ratifier is who decided, so `nominated deciders: 0, ratified: yes` reads as it
+  should) and, inside `authority`, `appliedLimits` → `evaluatedLimits` (what the request was measured against - the
+  requested amount, the auto-approve threshold, the hard cap - not limits that "applied"). New records carry the v2
+  `payloadSchemaUri`; the canonicalization (`jcs-v1`) is unchanged, so verification is untouched. Both verifiers print
+  `nominated deciders: N` and read the v1 names too (every record sealed before 0.5.0 is lab test data). Founder
+  ruling 2026-09-04: rename now, while no customer record carries the old names.
+- **From the 0.4.4 first-run audit (B+), the small items** (founder: go): quickstart checks connectivity BEFORE its
+  first disk write (a dead host leaves the directory untouched and says "Nothing was written"); `tokens list --mine`
+  after cleanup reads this directory's agents from the token recovery journal; `receipt` prints resolved identities
+  only on a terminal (a pipe or a log gets a one-line note; `--json` hands them over explicitly); the ④ frame says the
+  issuer DID was first seen over this connection and where to cross-check it (`<api>/api/did`, public, no sign-in);
+  the help page and README say what cleanup leaves behind; the README no longer calls the lab ONE SHARED workspace
+  (every invited tester has their own), explains the in-memory quota counter, lists `receipt --json` and `dev --port`,
+  and calls the journal append-only by behaviour, not by enforcement. Vectors: the dead-host tour, `--mine` from the
+  journal, the receipt in a pipe vs on a terminal.
+- Two Lows from the prodsec retest of 0.4.4: `quickstart cleanup` with nothing to clean still ENDS the stored sign-in
+  (the early "Nothing to clean up here" return skipped it, contradicting the documented promise; vector in both
+  suites), and the resume module's comments say `lost_race` / `already_resolved` where the runtime does (they still
+  said `unknown`); `onResolved` is documented as firing for every outcome except `unknown`.
+
+## 0.4.4 — the small findings of the 0.4.3 prodsec run: frames at 80 columns, a local install upgrades in place, a key-less .env survives the tour
+
+An external prodsec reviewer ran 0.4.3 from a stranger's install (2026-09-04; grade B, "trust in the core mechanics
+went up"). Its design questions (a mandatory `--issuer`, out-of-band issuer distribution, npm provenance) are founder
+calls in the backlog; these are its small findings, each with a vector that was red first.
+
+- **Frames never wider than the terminal.** The 0.4.2 frames had a width FLOOR of 84 columns, and the terminal driver
+  that gates the tours ran only at 300 columns - so on the most common width, 80, every border wrapped. The floor now
+  yields to the terminal, and both suites run the approval tour at 80 columns: no frame line wider than the window,
+  every frame line closes with its border.
+- **The update gate knows a project-local install.** `npm install @decidio/sdk` then `npx @decidio/sdk …` (this
+  README's own path) runs the CLI from the project's node_modules; the gate offered `npm i -g` (global state nobody
+  asked for) and then re-ran the same old local file. Three shapes now, each upgraded the way it was installed:
+  project-local → `npm i @decidio/sdk@latest` in that project; global → `-g`; under npx → the `@latest` form,
+  printed. The re-run the gate spawns carries `DECIDIO_UPDATE_REEXEC=1` and never checks again, so a version that did
+  not move cannot loop the prompt. (Python: `pip install -U` already upgrades the interpreter that is running; it
+  gains the re-run marker.)
+- **A key-less agent `.env` is left alone.** The tour used its own `.env.quickstart` only when `.env` held a signing
+  key; the SDK's `agentKey` is optional, so an agent configured without one had its agent fields overwritten and then
+  stripped by cleanup. ANY agent identity in `.env` (`DECIDIO_AGENT_ID`, `_DID`, `_KEY` or `DECIDIO_API_TOKEN`) now
+  sends the tour to its own file. Vector: such a file is byte-identical after the tour and its cleanup.
+- **The ④ frame names what was sealed** without `--explain`: `decision  payInvoice $86,000 · APPROVED · routed to
+  a human by policy (no auto-approve rule for this agent)` (REJECTED on the denial's record).
+- A `.gitignore` the tour CREATES also ignores `node_modules/`; an existing file gets only the secret entries.
+- `openapi.yaml` now states the release version (it read 0.1.11 beside a 0.4.3 package), and a seven-manifest
+  lockstep check (`packages/conformance/manifests.mjs`: both package.json, both package-lock.json, pyproject,
+  `__init__`, openapi) runs in CI and on the publish path - 0.4.3 shipped with both locks a version behind.
+- Documented: the token recovery journal's vocabulary (`minted`, `retired how=persisted`, `retired how=revoked`,
+  `probe`) - `persisted` means the credential file holds the token and is its handle, not that it was revoked.
+- **`logout` says what it does** (prodsec second pass on 0.4.3 - "A / A-", two Lows): it forgets the stored sign-in on
+  this computer; the session token itself stays valid until it expires - there is no server-side revocation yet, and no
+  wording implies one any more (`logout`, cleanup, the sign-in prompt, the usage page, both READMEs). Vectors: the
+  statement is asserted, and `logout` makes no API call.
+- The shipped `.d.ts` state-machine comment names the terminal `discarded` state beside the chain that omitted it.
+- Confirmed as intended, no change: the online `receipt` command prints the tokenized identities your access
+  covers ("Resolved for you"); the file keeps its tokens.
+
 ## 0.4.3 — the stale-install gate, frames you can read at a glance, and a phone door that lands
 
 The founder's UAT round 2, second half (2026-09-04). Nobody is on 0.4.2 yet, so it was never tagged; this carries both.

package/README.md

@@ -29,17 +29,18 @@ prints the approve command and exits rather than approve its own request (CI can
 
 ## Quickstart — seven steps to your first sealed receipt
 
-Under 30 minutes, no help needed. You'll need Node 20.6+ and a terminal.
+Under 30 minutes for all seven steps (the tour itself is two minutes), no help needed. You'll need Node 20.6+ and a terminal.
 
 **You'll need a Decidio workspace.** → Request one at [decidioai.com](https://decidioai.com/#early-access)
 
-The hosted sandbox is synthetic data, safe to experiment in. Note it is ONE SHARED workspace:
-workspace-wide views like `tokens list` or `approvals` show every lab member's agents and
-decisions — the shared-lab boundary working as designed. Production workspaces are per-tenant.
+The hosted sandbox is synthetic data, safe to experiment in. Every invited tester gets their OWN
+workspace: workspace-wide views like `tokens list` or `approvals` show every agent and decision in
+your workspace — yours alone unless you invite others into it. Production workspaces are per-tenant too.
 
 Lab workspaces have a **governed-action allowance** (currently 30 actions/hour); hitting it raises
 a typed `DecidioRateLimitError` naming the limit and reset time — nothing is routed or executed —
-and `tokens list` shows your remaining allowance any time.
+and `tokens list` shows your remaining allowance any time. The counter is in memory, per API instance: a
+deploy resets it, so `30/30` right after a governed action means the API restarted, not that the action was free.
 
 **PowerShell users** — the equivalents for every Bash idiom used below:
 
@@ -66,7 +67,7 @@ npx @decidio/sdk init --unique my-agent   # --unique appends a random suffix: co
 > Just ran `npx @decidio/sdk quickstart` in this directory and kept its agent? Its `.env` already
 > works — skip this step and continue at step 3.
 
-Every CLI command talks to the hosted sandbox by default and announces its target host on
+Every network command talks to the hosted sandbox by default (`verify` is offline) and announces its target host on
 stderr each run — set `DECIDIO_API_URL` (env or `.env`) to point at another Decidio instead.
 
 `init` signs you into your workspace (email + password, or paste the sign-in link from your
@@ -152,9 +153,10 @@ npx @decidio/sdk verify --issuer <did:key:...> decidio-receipt-<decisionId>.json
 ```
 
 Lead with the pin: `--issuer` binds the check to YOUR workspace's DID (the `receipt` command
-prints it from the authenticated response, so it is already on your screen). An UNPINNED
-`verify` proves internal consistency only — any keyholder could have issued such a file — and
-says so; pinned verification proves *who*. The download is an authenticated fetch from your
+prints it from the authenticated response, so it is already on your screen). Since 0.5.0 the
+CLI refuses to run without it: an UNPINNED check proves internal consistency only — any keyholder
+could have issued such a file — so it is a named choice (`--allow-unpinned`), and its verdict says
+so; pinned verification proves *who*. The download is an authenticated fetch from your
 workspace; the *verification* is fully offline — the verifier ships inside this package (no second download, no registry probe, same
 implementation as the standalone `@decidio/verify`). The receipt is a W3C Verifiable
 Credential: signature and content binding verify with no Decidio account and no network — the
@@ -523,14 +525,14 @@ ever wanted it is an offline job with every writer stopped.
 The cryptography is only half the evidence. These are the fields that an outside reader has
 actually misread on a first run, and what each one means.
 
-**`ratified: yes` next to `deciders: 0` is not a contradiction.** `deciders` is the list of people
+**`ratified: yes` next to `nominated deciders: 0` is not a contradiction.** `nominatedDeciders` is the list of people
 nominated **in advance** to decide. When an agent's request is *routed* rather than pre-assigned,
 that list is empty — nobody was nominated, because the request had not happened yet. The person who
 actually decided is the **ratifier** (`ratifiedBy`). So a receipt for a human-approved action reads
-`deciders: 0, ratified: yes`, and the human is recorded, in the field named for the role they
+`nominated deciders: 0, ratified: yes`, and the human is recorded, in the field named for the role they
 played. The verifier prints this explanation whenever the pair appears.
 
-**`appliedLimits` is what the request was MEASURED AGAINST, not a rule that fired.** It holds up to
+**`evaluatedLimits` is what the request was MEASURED AGAINST, not a rule that fired.** (Receipts sealed before 0.5.0 spell these two `deciders` and `appliedLimits` - schemaVersion 1; the verifier reads both.) It holds up to
 three entries, and only those that have a value: `requested_amount` (the amount actually asked for),
 `auto_approve_threshold` and `hard_cap` (the ceilings on the agent's own token). So a decision routed
 to a human because *no rule matched* can still list an `auto_approve_threshold` — that is the bar the
@@ -551,14 +553,14 @@ the roadmap; today the URN is an identifier only, and this note exists so it doe
 
 **`prevHash` proves a pointer, not an ancestry.** A non-null `prevHash` shows this record was
 sealed after a specific predecessor, but a single-file verification cannot check that predecessor
-exists or is what it claims. Verify a chain (`verify a.json b.json c.json`) when the sequence
+exists or is what it claims. Verify a chain (`verify --issuer <did> a.json b.json c.json`) when the sequence
 matters.
 
 **Pinning is trust-on-first-use.** The first time you fetch a receipt, the record *and* the issuer
 DID arrive in the same authenticated response — so that first check trusts the connection, not the
 key. What pinning buys is everything afterwards: record the DID once, out of band if you can, and
 every later verification is checked against a key you chose rather than one you were handed. The
-verifier says so on every unpinned run.
+verifier refuses an unpinned run unless you ask for one (`--allow-unpinned`), and marks that verdict.
 
 ## Upgrading from 0.2.x to 0.3.0
 
@@ -638,20 +640,22 @@ that fits every other confirm error.
 
 - `quickstart` — the guided two-minute tour (gate → approve → execute → proof)
   - `--auto-approve-demo` approves the tour's own synthetic decision so it can run headless; it
-    then CLEANS UP the tour agent and token automatically. Pass `--keep-agent` to keep them.
+    then revokes the tour token and deletes its local credentials automatically (the inert
+    registration row and the permanent sealed record stay). Pass `--keep-agent` to keep them.
   - An interactive run keeps the agent by default and offers cleanup at the end;
     `quickstart cleanup` works later too.
 - `init [agentId] [--unique] [--force] [--expires-days N]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries). Refuses to overwrite a *different* agent's key in this directory; `--force` backs the old `.env` up first.
 - `doctor` — config, connectivity, and what your current token can do
 - `approvals [--mine] [--json]` / `approvals approve|reject <id> [reason]` — the human side, from your terminal (the list is workspace-wide; `--mine` narrows it to this directory's agent)
-- `receipt <id>` — download a sealed decision's Authority Receipt to a `.json` file
+- `receipt <id> [--json]` — download a sealed decision's Authority Receipt to a `.json` file (`--json`: stdout is the JSON result only; the identities your access covers print only on a terminal, or in the JSON)
 - `verify [--issuer <did>] <file>...` — verify receipts offline (the canonical verifier; the standalone `@decidio/verify` package is the same implementation, for auditors who want zero Decidio dependency — the sdk depends on the verifier released alongside it, at the same version). Unknown flags are refused, never ignored. Fully offline AND fully decoupled: it touches no network and reads no `.env` — a receipt verifies identically from an empty directory.
 - `tokens list [--mine]` / `tokens revoke <jti>` — see and kill agent tokens (values are never re-shown; the jti is the revocation handle). Each row carries its status — `active`, `expired`, or `REVOKED <date>` — so the list confirms the revocations it performs; re-revoking is an honest no-op (exit 1). The list is workspace-wide (a shared workspace shows every member's agents); `--mine` narrows to this directory's agent
 - `quickstart cleanup` — revoke the tour's token and delete its local credentials. What stays, honestly: sealed records (permanent by design) and the agent's registration row (inert without key or token; server-side deregistration is on the roadmap) Also ends the stored sign-in.
-- **Update check.** Network commands ask the public npm registry once a day whether a newer version exists; if so, an interactive run asks `Upgrade now? [y/n]` first (`y` upgrades through npm and re-runs your command; `n` exits), a headless run prints the notice and continues (`DECIDIO_REQUIRE_LATEST=1` makes it exit). `DECIDIO_NO_UPDATE_CHECK=1` skips it. Nothing is sent to Decidio; `verify` never checks.
+- **Update check.** Network commands ask the public npm registry once a day whether a newer version exists; if so, an interactive run asks `Upgrade now? [y/n]` first (`y` upgrades the way you installed - `npm i @decidio/sdk@latest` in the project for a local install, `-g` for a global one, and under `npx` it prints the `@latest` form - then re-runs your command once; `n` exits), a headless run prints the notice and continues (`DECIDIO_REQUIRE_LATEST=1` makes it exit). `DECIDIO_NO_UPDATE_CHECK=1` skips it. Nothing is sent to Decidio; `verify` never checks.
+- **The token recovery journal** (`.decidio-token-journal`, owner-only, gitignored; ids and timestamps, never a token value; append-only by the CLI's behaviour — not OS-enforced or tamper-evident). One JSON row per event: `minted` (a token was issued, written BEFORE its credential file), `retired how=persisted` (the credential file now holds it - the token is live and that file is its handle; not revoked), `retired how=revoked` (revoked server-side), `probe` (a durability check). `doctor` names rows still outstanding; `quickstart cleanup` sweeps them.
 - `quickstart --phone web` — the QR at the human step opens the phone web rendering even when the Decidio app is installed (by default it opens the app when there is one).
-- `login [email]` / `logout` — sign in ONCE (the CLI emails you a link; you paste it) and end that sign-in. The session is stored in your user profile, owner-only, bound to the terminal window that created it, for 30 days; `DECIDIO_SESSION_TOKEN` in the environment outranks it (headless shells).
-- `dev [--target URL]` — local relay for the resume webhook (operator setups)
+- `login [email]` / `logout` — sign in ONCE (the CLI emails you a link; you paste it) and forget that sign-in on this computer (the session token itself stays valid until it expires (up to 30 days) — there is no server-side revocation yet). The session is stored in your user profile, owner-only, bound to the terminal window that created it, for 30 days; `DECIDIO_SESSION_TOKEN` in the environment outranks it (headless shells).
+- `dev [--target URL] [--port N]` — local relay for the resume webhook (operator setups)
 
 The CLI's stream contract: **stdout carries results only** (safe to pipe — `--json` output is
 pure JSON); errors, usage shown on *error* paths, and the per-run target-host announcement go
@@ -660,7 +664,7 @@ result and prints on stdout. Exit codes: 0 success · 1 failure or honest no-op
 
 Commands that administer your workspace (`init`, `approvals`, `receipt`, `tokens`) use a **session**
 sign-in: `login` stores it in your user profile (owner-only, bound to this terminal window, 30 days;
-`logout` or `quickstart cleanup` ends it), or `DECIDIO_SESSION_TOKEN` supplies it for headless shells. What lands on disk in `.env`: the agent's floor-limited
+`logout` or `quickstart cleanup` forgets it here — the token itself stays valid until it expires), or `DECIDIO_SESSION_TOKEN` supplies it for headless shells. What lands on disk in `.env`: the agent's floor-limited
 API token, its locally-generated private signing key, and a webhook secret (used only in
 operator deployments) — `init` adds `.env` to `.gitignore` for you; move secrets to a secret
 manager for production.
@@ -705,7 +709,7 @@ the next reader grades a promise, not a moving target:
 - **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).
+  record-verify panel, and published in the open by the Decidio host you use at `<api>/api/did` — for the hosted sandbox https://decidio-api.onrender.com/api/did).
 - **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

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync, rmSync, openSync, writeSync, fsyncSync, closeSync, renameSync, mkdirSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-import { join as joinPath } from "node:path";
+import { join as joinPath, resolve as resolvePath, sep as pathSep } from "node:path";
 import { createServer } from "node:http";
 import { execFileSync, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
@@ -12,7 +12,7 @@ import { createRequire } from "node:module";
 import { generateKeypair, assertSafeTransport, redactUrl } from "./signing.js";
 import { hardenFile } from "./resume.js";
 import { withApproval, DecidioRateLimitError, DecidioRejectedError, DecidioTimeoutError, didFromPrivateKey } from "./index.js";
-import { verifyReceipt, runVerify } from "@decidio/verify";
+import { verifyReceipt, runVerify, pinRequiredMessage } from "@decidio/verify";
 const VERSION = (() => {
     try {
         return createRequire(import.meta.url)("../package.json").version;
@@ -378,12 +378,15 @@ function assertNotTracked(path) {
 }
 function ensureGitignore() {
     const entries = [".env", ".env.quickstart", ".env.*.bak", ".env.*.tmp", ".decidio-pending/", ".decidio-token-journal"];
-    const existing = existsSync(".gitignore") ? readFileSync(".gitignore", "utf8") : "";
+    const creating = !existsSync(".gitignore");
+    if (creating)
+        entries.push("node_modules/");
+    const existing = creating ? "" : readFileSync(".gitignore", "utf8");
     const missing = entries.filter((e) => !existing.split(/\r?\n/).some((l) => l.trim() === e || l.trim() === e.replace(/\/$/, "")));
     if (!missing.length)
         return;
     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)`);
+    log(`✔ ${creating ? "wrote" : "added"} ${missing.join(" + ")} to .gitignore (secret files here will not be committed)`);
 }
 function recordKindOf(credential) {
     try {
@@ -396,7 +399,7 @@ function recordKindOf(credential) {
     }
 }
 function sessionReminder() {
-    log(`  ⚠ agent code launched from THIS terminal inherits your sign-in — run logout first (it also ends on close or cleanup); if you`);
+    log(`  ⚠ agent code launched from THIS terminal inherits your sign-in — run logout first (it forgets the sign-in here; the token itself stays valid until it expires); if you`);
     log(`    exported DECIDIO_SESSION_TOKEN, unset it ${dim("(bash/zsh: unset DECIDIO_SESSION_TOKEN · PowerShell: Remove-Item Env:DECIDIO_SESSION_TOKEN)")}`);
 }
 const TTY_OUT = !!process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
@@ -409,7 +412,7 @@ const visibleLength = (s) => s.replace(/\x1b\[[0-9;]*m|\x1b\]8;;[^\x1b]*\x1b\\/g
 function frameWidth(rows) {
     const cols = (process.stdout.columns ?? 0) > 20 ? process.stdout.columns : 120;
     const widest = rows.reduce((m, r) => Math.max(m, visibleLength(r)), 0);
-    return Math.max(FRAME_WIDTH, Math.min(widest + 4, cols - 1));
+    return Math.min(cols - 1, Math.max(FRAME_WIDTH, widest + 4));
 }
 function block(n, title, rows, tone) {
     const tint = tone === "choice" ? (process.env.TERM?.includes("256") || process.env.COLORTERM || process.env.WT_SESSION ? "38;5;208" : "33") : tone === "good" ? "32" : tone === "bad" ? "31" : null;
@@ -538,7 +541,7 @@ function endSession() {
     }
 }
 async function loginFlow(purpose, emailArg) {
-    log(purpose === "Signing in" ? `Sign in once — 30 days, or until this terminal closes, logout, or cleanup.` : `${purpose} needs your Decidio workspace sign-in — once: 30 days, or until this terminal closes, logout, or cleanup.`);
+    log(purpose === "Signing in" ? `Sign in once — kept on this computer for 30 days, or until this terminal closes, logout, or cleanup.` : `${purpose} needs your Decidio workspace sign-in — once: kept on this computer for 30 days, or until this terminal closes, logout, or cleanup.`);
     const email = emailArg ?? await ask("  email: ");
     if (!email) {
         log("  ✘ no email given - re-run when you have it.");
@@ -617,9 +620,12 @@ async function cmdLogin(emailArg) {
     const token = await loginFlow("Signing in", emailArg);
     return token ? 0 : 1;
 }
+const TRUTH_SESSION = "The session token itself stays valid until it expires (up to 30 days) — there is no server-side revocation yet";
 function cmdLogout() {
-    if (endSession())
-        log("✔ signed out — the stored sign-in is removed.");
+    if (endSession()) {
+        log("✔ signed out — the stored sign-in is removed from this computer.");
+        log(`  ${TRUTH_SESSION}; if you exported DECIDIO_SESSION_TOKEN or pasted the link anywhere else, those copies still work.`);
+    }
     else
         log("• no stored sign-in on this machine for this Decidio.");
     if (process.env.DECIDIO_SESSION_TOKEN)
@@ -1034,7 +1040,10 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
-    if (resolved && Object.keys(resolved).length) {
+    if (resolved && Object.keys(resolved).length && !process.stdout.isTTY) {
+        log(`  ${Object.keys(resolved).length} identity field(s) your access covers are shown only on a terminal (this is a pipe or a log) — use --json to receive them explicitly.`);
+    }
+    else if (resolved && Object.keys(resolved).length) {
         log(`  Resolved for you (${Object.keys(resolved).length} field${Object.keys(resolved).length === 1 ? "" : "s"} your access covers — the FILE keeps the tokens, so it stays verifiable and safe to hand on):`);
         for (const [tok, val] of Object.entries(resolved))
             log(`    ${tok}  →  ${val}`);
@@ -1045,11 +1054,12 @@ async function cmdReceipt(id, jsonMode = false) {
         log(``);
         log(`${issuer}`);
         log(``);
+        log(`  Cross-check it out of band — the same DID is published by this Decidio host at ${API}/api/did (public, no sign-in).`);
         log(`  Then verify, pinned to it (the same DID, inline — copy from the line above, not this one,`);
         log(`  which your terminal may wrap):`);
         log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
-        log(`  Without --issuer the verifier proves the receipt is internally consistent, but NOT who`);
-        log(`  issued it; it says so in its output.`);
+        log(`  The verifier refuses to run without --issuer: a pin is what makes VALID mean "issued by your`);
+        log(`  workspace"; --allow-unpinned runs a structural check only, and says so.`);
     }
     else {
         log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
@@ -1059,6 +1069,7 @@ async function cmdReceipt(id, jsonMode = false) {
 }
 function cmdVerify(argsIn) {
     let expectedIssuer;
+    let allowUnpinned = false;
     const files = [];
     for (let i = 0; i < argsIn.length; i++) {
         const a = argsIn[i];
@@ -1066,6 +1077,10 @@ function cmdVerify(argsIn) {
             files.push(...argsIn.slice(i + 1));
             break;
         }
+        if (a === "--allow-unpinned") {
+            allowUnpinned = true;
+            continue;
+        }
         if (a === "--issuer") {
             const v = argsIn[i + 1];
             if (v === undefined || v === "" || v.startsWith("-")) {
@@ -1096,10 +1111,18 @@ function cmdVerify(argsIn) {
         }
     }
     if (!files.length) {
-        err("usage: npx @decidio/sdk verify [--issuer <did:key>] <receipt.json> [more.json ...]");
+        err("usage: npx @decidio/sdk verify --issuer <did:key> <receipt.json> [more.json ...]   (or --allow-unpinned)");
         err("  Verifies Authority Receipts OFFLINE — signature, content binding, and (for several files) chain order.");
         return 2;
     }
+    if (expectedIssuer !== undefined && allowUnpinned) {
+        err("✘ --allow-unpinned and --issuer together — an unpinned check and a pinned one are different questions; ask one.");
+        return 2;
+    }
+    if (expectedIssuer === undefined && !allowUnpinned) {
+        err(pinRequiredMessage("npx @decidio/sdk verify"));
+        return 2;
+    }
     const texts = new Map();
     for (const f of files) {
         try {
@@ -1148,9 +1171,15 @@ async function cmdQuickstart(opts = {}) {
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
-    const envFile = readEnvFile().DECIDIO_AGENT_KEY ? ".env.quickstart" : ENV_PATH;
+    const prior = readEnvFile();
+    const envFile = ["DECIDIO_AGENT_KEY", "DECIDIO_AGENT_ID", "DECIDIO_AGENT_DID", "DECIDIO_API_TOKEN"].some((k) => (prior[k] ?? "").trim()) ? ".env.quickstart" : ENV_PATH;
     if (!assertNotTracked(envFile))
         return 1;
+    const reach = await api("/api/health", {}, "", true);
+    if (!(reach.status >= 200 && reach.status < 300)) {
+        err(`✘ cannot reach ${API}${reach.status ? ` (HTTP ${reach.status})` : " (no response)"} — check the network (or DECIDIO_API_URL) and re-run. Nothing was written.`);
+        return 1;
+    }
     ensureGitignore();
     let agentId = `quickstart-${randomBytes(5).toString("hex")}`;
     if (EXPLAIN)
@@ -1470,8 +1499,9 @@ async function cmdQuickstart(opts = {}) {
                 }
                 block("④", "The record", [
                     `✔ VALID — ${fname} ${dim("(signature + content binding, offline, PINNED to your workspace issuer)")}`,
+                    `${bold("decision")} payInvoice $86,000 · REJECTED · routed to a human by policy (no auto-approve rule for this agent)`,
                     `${bold("record")}   record kind: ${recordKindOf(rec.body.credential) ?? "?"} ${dim("— the denial is sealed too")}`,
-                    `${bold("issuer")}   ${issuer} ${dim("· your trust anchor: verify --issuer <did> <receipt.json>")}`,
+                    `${bold("issuer")}   ${issuer} ${dim(`· your trust anchor — first seen over this signed-in connection; cross-check ${API}/api/did, then verify --issuer <did> <receipt.json>`)}`,
                 ], "bad");
                 denialVerified = true;
             }
@@ -1554,8 +1584,9 @@ async function cmdQuickstart(opts = {}) {
         const tier = detail.body?.record?.confirmation?.status;
         block("④", "The receipt", [
             `✔ VALID — ${fname} ${dim("(signature + content binding, offline, PINNED to your workspace issuer)")}`,
+            `${bold("decision")} payInvoice $86,000 · APPROVED · routed to a human by policy (no auto-approve rule for this agent)`,
             `${bold("record")}   record kind: ${recordKindOf(rec.body.credential) ?? "?"}${tier ? ` · evidence: ${tier}` : ""} ${dim("— the receipt seals the DECISION; execution evidence lives on the record")}`,
-            `${bold("issuer")}   ${issuer} ${dim("· your trust anchor: verify --issuer <did> <receipt.json>")}`,
+            `${bold("issuer")}   ${issuer} ${dim(`· your trust anchor — first seen over this signed-in connection; cross-check ${API}/api/did, then verify --issuer <did> <receipt.json>`)}`,
         ], "good");
         const secs = Math.round((Date.now() - t0) / 1000);
         block("✔", `Done in ${secs}s`, [
@@ -1753,7 +1784,7 @@ async function quickstartCleanup(session, envFile) {
         log(`      ${process.platform === "win32" ? "Remove-Item -Recurse .decidio-pending" : "rm -r .decidio-pending"}`);
     }
     if (endSession())
-        log(`  ✔ signed out — the stored sign-in is ended (npx @decidio/sdk login to sign in again).`);
+        log(`  ✔ signed out — the stored sign-in is removed from this computer (the token itself stays valid until it expires; npx @decidio/sdk login to sign in again).`);
     else if (process.env.DECIDIO_SESSION_TOKEN)
         log(`  • DECIDIO_SESSION_TOKEN is still exported in this shell — unset it when you are done.`);
     return 0;
@@ -1769,7 +1800,16 @@ async function cmdTokens(sub, jti, mineOnly = false) {
         err("usage: npx @decidio/sdk tokens revoke <jti>   (find the jti with: npx @decidio/sdk tokens list)");
         return 2;
     }
-    if (mineOnly && !process.env.DECIDIO_AGENT_ID) {
+    const journalAgents = (() => {
+        try {
+            return [...new Set(journalRows().map((row) => row?.agentId).filter((a) => typeof a === "string" && a.length > 0))];
+        }
+        catch {
+            return [];
+        }
+    })();
+    const myAgents = process.env.DECIDIO_AGENT_ID ? [process.env.DECIDIO_AGENT_ID] : journalAgents;
+    if (mineOnly && !myAgents.length) {
         err(`✘ --mine needs an agent identity, and there is no DECIDIO_AGENT_ID in this directory's .env or your environment.`);
         err(`  Run this from your agent's directory (where init wrote .env), or drop --mine for the workspace-wide list.`);
         return 2;
@@ -1809,8 +1849,8 @@ async function cmdTokens(sub, jti, mineOnly = false) {
         return 1;
     }
     const all = r.body?.tokens ?? r.body ?? [];
-    const myAgent = process.env.DECIDIO_AGENT_ID;
-    const tokens = mineOnly ? all.filter((t) => t.agentId === myAgent) : all;
+    const myAgent = process.env.DECIDIO_AGENT_ID || (journalAgents.length ? `${journalAgents.join(", ")} (from the token recovery journal)` : undefined);
+    const tokens = mineOnly ? all.filter((t) => myAgents.includes(t.agentId)) : all;
     if (!Array.isArray(tokens) || !tokens.length) {
         log(mineOnly ? `No agent tokens for "${myAgent}"${all.length ? ` (${all.length} elsewhere in this workspace — drop --mine to see them)` : ""}.` : "No agent tokens in this workspace.");
         return 0;
@@ -1879,15 +1919,17 @@ THE TOUR
                                        automated; ends with a keep-or-cleanup choice; --explain prints
                                        the long narration of each step; --phone web makes the QR open
                                        the phone web rendering even when the Decidio app is installed)
-  npx @decidio/sdk quickstart cleanup  revoke the tour's token + delete its local credentials
+  npx @decidio/sdk quickstart cleanup  revoke the tour's token + delete its local credentials (the inert
+                                       registration row and the permanent sealed record stay)
                                        (and end the stored sign-in)
   npx @decidio/sdk quickstart --auto-approve-demo   headless tour; cleans up after itself
                                        (add --keep-agent to KEEP the tour agent + token)
 
 SIGN IN (once)
   npx @decidio/sdk login [email]       sign in ONCE: the CLI emails you a link, you paste it; the sign-in
-                                       lasts 30 days, or until this terminal closes, logout, or cleanup
-  npx @decidio/sdk logout              end the stored sign-in
+                                       is kept on this computer 30 days, or until this terminal closes, logout, or cleanup
+  npx @decidio/sdk logout              forget the stored sign-in on this computer (the token itself stays valid
+                                       until it expires — there is no server-side revocation yet)
 
 YOUR AGENT AND ITS TOKENS
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
@@ -1912,7 +1954,8 @@ APPROVALS AND RECEIPTS
                                          ... approve <id> -- "-50% cut, per the board"
                                          ... approve <id> --reason "-50% cut, per the board"
   npx @decidio/sdk receipt <id> [--json]   download a sealed decision's Authority Receipt (.json)
-  npx @decidio/sdk verify [--issuer <did>] <receipt.json> [more...]   verify receipts OFFLINE
+  npx @decidio/sdk verify --issuer <did> <receipt.json> [more...]   verify receipts OFFLINE, pinned to your
+                                       workspace's issuer (--allow-unpinned: structural check only)
 
 DEVELOPMENT
   npx @decidio/sdk dev [--target URL] [--port N]   local relay for the resume webhook
@@ -1923,7 +1966,8 @@ NOTES
   DECIDIO_API_URL says otherwise; the target host is announced on stderr each run. "verify" is
   fully offline — it touches no network and reads no .env.
   Update check: network commands ask the public npm registry once a day whether a newer version exists. If so,
-  an interactive run asks "Upgrade now? [y/n]" first (y upgrades and re-runs your command; n exits); a headless
+  an interactive run asks "Upgrade now? [y/n]" first (y upgrades the way you installed - global, or in the
+  project for a local install; under npx it prints the @latest form - and re-runs your command; n exits); a headless
   run prints the notice and continues (DECIDIO_REQUIRE_LATEST=1 makes it exit). DECIDIO_NO_UPDATE_CHECK=1 skips
   the check. Nothing is sent to Decidio; verify never checks.
   Help: --help (or -h) after any command prints this page - one page for every command.
@@ -1976,13 +2020,23 @@ async function latestPublished() {
     }
 }
 async function updateGate(cmd, argv) {
-    if (!cmd || !GATED_CMDS.has(cmd) || SHELL_ENV.DECIDIO_NO_UPDATE_CHECK || VERSION === "unknown" || VERSION.includes("-"))
+    if (!cmd || !GATED_CMDS.has(cmd) || SHELL_ENV.DECIDIO_NO_UPDATE_CHECK || SHELL_ENV.DECIDIO_UPDATE_REEXEC || VERSION === "unknown" || VERSION.includes("-"))
         return null;
     const latest = await latestPublished();
     if (!latest || !semverNewer(latest, VERSION))
         return null;
-    const underNpx = /[\\/]_npx[\\/]/.test(process.argv[1] ?? "");
-    const upgradeCmd = underNpx ? `npx @decidio/sdk@latest ${argv.slice(2).join(" ")}` : "npm i -g @decidio/sdk@latest";
+    const entry = process.argv[1] ?? "";
+    const underNpx = /[\\/]_npx[\\/]/.test(entry);
+    const localRoot = (() => {
+        const m = /^(.*?)[\\/]node_modules[\\/]@decidio[\\/]sdk[\\/]/.exec(entry);
+        if (!m)
+            return null;
+        const norm = (s) => (process.platform === "win32" ? s.toLowerCase() : s);
+        const root = resolvePath(m[1]);
+        const cwd = norm(process.cwd());
+        return cwd === norm(root) || cwd.startsWith(norm(root) + pathSep) ? root : null;
+    })();
+    const upgradeCmd = underNpx ? `npx @decidio/sdk@latest ${argv.slice(2).join(" ")}` : localRoot ? "npm i @decidio/sdk@latest" : "npm i -g @decidio/sdk@latest";
     const notice = `${latest} is available (you have ${VERSION}).`;
     if (!(process.stdin.isTTY && process.stdout.isTTY)) {
         err(`⚠ ${notice} Upgrade: ${upgradeCmd}`);
@@ -2005,14 +2059,14 @@ async function updateGate(cmd, argv) {
         log(`  would run: ${upgradeCmd}`);
         return null;
     }
-    log(`  upgrading: ${upgradeCmd}`);
-    const up = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", ["i", "-g", "@decidio/sdk@latest"], { stdio: "inherit", shell: process.platform === "win32", env: SHELL_ENV });
+    log(`  upgrading: ${upgradeCmd}${localRoot ? ` (in ${localRoot})` : ""}`);
+    const up = spawnSync(process.platform === "win32" ? "npm.cmd" : "npm", localRoot ? ["i", "@decidio/sdk@latest"] : ["i", "-g", "@decidio/sdk@latest"], { stdio: "inherit", shell: process.platform === "win32", env: SHELL_ENV, ...(localRoot ? { cwd: localRoot } : {}) });
     if (up.status !== 0) {
         err(`✘ the upgrade did not complete (exit ${up.status ?? "?"}) — run it by hand: ${upgradeCmd}`);
         return 1;
     }
     log(`  ✔ upgraded — re-running: decidio ${argv.slice(2).join(" ")}`);
-    const rerun = spawnSync(process.execPath, [process.argv[1], ...argv.slice(2)], { stdio: "inherit", env: SHELL_ENV });
+    const rerun = spawnSync(process.execPath, [process.argv[1], ...argv.slice(2)], { stdio: "inherit", env: { ...SHELL_ENV, DECIDIO_UPDATE_REEXEC: "1" } });
     return rerun.status ?? 1;
 }
 async function main(argv) {
@@ -2042,7 +2096,7 @@ async function main(argv) {
         doctor: { flags: [] },
         approvals: { flags: ["--json", "--mine"], valued: ["--reason"] },
         receipt: { flags: ["--json"] },
-        verify: { flags: [], valued: ["--issuer"] },
+        verify: { flags: ["--allow-unpinned"], valued: ["--issuer"] },
         tokens: { flags: ["--mine"] },
         dev: { flags: [], valued: ["--target", "--port"] },
     };
@@ -2122,6 +2176,8 @@ async function main(argv) {
                     log(held.length
                         ? `Nothing to clean up here: no tour credentials. The token recovery journal names ${held.length} live token(s) held by a credential file here (${held.map((j) => j.jti).join(", ")}) — not tour tokens, left alone; doctor lists them.`
                         : "Nothing to clean up here: no .env.quickstart, .env doesn't belong to a quickstart agent, and the token recovery journal has no live token to act on.");
+                    if (endSession())
+                        log(`  ✔ signed out — the stored sign-in is removed from this computer (the token itself stays valid until it expires).`);
                     return 0;
                 }
                 const session = await acquireSession("Cleaning the quickstart up");

package/dist/resume.d.ts

@@ -37,6 +37,7 @@ export interface PendingAction {
 /** The durable execution state machine (v2).
  *
  *  parked → claimed_preinvoke → invoking → (executed_unreported | indeterminate) → reported
+ *  plus the terminal `discarded` (a human or policy said NO: written from parked/claimed_preinvoke, never invoked).
  *
  *  THE ONE RULE: nothing transitions BACK to parked once `invoking` has been written. Deletion
  *  is cleanup, never the single-use guarantee — that was the 0.1.x model, and a store whose
@@ -469,7 +470,7 @@ export type RecoveryState =
 "parked"
 /** Claimed by an attempt that never reached the invocation boundary, so the handler PROVABLY
  *  did not run — but the row is not parked either: `list()` excludes it and every ordinary
- *  signal answers `unknown`, so nothing will pick it up on its own. It is stalled until an
+ *  signal answers `lost_race`, so nothing will pick it up on its own. It is stalled until an
  *  operator releases it. Reporting this as "parked" (as 0.2.0's first draft did) told a UI an
  *  approved action was still queued to resume when in fact it had been silently dropped. */
  | "claimed_stalled"
@@ -581,8 +582,9 @@ export interface ResumeConfig {
     /** The callback URL Decidio should POST the verdict to (webhook transport). Sent
      *  on /agent/authorize so the decision carries it; omit when using the poll worker. */
     resumeUrl?: string;
-    /** Fired after every terminal resolution (executed / indeterminate / rejected / blocked /
-     *  no_handler), via either transport. Use it to log, close a listener, or exit a CLI.
+    /** Fired for every outcome except `unknown` (executed / indeterminate / rejected / blocked /
+     *  no_handler / already_resolved / lost_race), via either transport. Use it to log, close a
+     *  listener, or exit a CLI.
      *  `indeterminate` is new in 0.2.0 and DOES fire here: a handler that ran and then threw is a
      *  terminal outcome for automation — nothing will retry it — so a listener that only handled
      *  the old four would silently miss the one case that needs a human. */
@@ -600,8 +602,9 @@ export interface ResumeController extends ResumeConfig {
     /** Park a routed action WITH its integrity binding (prefer this over store.put — the
      *  binding is what lets resolve() refuse a tampered payload). */
     park(p: Omit<PendingAction, "createdAt" | "argsSig">): Promise<void>;
-    /** Drive a parked decision to completion once a verdict is known. Idempotent:
-     *  a second call after success finds nothing parked → "unknown" (no double-write). */
+    /** Drive a parked decision to completion once a verdict is known. Idempotent: a second call
+     *  after success answers `already_resolved` (no double-write); an id this SDK never parked
+     *  answers `unknown`; a call that loses the pre-invocation claim answers `lost_race`. */
     resolve(input: {
         decisionId: string;
         verdict: "approved" | "rejected" | "blocked";

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.11
+  version: 0.5.0   # tracks the SDK release - checked by packages/conformance/manifests.mjs
   description: >
     Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
     receive the signed resume webhook when a routed action is decided. Every outcome seals a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "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",
@@ -84,7 +84,7 @@
     "prepublishOnly": "npm run typecheck && npm run build && node ../publish-boundary/check.mjs --only @decidio/sdk"
   },
   "dependencies": {
-    "@decidio/verify": "0.4.3"
+    "@decidio/verify": "0.5.0"
   },
   "author": "OmniTwin Technologies Inc.",
   "bugs": {