@north-light/cli 0.3.414 → 0.3.416

package/dist/daemon/reconcilers/cron-lane.js

@@ -1 +1 @@
-var l=Object.defineProperty;var t=(c,r)=>l(c,"name",{value:r,configurable:!0});import{emitEvent as i}from"../../core/events/emit.js";import{operationIdContext as n}from"../../core/events/operation-id.js";import{recoverStaleCronLeases as a,runDueCrons as s}from"../cron-run.js";class h{static{t(this,"CronLaneReconciler")}run(r,o){if(n.fresh(()=>{try{a(r,{register:t(e=>o.lifecycle.registerDetached(e),"register")})}catch(e){i({level:"error",event:"cron.lease_recovery.failed",error:e})}}),!!o.lifecycle.acceptsDetachedWork())try{s(r,{register:t(e=>o.lifecycle.registerDetached(e),"register")})}catch(e){i({level:"error",event:"cron.run.failed",error:e})}}}export{h as CronLaneReconciler};
+var i=Object.defineProperty;var o=(c,r)=>i(c,"name",{value:r,configurable:!0});import{emitEvent as t}from"../../core/events/emit.js";import{operationIdContext as a}from"../../core/events/operation-id.js";import{sweepOrphanCronFolders as n}from"../cron/folders.js";import{reapRebuiltCronExecutions as s}from"../cron/run-socket.js";import{recoverStaleCronLeases as f,runDueCrons as p}from"../cron-run.js";class C{static{o(this,"CronLaneReconciler")}lastFolderSweep=0;run(r,l){a.fresh(()=>{try{f(r,{register:o(e=>l.lifecycle.registerDetached(e),"register")})}catch(e){t({level:"error",event:"cron.lease_recovery.failed",error:e})}});try{s()}catch(e){t({level:"error",event:"cron.execution.reap_failed",error:e})}if(r-this.lastFolderSweep>=6e4){this.lastFolderSweep=r;try{n()}catch(e){t({level:"error",event:"cron.folder.sweep_failed",error:e})}}if(l.lifecycle.acceptsDetachedWork())try{p(r,{register:o(e=>l.lifecycle.registerDetached(e),"register")})}catch(e){t({level:"error",event:"cron.run.failed",error:e})}}}export{C as CronLaneReconciler};

package/dist/shared/env.d.ts

@@ -1,12 +1,13 @@
 /** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
 export declare function envNodeId(): string | undefined;
 /** Find the single launch snapshot mounted by the launcher into this process's
- * Linux namespace. Cron bash has no CRTR_NODE_ID, but its creator's mounted
- * launch snapshot supplies config and granted-command projection without
- * claiming the cron is a node. Its broker relay may already have closed when
- * the cron fires; still classify the sandbox so CLI bootstrap never falls back
- * to host stores or person authority. Neither CRTR_NODE_ID, CRTR_ANCHOR, nor
+ * Linux namespace. Cron bash has no CRTR_NODE_ID: its own execution folder
+ * (`cron-<execution_id>`, holding `cron-launch.json` and the execution socket)
+ * supplies config and granted-command projection without claiming the cron is
+ * a node, and never falls back to host stores or person authority. Neither CRTR_NODE_ID, CRTR_ANCHOR, nor
  * the caller-editable CRTR_API_SOCKET selects the launch identity. */
+/** The launch snapshot a mounted run folder carries: a node's `broker-launch.json`, or a cron execution's `cron-launch.json`. */
+export declare function launchSnapshotFile(dir: string): string | undefined;
 export declare function sandboxCliNodeId(): string | undefined;
 /** A Linux app command uses its mounted launch snapshot, not host user stores. */
 export declare function isSandboxedNode(): boolean;

package/dist/shared/env.js

@@ -1,2 +1,2 @@
-var _=Object.defineProperty;var e=(n,r)=>_(n,"name",{value:r,configurable:!0});import{lstatSync as R,readFileSync as p,readdirSync as T}from"node:fs";import{join as i}from"node:path";import{covers as E}from"@north-light/identity";function U(){return process.env.CRTR_NODE_ID}e(U,"envNodeId");function d(){if(process.platform==="linux")try{const n="/run/crtr/nodes",r=new Set(p("/proc/self/mountinfo","utf8").split(`
-`).map(s=>s.split(" ")[4])),t=T(n,{withFileTypes:!0}).filter(s=>s.isDirectory()&&/^[a-zA-Z0-9][a-zA-Z0-9-]{0,127}$/.test(s.name)&&r.has(i(n,s.name))&&R(i(n,s.name,"broker-launch.json"),{throwIfNoEntry:!1})?.isFile());return t.length===1?t[0].name:void 0}catch{return}}e(d,"sandboxCliNodeId");function L(){return d()!==void 0}e(L,"isSandboxedNode");function P(){return process.env.CRTR_GRANTEE}e(P,"envGrantee");const f="CRTR_INBOX_BETWEEN_TURNS";function W(){return process.env[f]==="1"}e(W,"envInboxBetweenTurns");function F(){const n=process.env.CRTR_SCOPES;return n===void 0?null:n===""?[]:n.split(",")}e(F,"envScopes");function H(n,r){return n==null?!0:n.some(t=>E(t,r))}e(H,"scopeAllowed");function G(){return process.env.CRTR_EXECUTION_ID}e(G,"envExecutionId");function K(){return process.env.CRTR_PROFILE_ID}e(K,"envProfileId");function h(){return process.env.CRTR_NODE_CWD}e(h,"envNodeCwd");function b(){return process.env.CRTR_MODEL_INTENT}e(b,"envModelIntent");function k(){return process.env.CRTR_MODEL_EXACT==="1"}e(k,"envModelExact");function g(){return process.env.CRTR_HOME}e(g,"envHomeOverride");function V(){return process.env.CRTR_RUNTIME_HOME}e(V,"envRuntimeHomeOverride");function o(n,r){if(n===void 0)return r;const t=Number(n);return Number.isFinite(t)&&t>0?t:r}e(o,"parsePositiveMs");const v=5*6e4;function w(){return o(process.env.CRTR_STREAM_WATCHDOG_MS,v)}e(w,"envStreamWatchdogMs");const C=800;function y(){return o(process.env.CRTR_WATCHER_TICK_MS,C)}e(y,"envWatcherTickMs");const A=6e4;function X(){return o(process.env.CRTR_WATCHER_BACKSTOP_MS,A)}e(X,"envWatcherBackstopMs");const a=1e3;function Y(){return o(process.env.CRTR_WATCHER_DEBOUNCE_MS,a)}e(Y,"envWatcherDebounceMs");const M=6e4;function j(){return o(process.env.CRTR_RECAP_IDLE_MS,M)}e(j,"envRecapIdleMs");function z(){const n=process.env.CRTR_RECAP_MODEL;return n!==void 0&&n.trim()!==""?n.trim():void 0}e(z,"envRecapModelOverride");const S=300*1e3;function Z(){return o(process.env.CRTR_BASH_VALVE_MS,S)}e(Z,"envBashValveMs");const N=60*1e3;function $(){return o(process.env.CRTR_BASH_AUTO_BG_DEADLINE_MS,N)}e($,"envBashAutoBgDeadlineMs");function q(){const n=process.env.CRTR_PIDFILE;return n!==void 0&&n!==""?n:void 0}e(q,"envPidfileOverride");const x="@earendil-works/pi-coding-agent";function J(){return process.env.CRTR_BROKER_ENGINE??x}e(J,"envBrokerEngine");function Q(){return process.env.CRTR_PI_BINARY}e(Q,"envPiBinaryOverride");function ee(){return process.env.CRTR_NO_DAEMON_AUTOSTART==="1"}e(ee,"envNoDaemonAutostart");function ne(){return process.env.CRTRD_TCP}e(ne,"envCrtrdTcp");function re(){const n=process.env.CRTRD_TOKEN;return n!==void 0&&n!==""?n:void 0}e(re,"envCrtrdToken");function te(){return process.env.CRTR_NO_EXPORTS==="1"}e(te,"envNoExports");function oe(){return process.env.CRTR_DEBUG==="1"}e(oe,"envDebug");function c(n){if(n===void 0||n==="")return;const r=Number(n);return Number.isSafeInteger(r)&&r>=1?r:void 0}e(c,"parsePositiveInteger");function se(){return c(process.env.CRTR_MAX_LIVE_BROKERS)}e(se,"envMaxLiveBrokers");function ue(){return c(process.env.CRTR_WARN_LIVE_BROKERS)}e(ue,"envWarnLiveBrokers");function u(n){if(n===void 0)return;const r=Number(n);return Number.isFinite(r)&&r>0?r:void 0}e(u,"parsePositiveMsNoDefault");function ie(){return u(process.env.CRTR_TEST_UNATTENDED_PARK_MS)}e(ie,"envTestUnattendedParkMs");function ce(){return u(process.env.CRTR_UNATTENDED_PARK_MS)}e(ce,"envUnattendedParkMs");function D(){return u(process.env.CRTR_TEST_PARK_SUMMARY_GRACE_MS)}e(D,"envTestParkSummaryGraceMs");const O=5*6e4;function _e(){return D()??O}e(_e,"parkSummaryGraceMs");export{f as INBOX_BETWEEN_TURNS_ENV,$ as envBashAutoBgDeadlineMs,Z as envBashValveMs,J as envBrokerEngine,ne as envCrtrdTcp,re as envCrtrdToken,oe as envDebug,G as envExecutionId,P as envGrantee,g as envHomeOverride,W as envInboxBetweenTurns,se as envMaxLiveBrokers,k as envModelExact,b as envModelIntent,ee as envNoDaemonAutostart,te as envNoExports,h as envNodeCwd,U as envNodeId,Q as envPiBinaryOverride,q as envPidfileOverride,K as envProfileId,j as envRecapIdleMs,z as envRecapModelOverride,V as envRuntimeHomeOverride,F as envScopes,w as envStreamWatchdogMs,D as envTestParkSummaryGraceMs,ie as envTestUnattendedParkMs,ce as envUnattendedParkMs,ue as envWarnLiveBrokers,X as envWatcherBackstopMs,Y as envWatcherDebounceMs,y as envWatcherTickMs,L as isSandboxedNode,_e as parkSummaryGraceMs,d as sandboxCliNodeId,H as scopeAllowed};
+var _=Object.defineProperty;var e=(n,r)=>_(n,"name",{value:r,configurable:!0});import{lstatSync as R,readFileSync as p,readdirSync as T}from"node:fs";import{join as u}from"node:path";import{covers as E}from"@north-light/identity";function L(){return process.env.CRTR_NODE_ID}e(L,"envNodeId");function f(n){for(const r of["broker-launch.json","cron-launch.json"]){const t=u(n,r);if(R(t,{throwIfNoEntry:!1})?.isFile())return t}}e(f,"launchSnapshotFile");function d(){if(process.platform==="linux")try{const n="/run/crtr/nodes",r=new Set(p("/proc/self/mountinfo","utf8").split(`
+`).map(s=>s.split(" ")[4])),t=T(n,{withFileTypes:!0}).filter(s=>s.isDirectory()&&/^[a-zA-Z0-9][a-zA-Z0-9-]{0,127}$/.test(s.name)&&r.has(u(n,s.name))&&f(u(n,s.name))!==void 0);return t.length===1?t[0].name:void 0}catch{return}}e(d,"sandboxCliNodeId");function P(){return d()!==void 0}e(P,"isSandboxedNode");function F(){return process.env.CRTR_GRANTEE}e(F,"envGrantee");const v="CRTR_INBOX_BETWEEN_TURNS";function W(){return process.env[v]==="1"}e(W,"envInboxBetweenTurns");function h(){const n=process.env.CRTR_SCOPES;return n===void 0?null:n===""?[]:n.split(",")}e(h,"envScopes");function H(n,r){return n==null?!0:n.some(t=>E(t,r))}e(H,"scopeAllowed");function G(){return process.env.CRTR_EXECUTION_ID}e(G,"envExecutionId");function K(){return process.env.CRTR_PROFILE_ID}e(K,"envProfileId");function b(){return process.env.CRTR_NODE_CWD}e(b,"envNodeCwd");function k(){return process.env.CRTR_MODEL_INTENT}e(k,"envModelIntent");function g(){return process.env.CRTR_MODEL_EXACT==="1"}e(g,"envModelExact");function V(){return process.env.CRTR_HOME}e(V,"envHomeOverride");function w(){return process.env.CRTR_RUNTIME_HOME}e(w,"envRuntimeHomeOverride");function o(n,r){if(n===void 0)return r;const t=Number(n);return Number.isFinite(t)&&t>0?t:r}e(o,"parsePositiveMs");const C=5*6e4;function y(){return o(process.env.CRTR_STREAM_WATCHDOG_MS,C)}e(y,"envStreamWatchdogMs");const A=800;function X(){return o(process.env.CRTR_WATCHER_TICK_MS,A)}e(X,"envWatcherTickMs");const a=6e4;function j(){return o(process.env.CRTR_WATCHER_BACKSTOP_MS,a)}e(j,"envWatcherBackstopMs");const M=1e3;function Y(){return o(process.env.CRTR_WATCHER_DEBOUNCE_MS,M)}e(Y,"envWatcherDebounceMs");const S=6e4;function z(){return o(process.env.CRTR_RECAP_IDLE_MS,S)}e(z,"envRecapIdleMs");function Z(){const n=process.env.CRTR_RECAP_MODEL;return n!==void 0&&n.trim()!==""?n.trim():void 0}e(Z,"envRecapModelOverride");const x=300*1e3;function $(){return o(process.env.CRTR_BASH_VALVE_MS,x)}e($,"envBashValveMs");const N=60*1e3;function q(){return o(process.env.CRTR_BASH_AUTO_BG_DEADLINE_MS,N)}e(q,"envBashAutoBgDeadlineMs");function J(){const n=process.env.CRTR_PIDFILE;return n!==void 0&&n!==""?n:void 0}e(J,"envPidfileOverride");const D="@earendil-works/pi-coding-agent";function Q(){return process.env.CRTR_BROKER_ENGINE??D}e(Q,"envBrokerEngine");function ee(){return process.env.CRTR_PI_BINARY}e(ee,"envPiBinaryOverride");function ne(){return process.env.CRTR_NO_DAEMON_AUTOSTART==="1"}e(ne,"envNoDaemonAutostart");function re(){return process.env.CRTRD_TCP}e(re,"envCrtrdTcp");function te(){const n=process.env.CRTRD_TOKEN;return n!==void 0&&n!==""?n:void 0}e(te,"envCrtrdToken");function oe(){return process.env.CRTR_NO_EXPORTS==="1"}e(oe,"envNoExports");function se(){return process.env.CRTR_DEBUG==="1"}e(se,"envDebug");function c(n){if(n===void 0||n==="")return;const r=Number(n);return Number.isSafeInteger(r)&&r>=1?r:void 0}e(c,"parsePositiveInteger");function ue(){return c(process.env.CRTR_MAX_LIVE_BROKERS)}e(ue,"envMaxLiveBrokers");function ie(){return c(process.env.CRTR_WARN_LIVE_BROKERS)}e(ie,"envWarnLiveBrokers");function i(n){if(n===void 0)return;const r=Number(n);return Number.isFinite(r)&&r>0?r:void 0}e(i,"parsePositiveMsNoDefault");function ce(){return i(process.env.CRTR_TEST_UNATTENDED_PARK_MS)}e(ce,"envTestUnattendedParkMs");function _e(){return i(process.env.CRTR_UNATTENDED_PARK_MS)}e(_e,"envUnattendedParkMs");function O(){return i(process.env.CRTR_TEST_PARK_SUMMARY_GRACE_MS)}e(O,"envTestParkSummaryGraceMs");const m=5*6e4;function Re(){return O()??m}e(Re,"parkSummaryGraceMs");export{v as INBOX_BETWEEN_TURNS_ENV,q as envBashAutoBgDeadlineMs,$ as envBashValveMs,Q as envBrokerEngine,re as envCrtrdTcp,te as envCrtrdToken,se as envDebug,G as envExecutionId,F as envGrantee,V as envHomeOverride,W as envInboxBetweenTurns,ue as envMaxLiveBrokers,g as envModelExact,k as envModelIntent,ne as envNoDaemonAutostart,oe as envNoExports,b as envNodeCwd,L as envNodeId,ee as envPiBinaryOverride,J as envPidfileOverride,K as envProfileId,z as envRecapIdleMs,Z as envRecapModelOverride,w as envRuntimeHomeOverride,h as envScopes,y as envStreamWatchdogMs,O as envTestParkSummaryGraceMs,ce as envTestUnattendedParkMs,_e as envUnattendedParkMs,ie as envWarnLiveBrokers,j as envWatcherBackstopMs,Y as envWatcherDebounceMs,X as envWatcherTickMs,P as isSandboxedNode,f as launchSnapshotFile,Re as parkSummaryGraceMs,d as sandboxCliNodeId,H as scopeAllowed};

package/docs/sdk/README.md

@@ -26,20 +26,38 @@ if (run.kind === 'result') console.log(run.output_parsed.root_cause);
 
 ## Go live with an app key
 
-Once you have installed the SDK and tried the local flow in [Getting started](./getting-started.md), generate the app's key on your server:
+Once you have installed the SDK and tried the local flow in [Getting started](./getting-started.md), register the app with `crtr cloud apps register` (or the console), then generate its key and pull its settings on your server:
 
 ```bash
 npx @north-light/sdk keygen --app <client id>
+npx @north-light/sdk env --app <client id>
 ```
 
-`keygen` saves the private JWK to `local/app-key.json` (mode `0600`); keep that file out of git. With `--app`, it offers to add the public key to your registered app through your own `crtr`, as an additional key that never replaces the current one. Otherwise, click **Add key** on the app's **Sign-in** tab and paste the public JWK printed on stdout (or paste it under **Register an app** for a new app). An app authenticates only with its key; the directory issues no client secret. On your server, load the saved key and pass it as `privateKey`:
+`keygen` saves the private JWK to `local/app-key.json` (mode `0600`); keep that file out of git. With `--app`, it offers to add the public key to your registered app through your own `crtr`, as an additional key that never replaces the current one. Otherwise, click **Add key** on the app's **Sign-in** tab and paste the public JWK printed on stdout (or paste it under **Register an app** for a new app). An app authenticates only with its key; the directory issues no client secret.
+
+`env` reads the registration through `crtr cloud apps get` and writes `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` into `local/app.env` (`--out` picks another file), keeping every other line. Both commands need this machine's `crtr` joined to your crouter cloud account; on a machine that isn't, they print the join step and exit 2. An app is configured from four variables:
+
+| Variable | Value |
+|---|---|
+| `CROUTER_ISSUER` | The directory's issuer URL |
+| `CROUTER_CLIENT_ID` | The app's client id |
+| `APP_ORIGIN` | The app's origin; its redirect URI is `${APP_ORIGIN}/auth/callback` by convention |
+| `CROUTER_KEY_FILE` | Path to the private JWK, default `local/app-key.json`. `env` never writes it |
+
+The SDK reads no environment itself: load the values in your own config and pass them to `OAuth2Client`.
 
 ```ts
 import {readFile} from 'node:fs/promises';
 import {OAuth2Client} from '@north-light/sdk';
 
-const privateKey = JSON.parse(await readFile('local/app-key.json', 'utf8'));
-const oauth = new OAuth2Client({clientId, issuer, redirectUri, privateKey, store}); // store: your ConnectionStore
+const privateKey = JSON.parse(await readFile(process.env.CROUTER_KEY_FILE ?? 'local/app-key.json', 'utf8'));
+const oauth = new OAuth2Client({
+  clientId: process.env.CROUTER_CLIENT_ID!,
+  issuer: process.env.CROUTER_ISSUER!,
+  redirectUri: `${process.env.APP_ORIGIN}/auth/callback`,
+  privateKey,
+  store, // your ConnectionStore
+});
 const {url, state, codeVerifier, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'crtr:llm', 'crtr:act'], state: sessionState});
 // Save state, codeVerifier, nonce in the user's session, then redirect to url.
 const connection = await oauth.exchangeCode({code: callbackCode, state: callbackState, expectedState: state, codeVerifier, nonce});

package/docs/sdk/client.md

@@ -199,6 +199,20 @@ await watcher.stop();
 - **`stop()`** stops sweeping, aborts every open read, and resolves once every turn has ended; no handler starts afterwards.
 - **One person, one request.** Without the watcher, `runtime.grant.get({wait: 25, since: grant.version})` holds a single read the same way; the request timeout is extended by `wait`. `wait` outside integer 1–25 throws `RangeError` before sending.
 
+### Show what a person's month has cost
+
+A person's grant caps what your app may spend of their AI subscription each UTC month (`grant.spend_cap`; crouter cloud sets $50). `usage.get()` answers where the month stands:
+
+```ts
+const usage = await runtime.usage.get(); // or {month: '2026-09'}
+// {grantee, month, usd_equivalent, by_model, app_paid, spend_cap, reset_at}
+```
+
+- **`usd_equivalent`** is user-paid spend at list price: model completions and provider receipts. Receipts have no `by_model` row, so it can exceed the sum of `by_model`. A model with no list price reports `usd_equivalent: null` on its row and adds nothing.
+- **`app_paid`** is usage your app pays for. It never counts toward `spend_cap`.
+- **At the cap.** Once `usd_equivalent` reaches `spend_cap`, user-paid model and provider calls answer 402 `cap_exhausted` (a `RateLimitError` with `retryable: false`, `userAction: 'raise_cap'` and `resetAt`) until `reset_at`, the first instant of the next UTC month. A run whose model call is refused ends with outcome reason `cap_exhausted`. The check runs before each call, so the call that crosses the cap completes and the next one is refused. Do not retry; tell the person when the count resets.
+- `spend_cap: null` means the grant is not capped.
+
 ### Link to the app's settings on crouter cloud
 
 Each person who uses your app has a page on their crouter cloud account where they change or remove what the app may do. Link to it with the URL the directory advertises; never compose the path yourself:
@@ -209,7 +223,7 @@ const href = await oauth.accountAppUrl(); // e.g. https://<directory>/account/ap
 
 - **What it is.** The discovery document's `account_app_uri_template` with its one `{client_id}` replaced by your encoded client id. It is the same URL for every person: the directory shows whoever is signed in to it their own page for your app (and sends someone without a directory session through sign-in first). Someone without an active grant, a sign-in-only visitor for one, sees that the app is not connected to their account.
 - **What it needs.** No user and no connection, so it serves owners and visitors alike. Its only request is the discovery read that `authorizeUrl`, `verifyIdToken` and `revoke` share.
-- **Errors.** Each is a `CrouterError` (code `crouter_error`) whose message names the fault: the directory advertises no `account_app_uri_template`, the template does not contain `{client_id}` exactly once, or the expansion is not a URL on the issuer's origin. A discovery read that fails throws `Directory discovery failed: <status>` or the fetch error; one that takes longer than 10 seconds throws the timeout. A failed or timed-out read is not kept, so the next call reads again; a successful one is kept for the client's life, so a template the directory changes reaches your app at its next start.
+- **Errors.** Each is a `CrouterError` (code `crouter_error`) whose message names the fault: the directory advertises no `account_app_uri_template`, the template does not contain `{client_id}` exactly once, the expansion is not a URL on the issuer's origin, or an endpoint field of the discovery document (`authorization_endpoint`, `token_endpoint`, `jwks_uri`, `revocation_endpoint`) is not an absolute https URL (`http:` when the issuer is `http:`) or `token_endpoint_auth_methods_supported` is not an array of strings. A discovery read that fails throws `Directory discovery failed: <status>` or the fetch error; one that takes longer than `timeoutMs` (default 10 seconds) throws `DeadlineExceededError`. A failed or timed-out read is not kept, so the next call reads again; a successful one is kept for the client's life, so a template the directory changes reaches your app at its next start.
 - **Warm it at startup and bound it on page loads.** Call `void oauth.accountAppUrl().catch(log)` when the process starts, so the discovery read is usually done before the first page needs it. A page that must not wait on the directory races it against a short timer (a couple of seconds, under the SDK's 10 s) and hides the link when the race is lost; the read keeps running and a later page load reuses its result.
 
 ### Testing your app
@@ -276,10 +290,27 @@ await client.nodes.retrieve(id, {
 | `signal` | `AbortSignal` | Aborts the underlying `fetch`. Raises `APIUserAbortError`. |
 | `timeout` | `number` (ms) | Overrides the client `timeout`. |
 | `maxRetries` | `number` | Overrides the client `maxRetries`. |
+| `budgetMs` | `number` (ms) | One overall deadline for the call, from now. It covers every attempt, every retry wait (a server's `Retry-After` too) and the response body; `timeout` still bounds each attempt but never past it. See [One deadline per call](#one-deadline-per-call). |
+| `deadlineAt` | `number` (epoch ms) | The same deadline as an absolute instant, for passing one deadline to several calls. With `budgetMs` too, the earlier wins. |
 | `headers` | `Record<string, string>` | Merged over `defaultHeaders`, client `headers`, and the token-generated header; a matching name, including `Authorization`, wins. |
 
 `signal` is real cancellation. The long-polling helpers (`waitForOutcome`, `createAndWait`, `parse`) honour it between polls and during the in-flight request, and aborting them stops the client — it does not cancel the node. To stop the run itself, call `client.nodes.cancel(id)` or `client.nodes.interrupt(id)`. Streams use `NodeEventsOptions`: the same fields except `timeout`, plus `after` for `nodes.events`; see [Streaming](./streaming.md).
 
+### One deadline per call
+
+Without `budgetMs`/`deadlineAt` a call has one `timeout` per attempt, so a keyed send (`runs.start`, `runs.message`) that is retried twice can take three timeouts plus the waits between them, and a server's `retry_after_s: 120` is waited out in full. Give the call a deadline and its total time is bounded:
+
+```ts
+await client.runs.message(runId, text, { budgetMs: 20_000 });
+```
+
+- The deadline is fixed once, when the call starts, and every attempt, every backoff, every `retry_after_s`/`Retry-After` wait, the token fetch and the refresh after a 401 share it. The call rejects at the deadline (plus the scheduling of one timer) whether the time goes to the headers, the body, a retry wait or the token hook, even when your `fetch` ignores its `AbortSignal`. The compound helpers (`runs.wait`, `runs.parse`, `nodes.waitForOutcome`, `nodes.createAndWait`, `nodes.parse`) fix one deadline for the whole helper, not one per poll.
+- A retry wait that would reach the deadline is not slept: the call rejects at once with `DeadlineExceededError` (`code: 'deadline_exceeded'`, status 504). `reason` is `'retry_after'` when the server asked for a wait longer than the time left (`retryAfterRequestS` is that request), and `'elapsed'` when time simply ran out; `deadlineAt` is the instant, and `cause` is the last refusal.
+- A stream (`nodes.stream`, `nodes.events`): `budgetMs` / `deadlineAt` bound opening it (the create or retrieve, the token hook and the connection); once open it lives until it ends or its `signal` aborts.
+- `budgetMs` and `deadlineAt` must fit a timer: at most 2,147,483,647 ms (about 24.8 days) from now, or the call throws `RangeError`.
+- **Holding a lease while you call.** An app that takes a lease or lock for an SDK call sets `budgetMs` and keeps the lease longer than it, with margin, so the call has ended or been abandoned before the lease can be taken over: `LEASE_MS >= BUDGET_MS + MARGIN_MS`. State that inequality next to the constants (or assert it at module load) rather than renewing the lease while a call is unbounded.
+- `OAuth2Client` gives each directory operation (discovery, a code exchange or refresh, a revocation, the JWKS read behind `verifyIdToken`) the same kind of deadline, `OAuth2Options.timeoutMs` (default 10 s). A refresh runs under the user's store lock, so the lock is held no longer than `timeoutMs` plus the store's own time.
+
 ## What is not on the client
 
 | Convention | Why it is absent |

package/docs/sdk/errors.md

@@ -32,6 +32,7 @@ Every class below extends `APIError`, which carries `status`, `code`, `message`,
 | HTTP 409 | `ConflictError` |
 | HTTP 413, 422 | `UnprocessableEntityError` |
 | HTTP 429 | `RateLimitError` |
+| Code `deadline_exceeded` | `DeadlineExceededError` (extends `APIConnectionTimeoutError`; status 504; `reason` `elapsed` or `retry_after`, `deadlineAt`, `cause`) |
 | HTTP 504 or code `request_timeout` | `APIConnectionTimeoutError` (extends `APIConnectionError`) |
 | Other HTTP ≥ 500 | `InternalServerError` |
 | Code `daemon_unavailable`, `transport_error`, `daemon_request_interrupted`, or `daemon_health_unavailable`; or a non-API transport failure | `APIConnectionError` |
@@ -104,6 +105,8 @@ try {
 const outcome = await client.nodes.waitForOutcome(runId);
 ```
 
+A call with `budgetMs` (or `deadlineAt`) has one deadline over all of these attempts and waits, a server's `Retry-After` included: a wait longer than the time left rejects at once with `DeadlineExceededError` instead of sleeping (see [One deadline per call](./client.md#one-deadline-per-call)). Without one, a keyed send honours any `retry_after_s`.
+
 Override the policy per request with `{ maxRetries: 0 }` or `{ maxRetries: 5 }`. Raising it on a `POST` other than `runs.start` and `runs.message` still does not make the client retry that `POST`.
 
 ## In-repo callers

package/docs/sdk/getting-started.md

@@ -172,20 +172,42 @@ An outcome is returned, never thrown — including a decline and a failure. Only
 
 ## Go live with an app key
 
-Register your app in the directory console, then generate its signing key on your app server:
+Register your app with `crtr cloud apps register` (or in the directory console), then generate its signing key and pull its settings on your app server:
 
 ```bash
 npx @north-light/sdk keygen --app <client id>
+npx @north-light/sdk env --app <client id>
 ```
 
-This creates `local/app-key.json` with mode `0600` (keep it out of git) and prints the public JWK on stdout. With `--app`, `keygen` offers to add that public key to your app through your own `crtr` (`crtr cloud apps keys add`). It asks first and `--yes` skips the question; with no terminal to ask on (CI, piped input) and no `--yes`, it adds nothing. The upload only ever adds a key: it never replaces or retires the key your app already has. If `crtr` isn't installed or the add fails, `keygen` says why and prints the manual steps instead: click **Add key** on your app's **Sign-in** tab and paste the public JWK, or paste it under **Register an app** for a new app. An app authenticates only with its key: the directory issues no client secret. Use the saved private JWK for the OAuth connect flow:
+`keygen` creates `local/app-key.json` with mode `0600` (keep it out of git) and prints the public JWK on stdout. With `--app`, `keygen` offers to add that public key to your app through your own `crtr` (`crtr cloud apps keys add`). It asks first and `--yes` skips the question; with no terminal to ask on (CI, piped input) and no `--yes`, it adds nothing. The upload only ever adds a key: it never replaces or retires the key your app already has. If `crtr` isn't installed or the add fails, `keygen` says why and prints the manual steps instead: click **Add key** on your app's **Sign-in** tab and paste the public JWK, or paste it under **Register an app** for a new app. An app authenticates only with its key: the directory issues no client secret.
+
+`env` runs `crtr cloud apps get --app-id <client id>` and writes `CROUTER_ISSUER`, `CROUTER_CLIENT_ID`, and `APP_ORIGIN` into `local/app.env` (`--out <path>` writes another file). It updates those three lines in place, keeps every other line and comment, and creates the file with mode `0600` when it doesn't exist. It never writes `CROUTER_KEY_FILE` or anything secret. It prints the values it set and the key file your app will read.
+
+Both commands reach your app through this machine's `crtr`, so the machine must be joined to your crouter cloud account. On one that isn't, they say so, print the join step (create a join token on `/account/machines`, then `crtr sys join`), and exit 2.
+
+An app built on the SDK is configured from four variables:
+
+| Variable | Value | Where it comes from |
+|---|---|---|
+| `CROUTER_ISSUER` | The directory's issuer URL | `env` |
+| `CROUTER_CLIENT_ID` | The app's client id | `env` |
+| `APP_ORIGIN` | The app's origin. Its redirect URI is `${APP_ORIGIN}/auth/callback` by convention | `env` (the registration's origin) |
+| `CROUTER_KEY_FILE` | Path to the private JWK, default `local/app-key.json` | You; it differs per deployment (a container might read `/run/secrets/app_key`) |
+
+The SDK reads no environment and has no `fromEnv` helper: your app loads the values and passes them to `OAuth2Client`:
 
 ```ts
 import {readFile} from 'node:fs/promises';
 import {OAuth2Client} from '@north-light/sdk';
 
-const privateKey = JSON.parse(await readFile('local/app-key.json', 'utf8'));
-const oauth = new OAuth2Client({clientId, issuer, redirectUri, privateKey, store}); // store: your ConnectionStore
+const config = {
+  issuer: process.env.CROUTER_ISSUER!,
+  clientId: process.env.CROUTER_CLIENT_ID!,
+  origin: process.env.APP_ORIGIN!,
+  keyFile: process.env.CROUTER_KEY_FILE ?? 'local/app-key.json',
+};
+const privateKey = JSON.parse(await readFile(config.keyFile, 'utf8'));
+const oauth = new OAuth2Client({clientId: config.clientId, issuer: config.issuer, redirectUri: `${config.origin}/auth/callback`, privateKey, store}); // store: your ConnectionStore
 const {url, codeVerifier, state, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'crtr:llm', 'crtr:act'], state: sessionState});
 // Save codeVerifier, state, nonce in the user's session; redirect them to url.
 const connection = await oauth.exchangeCode({code: callbackCode, codeVerifier, state: callbackState, expectedState: state, nonce});

package/docs/sdk/release-notes.md

@@ -7,6 +7,29 @@ description: Behavior changes in @north-light/sdk that an app must act on, newes
 
 Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
 
+## 0.3.415
+
+### Monthly spend cap enforced; `usage.get` (additive; one behavior change)
+
+- **Behavior change:** user-paid model calls (`/v1/llm`) and provider calls now count against the grant's `spend_cap` (from `grant.get()`; crouter cloud sets $50) for the current UTC month. Once the month reaches it, the next call answers 402 `cap_exhausted` (a `RateLimitError`, `retryable: false`, `userAction: 'raise_cap'`, `resetAt` the first instant of next month) before any model or provider is called. A run whose model call is refused this way ends with outcome reason `cap_exhausted`. The check runs before each call, so the call that crosses the cap still completes. App-paid usage never counts. A grant with `spend_cap: null` is not capped.
+- New `client.usage.get({month?})` (`month` is `YYYY-MM`, UTC; default the current month) answers `SpendUsageDTO`: `usd_equivalent` (user-paid spend, provider receipts included), `by_model`, `app_paid`, `spend_cap` and `reset_at`. See [Show what a person's month has cost](./client.md#show-what-a-persons-month-has-cost).
+- A completion's `usage.usd_equivalent` is now the served model's list-price cost; before it was always `null`. It stays `null` for a model with no list price, and that usage adds nothing to the month.
+
+### `npx @north-light/sdk env` (additive); keygen on an unjoined machine exits 2
+
+- New `npx @north-light/sdk env --app <client id> [--out <path>]` writes `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` from `crtr cloud apps get` into `local/app.env`, keeping every other line. See [Go live with an app key](./getting-started.md#go-live-with-an-app-key).
+- `keygen --app` on a machine whose `crtr` isn't joined to a crouter cloud account now prints the join step and the manual steps and exits 2. A missing `crtr` keeps its message and exit 0.
+
+### One deadline per SDK call, and a deadline on every OAuth/JWKS fetch (additive, with one behaviour change)
+
+Not breaking: no type or wire shape an app reads is removed or changed. Apps pinned to the previous release keep working unchanged.
+
+- `RequestOptions` gains `budgetMs` and `deadlineAt`: one absolute deadline for the call covering every attempt, every retry wait (including a `Retry-After`) and the token fetch/refresh. A wait that would pass the deadline rejects at once with the new `DeadlineExceededError` (`code: 'deadline_exceeded'`, `reason: 'elapsed' | 'retry_after'`, `deadlineAt`, `cause`), which extends `APIConnectionTimeoutError`, so code catching that still catches it. A transport that ignores its `AbortSignal` can no longer outlive the deadline. Without `budgetMs`/`deadlineAt` nothing about retries changes. See [One deadline per call](./client.md#one-deadline-per-call).
+- An app that holds a lease or lock while it makes an SDK call should pass `budgetMs` and keep the lease longer than it, with margin, and state that in code.
+- `OAuth2Options.timeoutMs` (default 10 s): one deadline per directory operation (discovery, token exchange, refresh, revoke, `runtime_provisioning` retries and their `retry_after_s`). A refresh under the connection-store lock now holds the lock at most `timeoutMs`. `JwksCache` (and so `verifyIdToken`) takes `{timeoutMs}` (default 10 s) over its discovery and key-set reads together.
+- **Behaviour change:** these directory fetches used to have no deadline (only discovery had one). A directory that takes longer than 10 s now fails with `DeadlineExceededError` where it used to wait; set `timeoutMs` to change it.
+- `OAuth2Client` validates the discovery document: `authorization_endpoint`, `token_endpoint`, `jwks_uri` (and `revocation_endpoint`, when present) must be absolute https URLs (`http:` when the issuer is `http:`), and `token_endpoint_auth_methods_supported` an array of strings. A wrong type is a `CrouterError` naming the field instead of a later `TypeError`.
+
 ## 0.3.409
 
 ### `@north-light/sdk/testing`: isolated runs start, `FakeCall.runId`, one `runs` shape (one breaking change)

package/docs/sdk/testing.md

@@ -32,7 +32,11 @@ const client = await oauth.client('user:o1');               // first call refres
 
 `cloud.crouter(userId)` returns a real `Crouter` on that person's runtime with a fresh token and no refresh. Refusals and refreshes never reach it. Use it only for code whose production signature takes a `Crouter`. Code that goes through `OAuth2Client` in production should go through `oauth.client` in tests too.
 
-Options: `new FakeCloud({clientId, issuer = 'https://directory.test', runtimeUrl = 'https://runtime.test' (or (userId) => url), runtimeId = 'runtime:test', runtimeClientId = 'runtime-client', runtimeVersion?, streamIdleMs = 60000, accountAppUriTemplate = '<issuer>/account/apps/{client_id}' (null omits it), runNotice?, isolatedRuns = 'available'})`.
+Options: `new FakeCloud({clientId, issuer = 'https://directory.test', runtimeUrl = 'https://runtime.test' (or (userId) => url), runtimeId = 'runtime:test', runtimeClientId = 'runtime-client', runtimeVersion?, streamIdleMs = 60000, accountAppUriTemplate = '<issuer>/account/apps/{client_id}' (null omits it), runNotice?, isolatedRuns = 'available', clock = Date.now})`.
+
+`clock` is `{now(): number}`; every timestamp the fake writes reads it (run `created_at` and `settled_at`, grant `exp`, memory `created_at`/`updated_at`, access-token `iat`/`exp`, `calls[].at`, `directoryCalls[].at`) and the idempotency window runs on it. Pass `manualClock()` (from `@north-light/sdk/testing`; `now()`, `advance(ms)`) to step time by hand. Stream idle, long-poll waits and run-notice retries stay on real timers.
+
+`cloud.activate(userId, {scopes?, dependencies?})` makes the grant active with no stored connection, for an app that mints a per-user runtime token itself. The fake directory serves that mint at `POST <issuer>/token` with `grant_type=client_credentials&sub=<userId>` (the client assertion is not verified): 200 `{access_token, token_type: 'Bearer', expires_in: 600, runtimeUrl}` (the token's `exp` claim is 600 s after `iat`; the fake runtime does not enforce token expiry); a missing `sub` is 400 `unauthorized_client`; an unknown or revoked user is 400 `invalid_grant` (`no active grant`); `user.refuse('runtime_provisioning')` is 400 `invalid_grant` with `error_description: runtime_provisioning`. A mint is a `directory.token` call (`userId` is the `sub`), so `failNext('directory.token', …, {user})` applies to it.
 
 ### Isolated runs
 
@@ -71,7 +75,9 @@ What a turn's input is: `reply` and `failTurn` deliver `messageIds` (default: ev
 
 Messages follow the runtime: `start_turn` true makes the run `running` at once and calls the responder; `start_turn` false only records it. A message to a run settled `canceled` or `deadline_exceeded` is refused 409 `run_settled`; to a run settled any other way it reopens the run. A deleted run answers 404.
 
-Idempotency follows the runtime too: the same `Idempotency-Key` with the same body replays the first answer (no new run, no responder call); the same key with a different body, or reused between `run.start` and `run.message`, is 409 `idempotency_conflict`. After a run is deleted, its start key creates a new run.
+Idempotency follows the runtime too: the same `Idempotency-Key` with the same body replays the first answer (no new run, no responder call); the same key with a different body, or reused between `run.start` and `run.message`, is 409 `idempotency_conflict`. After a run is deleted, its start key creates a new run. A key is live for 24 hours (`IDEMPOTENCY_WINDOW_MS`): at exactly the window it reads as absent, and the next accept replaces the record. Step the window with `clock`.
+
+`run.openStreams` counts the run's open event streams. It rises when the SDK starts reading the response body, which is after `cloud.calls` records `run.events`, so poll `openStreams`, not `calls`, to know a stream is attached. It falls on idle, error, abort or revoke. Run notices are owed only while no stream is open.
 
 ## Grants and setup state
 
@@ -158,6 +164,6 @@ Build two app instances (two `OAuth2Client`s) on the same `cloud`. They see the
 
 ## Fidelity
 
-FakeCloud is checked against the real runtime on every crouter release: one set of conformance scenarios runs on the fake and on the real app listener (run start and idempotency, messages, reply streams, long-poll, every settle outcome, delete, the event stream's edges, grant holds, memory, providers, run notices). Two behaviours are fake-only because the runtime cannot be scripted that way: a successful provider call (the real side needs an installed provider), and `setActivity`. An isolated run that starts is checked only against `startRun`'s documented checks: the real listener in the suite runs without the Linux root launcher, so on it the `isolatedRuns: 'unavailable'` refusal is what is conformance-checked.
+FakeCloud is checked against the real runtime on every crouter release: one set of conformance scenarios runs on the fake and on the real app listener (run start and idempotency, messages, reply streams, long-poll, every settle outcome, delete, the event stream's edges, grant holds, memory, providers, run notices). The keyed-write scenarios K1–K8 (equal-key replay, conflict, concurrent equal keys accepted once, the 24h window, replay after cancel, a key bound to its operation, keys scoped to the grantee, concurrent notes) are exported as `@north-light/sdk/testing/conformance` (`keyedWriteScenarios`, `IDEMPOTENCY_WINDOW_MS`) and run on FakeCloud and on the real daemon; an app test double for the runtime should run them against its own target. Two behaviours are fake-only because the runtime cannot be scripted that way: a successful provider call (the real side needs an installed provider), and `setActivity`. An isolated run that starts is checked only against `startRun`'s documented checks: the real listener in the suite runs without the Linux root launcher, so on it the `isolatedRuns: 'unavailable'` refusal is what is conformance-checked.
 
 Not faked: sign-in (`authorizeUrl`, `exchangeCode`, ID tokens — start from `cloud.connect`), token revocation, the owner and local-daemon surface (`nodes`, `canvas`, `crons`, `files`, …), and several apps on one cloud. `trace.get`, `run.rename`, `run.interrupt` and `profile.list` answer the right shape only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.414",
+  "version": "0.3.416",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -134,7 +134,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.414",
+    "@north-light/identity": "0.3.416",
     "@earendil-works/pi-agent-core": "0.99.1",
     "@earendil-works/pi-ai": "0.99.1",
     "@earendil-works/pi-coding-agent": "0.99.1",

package/packages/crouter-identity/dist/index.d.ts

@@ -27,7 +27,31 @@ export type Scope = 'crtr:llm' | 'crtr:act' | 'crtr:schedule' | `crtr:memory:${'
 export declare const ENFORCED: ReadonlySet<string>;
 export declare function parseScope(value: string, grantee?: string): Scope;
 export declare function covers(held: string, requested: string): boolean;
-/** Keys are scoped to one configured issuer; failed refreshes keep the last successful set. */
+/** A directory fetch ran past its deadline (or was aborted by its caller before that). `code` is `deadline_exceeded`;
+ *  `deadlineAt` is the instant (epoch ms) the operation had to finish by. The `@north-light/sdk` maps it to its
+ *  `DeadlineExceededError`. */
+export declare class FetchDeadlineError extends Error {
+    readonly deadlineAt: number;
+    readonly url: string;
+    readonly code = "deadline_exceeded";
+    constructor(deadlineAt: number, url: string);
+}
+/** The default deadline for one `JwksCache.load`, covering its discovery read and its key-set read together. */
+export declare const DEFAULT_JWKS_TIMEOUT_MS = 10000;
+/**
+ * One `fetch` plus the reading of its answer (`read`, e.g. `response.json()`), bounded by one absolute deadline. The
+ * request is aborted when the deadline passes or `signal` fires, and the returned promise rejects at that moment
+ * even when `fetcher` ignores its signal, so a directory that accepts the connection and never answers cannot hold a
+ * caller (or a lock the caller holds) past `deadlineAt`. Rejects `FetchDeadlineError` at the deadline and the signal's
+ * reason when `signal` fired first.
+ */
+export declare function boundedFetch<T>(fetcher: typeof fetch, url: string, init: RequestInit, bounds: {
+    deadlineAt: number;
+    signal?: AbortSignal;
+}, read: (response: Response) => Promise<T>): Promise<T>;
+/** Keys are scoped to one configured issuer; failed refreshes keep the last successful set. Every `load` is bounded by
+ *  one deadline (`timeoutMs`, default `DEFAULT_JWKS_TIMEOUT_MS`) over its discovery read and its key-set read together;
+ *  callers that join an in-flight load share that load's deadline. */
 export declare class JwksCache {
     readonly issuer: string;
     private readonly fetcher;
@@ -35,7 +59,10 @@ export declare class JwksCache {
     private lastUnknownRefresh;
     private loading;
     private discovery;
-    constructor(issuer: string, fetcher?: typeof fetch, jwksUri?: string);
+    private readonly timeoutMs;
+    constructor(issuer: string, fetcher?: typeof fetch, jwksUri?: string, options?: {
+        timeoutMs?: number;
+    });
     load(): Promise<JSONWebKeySet>;
     private fetchKeys;
     forKid(kid: string | undefined): Promise<JSONWebKeySet>;

package/packages/crouter-identity/dist/index.js

@@ -71,7 +71,70 @@ export function covers(held, requested) {
     }
     return held === requested;
 }
-/** Keys are scoped to one configured issuer; failed refreshes keep the last successful set. */
+/** A directory fetch ran past its deadline (or was aborted by its caller before that). `code` is `deadline_exceeded`;
+ *  `deadlineAt` is the instant (epoch ms) the operation had to finish by. The `@north-light/sdk` maps it to its
+ *  `DeadlineExceededError`. */
+export class FetchDeadlineError extends Error {
+    deadlineAt;
+    url;
+    code = 'deadline_exceeded';
+    constructor(deadlineAt, url) {
+        super(`${url} did not answer by the deadline (${new Date(deadlineAt).toISOString()})`);
+        this.deadlineAt = deadlineAt;
+        this.url = url;
+        this.name = 'FetchDeadlineError';
+    }
+}
+/** The default deadline for one `JwksCache.load`, covering its discovery read and its key-set read together. */
+export const DEFAULT_JWKS_TIMEOUT_MS = 10_000;
+/**
+ * One `fetch` plus the reading of its answer (`read`, e.g. `response.json()`), bounded by one absolute deadline. The
+ * request is aborted when the deadline passes or `signal` fires, and the returned promise rejects at that moment
+ * even when `fetcher` ignores its signal, so a directory that accepts the connection and never answers cannot hold a
+ * caller (or a lock the caller holds) past `deadlineAt`. Rejects `FetchDeadlineError` at the deadline and the signal's
+ * reason when `signal` fired first.
+ */
+export async function boundedFetch(fetcher, url, init, bounds, read) {
+    const { deadlineAt, signal } = bounds;
+    if (signal?.aborted)
+        throw signal.reason;
+    const remaining = deadlineAt - Date.now();
+    if (remaining <= 0)
+        throw new FetchDeadlineError(deadlineAt, url);
+    const controller = new AbortController();
+    let timer;
+    let onAbort;
+    const stop = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => { const error = new FetchDeadlineError(deadlineAt, url); controller.abort(error); reject(error); }, remaining);
+        if (signal) {
+            onAbort = () => { controller.abort(signal.reason); reject(signal.reason); };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+    const work = (async () => {
+        const response = await fetcher(url, { ...init, signal: controller.signal });
+        // A response that arrives after the deadline won is discarded: close it so its connection is not retained.
+        if (controller.signal.aborted) {
+            void response.body?.cancel().catch(() => { });
+            throw controller.signal.reason;
+        }
+        return read(response);
+    })();
+    // The loser of the race must not surface as an unhandled rejection.
+    work.catch(() => { });
+    stop.catch(() => { });
+    try {
+        return await Promise.race([work, stop]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (onAbort)
+            signal?.removeEventListener('abort', onAbort);
+    }
+}
+/** Keys are scoped to one configured issuer; failed refreshes keep the last successful set. Every `load` is bounded by
+ *  one deadline (`timeoutMs`, default `DEFAULT_JWKS_TIMEOUT_MS`) over its discovery read and its key-set read together;
+ *  callers that join an in-flight load share that load's deadline. */
 export class JwksCache {
     issuer;
     fetcher;
@@ -79,16 +142,20 @@ export class JwksCache {
     lastUnknownRefresh = -Infinity;
     loading;
     discovery;
-    constructor(issuer, fetcher = fetch, jwksUri) {
+    timeoutMs;
+    constructor(issuer, fetcher = fetch, jwksUri, options = {}) {
         this.issuer = issuer;
         this.fetcher = fetcher;
         if (jwksUri)
             this.discovery = { jwks_uri: jwksUri };
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_JWKS_TIMEOUT_MS;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0 || this.timeoutMs > 2_147_483_647)
+            throw new RangeError('JwksCache timeoutMs must be a positive finite number of at most 2147483647');
     }
     async load() {
         if (this.loading)
             return this.loading;
-        const loading = this.fetchKeys();
+        const loading = this.fetchKeys(Date.now() + this.timeoutMs);
         this.loading = loading;
         try {
             return await loading;
@@ -97,20 +164,22 @@ export class JwksCache {
             this.loading = undefined;
         }
     }
-    async fetchKeys() {
+    async fetchKeys(deadlineAt) {
         if (!this.discovery) {
-            const response = await this.fetcher(`${this.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`);
-            if (!response.ok)
-                throw new Error(`Directory discovery failed: ${response.status}`);
-            const value = await response.json();
+            const value = await boundedFetch(this.fetcher, `${this.issuer.replace(/\/$/, '')}/.well-known/openid-configuration`, {}, { deadlineAt }, async (response) => {
+                if (!response.ok)
+                    throw new Error(`Directory discovery failed: ${response.status}`);
+                return await response.json();
+            });
             if (!value || typeof value !== 'object' || !('jwks_uri' in value) || typeof value.jwks_uri !== 'string')
                 throw new Error('Directory discovery has no jwks_uri');
             this.discovery = { jwks_uri: value.jwks_uri };
         }
-        const response = await this.fetcher(this.discovery.jwks_uri);
-        if (!response.ok)
-            throw new Error(`Directory JWKS failed: ${response.status}`);
-        const keys = await response.json();
+        const keys = await boundedFetch(this.fetcher, this.discovery.jwks_uri, {}, { deadlineAt }, async (response) => {
+            if (!response.ok)
+                throw new Error(`Directory JWKS failed: ${response.status}`);
+            return await response.json();
+        });
         if (!keys || typeof keys !== 'object' || !('keys' in keys) || !Array.isArray(keys.keys))
             throw new Error('Invalid directory JWKS');
         this.keys = keys;

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.414",
+  "version": "0.3.416",
   "description": "crouter cloud access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.414",
+  "version": "0.3.416",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.414",
+      "version": "0.3.416",
       "hasInstallScript": true,
       "license": "UNLICENSED",
       "workspaces": [
@@ -18,7 +18,7 @@
         "@earendil-works/pi-ai": "0.99.1",
         "@earendil-works/pi-coding-agent": "0.99.1",
         "@earendil-works/pi-tui": "0.99.1",
-        "@north-light/identity": "0.3.414",
+        "@north-light/identity": "0.3.416",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -13814,17 +13814,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/api",
-      "version": "0.3.414",
+      "version": "0.3.416",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.414",
+      "version": "0.3.416",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.414",
+      "version": "0.3.416",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -13832,20 +13832,20 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.414",
+      "version": "0.3.416",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.414",
-        "@north-light/identity": "0.3.414"
+        "@north-light/api": "0.3.416",
+        "@north-light/identity": "0.3.416"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.414",
+      "version": "0.3.416",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.414",
-        "@north-light/identity": "0.3.414",
+        "@north-light/api": "0.3.416",
+        "@north-light/identity": "0.3.416",
         "jose": "^6.2.1"
       },
       "bin": {