@decidio/sdk 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -4,6 +4,164 @@ Release notes for the client SDK. The Python package `decidio` ships the same ch
 version (the two are conformance-locked twins). Each entry names what changed, what a reader must do
 on upgrade, and what proved it.
 
+## 0.4.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.
+
+- **A stale install must not keep running its defects** (founder ruling). Network commands (`quickstart`, `init`,
+  `login`, `doctor`, `approvals`, `receipt`, `tokens`) ask the public registry once a day whether a newer version
+  exists — npm for the TypeScript CLI, PyPI for Python, never our servers, cached in the user's profile, silent when
+  offline. If one does, an interactive run asks `<latest> is available (you have <yours>). Upgrade now? [y/n]`: `y`
+  runs the package manager's own upgrade (`npm i -g @decidio/sdk@latest` / `pip install -U decidio`, with its
+  integrity checks) and re-runs your command on the new version; `n` exits 1 naming the command to run when ready.
+  Under `npx` there is nothing installed to upgrade, so it prints the `@latest` form and exits. A headless run prints
+  the notice and continues; `DECIDIO_REQUIRE_LATEST=1` makes it exit instead (pinned CI is a choice, not a
+  surprise). `DECIDIO_NO_UPDATE_CHECK=1` skips the check. `verify`, `--help` and `--version` stay fully offline.
+  Seven vectors in both suites: not newer prints nothing; headless + newer notices and runs; the strict flag exits 1;
+  interactive `n` exits 1 running nothing; interactive `y` runs the upgrade (a labelled dry-run in the suite); an
+  unreachable registry is silent; `verify` never checks.
+- **Frames carry a tone.** ③ (the choice) in orange, ④ and the summary in green for an approval and red for a
+  rejection — the frame and its title only, 256-colour orange with a yellow fallback, nothing under `NO_COLOR`
+  or a pipe. Founder: "it's hard for the eye to pick out which box means what."
+- **The phone door lands.** iOS opens the installed app for `app.decidioai.com/q/*` (the association file now
+  claims it); the app consumes the code, signs in, and opens the decision. A phone without the app lands in its
+  browser on the phone build (`/phone/q/<code>`), the same single-decision screen the app shows. The desktop landing
+  is a hand-off page: the one decision on stage with its actions in view, the queue a click away (`?stage=1`).
+- **`quickstart --phone web`** is the founder's test fork: the QR points at the phone web rendering, a path the app
+  never claims, so it opens in the browser even with the app installed. The default QR opens the app when it is
+  there. (`--demo` will pick the sandbox the same way, once it exists.)
+- Founder decisions recorded (backlog): the sandbox for uninvited developers is TOUR-ONLY in v1 (no own agents —
+  surface risk and a second policy to maintain), its boxes are torn down at cleanup or by a one-hour sweeper, and
+  its phone surface is the web page, never the native app.
+
+## 0.4.2 — the zero-miss release: three gates, and every finding of the two 0.4.1 reviews
+
+Built to the plan in `docs/Decidio_SDK_Zero_Miss_Plan.md` after an outside engineer's first-run review of 0.4.1 (B+)
+and the prodsec retest of 0.4.1 (A-, safety A). Every item of both reports has a disposition below; the gates that
+would have caught them now run on every pull request, on Linux AND Windows.
+
+**The founder's UAT, round 2 (2026-09-04), folded in before the tag.** Steps 0–6 green on the previous build; the
+web-app door landed on home (fixed twice the same night: the desktop's deep link is `/queue?focus=<id>`, and a browser
+with no session bounced to `/login` before the link was consumed), and approving from the queue proved the terminal
+follows an outside decision. Then six findings on the tour itself, all taken but one (which became a founder call):
+- **One line per event.** The tour's paragraphs are gone from the default output: every step is a frame with two to
+  four terse rows, the outcome is one line, the reminder is two, and "Where next" is one. `--explain` prints the
+  narration that used to be the default. Target met: the approval tour is about 40 lines without the QR.
+- **Every step framed** (①②③④ and the summary), with an escape-aware word wrap so a styled row never overflows a
+  narrow window; continuation lines hang under the label column.
+- **A short hand-off link.** `POST /demo/session-link` now returns `https://app.decidioai.com/q/<13-char code>`
+  instead of a 110-character URL: it fits the frame, stays clickable AND copyable, and the credential row remembers
+  which decision the code was minted for (`handoff_decision_id`, cleared in the same single-use burn), so the web
+  app's new `/q/<code>` route signs in and lands on that decision. A hand-off never flips `emailVerified`.
+- **A small QR, still printed by default** (the founder's call: "it looks impressive in a demo"). The QR carries the
+  short link upper-cased, so the encoder uses its alphanumeric mode, at the lowest error-correction level with a
+  one-module quiet zone: 25 modules instead of 41, about 14 rows instead of 23.
+- **The lab is invite-only, and the CLI says so.** An uninvited address running `login` used to be told "we emailed
+  you a link" and wait for nothing (the server's anti-enumeration answer). The CLI now says a link arrives only for
+  an invited address and where to request access.
+- **"The wrapper IS the SDK."** The first sentence of the help (and the READMEs) settles the SDK-versus-wrapper
+  question: `guard.protect(fn, describe)` ships in this package; the CLI is the tour, the sign-in and the token admin.
+- Founder calls recorded, not built: a sandbox tenant with device-bound identities and a single-decision preview page
+  for developers who are not invited (the SDK's distribution unlock); scan → native app → the decision (iOS claims
+  `/d/*` for the installed app; the QR opens Safari today); `record kind: agent-receipt` wording.
+
+**Round 2, second look (2026-09-04, same night).** The founder re-ran on the deployed build: web-app approval and the
+deep link now work; the QR was MISSING; the text above and below the frames was still dense. Fixes: (1) `qrcode@1.5`'s
+half-block renderer throws "Invalid array length" on an ODD margin, so the 1-module quiet zone silently produced no QR
+(the server logged it, the CLI showed nothing) - margin 2 with level L renders 25 modules in 13 rows, and the CLI now
+says when no QR came back instead of dropping the row; (2) the sign-in block is six lines instead of eleven (one intro,
+prompts that carry their own hints, one signed-in line); (3) the tour no longer prints the stderr "decidio →" host line
+when its own Target line already said it; (4) ④ is three short rows (VALID + file / record kind + evidence / issuer)
+instead of one wrapping line; (5) the reminder is two lines, the take-away has a breath around it.
+
+**The founder's UAT pass (2026-09-03), folded in before the tag.** The script's steps 1–5 went green in a real
+PowerShell; step 6 stopped on the sign-in: every command that needed the workspace asked for a fresh emailed link,
+and "nobody would log in this many times". Ruled: sign in ONCE, no better and no worse than the web app; and a
+human step you can believe from outside the terminal.
+- **Sign in once.** `login [email]`: the CLI requests the emailed link itself, you paste it; the 30-day session is
+  kept in your user profile (`%LOCALAPPDATA%\decidio` / `~/.config/decidio`, owner-only, written through the same
+  atomic secret writer as `.env`), bound to the terminal window that created it (a second window gets its own) and to
+  the token's expiry. `logout` ends it; so does `quickstart cleanup` (the tour's sign-in ends with the tour, the way
+  the web app drops its session on sign-out). An exported `DECIDIO_SESSION_TOKEN` still outranks it for headless
+  shells. No server-side session revocation exists yet (the web app has none either); the stored token is discarded.
+- **Three doors at the human step.** The ③ frame offers: answer **here** (y/n), open the decision in the **web app**
+  (a link that lands on it signed in), or scan a **QR** with **your phone** (the same link). The link comes from a
+  new authenticated endpoint, `POST /demo/session-link {decisionId}`: it mints the SAME single-use sign-in token the
+  emailed link carries, for the caller's own credential, five minutes instead of fifteen because it is shown on a
+  screen and lands in terminal scrollback, and it replaces any pending emailed link (one slot per credential). It
+  grants a sign-in and only a sign-in: the token is prefixed `h.` and the password-reset door refuses it, so a
+  session can move itself to a browser but never mint itself a durable password (invariant-guard block, fixed, with a
+  negative-smoke lock). The terminal races the prompt against the gated call: a decision
+  made in the app or on the phone closes the prompt, the CLI posts no approve/reject of its own, says "approved (or
+  rejected) in the web app (or on your phone) — this terminal saw it and followed", and the function runs
+  once, after the approval, exactly as before. If the hand-off endpoint fails, the terminal door still works alone.
+- **Layout.** Each step is a headed section; the doors and the closing summary are frames sized to their content and
+  the terminal; the summary is a table (gated / decided / executed / receipt); the help page is in sections. Colour,
+  bold and clickable (OSC-8) links only on a TTY and never under `NO_COLOR`; every phrase the gates assert is unchanged.
+- **Two platform defects found by the doors vector, both fixed:** on Windows a console read abandoned when the app
+  decided first kept libuv's reader thread blocked and Node's teardown waited forever (the process printed its last
+  line and never exited) — the CLI now drains stdout/stderr and exits explicitly on that path only; and Python's
+  `isatty()` is true for `NUL`, so the console-key reader spun on a headless run — a real console is now detected
+  through `GetConsoleMode` (and that same check now decides whether the CLI may prompt at all, so `NUL` is headless on every OS), pipes and `NUL` read on a thread, POSIX uses `select`.
+- Vectors, both languages: `login` under a real terminal (email → link → stored session); the next command in the
+  same terminal asks nothing; another terminal is refused; `logout` removes the file; a headless tour on the stored
+  session; cleanup signs out; and the browser-decided tour (the fake gate approves after two polls; the CLI must post
+  no approval, run the function once, exit 0).
+
+**Gates (structural):**
+- **The stranger run.** Both CLI suites drive the interactive tour under a REAL terminal on every platform through one
+  shared driver (`packages/conformance/tty_driver.py`: POSIX pty, Windows ConPTY). `y`, `n` and three blank answers
+  are exercised end to end; a missing terminal driver is red on CI, never a skip. A `windows-latest` gates job runs
+  both CLI suites under ConPTY.
+- **Claims as vectors.** `packages/conformance/vectors/claims.json`: retired phrases are tombstones that fail the build
+  if they reappear in shipped text; the help must carry what is true (`y approves`, `n rejects`, exit 3 at the human
+  moment, `--help` anywhere, `receipt <id> [--json]`); the no-answer stop's exit code is asserted from what the help
+  promises. The tombstone gate found a Python twin of a 0.4.1 text fix that had been missed.
+- **Twin parity.** `packages/conformance/parity.mjs`: the vector labels of the TS and Python suites must match; a
+  one-sided vector is red unless `parity-allowlist.json` names it with a reason. The pre-0.4.2 asymmetry is
+  recorded as a baseline to burn down before 1.0.
+- **No swallowed ledger read.** `packages/conformance/sdk-lint.mjs` refuses `.catch(() => undefined)`,
+  `except Exception: x = None` and empty catches around ledger and journal reads; it was red on seven such sites in
+  0.4.1 and is green now, with two justified allowances that carry their reason.
+
+**Fixed, both languages unless noted:**
+- The help said "YOUR Enter is the approval" (false since 0.4.1); it now says y approves, n rejects, Enter is not an
+  answer. `--help`/`-h` after any command prints the one help page (exit 0); the bare word `help` past the usage
+  positions stays a positional. `receipt <id> [--json]` is documented.
+- The rejection half of the tour downloads and verifies the DENIAL's receipt, pinned, and names its record kind; all
+  three verifier doors print `kind:` (read from the receipt's own canonical record). The approval half names its kind
+  too. The tour's receipt goes through the same no-overwrite writer as the `receipt` command.
+- Receipt filenames escape rather than strip: `a.b` and `ab` can no longer share a file (`~` + hex code point).
+- The unset-session reminder prints on every end of the tour (approved, rejected, stopped) with both the bash and the
+  PowerShell command; the README carries both.
+- An answer typed after the tour's blocking call expired (5 minutes) is not posted; the tour says the request must be
+  decided in the queue.
+- `resolve()` on a decision whose entry was consumed between reading and claiming it now reads the ledger through one
+  shared mapping: `already_resolved` when it ran, never "durable state undefined" or a false live-attempt claim; the
+  resolved hook fires for every non-`unknown` outcome including the ledger-fallback ones.
+- **A corrupt terminal ledger head is loud** (prodsec V041-01): `resolve()` propagates the state-corrupt error instead
+  of returning `unknown`; the poll worker says it once per decision and keeps serving the other actions; the webhook
+  doors answer 500 naming the error.
+- A landed `init` token whose `persisted` journal note failed to write is held, not an orphan (the credential file is
+  the proof); the failed note is reported, never silent. `quickstart cleanup` names a held token instead of saying
+  the journal owes nothing (prodsec V041-02).
+- The tour prints the call it actually makes (TS: the blocking primitive, with the note that real agents use
+  `guard.protect`; Python already ran `guard.protect(..., mode="blocking")` and now prints that too).
+- Node relay: `--target` is never echoed raw, even on the shape-check refusal; the relay binds `127.0.0.1`.
+
+**Guard round (one, by ruling): no block, six warnings, all taken.** The verifiers no longer print a record kind on an
+INVALID receipt (an attacker-supplied field on a rejected document); Python's `receipt --json` keeps stdout JSON-only
+and both suites now assert that on a stdout-only capture; an unreadable store directory is corruption, not "no
+revisions", and an unlistable store makes the worker say so once instead of idling silently; the lint reaches
+directory listings and multi-form excepts and refuses a `lint-allow` without a reason; the three-door gate carries a
+correctly signed DENIAL fixture and all three doors print `kind: denial` (69/69); the claims scan walks the adapters too.
+
+**Not reproduced:** the reviewer saw the no-answer stop exit 1 in PowerShell; under ConPTY on Windows and under a pty
+on Linux both CLIs exit 3, and the gates now assert that code from the help's own table on both platforms.
+
+**Unchanged by ruling:** adapters stay Beta (no real-engine suites yet); provenance and repository metadata stay
+post-1.0.
+
 ## 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

package/README.md

@@ -3,6 +3,8 @@
 One line to put a human-or-policy approval gate in front of any AI-agent action — and get a signed, verifiable Authority Receipt for every decision, with execution evidence accruing on the record.
 
 `@decidio/sdk` is the client for Decidio — the system of record for enterprise authority, from OmniTwin Technologies.
+The wrapper IS the SDK: `guard.protect(fn, describe)` ships in this package, and the `npx @decidio/sdk` command line
+is the two-minute tour, the sign-in and the token admin around it. Install, wrap one function, run — the tour is optional.
 
 ## The two-minute tour
 
@@ -16,7 +18,11 @@ you approve right there (or from your Decidio app), executes on approval, then d
 sealed Authority Receipt and verifies it offline in front of you, pinned to your workspace's
 issuer. It mints a **7-day** tour token (`init` mints 90-day tokens — different jobs, different
 lifetimes) and ends by offering to clean itself up (`quickstart cleanup` works later too).
-Sign in when prompted. No config: with no `DECIDIO_API_URL` set it targets the hosted synthetic
+Sign in once — `npx @decidio/sdk login`, or when the tour asks: the CLI emails you a link, you paste it, and
+the sign-in is kept in your profile (owner-only) for 30 days, or until this terminal closes, `logout`, or
+`quickstart cleanup`. At the human step the tour offers three doors: answer here, open the decision in
+the web app (a one-time link, signed in for you), or scan the QR with your phone — whichever answers
+first wins, and the terminal follows. No config: with no `DECIDIO_API_URL` set it targets the hosted synthetic
 sandbox. Headless, the tour **stops at the routed decision** — approving is a human act, so it
 prints the approve command and exits rather than approve its own request (CI can pass
 `--auto-approve-demo`, which labels that authority as automated).
@@ -78,12 +84,14 @@ What `.env` contains after a successful init: `DECIDIO_API_URL`, `DECIDIO_AGENT_
 `DECIDIO_WORKSPACE_ID`, and `DECIDIO_WEBHOOK_SECRET` (operator deployments only). Pick any
 agent name — if it's already taken in your workspace, `init` stops cleanly and suggests a
 fresh one (or pass `--unique` to auto-append a random suffix — collision-proof for shared
-workspaces and CI). Headless terminal (no prompts possible)? Export `DECIDIO_SESSION_TOKEN` first:
+workspaces and CI). Interactive terminals sign in once (`npx @decidio/sdk login` — stored owner-only in your
+profile, bound to this terminal window, 30 days). 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). 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
+variables (`unset DECIDIO_SESSION_TOKEN` in bash/zsh, `Remove-Item Env:DECIDIO_SESSION_TOKEN` in
+PowerShell). 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`:
@@ -639,7 +647,10 @@ that fits every other confirm error.
 - `receipt <id>` — download a sealed decision's Authority Receipt to a `.json` file
 - `verify [--issuer <did>] <file>...` — verify receipts offline (the canonical verifier; the standalone `@decidio/verify` package is the same implementation, for auditors who want zero Decidio dependency — the sdk 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)
+- `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.
+- `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)
 
 The CLI's stream contract: **stdout carries results only** (safe to pipe — `--json` output is
@@ -647,8 +658,9 @@ pure JSON); errors, usage shown on *error* paths, and the per-run target-host an
 to **stderr**. Asked-for help (an explicit `--help`, or invoking the bare CLI) is itself a
 result and prints on stdout. Exit codes: 0 success · 1 failure or honest no-op · 2 usage error · 3 `quickstart` stopped at the human moment (headless: the decision routed, but nothing executed and no receipt was written, so the run is deliberately not reported as a completed tour).
 
-Commands that administer your workspace (`init`, `approvals`, `receipt`) use a **session**
-sign-in held in memory for that run. What lands on disk in `.env`: the agent's floor-limited
+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
 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.

package/dist/cli.d.ts

@@ -1,3 +1,7 @@
 #!/usr/bin/env node
 export type ApprovalAnswer = "approve" | "reject" | "again";
 export declare function approvalAnswer(answer: unknown): ApprovalAnswer;
+/** `decidio-receipt-<id>.json`, with every character outside [A-Za-z0-9_-] escaped as `~` + hex code point, so two
+ *  distinct decision ids can never share a file (first-run review of 0.4.1: dots were STRIPPED, `a.b` and `ab`
+ *  collided). `~` is outside the allowed set, so the escape is unambiguous. Exported for the smokes. */
+export declare function receiptFileName(id: string): string;