ordainer 1.2.4 → 1.2.6

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 Entries before 1.1.0 are written with the current names. Those versions used the product's former name for the
 package, class, env vars, outage error code, User-Agent and key prefix: the full list is in 1.1.0 "Renamed".
 
+## 1.2.6 (2026-11-09)
+
+README-only: install with `npm install ordainer`. The code is the same as 1.2.5, byte for byte; only the install
+instructions in this README changed.
+
+## 1.2.5 (2026-11-09)
+
+Changed: **the retry pause is jittered** (P89-L1), like the Ruby SDK: 50 ms ± 50% (25–75 ms) before the first retry,
+doubling for each further one. Retry count, `retryBudgetMs` and which answers are retried are unchanged. When a server
+sheds load (`503 decide_timeout`, "at capacity"), callers no longer all retry in one wave 50 ms later.
+
+Changed: **Error messages reworded; codes, statuses and fields unchanged. Match on error.code, not the message.** `429 plan_limit_reached`: "This call wasn't run because the usage limit was reached (0 of 5 left). It resets at {resets_at}. Retrying before then won't work." The same sentence is used when the key's label is present: the message does not name the key. `error.label` is unchanged. The "It resets at" sentence is still omitted when `resets_at` is missing. A sticky deny reuses this sentence. `403 plan_denied` with `tool_not_in_plan`: "This call wasn't run because "<tool>" isn't included in your current access. If you need it, contact the provider of this service. (tool_not_in_plan)", with the same quoting rules as 1.2.3 (otherwise "this action"). Any other plan deny is unchanged. Status, `error.code`, `reason`, `remaining`, `limit`, `resets_at`, `request_id`, `label`, headers (`Retry-After`, `X-Request-Id`) and whether the call runs are unchanged.
+
+This is the first Node SDK build that passes the deny `explanation` through to callers, so it should be published only after the matching API change (#207) is live.
+
 ## 1.2.4 (2026-10-22)
 
 The first release on npm: `npm install ordainer`. The code is the same as 1.2.3, byte for byte; only the install
@@ -14,7 +29,7 @@ Added (T18-P39): **the 429 `plan_limit_reached` names the agent** when the API's
 agent (agent-a) has reached its plan limit (0 of 3 left). …" and `error.label`. Also on `result.label` (denies only; null
 on allows), on a sticky deny, and JSON-escaped in the shadow "would deny" log line. The label is cleaned (control,
 invisible and bidi characters removed, whitespace collapsed) and cut to 64 characters. It is off by default on both
-sides: the API sends `label` only for accounts that turned it on, and `exposeKeyLabel: true` opts the SDK in; without
+sides: the API sends `label` only once it's turned on for your account (email support), and `exposeKeyLabel: true` opts the SDK in; without
 either, the body and sentence are exactly as before. Without a label (an older server) nothing changes. Status, `error.code`, `Retry-After` and
 whether the call runs are unchanged.
 

package/README.md

@@ -5,6 +5,8 @@ A small wrapper that asks Ordainer (`POST /v1/decide`) before your tool handler
 
 ## Install
 
+<!-- Checked by test/sdk-pack.test.js. LAUNCH SWAP applied (Nov 9 2026): install is `npm install ordainer`.
+Live docs already use that command. This README does not follow sites/docs SDK_INSTALL while SDK_ON_NPM is still false on main. -->
 ```bash
 npm install ordainer
 ```
@@ -51,14 +53,14 @@ if (d.allowed) { /* run it */ }
 | Situation | Default result |
 |---|---|
 | Ordainer says allow | Handler runs. `req.ordainer` holds the decision (`remaining`, `limit`, `requestId`, …). `remaining` and `limit` are `number \| null`: `null` on a plan with no cap (and when Ordainer didn't answer), so check before doing arithmetic. |
-| Ordainer says deny, **enforce** | Handler does not run. `429 plan_limit_reached` with `Retry-After` and a message you can show the agent as-is. `tool_not_in_plan` gives `403 plan_denied`. `result.decision` is `'deny'`, `result.allowed` is `false` and `result.wouldDeny` is `false` (1.2.2: it's a real deny, not a would-deny). |
+| Ordainer says deny, **enforce** | Handler does not run. The status follows the API `reason`. `quota_exceeded` (the plan allowance) is `429 plan_limit_reached` with `Retry-After` and a message you can show the agent as-is. `402` is only that quota deny, and only when `denyStatus` is set. `tool_not_in_plan`, `credits_exhausted` and `key_credits_exhausted` are `403 plan_denied`, not `402`. `test_limit_reached` is its own row below. `result.decision` is `'deny'`, `result.allowed` is `false` and `result.wouldDeny` is `false` (1.2.2: it's a real deny, not a would-deny). |
 | Ordainer says deny, **shadow** | Handler runs. A `[ordainer] shadow: would deny …` warning is logged, `onDecision` gets `wouldDeny: true`, and the console shows "would deny (call ran)". |
-| Timeout (`timeoutMs`), network error, 5xx, or a 200 that isn't a decision | **Fail open**: the handler runs and a warning is logged. With `failMode: 'closed'` you get `503 ordainer_unavailable` instead. These are the **only** cases `failMode` covers (`403 subscription_inactive` follows `billingLapse`, below). |
+| Timeout (`timeoutMs`), network error, 5xx, or a 200 that isn't a decision | **Fail open**: the handler runs and a warning is logged. This includes `503 decide_timeout` when the Ordainer server is at capacity (it refuses the call at once, before deciding, nothing counted; the message says "at capacity"): retried once (`retries`), then `failMode`. With `failMode: 'closed'` you get `503 ordainer_unavailable` instead. These are the **only** cases `failMode` covers (`403 subscription_inactive` follows `billingLapse`, below). |
 | Any other 4xx (`400`, `401 unknown_key`/`revoked_key`, `403 subscription_required`, `409 idempotency_conflict`, `429` other than `safety_limit_reached`, …) or no agent key configured | **Blocked in any `failMode`** (QA S2): Ordainer answered, and the answer isn't "allow", so the call is never let through unchecked. `plan_check_rejected` with **no `Retry-After`** (a retry won't fix it): `500` for a key, config, `400` or `409` problem, `403` for `subscription_required` (Q2; never `503`, which means "outage, retry"); or `429 rate_limited` with `Retry-After` for a rate limit; `result.rejected: true` (`failClosed` stays `false`), `result.error` has the code and status. A "rejected (call blocked in any failMode): <code>: <message> X-Request-Id=req_… tool=…" warning is logged. The warning is logged at most once a minute per failure mode and error code (`warningIntervalMs`), with "(N more since the last warning)", so an outage doesn't flood your logs; `onDecision` still sees every result. |
 | `403 subscription_inactive`: your own Ordainer subscription is inactive | A **billing state, not an outage**. Follows the **billing-lapse setting `billingLapse`**, never `failMode` (Terms 10.3(b)): `'open'` (default) runs the handler, unchecked and uncounted (`result.allowed: true`, `result.failOpen: false`); `'closed'` (opt-in) blocks with `403 plan_check_rejected`, **no `Retry-After`** and a neutral message (`result.rejected: true`). Either way: its own warning at most once a minute (not the generic one), `result.billingInactive: true`, `result.billingLapse`, `result.reason: 'subscription_inactive'` and `onBillingInactive(result)` on every call. See below. |
 | `403 subscription_required`: your Ordainer account has never had a paid subscription (live key) | **Blocked in any `failMode`**, like other 4xx (`result.rejected: true`). It gets its own billing warning (`[ordainer] subscription required: … no paid subscription yet … Subscribe …`, never "subscription inactive"), `result.billingInactive: true`, `result.reason: 'subscription_required'` and `onBillingInactive(result)`. |
-| `429 rate_limited`: this agent key sent more than the per-key limit (default: about 100 requests a second per key (each server counts separately)) | A **rate limit, not an outage**. Blocked in any `failMode` with `429 rate_limited` and the server's `Retry-After`. Never silent: its own warning at most once a minute, `result.rateLimited: true`, `result.error.limitScope: 'per_key'`, `result.retryAfterSec`, and `onRateLimited(result)` on every such call. |
-| `429 concurrency_limited`: this agent key already has too many plan checks in flight at once on one Ordainer server (4 in flight at once per key on our hosted service; up to 20 more wait briefly, so small bursts just serialize) | Handled **exactly like `429 rate_limited`**: blocked in any `failMode` (never a fail-open; it is answered inside the timeout), `429 rate_limited` with `Retry-After` to the end user, `result.rateLimited: true`, `result.reason: 'concurrency_limited'`, `result.error.limitScope: 'per_key_concurrency'`, `onRateLimited(result)`, and its own "concurrency limited" warning at most once a minute. Send fewer calls in parallel per agent key. For abuse-prone tools consider `failMode: 'closed'`. |
+| `429 rate_limited`: this agent key sent more than the per-key limit. About 100 requests a second, each server counts separately. | A **rate limit, not an outage**. Blocked in any `failMode` with `429 rate_limited` and the server's `Retry-After`. Never silent: its own warning at most once a minute, `result.rateLimited: true`, `result.error.limitScope: 'per_key'`, `result.retryAfterSec`, and `onRateLimited(result)` on every such call. |
+| `429 concurrency_limited`: this agent key already has too many plan checks in flight at once on one Ordainer server (4 in flight at once per key on our hosted service; up to 20 more wait in line within the server's 250 ms deadline, so small bursts just serialize). Also a call that waited in that line and then found the server at capacity (the message says so): it is still this key's burst, so still a 429 | Handled **exactly like `429 rate_limited`**: blocked in any `failMode` (never a fail-open; it is answered inside the timeout), `429 rate_limited` with `Retry-After` to the end user, `result.rateLimited: true`, `result.reason: 'concurrency_limited'`, `result.error.limitScope: 'per_key_concurrency'`, `onRateLimited(result)`, and its own "concurrency limited" warning at most once a minute. Send fewer calls in parallel per agent key. For abuse-prone tools consider `failMode: 'closed'`. |
 | `429 too_many_failed_auth`: too many requests with a missing or unrecognized agent key came from your server's address (Ordainer's per-address limit; never sent for a valid key) | A **bad key, not a rate problem**: rejected like other 4xx (`result.rejected: true`, `result.rateLimited: false`, `result.error.limitScope: 'per_address'`; `onRateLimited` is not called). Its own warning: "too many requests with a missing or unrecognized agent key from this server's address (Ordainer's per-address limit …) Check the agent key …". Fix the key; retrying won't help. |
 | Deny `test_limit_reached`: your account used its free test-key decisions for the month (test keys only) | **Enforce: blocks** regardless of `failMode`: `429 test_limit_reached` with `Retry-After` until the 1st (UTC). **Shadow (1.2.0): runs.** Shadow never blocks: the server counts the call and records a would-deny `test_limit_reached` (answer `mode: 'shadow'`), and the handler runs (`result.allowed: true`, `result.wouldDeny: true`). Not an outage and not your customer's plan. Both: `result.testLimitReached: true`, its own warning at most once a minute, and `onTestLimit(result)` on every such call. Live keys are never affected. |
 | `429 safety_limit_reached` (1.2.0): shadow calls passed the safety ceiling, 10 times your account's monthly test limit | A **safety limit, not a deny**. The handler **runs in every `failMode`** (like `billingLapse: 'open'`), unchecked and not recorded, until your test usage resets at the start of next month (UTC). `result.allowed: true`, `result.safetyLimited: true`, `result.failOpen: false`, `result.rejected: false`, `result.error.limitScope: 'org_safety'`, `result.resetsAt`, `result.retryAfterSec`; its own warning at most once per `warningIntervalMs`, and `onSafetyLimit(result)` on every such call. |
@@ -102,14 +104,14 @@ it the SDK blocks and warns:
 
 Mock the SDK in CI test suites instead of calling Ordainer on every run; they share the account's 1,000.
 
-**Shadow at the test limit (1.2.0).** In shadow mode the test limit never blocks: past it, each shadow call is still
-counted and recorded as a would-deny `test_limit_reached`, and the SDK runs it (a "test limit reached (shadow)"
+**Shadow at the test limit (1.2.0).** In shadow mode the test limit never blocks: past it, each shadow call is
+recorded as a would-deny `test_limit_reached` and counts only toward the safety ceiling, and the SDK runs it (a "test limit reached (shadow)"
 warning, at most once per `warningIntervalMs`). Past a safety ceiling of 10 times the limit the server answers
 `429 safety_limit_reached` until the start of next month (UTC); the SDK runs the call in every `failMode`
 (`result.safetyLimited`, `onSafetyLimit`). If you call our API directly, we recommend letting the tool run and logging
 the error. If you reach it, email support@ordainer.ai.
 
-**Rate limit.** The server allows each agent key `DECIDE_RATE_LIMIT_PER_SEC` requests a second (default: about 100 requests a second per key (each server counts separately)). Over
+**Rate limit.** The server allows each agent key `DECIDE_RATE_LIMIT_PER_SEC` requests a second. About 100 requests a second, each server counts separately. Over
 it, the SDK logs (at most once a minute, with a suppressed count):
 
 ```
@@ -124,7 +126,7 @@ operation**. The server replays a key for 24 hours; after that it's a new, count
 
 `retries: n` (default **1**, max 5, `0` = off; on the client, `decide()`, `middleware()` or `wrap()`) retries a timeout,
 a network error or a **503** (the server's fast `decide_timeout` / `db_timeout` / `db_unavailable` answers, or an outage) with the **same**
-key, after a 50 ms pause, so a lost answer is replayed by the server, not counted twice. 4xx answers and other 5xx
+key, after a short jittered pause (25–75 ms, doubling for each further retry, as in the Ruby SDK), so a lost answer is replayed by the server, not counted twice. 4xx answers and other 5xx
 (500, 502, …) are never retried. All attempts of one call share `retryBudgetMs` (default 650: a 300 ms attempt, the
 pause, and one more 300 ms attempt): a retry starts only with at least 50 ms left and its timeout is cut to the time
 left, so a call never takes much longer than the budget. Only after the last attempt does `failMode` apply (default
@@ -165,15 +167,15 @@ HTTP/1.1 429 Too Many Requests
 Retry-After: 3600
 X-Request-Id: req_KdimJCxq8zbjfL4g
 
-{"error":{"code":"plan_limit_reached","message":"This agent's plan limit is reached (0 of 5 left). It resets at 2026-11-01T00:00:00.000Z. Retrying before then will not succeed. This call was not run.","request_id":"req_KdimJCxq8zbjfL4g","reason":"quota_exceeded","remaining":0,"limit":5,"resets_at":"2026-11-01T00:00:00.000Z"}}
+{"error":{"code":"plan_limit_reached","message":"This call wasn't run because the usage limit was reached (0 of 5 left). It resets at 2026-11-01T00:00:00.000Z. Retrying before then won't work.","request_id":"req_KdimJCxq8zbjfL4g","reason":"quota_exceeded","remaining":0,"limit":5,"resets_at":"2026-11-01T00:00:00.000Z"}}
 ```
 
-**Naming the agent** (unreleased, DRAFT T18-P39): when the API sends the agent key's label on the deny, the sentence
-names it and the body gets a `label` field: "This agent (agent-a) has reached its plan limit (0 of 3 left). It resets at
-…. Retrying before then will not succeed. This call was not run." The label is the name you gave the key, cleaned and cut
-to 64 characters; nothing else about the key is sent. This is off by default in two places: the API only sends `label`
-when your account has it turned on (ask us; a console setting is coming), and the SDK only uses it when you pass
-`exposeKeyLabel: true`. With either one off, the body and sentence stay exactly as above. Labels are yours to choose,
+**Naming the agent** (T18-P39): when the API sends the agent key's label on the deny and you pass
+`exposeKeyLabel: true`, the body gets a `label` field. The message does not name the key. It is the sentence above,
+with or without a label. The label is the name you gave the key, cleaned and cut to 64 characters; nothing else about
+the key is sent. This is off by default in two places: the API only sends `label` when your account has it turned on
+(ask us; a console setting is coming), and the SDK only puts it on the body when you pass `exposeKeyLabel: true`.
+With either one off, there is no `label` field and the message stays exactly as above. Labels are yours to choose,
 so only turn it on if your key names are fine for your callers to see.
 
 `Retry-After` is always the real number of seconds from the moment of the call until `resets_at`, rounded up (at
@@ -193,7 +195,7 @@ decision id exists). Earlier builds used `Ordainer-Request-Id` and `error.type`;
 |---|---|---|---|
 | Quota (`plan_limit_reached`) | 429 (or `denyStatus`) | seconds until the reset | says when it resets |
 | `test_limit_reached` | 429 | seconds until the reset (none if `resets_at` is unknown) | "This call wasn't run. This service's test calls for the month are used up. They reset on November 1 (UTC). Nothing is wrong on your side, and trying again won't help until they reset. If you need it sooner, contact the service's team. (test_limit_reached)" (the day is `resets_at` in UTC, as "<Month D>"; no "They reset on …" sentence unless `resets_at` is a valid ISO-8601 date-time) |
-| Any other deny (today `tool_not_in_plan`) | 403 `plan_denied` | **none** | `tool_not_in_plan`: "This call wasn't run because your plan doesn't include "research.run". If you need it, ask whoever manages your plan. (tool_not_in_plan)" (the tool you passed to `decide()`, in quotes only when it matches `^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$` and has no `//` and no leading `scheme:` (`^[A-Za-z][A-Za-z0-9+.-]*:`, so nothing URL-like is echoed); otherwise "this action"). Any other reason: "This call wasn't run because it isn't allowed on your account right now. If you need it, contact the service's team. (reason)" (the reason in brackets only when it looks like an API code: lowercase letters and `_`, up to 40 characters) |
+| Any other deny (today `tool_not_in_plan`) | 403 `plan_denied` | **none** | `tool_not_in_plan`: "This call wasn't run because "research.run" isn't included in your current access. If you need it, contact the provider of this service. (tool_not_in_plan)" (the tool you passed to `decide()`, in quotes only when it matches `^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$` and has no `//` and no leading `scheme:` (`^[A-Za-z][A-Za-z0-9+.-]*:`, so nothing URL-like is echoed); otherwise "this action"). Any other reason: "This call wasn't run because it isn't allowed on your account right now. If you need it, contact the service's team. (reason)" (the reason in brackets only when it looks like an API code: lowercase letters and `_`, up to 40 characters) |
 | `429 rate_limited` | 429 `rate_limited` | the server's value | "The service is getting too many requests on this key right now, so this call was held back. Please wait a moment and try again. (rate_limited)" (the seconds are in `Retry-After` and `retry_after`) |
 | `429 concurrency_limited` | 429 `rate_limited` | the server's value | "The service is handling too many calls on this key at once, so this call was held back. Please wait a moment and try again. (concurrency_limited)" (the seconds are in `Retry-After` and `retry_after`) |
 | Outage under `failMode: 'closed'` (timeout, network error, 5xx, malformed answer) | **503 `ordainer_unavailable`** (only here) | `5` | "This call wasn't run. The service couldn't finish a safety check it does before each call, so it stopped instead of going ahead without it. Nothing is wrong on your side. Please try again in a minute. (ordainer_unavailable)" |

package/index.d.ts

@@ -32,7 +32,7 @@ export interface DecideResult {
   replayed: boolean;
   /** Sticky deny: Ordainer couldn't answer (would fail open), but this (agent key, tool) got quota_exceeded within stickyDenyMs, so the call is denied (allowed false, reason 'quota_exceeded', 429 plan_limit_reached), or in shadow allowed and reported (wouldDeny). `error` says why there was no answer. */
   stickyDeny: boolean;
-  /** The agent key's label (its name), sent by the API on denies only, cleaned and at most 64 characters. null on allows, errors, older servers, or unless exposeKeyLabel: true. Shown in the 429 plan_limit_reached body and sentence. */
+  /** The agent key's label (its name), sent by the API on denies only, cleaned and at most 64 characters. null on allows, errors, older servers, or unless exposeKeyLabel: true. Shown on the 429 plan_limit_reached body as error.label. The message does not include it. */
   label: string | null;
   /** HTTP attempts made (retries reuse the same idempotency key). 0 when no request was sent. */
   attempts: number;
@@ -79,7 +79,7 @@ export interface OrdainerOptions {
   /** Sticky deny window (ms) after a quota_exceeded deny for an (agent key, tool): a would-be fail-open for that pair is denied (shadow: reported). Default 60000, 0 = off, max 300000. Ends early at the plan's reset or on an allow. */
   stickyDenyMs?: number;
   denyStatus?: DenyStatus;
-  /** Name the agent key (its label) in the 429 plan_limit_reached body and sentence when the API sends it. Default false (labels stay out of caller responses and result.label is null); set true to opt in. */
+  /** Put the agent key's label on the 429 plan_limit_reached body (error.label) when the API sends it. The message does not include it. Default false (labels stay out of caller responses and result.label is null); set true to opt in. */
   exposeKeyLabel?: boolean;
   onDecision?: (result: DecideResult) => void | Promise<void>;
   /** Called on every call answered 403 subscription_inactive (subscription inactive, under either billingLapse setting) OR 403 subscription_required (live key, no paid subscription yet); check result.error.code. The log warning is rate-limited; this hook is not. */

package/index.js

@@ -82,7 +82,7 @@ const { version: SDK_VERSION } = require('./package.json'); // npm pack always s
 // Brand strings in one place ("Ordainer" is a working name; the rename sweep edits this block).
 const BRAND = Object.freeze({
   name: 'Ordainer',
-  baseUrl: 'https://api.ordainer.dev', // docs-site download (the npm release defaults to the launch host)
+  baseUrl: 'https://api.ordainer.dev',
   envKey: 'ORDAINER_KEY',
   envBaseUrl: 'ORDAINER_BASE_URL',
   logPrefix: '[ordainer]',
@@ -112,7 +112,7 @@ const DNS_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN']);
 // The server rejects idempotency keys longer than this (400 invalid_idempotency_key).
 const MAX_IDEMPOTENCY_LEN = 255;
 const MAX_RETRIES = 5;
-const RETRY_DELAY_MS = 50;
+const RETRY_DELAY_MS = 50; // first pause; doubles each retry, with +/-50% jitter (25-75 ms first), like the Ruby SDK
 // Architecture review #1: one retry by default, only for a timeout, a network error or a 503 (the server's
 // fast decide_timeout / db_timeout / db_unavailable / outage answers), and only inside a small total time budget for the
 // whole decide() (all attempts and the pauses between them). 4xx and other 5xx are never retried.
@@ -283,7 +283,7 @@ function showableTool(tool) {
 function planDeniedMessage(reason, tool) {
   if (reason === 'tool_not_in_plan') {
     const what = showableTool(tool) ? `"${tool}"` : 'this action';
-    return `This call wasn't run because your plan doesn't include ${what}. If you need it, ask whoever manages your plan. (tool_not_in_plan)`;
+    return `This call wasn't run because ${what} isn't included in your current access. If you need it, contact the provider of this service. (tool_not_in_plan)`;
   }
   const msg = "This call wasn't run because it isn't allowed on your account right now. If you need it, contact the service's team.";
   return typeof reason === 'string' && /^[a-z][a-z_]{0,39}$/.test(reason) ? `${msg} (${reason})` : msg;
@@ -391,18 +391,19 @@ function denyResponse(result, now = Date.now()) {
       body: {
         error: {
           code: 'plan_limit_reached',
-          // T18-P39: name the agent when the API sent its key's label (and exposeKeyLabel isn't false).
-          message: (label
-            ? `This agent (${label}) has reached its plan limit (${result.remaining ?? 0} of ${result.limit ?? '?'} left).`
-            : `This agent's plan limit is reached (${result.remaining ?? 0} of ${result.limit ?? '?'} left).`)
+          // Approved Nov 3 2026 (decisions.md:365 and :368). The message does not name the key.
+          // error.label is still set when the API sent one and exposeKeyLabel is on.
+          // The reset sentence is omitted when resets_at is missing, same as before.
+          message: `This call wasn't run because the usage limit was reached (${result.remaining ?? 0} of ${result.limit ?? '?'} left).`
             + (result.resetsAt ? ` It resets at ${result.resetsAt}.` : '')
-            + ' Retrying before then will not succeed. This call was not run.',
+            + " Retrying before then won't work.",
           ...(label ? { label } : {}),
           request_id: result.requestId,
           reason: result.reason,
           remaining: result.remaining,
           limit: result.limit,
           resets_at: result.resetsAt,
+          ...(result.explanation ? { explanation: result.explanation } : {}),
         },
       },
     };
@@ -509,6 +510,7 @@ class Ordainer {
     this.stickyDenyMs = opts.stickyDenyMs ?? DEFAULT_STICKY_DENY_MS;
     this._sticky = new Map(); // sha256(key)\0tool -> { until, mode, limit, resetsAt }
     this._sleep = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms))); // tests
+    this._random = opts.random || Math.random; // tests (the retry jitter)
     this.apiKey = opts.apiKey ?? process.env[BRAND.envKey];
     this.baseUrl = String(opts.baseUrl || process.env[BRAND.envBaseUrl] || DEFAULT_BASE_URL).replace(/\/+$/, '');
     this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -516,7 +518,8 @@ class Ordainer {
     this.failMode = opts.failMode || 'open';
     this.billingLapse = opts.billingLapse || 'open';
     this.denyStatus = opts.denyStatus || 429;
-    // T18-P39: put the agent key's label (from a deny answer) in the 429 plan_limit_reached body and sentence.
+    // T18-P39: put the agent key's label (from a deny answer) on the 429 plan_limit_reached body
+    // as error.label. The message does not include it (decisions.md:368).
     // Labels are yours to choose; set false if they are internal names your callers shouldn't see.
     if (opts.exposeKeyLabel !== undefined && typeof opts.exposeKeyLabel !== 'boolean') {
       throw new TypeError(`${BRAND.name}: exposeKeyLabel must be true or false`);
@@ -578,7 +581,9 @@ class Ordainer {
         result = await this._call(base, { key, tool, idem, requestedMode, effectiveFailMode, effectiveBillingLapse, timeoutMs });
         result.attempts = attempt;
         if (!result.retryable || attempt >= maxAttempts) break;
-        const pause = RETRY_DELAY_MS * 2 ** (attempt - 1);
+        // P89-L1: jittered, so callers shed at the same moment (503 at capacity) don't all retry in one wave.
+        // Whole ms: the next attempt's timeout is cut to the time left, and AbortSignal.timeout() takes integers only.
+        const pause = Math.round(RETRY_DELAY_MS * 2 ** (attempt - 1) * (0.5 + this._random()));
         const left = budgetEnd - Date.now() - pause;
         if (left < MIN_ATTEMPT_MS) break; // out of budget: failMode applies now
         timeoutMs = Math.min(this.timeoutMs, left);
@@ -709,6 +714,7 @@ class Ordainer {
       limit: json.limit,
       resetsAt: json.resets_at,
       requestId: json.request_id,
+      ...(typeof json.explanation === 'string' ? { explanation: json.explanation } : {}),
       mode: effectiveMode,
       wouldDeny,
       // T18-P39: the server sends the key's label on denies only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ordainer",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "Ask Ordainer before your tool runs: one decide() call checks the caller's plan and counts the use.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -29,7 +29,7 @@
     "middleware",
     "express"
   ],
-  "homepage": "https://ordainer.dev",
+  "homepage": "https://docs.ordainer.dev",
   "bugs": {
     "email": "support@ordainer.ai"
   },