@decidio/sdk 0.6.4 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,173 @@ the gate, signing, receipts and the verifier - is conformance-locked between the
 first-run surfaces (the fork, `--demo`, the code sign-in) are TypeScript-first and named as such in the parity
 allowlist. Each entry names what changed, what a reader must do on upgrade, and what proved it.
 
+## 0.7.0 — approvals bind to the exact request they approved; receipts pin to a real trust anchor
+
+- **The receipt trust anchor is built in — nobody pastes an issuer DID, and nothing pins to a receipt's own
+  claimed issuer** (founder-approved 3A, 2026-09-24). `receipt` and the tour used to pin their offline check to the
+  `issuer` field of the server's verify response — which echoes the credential's OWN claim — and never read `valid`:
+  a receipt signed by any key that names itself verified "pinned" against itself, and a record the server's own check
+  had failed was shown as VALID. Now:
+  - `receipt` and the tour pin to `expectedIssuer` — the server's configured key, which the API now returns beside
+    `issuer` — else to the DID remembered for that host; they fail (exit 1) when the server says `valid: false`.
+  - Sign-in (`login`, the tour's or `init`'s sign-in) and `init` fetch the host's public `/api/did` and remember it in
+    the profile beside the stored sign-in (`issuers.json`, owner-only; kept past logout). A later `/api/did` answering
+    a DIFFERENT DID is warned about loudly and NOT adopted.
+  - `verify` with no `--issuer` pins to that remembered DID for the configured host, else to the built-in
+    `KNOWN_ISSUERS` (exported by `@decidio/verify`: the hosted service's issuer only — never the verification kit's
+    published sample key), else refuses (exit 2) with the remedy. An explicit `--issuer` always wins, and every run
+    prints its trust anchor first. An unreadable `issuers.json` refuses rather than falling back.
+  - `@decidio/verify` (and `npx @decidio/verify`) with no `--issuer` pins to the built-in list; a receipt from any other
+    issuer is refused (exit 2) with the remedy. `runVerify` takes an optional anchor description and prints
+    `trust anchor: …` as its first line.
+  On upgrade: nothing to do; scripts that pass `--issuer` behave as before (plus the anchor line on stdout). Deploy the
+  API first: against a server without `expectedIssuer`, `receipt` and the tour fall back to the remembered DID and
+  otherwise fail closed. Proved by: `cli-smoke.ts` (a forged receipt naming itself fails the tour and is never offered
+  as the anchor; `valid:false` fails `receipt` and the tour; init/sign-in remember `/api/did`; flagless verify pins to
+  it; `--issuer` wins; a changed DID is not adopted; nothing remembered → exit 2 naming the built-in anchor; an
+  unreadable store refuses), `decidio-verify/smoke.ts` (the built-in list's content and refusals), the three-door
+  conformance run (every door names the same built-in anchor), and a claims tombstone for the retired
+  "refuses to run without --issuer" sentence.
+
+- **3A follow-up (independent invariant-guard review, 2026-09-24).**
+  - **The remembered DID wins over a server that names another.** `receipt` and the tour compared nothing: a server whose
+    `expectedIssuer` differed from the DID remembered for its host was followed, so "not adopted" held at sign-in and
+    failed one command later. Now the same loud HAS CHANGED warning prints and the pin stays the remembered DID (the
+    receipt then fails its offline check: `receipt` exits 1, the tour fails). An unreadable `issuers.json` now yields no
+    anchor at all rather than the server's.
+  - **`receipt` checks the file offline against the anchor it prints.** It honoured the server's `valid` but never
+    checked the credential against the anchor it recommended - a server naming the built-in DID over another key's
+    credential got "No --issuer needed" and exit 0 while that flagless verify then refused. Any failure now behaves like
+    `valid:false`: exit 1, the file kept for inspection only.
+  - **One host rule.** `verify` resolves its remembered DID for `DECIDIO_API_URL` from the shell (it reads no `.env`),
+    and `receipt` prints the flagless command only when that verify lands on the same anchor - a host set only in `.env`
+    gets the explicit `--issuer` form and says why.
+  - **`issuers.json` is keyed by URL origin** (scheme + lowercased host + non-default port, no path, no trailing slash):
+    `HTTP://Host:80/` and `http://host` are one entry, so a variant spelling cannot pass as a first sighting and skip
+    the change warning.
+  - **Output contract.** `receipt --json`'s `issuer` is the trust anchor the file was checked against (null against an
+    older server with nothing remembered), and `valid` is false when the server's check or the offline check failed.
+    `verify`'s stdout starts with a `trust anchor: <did>  (<source>)` line before the verdicts.
+  Proved by: `cli-smoke.ts` +9 (a server naming a different key than the remembered DID: warned, not followed, receipt
+  exit 1, tour fails; a server naming the built-in DID over another key's credential: exit 1, never "No --issuer
+  needed"; the flipped forged vector now exits 1; a variant spelling of the host is the same entry; eight origin-key
+  cases shared with Python; `.env` never chooses verify's anchor; the flagless command follows verify's host; an issuer
+  store with `"v": true` is refused; the update gate's switches come from the shell) - 8 of them red against the
+  previous commit's code; the other three are the twins of Python-only bugs the TS CLI never had. The release workflow
+  now fails if `KNOWN_ISSUERS` (TS or Python) differs from the live `https://decidio-api.onrender.com/api/did`.
+- **3A follow-up, round 2 (guard re-review, 2026-09-24) — same hostile-`.env` threat model.**
+  - **The session and the trust store live where the SHELL says.** `sessionDir()` (and the terminal-id read) took
+    `XDG_CONFIG_HOME`/`LOCALAPPDATA`/`HOME` from the environment *after* `.env` was promoted, so a project `.env` with
+    `XDG_CONFIG_HOME=.cfg` put the session token and `issuers.json` inside the repo — and let the repo plant a DID that
+    then showed as "remembered on this computer". Both now read the shell snapshot.
+  - **A project `.env` promotes only `DECIDIO_*`.** It configures Decidio; it does not reconfigure the OS, toolchain or
+    network stack. A cloned repo's `.env` can no longer inject `HTTP(S)_PROXY`/`NO_PROXY` (which would route this CLI's
+    authenticated calls, bearer token and all, through the repo's server), TLS-trust or CA-bundle variables,
+    `NODE_OPTIONS`/`GIT_*` code loaders, or the session-dir variables into the environment a network command runs with.
+    A switch genuinely wanted is set in the shell, which still wins.
+  - **The cached update-check value is validated like the network answer** (a full `x.y.z`), and `semverNewer` requires
+    exactly three all-digit components: a planted `update-check.json` with trailing bytes can no longer be printed as an
+    available-version notice, escape codes and all, or used to force an upgrade.
+  - **`issuerStoreKey` fails closed** on host spellings it cannot canonicalise identically to the Python twin
+    (percent-encoding, IDN, numeric-shorthand IPs, backslashes): it no longer uses the browser URL's canonicalisation,
+    which mapped `https://%64ecidio-api.onrender.com` onto the real host — a planted store entry under an exotic spelling
+    is never trusted as the real Decidio.
+  - **An `issuers.json` whose version literal is `1.0`** (a float, not the integer `1`) is refused, matching Python: JS
+    cannot tell `1.0` from `1` after `JSON.parse`, so the raw token is checked.
+  - **`receipt --json` reports `valid: null` when no offline check ran** (no anchor — e.g. an unreadable store): the
+    server's own verdict alone is not enough to call a receipt verified, because the point is the offline pin.
+  Proved by: `cli-smoke.ts` +5 (session/trust-store location; `.env` promotes only `DECIDIO_*`; the poisoned cache; the
+  `1.0` version literal; `receipt --json` valid:null) plus 7 new origin-key cases, all red against the previous commit's
+  code. The release workflow's live-DID gate now uses `curl --retry-all-errors` and emits an explicit `::error::` when
+  the host is unreachable or the body is malformed.
+
+### An approval is bound to the exact request it approved (#4B, BREAKING)
+
+**Breaking.** Read "On upgrade" before bumping. The version is not bumped here; this ships as the next minor.
+
+- **Every door confirms with Decidio that THIS request was approved before it runs it** — inline (the blocking
+  wait), the durable webhook and worker, LangGraph, Temporal, Inngest and OpenAI Agents, through one check
+  (`checkApproval`, exported; the adapters share `adapters/_gate.ts`). `GET /agent/status` must answer
+  `approved`/`auto_approved` AND return the request commitment this SDK sent with `/agent/authorize`, recomputed
+  over the request about to run. A resume webhook, a Temporal signal, an Inngest event or a LangGraph resume value
+  is now only a WAKE-UP; before, each of them was the authority, so anything able to send one approved the action.
+  A mismatch throws `DecidioRequestChangedError` ("the request changed after approval", naming the decision); a
+  gate that returns no commitment for a request this SDK bound throws `DecidioApprovalUnverifiedError`
+  (`code: "commitment_missing"`; `"unverifiable"` when there is no key material to recompute it). Both extend
+  `DecidioBlockedError`, so existing `catch` blocks still see a refusal. The durable resolve reports
+  `not_approved` (Decidio still says pending - the entry stays parked for the next wake-up) or
+  `request_unverified` (refused, kept parked, named once). Because it now asks Decidio first, **`resolve()` THROWS
+  when Decidio is unreachable** (nothing ran; the entry stays parked) - callers must catch it.
+- **The commitment is keyed, never a digest** (invariant I5): lowercase-hex HMAC-SHA256 over the canonical
+  request (`committedRequestJson`) under a subkey of a secret only the agent holds - the Ed25519 signing key when
+  `agentKey`+`agentDid` are configured, else the API token (`bindingMaterial`, `requestCommitment`). An unkeyed
+  sha256 would sit in Decidio's database as a dictionary-attackable fingerprint of the request. Byte-identical to
+  the Python twin: shared vectors in `packages/conformance/vectors/canonical.json` (`commitments`), consumed by
+  both runners. A keyless agent sends none and is checked on Decidio's state alone. **Prefer the Ed25519 key for
+  binding**: under the API-token fallback the key is a bearer Decidio receives on every call, so the commitment is
+  opaque to everyone except the Decidio server itself. **Rotation strands pending approvals**: re-minting the
+  token, changing `DECIDIO_AGENT_KEY`, or a guard and resume controller with different key material turns every
+  routed approval still pending into `request_changed` - drain before rotating, or ask again.
+- **LangGraph: the $100 -> $1,000,000 resume bug is closed.** LangGraph re-runs an interrupted node on resume, so
+  the node authorized AGAIN - minting a phantom second decision nobody saw - and then ran whatever it computed the
+  second time under the first approval: approve $100, edit the graph state, resume, and $1,000,000 executed (and
+  was confirmed under the phantom). Now the re-run authorizes with an idempotency key derived from its own thread +
+  checkpoint namespace + call index + commitment (`idempotencyKey`), Decidio answers with the SAME decision, the
+  resume value must name that decision, and the check runs. An edited state is a new task and a new request: it
+  becomes a NEW pending decision and the graph pauses on it; the old approval is never applied across requests.
+  `decidioResumeCommand(body)` now carries - and requires - the webhook's `decisionId`. The gate needs key material
+  and a checkpointed run with a `thread_id` and the node execution's scratchpad; without them it refuses (before
+  sending anything, or before pausing on a decision it could never find again, naming it - it never falls back to
+  a constant call index).
+- **Temporal**: `DecidioGateOpts.verify` runs the check (as your activity) after the signal and before `run()`;
+  it is REQUIRED whenever `authorize` is supplied (refused before anything is routed). The activity body is
+  exported: `verifyApprovalActivity(config, decisionId, ctx)`. A signal only wakes the workflow; still pending
+  -> it waits for the next signal.
+- **Inngest**: after each wait the check runs as a memoized step (`decidio-verify-approval`); a premature or
+  forged event waits again (later waits are `decidio-await-approval-1`, `-2`, ...: deterministic across replays).
+- **OpenAI Agents: `applyResume(state, item, verdict)` is REMOVED**, not deprecated. Its only input was a verdict
+  string, so no deprecation shim could check anything - keeping it would keep the hole. Use
+  `await applyVerifiedResume(config, state, item, decisionId, describe)`: it approves the interruption only when
+  Decidio records that decision as approved for THIS tool call, rejects on a rejection, and otherwise throws with
+  the RunState unmodified. The approval is bound to the call itself - its name, call id and exact argument string
+  from `rawItem`, beside `describe(item)` (`toolCallRequest`) - so a parked item edited after approval (a target
+  `describe()` never covered) and a second identical call whose own decision is still pending are both refused
+  (`request_changed`); binding `describe(item)` alone let both through (#4B review W2). `pending[]` now carries
+  each `callId`; an interruption with no call id is refused before anything is sent.
+- **The resume webhook no longer falls back to the API token** (`webhookHandler`, `fetchHandler`): with no
+  `webhookSecret` (and no `allowUnsigned`) it answers 401 naming the fix - a dedicated secret, **never the Decidio
+  server's `API_AUTH_TOKEN`** (its admin bearer). The token is a credential the agent SENDS; accepting webhooks
+  signed with it let anyone holding it drive resumes. The LOCAL integrity signature on parked payloads keeps its
+  token fallback, so entries parked before the upgrade still verify.
+- **Known limit (predates this release): one gated action per LangGraph node.** The node re-runs on resume, so an
+  earlier gate in it runs again; one whose request auto-approved (action already run) replays as `proceed` to a
+  verified agent and its action runs a second time when a later gate in the node resumes. Put each gated action
+  in its own node, or make the actions idempotent.
+- **Known limit (predates this release): LangGraph and OpenAI Agents have no single-execution claim.** Two
+  concurrent resumes of the same thread or RunState can both pass the check and both run the action; resume each
+  from one place. The core durable path claims each execution in its store.
+- The demo gate (`demo-gate.ts`, the `--demo` stand-in) stores and returns commitments like the real gate.
+
+**On upgrade:** (1) deploy the Decidio gate from this release FIRST - an older gate returns no commitment and a
+keyed SDK refuses its routed approvals (`commitment_missing`: fail closed, never a silent pass). (2) Webhook
+deployments: set `DECIDIO_WEBHOOK_SECRET` on both sides, or switch to `worker()`. (3) LangGraph: run with a
+checkpointer + `thread_id`, and build the resume with `decidioResumeCommand(webhookBody)`. (4) Temporal: add the
+`verify` activity. (5) OpenAI Agents: replace `applyResume` with `applyVerifiedResume`, park each pending
+`{ callId, decisionId }` and find items again by `rawItem.callId`. (6) A test double of the gate must return
+`requestCommitment` from `/agent/status`. (7) Catch errors from `resolve()`. (8) Drain pending approvals before
+rotating the agent token or key. Entries parked by 0.6.x carry no commitment and are checked on Decidio's state
+alone.
+
+Proved by: `smoke.ts` (the request-binding block: approved-for-another-request, gate drops the commitment,
+keyless, rejected/pending wake-ups, the durable webhook and worker), `adapters-smoke.ts` (the REAL
+`@langchain/langgraph`: unedited resume = one decision; edit after approval = a new pending decision and
+nothing executed; rejected; keyless refused; no scratchpad refused; Inngest forged event; Temporal verify
+required; OpenAI verified resume incl. an edited target and a second identical call), `inngest-smoke.ts` (a forged
+event executes nothing), both conformance runners (commitment vectors incl. the OpenAI tool-call binding built by
+each SDK from its own native item, every door with a gate that returns the commitment), and `conformance/run.mjs` -
+which caught the two twins committing different bytes for the same call (Python sent an empty `kwargs` member)
+before this shipped.
+
 ## 0.6.4 — the request closes when the agent gives up
 
 - **The README links the agent skill file** published on the site (https://decidioai.com/skills/decidio-guard.md, one page for both languages) and the site's llms.txt. The file is served by the site, not shipped in the package; an in-package copy is a one-line publish-boundary decision for this release if wanted.

package/README.md

@@ -154,21 +154,30 @@ becomes the record's execution evidence.
 
 ```bash
 npx @decidio/sdk receipt <decisionId>
-npx @decidio/sdk verify --issuer <did:key:...> decidio-receipt-<decisionId>.json
+npx @decidio/sdk verify 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). 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
+No DID to paste: `verify` pins to a **trust anchor** and prints it first. In order: an explicit
+`--issuer <did:key>` if you give one; else the issuer DID this computer remembered for your Decidio
+when you signed in (`login`, or the sign-in `init`/the tour asks for) — fetched from the host's
+public `<api>/api/did` and kept in your profile beside the stored sign-in; else the built-in
+issuer of Decidio's hosted service (`did:key:z6MkmLGeR5NjJ87a1yU5ygqju49CtnUrt38esqM54Y9tXnKq`,
+published at https://decidio-api.onrender.com/api/did). A receipt's own `issuer` field is never the
+anchor — it is only what the file claims, and any key can sign a file that names itself. If a later
+sign-in sees the host publish a DIFFERENT DID - or a server's verify response names one - the CLI
+says so loudly and keeps the remembered one: a new key is confirmed with the host's operator, not
+adopted silently. The `receipt` command pins to the DID remembered for the host, else the DID the
+server names as its own (`expectedIssuer`); checks the file offline against it; fails (exit 1) when
+that check or the server's own check says the record does not verify; and prints the flagless verify
+command only when `verify` - which takes its host from your shell's `DECIDIO_API_URL`, never `.env` -
+would land on the same DID. An UNPINNED check proves internal consistency only, so it stays a named choice
+(`--allow-unpinned`), and its verdict says so. 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
-evidence is yours, not ours. To also prove *who* issued it, pin your workspace's issuer:
-`npx @decidio/sdk verify --issuer <did:key:...> receipt.json` (the DID is shown in your app's
-record verify panel — or simply read it off the `receipt` command's output, which prints your
-workspace's issuer DID from the authenticated response so you never have to hunt for it).
+evidence is yours, not ours. On another machine, pin the same DID explicitly:
+`npx @decidio/verify --issuer <did:key:...> receipt.json` (receipts from the hosted service need no
+flag there either — the anchor is built in).
 
 **What VALID means — and what it does not.** A pinned `VALID` proves the receipt's **claims** were
 sealed by your workspace's issuer and that none of them has changed since. Not its *bytes*: the
@@ -320,8 +329,10 @@ executed, so without a second submission there is nothing left to approve.
 those two, a cold worker has an empty registry and reports `no_handler` (the parked action is
 kept, not lost, and the message names the exact fix).
 
-**The signed webhook (operator deployments).** Decidio POSTs a signed verdict to your agent's
-`resumeUrl`; the handler verifies the HMAC signature fail-closed, then re-runs your function:
+**The signed webhook (operator deployments).** Decidio POSTs a signed wake-up to your agent's
+`resumeUrl`; the handler verifies the HMAC signature fail-closed, asks Decidio for the decision, and
+re-runs your function only if Decidio says THIS request was approved (the verdict inside the webhook
+is never the authority — see "Every door confirms the approval" below):
 
 ```js
 // Express:   app.post("/decidio/resume", guard.resumeHandler())
@@ -332,7 +343,12 @@ Honest requirement: webhook signing uses a **shared secret configured on both si
 `DECIDIO_WEBHOOK_SECRET` must equal the Decidio server's, and self-hosted production deployments
 also allow-list resume hosts (default-deny). That's operator territory: if you run your own
 Decidio (or we run a pilot with you), the webhook is set up then. Against the hosted sandbox,
-use the worker — a webhook secret your server never learned would (correctly) fail closed.
+use the worker — a webhook secret your server never learned would (correctly) fail closed. Since
+0.7.0 there is **no API-token fallback**: without `webhookSecret` (or `allowUnsigned`, for a trusted
+network only) the handler answers 401 and names the fix. The worker needs no inbound secret. The
+secret is a dedicated one — **never the Decidio server's `API_AUTH_TOKEN`** (its admin bearer, which
+must not be copied onto an agent host); since this release the server sends no webhook at all without
+`DECIDIO_WEBHOOK_SECRET`.
 
 **Earning the strongest evidence tier.** Decidio records `application_confirmed` — its
 strongest wrapper tier — only when your function's captured response shows a committed record:
@@ -475,6 +491,64 @@ imports none of them — install the engine you use alongside the SDK (`npm i in
 for engines you don't. Each adapter's shipped `.d.ts` header documents its wiring; `npx
 @decidio/sdk quickstart` is the fastest runnable end-to-end.
 
+### Every door confirms the approval is for THIS request (0.7.0)
+
+Before 0.7.0 a resume ran on the word of whatever woke it — a webhook, a Temporal signal, an Inngest
+event, a LangGraph resume value saying "approved". Now every door (inline, the durable webhook and
+worker, LangGraph, Temporal, Inngest, OpenAI Agents) asks Decidio before your function runs:
+`GET /agent/status` must say `approved` (or `auto_approved`) **and** return the request commitment
+this SDK sent with `/agent/authorize`, recomputed over the request about to run. A wake-up is only a
+wake-up.
+
+- **The commitment** is an HMAC-SHA256 under your agent's key material over the canonical request:
+  `{action, amount, scope, args}` on the core wrapper, the described context on an engine adapter
+  (plus the tool call itself on the OpenAI door). With the Ed25519 key `init` writes
+  (`DECIDIO_AGENT_KEY` + `DECIDIO_AGENT_DID`) only your agent holds the key, and Decidio stores and
+  returns an opaque value it can neither read nor forge for another request. **Prefer that key.** Without
+  it the commitment is keyed by `DECIDIO_API_TOKEN` — a bearer Decidio receives on every call — so it is
+  opaque to everyone except the Decidio server itself.
+- **Rotating key material strands pending approvals.** Re-minting the agent token, changing
+  `DECIDIO_AGENT_KEY`, or running the guard and the resume controller with different key material makes
+  every routed approval still pending fail its check as `request_changed` (the recompute no longer
+  matches). Drain pending approvals before rotating, or ask again for each afterwards.
+- **Refusals** (both extend `DecidioBlockedError`; nothing ran): `DecidioRequestChangedError` —
+  "the request changed after approval", naming the decision — and `DecidioApprovalUnverifiedError`
+  (`code: "commitment_missing"` when Decidio returns no commitment for a request this SDK bound, or
+  `"unverifiable"`). The durable path reports `not_approved` (Decidio still says pending: the action
+  stays parked) or `request_unverified`. **`resolve()` now asks Decidio before it runs, so it THROWS when
+  Decidio is unreachable** (nothing ran; the entry stays parked) — catch it and retry, or leave the entry
+  for the worker.
+- **LangGraph** needs key material (`init`, or `DECIDIO_API_TOKEN`) and a checkpointer run with a
+  `thread_id` (a routed gate without the run's thread, task and per-execution scratchpad refuses, naming
+  its decision). LangGraph re-runs an interrupted node on resume; the re-run authorizes with an
+  idempotency key derived from its own thread + task + commitment, so Decidio answers with the SAME
+  decision instead of minting a second one. Edit the graph state and the edited request becomes a
+  NEW pending decision — an approval is never applied across requests. `decidioResumeCommand` now
+  requires the webhook's `decisionId`.
+- **Temporal**: whenever you pass `authorize`, also pass `verify: (id) => executeActivity(verifyActivity, id)`,
+  where the activity returns `verifyApprovalActivity(config, id, ctx)` (from `@decidio/sdk/temporal`)
+  for the same `ctx`. A signal only wakes the workflow; still pending → it waits for the next one.
+- **Inngest**: the check runs as a memoized step after the event; a premature or forged event waits again.
+- **OpenAI Agents**: `applyResume(state, item, verdict)` is removed. Use
+  `await applyVerifiedResume(config, state, item, decisionId, describe)`, which approves the
+  interruption only when Decidio records that decision as approved for THIS tool call: the approval is
+  bound to the call's name, call id and exact argument string as well as `describe(item)`, so an item
+  edited after approval, or a second identical call, never rides it. Park each pending
+  `{ callId, decisionId }` (both on `authorizeInterruptions(...).pending`) with the serialized state and,
+  after `RunState.fromString`, find each item again by `item.rawItem.callId`. An interruption with no
+  call id is refused before anything is sent.
+- **Known limit — one gated action per LangGraph node** (true before 0.7.0 too). LangGraph re-runs the
+  whole node on resume, so an earlier gate in the same node runs again: if its request auto-approved and
+  its action already ran, the replay answers `proceed` to your verified agent and the action runs twice.
+  Put each gated action in its own node, or make the actions idempotent.
+- **Known limit — LangGraph and OpenAI Agents have no single-execution claim** (true before 0.7.0 too).
+  The checkpoint or the RunState is your storage, so two concurrent resumes of the same thread or run
+  can both pass the check and both run the action. Resume each one from one place (one worker per
+  thread/run id, or a lock). The core durable path claims each execution in its store; Temporal and
+  Inngest rely on their engine's own activity/step semantics.
+- **Upgrade the gate first.** A keyed SDK refuses a routed approval from a Decidio gate that does not
+  return commitments (`commitment_missing`) — it fails closed, never silently passes.
+
 
 
 
@@ -561,11 +635,13 @@ sealed after a specific predecessor, but a single-file verification cannot check
 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 refuses an unpinned run unless you ask for one (`--allow-unpinned`), and marks that verdict.
+**Pinning is trust-on-first-use.** The first sign-in (or `init`) against a Decidio remembers the DID
+it publishes at `<api>/api/did` — so that first contact trusts the connection, not the key. What
+remembering buys is everything afterwards: every later verification is checked against a key this
+computer already holds rather than one it was handed with the receipt, and a host that starts
+publishing a different key is flagged, never silently adopted. Receipts from Decidio's hosted service
+also verify against the issuer built into the verifier. The 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
 
@@ -653,7 +729,7 @@ that fits every other confirm error.
 - `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> [--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.
+- `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. It pins to the trust anchor it prints first: `--issuer`, else the DID remembered for your Decidio at sign-in, else the built-in hosted-service issuer — never the receipt's own `issuer` field. Fully offline AND fully decoupled: it touches no network and reads no `.env` (only the issuer DIDs remembered in your profile) — a receipt verifies identically from any 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 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.
@@ -679,6 +755,8 @@ manager for production.
 
 - `DecidioBlockedError` — policy blocked the action: a named block rule, or the universal backstop that fires when NO active policy governs agents at all (fail closed, no human involved). Distinct from routing-by-default — with an active policy and no matching auto-approve rule, a request is not blocked, it is ROUTED to a person.
 - `DecidioRejectedError` — a human rejected the routed action.
+- `DecidioRequestChangedError` (0.7.0, a `DecidioBlockedError`) — Decidio approved the decision for a *different* request than the one about to run ("the request changed after approval"); nothing executed. Ask again for the request you mean to run.
+- `DecidioApprovalUnverifiedError` (0.7.0, a `DecidioBlockedError`) — the approval could not be tied to this request: `code: "commitment_missing"` (Decidio returned no request commitment although this SDK sent one — typically a gate older than 0.7.0) or `"unverifiable"`. Nothing executed.
 - `DecidioSuspendedError` — (durable mode) the action was routed and is parked for async approval; the process may exit and resume later. Not a failure.
 - `DecidioTimeoutError` — (blocking mode only) no human decided within `pollTimeoutMs` (default 10 min); nothing executed locally. Since 0.6.4 the SDK's last act before throwing is to tell Decidio it gave up, so the request is closed as **withdrawn** (it leaves the queue; a later approval does nothing) — `error.withdrawn` is `true` when that landed and `false` when the call failed and the request may still be open. Withdrawing needs the bound agent token and the signing key `init` writes (an unbound or unsigned caller cannot withdraw anything — it just gets `withdrawn:false`). If a human decided in the last poll window, the SDK honours that decision instead: the action runs as approved, or `DecidioRejectedError` is thrown. The durable path never withdraws: its parked action is what a later approval resumes.
 - `DecidioRateLimitError` — the workspace's governed-action limit was hit; carries the server's `limit` / `remaining` / `resetAt`.
@@ -712,10 +790,12 @@ 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, 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).
+- **The issuer DID is trust on first use.** Sign-in and `init` remember the DID your Decidio publishes at
+  `<api>/api/did`; the tour and `receipt` pin to the DID the server names as its own, never to the one
+  the receipt claims. Pinned verification is only as strong as that first contact: cross-check the DID
+  through a channel you trust independently (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, which is also the
+  issuer built into the verifier).
 - **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/adapters/_gate.d.ts

@@ -1,4 +1,4 @@
-import { type GuardConfig, type ApprovalContext, type EvidenceOutcome } from "../index.js";
+import { type GuardConfig, type ApprovalContext, type EvidenceOutcome, type ApprovalCheck, type CommittedRequest } from "../index.js";
 /** The ONLY authorization verdicts this SDK understands. A gate answer outside this set means
  *  the SDK does not understand the decision — and an answer you do not understand means NO. */
 export declare const AUTHORIZE_VERDICTS: readonly ["proceed", "route", "block"];
@@ -15,7 +15,32 @@ export interface GateAuth {
  *  how an unknown verdict reached a protected action. Version skew (the day the gate learns a
  *  fourth verdict) is the realistic trigger, and it must never mean "run it". */
 export declare function assertAuthorizeVerdict(auth: unknown, fallbackDecisionId?: string): GateAuth;
-export declare function gateAuthorize(config: GuardConfig, ctx: ApprovalContext): Promise<GateAuth>;
+/** What an ENGINE door binds a routed approval to (0.7.0): the whole described context, canonicalized
+ *  exactly as gateAuthorize canonicalizes it. An adapter cannot see inside its `run()` closure, so the
+ *  described request - action, amount, scope and the display details a human approved - is the request.
+ *  Recompute it from the SAME describe() the door authorized with. */
+export declare function adapterRequest(ctx: ApprovalContext): CommittedRequest;
+/** What the OpenAI Agents door binds a routed approval to (#4B review W2): the described context AND the
+ *  tool call itself - its name, its call id and its exact argument string, from the interruption's raw
+ *  item. describe(item) is the host's summary and need not cover every argument (edit a parked item's
+ *  target and it can stay the same), and it never says WHICH call: without the call id one approval could
+ *  be applied to a second, identical call whose own decision is still pending. An item with no call id
+ *  cannot be bound to one call, so it is refused - nothing routed, nothing approved. (Python twin:
+ *  tool_call_request.) */
+export declare function toolCallRequest(item: unknown, ctx: ApprovalContext): CommittedRequest;
+/** THE ONE APPROVAL CHECK on an engine door: GET /agent/status + the request commitment recomputed over
+ *  this `ctx` (see checkApproval) - or over `request` when the door binds more than the described context
+ *  (the OpenAI door's toolCallRequest). Returns the plain-JSON outcome - an engine that must run HTTP
+ *  inside an activity or a step (Temporal, Inngest) memoizes exactly this value. */
+export declare function gateCheckApproval(config: GuardConfig, decisionId: string, ctx: ApprovalContext, request?: CommittedRequest): Promise<ApprovalCheck>;
+/** Validate an approval check that crossed a serialization boundary (a Temporal activity result, an
+ *  Inngest step memo). Anything that is not a well-formed check is refused as unverifiable - the same
+ *  "an answer you do not understand is never permission" rule the verdict allow-list applies. */
+export declare function assertApprovalCheckShape(raw: unknown, decisionId: string): ApprovalCheck;
+export declare function gateAuthorize(config: GuardConfig, ctx: ApprovalContext, opts?: {
+    idempotencyKey?: string;
+    request?: CommittedRequest;
+}): Promise<GateAuth>;
 /** Report an adapter-path execution and RETURN what Decidio recorded.
  *
  *  Two 0.2.0 changes, both closing the same gap. It applies the caller's `evidence` mapper — the

package/dist/adapters/_gate.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, assertDescribed, readConfirmResponse, buildConfirmBody, decisionIdProblem } from "../index.js";
+import { DecidioBlockedError, DecidioRejectedError, DecidioHttpError, signBoundProof, signConfirm, assertSafeTransport, carriesCredential, canonicalize, assertDescribed, readConfirmResponse, buildConfirmBody, decisionIdProblem, bindingMaterial, requestCommitment, checkApproval } from "../index.js";
 export const AUTHORIZE_VERDICTS = ["proceed", "route", "block"];
 export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     const a = auth;
@@ -13,7 +13,34 @@ export function assertAuthorizeVerdict(auth, fallbackDecisionId = "unknown") {
     }
     return a;
 }
-export async function gateAuthorize(config, ctx) {
+export function adapterRequest(ctx) {
+    const c = canonicalize(ctx, "describe(...)");
+    return { action: c.action, amount: c.amount, ...(c.scope !== undefined && c.scope !== null ? { scope: c.scope } : {}), ...(c.context !== undefined && c.context !== null ? { context: c.context } : {}) };
+}
+export function toolCallRequest(item, ctx) {
+    const it = (item && typeof item === "object" ? item : {});
+    const raw = (it.rawItem && typeof it.rawItem === "object" ? it.rawItem : it);
+    const callId = raw.callId ?? raw.call_id ?? raw.id;
+    if (typeof callId !== "string" || callId === "") {
+        throw new Error("[decidio] openai: this tool-approval item carries no call id (rawItem.callId), so an approval could not be bound to this ONE call - nothing was routed or approved. Pass the items state.getInterruptions() returns.");
+    }
+    const name = raw.name ?? it.name ?? it.toolName;
+    const args = raw.arguments ?? it.arguments;
+    return { ...adapterRequest(ctx), args: [{ arguments: args === undefined ? null : args, callId, name: typeof name === "string" ? name : null }] };
+}
+export async function gateCheckApproval(config, decisionId, ctx, request) {
+    return checkApproval(config, decisionId, request ?? adapterRequest(ctx));
+}
+export function assertApprovalCheckShape(raw, decisionId) {
+    const c = raw;
+    if (!c || typeof c !== "object" || typeof c.ok !== "boolean" || c.decisionId !== decisionId || typeof c.state !== "string") {
+        return { ok: false, decisionId, state: "", code: "unverifiable", reason: `the approval check for decision ${decisionId} came back malformed (${JSON.stringify(raw ?? null).slice(0, 120)}) - return checkApproval(...) / gateCheckApproval(...) from your activity unchanged` };
+    }
+    if (c.ok === true && c.code !== undefined)
+        return { ok: false, decisionId, state: c.state, code: "unverifiable", reason: "the approval check came back contradictory (ok with a refusal code)" };
+    return c;
+}
+export async function gateAuthorize(config, ctx, opts = {}) {
     ctx = canonicalize(ctx, "describe(...)");
     assertDescribed(ctx);
     assertSafeTransport(config.apiUrl, carriesCredential(config));
@@ -22,6 +49,8 @@ export async function gateAuthorize(config, ctx) {
     const requesterIdentity = (config.agentKey && config.agentDid)
         ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
         : undefined;
+    const material = bindingMaterial(config);
+    const commitment = material ? requestCommitment(material, opts.request ?? adapterRequest(ctx)) : undefined;
     const res = await f(config.apiUrl.replace(/\/$/, "") + "/agent/authorize", {
         method: "POST",
         headers: { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) },
@@ -29,6 +58,8 @@ export async function gateAuthorize(config, ctx) {
             requester: config.agentId, action: ctx.action, amount: ctx.amount, scope: ctx.scope,
             sourceSystem: config.sourceSystem, ...(ctx.context ? { context: ctx.context } : {}),
             ...(requesterIdentity ? { requesterIdentity } : {}), ...(resumeUrl ? { resumeUrl } : {}),
+            ...(commitment ? { requestCommitment: commitment } : {}),
+            ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
         }),
     });
     if (!res.ok) {

package/dist/adapters/langgraph.d.ts

@@ -1,22 +1,16 @@
 import { Command } from "@langchain/langgraph";
 import { type GuardConfig, type ApprovalContext, type ProtectedExecution } from "../index.js";
-/**
- * @decidio/sdk/langgraph — durable suspend via LangGraph's native `interrupt()`.
- * `interrupt` finds the running graph itself (no handle needed), so the gate drops into
- * a node: authorize → on route, interrupt() durably pauses (the checkpointer persists;
- * the process can die) → on resume (Command(resume={verdict})) run the agent's own
- * action + confirm. Decidio is the approval system; the host bridges its webhook to the
- * graph resume (decidioResumeCommand). Requires @langchain/langgraph (optional peer dep).
- *
- * (This wiring doc ships in the .d.ts — the README points here.)
- */
 /** Gate `run()` behind Decidio inside a LangGraph node. */
 export declare function decidioGate<R>(config: GuardConfig, ctx: ApprovalContext, run: () => Promise<R>, opts?: {
     evidence?: (r: R) => unknown;
 }): Promise<ProtectedExecution<R>>;
 /** Translate Decidio's signed resume webhook into the LangGraph resume Command. The host
- *  maps decisionId → thread_id and passes this to graph.invoke/stream. */
+ *  maps decisionId → thread_id and passes this to graph.invoke/stream. Since 0.7.0 the Command
+ *  carries the decisionId - the gate refuses a resume value that does not say which decision it
+ *  approves - and the verdict in it is informational only: the node confirms the approval with
+ *  Decidio. Verify the webhook's signature BEFORE building this (verifyResumeSignature). */
 export declare function decidioResumeCommand(body: {
+    decisionId?: string;
     verdict?: string;
     reason?: string;
 }): Command;

package/dist/adapters/langgraph.js

@@ -1,19 +1,70 @@
 import { interrupt, Command } from "@langchain/langgraph";
-import { DecidioBlockedError } from "../index.js";
-import { gateAuthorize, gateConfirm, verdictFrom, assertVerdict, checkEngineVersion } from "./_gate.js";
+import * as langgraph from "@langchain/langgraph";
+import { DecidioBlockedError, approvalRefusal, bindingMaterial, requestCommitment, idempotencyKey, decisionIdProblem } from "../index.js";
+import { gateAuthorize, gateConfirm, gateCheckApproval, adapterRequest, checkEngineVersion } from "./_gate.js";
+const gatesOpened = new WeakMap();
+function runIdentity() {
+    let conf;
+    try {
+        const getConfig = langgraph.getConfig;
+        conf = typeof getConfig === "function" ? getConfig()?.configurable : undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const thread = conf?.["thread_id"], ns = conf?.["checkpoint_ns"];
+    if ((typeof thread !== "string" && typeof thread !== "number") || String(thread) === "")
+        return undefined;
+    if (typeof ns !== "string" || ns === "")
+        return undefined;
+    const scratch = conf?.["__pregel_scratchpad"];
+    if (!scratch || typeof scratch !== "object")
+        return undefined;
+    const call = gatesOpened.get(scratch) ?? 0;
+    gatesOpened.set(scratch, call + 1);
+    return { thread: String(thread), ns, call };
+}
 export async function decidioGate(config, ctx, run, opts) {
-    const auth = await gateAuthorize(config, ctx);
+    const material = bindingMaterial(config);
+    if (!material) {
+        throw new Error("[decidio] the LangGraph adapter binds a routed approval to the exact request with a key only this agent holds, and none is configured - set DECIDIO_AGENT_KEY + DECIDIO_AGENT_DID (npx @decidio/sdk init) or DECIDIO_API_TOKEN. Nothing was routed or executed.");
+    }
+    const request = adapterRequest(ctx);
+    const self = runIdentity();
+    const key = self ? idempotencyKey(material, { thread: self.thread, ns: self.ns, call: self.call, commitment: requestCommitment(material, request) }) : undefined;
+    const auth = await gateAuthorize(config, ctx, key ? { idempotencyKey: key } : {});
     if (auth.decision === "block")
         throw new DecidioBlockedError(auth.reason ?? "blocked by policy", auth.decisionId);
     if (auth.decision === "route") {
-        const resumed = interrupt({ decidio: { decisionId: auth.decisionId, action: ctx.action, amount: ctx.amount, scope: ctx.scope } });
-        assertVerdict(verdictFrom(resumed), auth.decisionId, resumed?.reason);
+        if (!self) {
+            throw new DecidioBlockedError(`this LangGraph run exposes no thread/task identity (a checkpointer with a thread_id, @langchain/langgraph's getConfig() and the node execution's scratchpad are required), so a resumed node could not recognise decision ${auth.decisionId} as its own. Nothing was executed; ${auth.decisionId} is pending in Decidio - reject it (npx @decidio/sdk approvals reject ${auth.decisionId}).`, auth.decisionId);
+        }
+        const payload = { decidio: { decisionId: auth.decisionId, action: ctx.action, amount: ctx.amount, scope: ctx.scope } };
+        let resumed = interrupt(payload);
+        for (;;) {
+            const named = resumed && typeof resumed === "object" ? resumed.decisionId : undefined;
+            if (typeof named !== "string" || named === "") {
+                throw new DecidioBlockedError(`the LangGraph resume value names no decision (${JSON.stringify(resumed ?? null).slice(0, 120)}) - refusing to execute. Build it with decidioResumeCommand(webhookBody), which carries the decisionId: an approval that does not say which decision it approves cannot be applied to this one.`, auth.decisionId);
+            }
+            if (named === auth.decisionId) {
+                const check = await gateCheckApproval(config, auth.decisionId, ctx);
+                if (check.ok)
+                    break;
+                if (check.code !== "pending")
+                    throw approvalRefusal(check);
+            }
+            resumed = interrupt(payload);
+        }
     }
     const result = await run();
     const confirmation = await gateConfirm(config, auth.decisionId, result, opts?.evidence);
     return { value: result, decisionId: auth.decisionId, confirmation };
 }
 export function decidioResumeCommand(body) {
-    return new Command({ resume: { verdict: body.verdict, reason: body.reason } });
+    const decisionId = body?.decisionId;
+    const problem = decisionIdProblem(decisionId);
+    if (problem)
+        throw new Error(`[decidio] decidioResumeCommand needs the webhook's decisionId (${problem}) - the node refuses a resume that does not say which decision it approves. Pass the webhook body verbatim.`);
+    return new Command({ resume: { decisionId, verdict: body.verdict, reason: body.reason } });
 }
 checkEngineVersion("langgraph");