onebrowser 0.4.0 → 0.5.0

package/README.md

@@ -15,14 +15,15 @@ const page = await session.newPage(); // Playwright; or any CDP client on sessio
 await page.goto('https://example.com');
 await session.close();
 
-await browsers.quota('steel'); // { remaining, unbilled, unit: 'USD', renewsAt: null }
-browsers.maxSessionCost('steel', {}); // what a session with these options costs at most, in USD
-await browsers.syncUsage(); // fetches the providers' records of ended sessions into the ledger
+await browsers.readQuota('steel'); // { remaining, unbilled, unit: 'USD', renewsAt: null }
+browsers.quota('steel'); // the same now, from that reading: sessions opened since count at once
+browsers.maxSessionCost('steel'); // what a session with the default options costs at most, in USD
+await browsers.syncUsage(); // stores the providers' records of ended sessions in the ledger
 browsers.usage({ since: Date.parse('2026-11-01') }); // [{ day, provider, client, sessions, minutes, … }]
 await browsers.close();
 ```
 
-**What it does not do**: choose a provider, cap the sessions held at once, spread sessions over providers, or stop using a provider whose quota runs low. Those are policy, and belong to the program using it. onebrowser opens the session it is asked for, and tells the program what it needs to decide: what is left of the quota once the sessions not billed yet are paid for, what a session costs at most, and `QuotaError` when a provider refuses a session for the account's quota.
+Choosing a provider, capping sessions and stopping before a quota runs out are the program's policy. onebrowser opens the sessions it is asked for and gives the program what it needs to decide: what the quota has left, what a session costs at most, and `QuotaError` when a provider refuses a session for the account's quota.
 
 Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbrowser](https://hyperbrowser.ai), [Lightpanda](https://lightpanda.io), [Kernel](https://www.kernel.sh), [Anchor Browser](https://anchorbrowser.io) and [Firecrawl](https://www.firecrawl.dev); a program can add its own (see [Adding a provider](#adding-a-provider)). Node 22.13 or later.
 
@@ -34,25 +35,26 @@ Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbro
 |---|---|
 | `client` | The program using it, recorded with each session; required |
 | `ledgerPath` | SQLite file of the ledger (default below; `':memory:'` for tests). Opened when first needed |
-| `providers` | Settings per provider name, on top of its adapter's `defaults`: `apiKey`, `price` and `billingDelayMs` (see [Quota](#quota)), and the adapter's own settings (API base URLs, plan facts such as `monthlyHours`) |
+| `providers` | Settings per provider name, on top of its adapter's `defaults`: `apiKey`, `price`, `billingDelayMs`, `minIdleTimeoutSec` (see [Quota](#quota)) and the adapter's own (API base URLs, plan facts such as `monthlyHours`) |
 | `adapters` | Further adapters by provider name, or replacements of built-in ones |
 
 | Method | |
 |---|---|
 | `providers` | Names of the providers it can open sessions with |
 | `checkReady(provider)` | Throws when the provider is unknown or has no API key |
-| `openSession({ provider, proxyCountry, idleTimeoutSec, maxDurationMs })` | A new session, recorded in the ledger once the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
-| `quota(provider, { maxAgeMs })` | `{ remaining, unbilled, unit, renewsAt }` in the provider's own unit: what the provider reads less `unbilled`, what the sessions it may not show yet cost (see [Quota](#quota)); `renewsAt` (ms) when it renews by itself, `null` when only a top-up renews it. The provider is read anew unless a reading started at most `maxAgeMs` ago (default 0) or one in progress can be used, a failed one too; `unbilled` is worked out anew every time. Throws when the provider cannot be read |
-| `maxSessionCost(provider, options)` | What a session with these session options costs at most, in the unit of the provider's quota: as if it lasted `maxDurationMs` and then `idleTimeoutSec`, at the provider's price |
-| `syncUsage()` | Stores the providers' records (duration, proxy traffic) of the ended sessions that have none yet: `{ reported, failed: [{ provider, error }] }`. Sessions of a provider it has no adapter for (another program's own) are left to the programs that have one |
+| `openSession({ provider, proxyCountry, idleTimeoutSec, maxDurationMs })` | A new session, in the ledger from when the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
+| `readQuota(provider, { maxAgeMs })` | Reads the provider's quota, unless a reading in progress or started at most `maxAgeMs` ago (default 0) can be used, a failed one too; then answers as `quota()` |
+| `quota(provider)` | What is left now, from the last reading: `{ remaining, unbilled, unit, renewsAt }` (see [Quota](#quota)). Throws until the provider has been read, and while its last reading failed |
+| `maxSessionCost(provider, options)` | What a session with these options costs at most, in the unit of the provider's quota |
+| `syncUsage()` | Stores the providers' records (duration, proxy traffic) of ended sessions: `{ reported, failed: [{ provider, error }] }` |
 | `usage({ since })` | Sessions opened since `since` (ms) per UTC day, provider and client: `sessions`, `minutes` (the provider's record, else the open-to-close timing), `untimed`, `unsynced`, `proxyBytes` |
 | `close()` | Closes the sessions still open and the ledger |
 
-A session (`openSession`) has `id`, `provider`, `egress`, `cdpUrl` (it may carry the API key: never log it), `openedAt` (when it was asked for), `closedAt`, and:
+A session has `id`, `provider`, `egress`, `cdpUrl` (it may carry the API key: never log it), `openedAt` (when it was asked for), `closedAt` (when its provider released it), and:
 
-- `connect()`: Playwright's `Browser` over its CDP connection, made once. A keep-alive command every 15 s keeps the provider's idle timeout from ending a session that is in use.
-- `newPage()`: always a new page in the default context: the page a remote browser starts with is not always one that can be navigated.
-- `close()`: disconnects and releases it; only the first call does. The ledger records it closed in any case. Throws when the provider could not release it: the provider then ends it by itself.
+- `connect()`: Playwright's `Browser` over its CDP connection, made once. A keep-alive command every 15 s keeps the provider's idle timeout from ending a session in use.
+- `newPage()`: a new page in the default context: the page a remote browser starts with cannot always be navigated.
+- `close()`: disconnects and releases it; every call answers as the first. Throws when the provider could not release it: the provider ends it by itself, and the ledger counts it as lasting as long as it can.
 
 A session and a `OneBrowser` are async-disposable: `await using session = await browsers.openSession({ provider: 'steel' })` closes the session at the end of its block (Node 24 or later; on Node 22 call `close()`).
 
@@ -61,7 +63,7 @@ A session and a `OneBrowser` are async-disposable: `await using session = await
 | Option | Default | Meaning |
 |---|---|---|
 | `proxyCountry` | `null` | A country code: the provider's proxy in that country. `null`: its default egress |
-| `idleTimeoutSec` | 60 | A session whose client is gone (its process was killed) ends this long after at the latest. At least 30 (twice the keep-alive interval) |
+| `idleTimeoutSec` | 60 | A session whose client is gone (its process was killed) ends this long after at the latest, or after the provider's `minIdleTimeoutSec` if longer. At least 30 (twice the keep-alive interval) |
 | `maxDurationMs` | 15 min | The session ends this long after it was opened at the latest: this process closes it then, and the provider's own limit is set to it where its API takes one |
 
 `sessionOptions(options)` returns them with the defaults filled in and throws when one is unknown or out of range, so that a program can check its configuration before it opens any session.
@@ -80,9 +82,9 @@ How each provider meets them:
 
 ### Quota
 
-`quota()` answers what is left of the account's quota once every session not billed yet is paid for. The provider's reading shows the sessions that ended up to `billingDelayMs` before it; the ledger has the others, still open or ended since, and each costs the provider's `price`: an open session as if it lasted as long as it can (`maxDurationMs`, then `idleTimeoutSec`, should its process die), an ended one as long as it lasted. So a program can check, before each session, that the account can pay for one more (`maxSessionCost`), also between readings and with other programs on the machine opening sessions. Sessions opened elsewhere, through another machine's ledger, are not known until the provider bills them, and proxy traffic billed by the GB is not in the price.
+`quota()` is the last reading less `unbilled`: what the ledger's sessions that the reading does not show cost at the provider's `price`. A reading shows the sessions that ended `billingDelayMs` before it; the others are open ones, counted as lasting as long as they can (`maxDurationMs`, then `idleTimeoutSec`, at least the provider's `minIdleTimeoutSec`), and those ended since, counted as long as they lasted. So each session counts once from when its provider has created it, whichever program on the machine opened it, and a program can check before each session that the account pays for it (`maxSessionCost`). A provider that bills a session while it runs has part of it counted twice, on the safe side. Not counted: sessions opened through another machine's ledger, until the provider bills them, and proxy traffic billed by the GB.
 
-`price` is in the quota's unit: `perHour`, `perSession` (default 0), and the session time billed in whole `stepSec`, rounded up (default 1), at least `minSec` (default 0). It bounds what sessions cost, so where a provider does not document its rounding the adapter takes the minute, rounded up. Both are settings: a program on another plan sets its own.
+`price` is in the quota's unit: `perHour`, `perSession` (default 0), the session time billed in whole `stepSec`, rounded up (default 1), and at least `minSec` (default 0). Where a provider does not document its rounding, the adapter takes the minute. `renewsAt` (ms) is when the quota renews by itself; `null` when only a top-up renews it. `price` and `billingDelayMs` are settings: a program on another plan sets its own.
 
 | Provider | Quota, unit | Read from | `price` | `billingDelayMs` |
 |---|---|---|---|---|
@@ -102,7 +104,7 @@ Every provider read from its API showed a session's cost within about a minute o
 
 ### The ledger
 
-One SQLite file per machine by default: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`). Every program that uses onebrowser on the machine shares it, each under its own `client`, so the record of a provider account's sessions is whole whichever program opened them; several processes may write to it at once. Each session is recorded when its provider has created it (it is billed from then on, also when connecting fails afterwards), with when it ends at the latest, closed when released, and completed with the provider's own record by `syncUsage()` once it has ended. A ledger made by an older onebrowser is brought up to date when it is opened.
+One SQLite file per machine by default: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`), shared by every program on the machine under its own `client`. A session is recorded when its provider has created it (it is billed from then on), with when it ends at the latest; closed when its provider has released it; and completed with the provider's own record by `syncUsage()`. A ledger made by an earlier onebrowser is brought up to date when opened; one made by a later onebrowser is refused.
 
 ## Command line
 
@@ -115,17 +117,17 @@ npx onebrowser usage --days 7        # the ledger's sessions per UTC day, provid
 npx onebrowser usage --json --env-file .env
 ```
 
-`usage` first fetches the providers' records of the sessions that have ended, as `syncUsage()` does. With `--json`, `quota` prints an array of what `quota()` returns, with the provider: `{ provider, remaining, unbilled, unit, renewsAt }`, or `{ provider, error }` for a failed reading; `usage` prints `{ ledger, since, sessions, failed }`, where `sessions` is what `usage()` returns and `failed` what `syncUsage()` could not fetch. API keys are read as by the library, from the environment (`--env-file PATH` loads a file into it first). Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
+`usage` first fetches the providers' records of the sessions that have ended, as `syncUsage()` does. With `--json`, `quota` prints an array of what `readQuota()` returns, with the provider: `{ provider, remaining, unbilled, unit, renewsAt }`, or `{ provider, error }` for a failed reading; `usage` prints `{ ledger, since, sessions, failed }`, where `sessions` is what `usage()` returns and `failed` what `syncUsage()` could not fetch. API keys are read as by the library, from the environment (`--env-file PATH` loads a file into it first). Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
 
 ## Adding a provider
 
 Write `src/providers/<name>.js` and register it in `ADAPTERS` (`src/providers/index.js`, where the contract is):
 
-- `defaults`: its settings: `price` and `billingDelayMs` (see [Quota](#quota)), and its own (API base URLs, plan facts).
+- `defaults`: `price`, `billingDelayMs`, `minIdleTimeoutSec` if the provider takes no idle timeout as short as asked (see [Quota](#quota)), and its own settings (API base URLs, plan facts).
 - `createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) → { id, cdpUrl, egress }`: maps the session options onto the provider's parameters; throws `QuotaError` when the provider refuses the session for the account's quota.
 - `releaseSession(settings, apiKey, session)`.
 - `sessionUsage(settings, apiKey, [{ id, openedAt, closedAt }]) → [{ id, durationMs, proxyBytes }]`: the record of those sessions that have ended: the provider's own, or the ledger's timing for a provider whose records its API key cannot read.
-- `quota(settings, apiKey, history) → { remaining, unit, renewsAt? }`: `history.endedSessionMsSince(ms)` is the session time of the provider's sessions in the ledger that have ended, for a provider that cannot report its own usage.
+- `quota(settings, apiKey, history) → { remaining, unit, renewsAt? }`: for a provider that cannot report its usage, `history.endedSessionMsSince(ms)` is the session time of the ledger's sessions that the reading shows.
 
 Requests go through `src/providers/http.js`: every status other than 2xx is an `HttpError` (with `status`), so an adapter handles only the statuses that mean something of their own, such as a quota refusal.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onebrowser",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "One interface to remote browser providers: sessions by provider name, a usage ledger, account quotas",
   "keywords": ["browser", "remote-browser", "cdp", "playwright", "steel", "hyperbrowser", "lightpanda", "kernel", "tinyfish", "anchorbrowser", "firecrawl"],
   "license": "MIT",

package/src/cli.js

@@ -30,7 +30,7 @@ const COMMANDS = {
       if (unknown.length) throw new CommandLineError(`unknown provider ${unknown.join(', ')} (expected ${browsers.providers.join(', ')})`);
       const asked = names.length ? names : browsers.providers.filter((p) => isReady(browsers, p));
       if (!asked.length) throw new Error(`no provider has an API key: set ${browsers.providers.map(apiKeyEnv).join(', ')}`);
-      const quotas = await Promise.all(asked.map((provider) => browsers.quota(provider).then((q) => ({ provider, ...q }), (e) => ({ provider, error: e.message }))));
+      const quotas = await Promise.all(asked.map((provider) => browsers.readQuota(provider).then((q) => ({ provider, ...q }), (e) => ({ provider, error: e.message }))));
       if (json) out.write(`${JSON.stringify(quotas, null, 2)}\n`);
       else {
         for (const q of quotas) {

package/src/cost.js

@@ -1,20 +1,22 @@
 /**
- * A provider's price (its adapter's `price` setting, providers/index.js), in the unit its quota is read in:
+ * A provider's price (its `price` setting), in the unit its quota is read in:
  *   perHour     for the session time
  *   perSession  for each session, however short (default 0)
  *   stepSec     the session time is billed in whole steps of this, rounded up (default 1)
  *   minSec      and at least this much of it (default 0)
- * Where a provider's documentation does not say how it rounds, its adapter takes the minute, rounded up: the
- * price is used to bound what sessions cost, so it errs on the high side.
+ * It bounds what sessions cost, so where a provider does not document its rounding the adapter takes the minute.
  */
-export function checkPrice(price) {
+
+/** The price with its defaults filled in; throws when it is not one */
+export function fullPrice(price) {
   const { perHour, perSession = 0, stepSec = 1, minSec = 0, ...unknown } = price ?? {};
   const fine = [perHour, perSession, minSec].every((x) => Number.isFinite(x) && x >= 0) && Number.isFinite(stepSec) && stepSec > 0;
   if (!fine || Object.keys(unknown).length) throw new Error(`price must be { perHour, perSession, stepSec, minSec } of numbers ≥ 0 (stepSec > 0), not ${JSON.stringify(price)}`);
+  return { perHour, perSession, stepSec, minSec };
 }
 
-/** What a session that lasts durationMs costs at `price` */
-export function sessionCost({ perHour, perSession = 0, stepSec = 1, minSec = 0 }, durationMs) {
+/** What a session that lasts durationMs costs at `price` (fullPrice) */
+export function sessionCost({ perHour, perSession, stepSec, minSec }, durationMs) {
   const billedSec = Math.max(minSec, Math.ceil(durationMs / 1000 / stepSec) * stepSec);
   return perSession + (perHour * billedSec) / 3600;
 }

package/src/index.js

@@ -2,7 +2,7 @@ import { sessionCost } from './cost.js';
 import { readApiKey } from './credentials.js';
 import { QuotaError } from './errors.js';
 import { defaultLedgerPath, Ledger } from './ledger.js';
-import { ADAPTERS, checkAdapter, checkSettings } from './providers/index.js';
+import { ADAPTERS, checkAdapter, fullSettings } from './providers/index.js';
 import { KEEP_ALIVE_MS, Session } from './session.js';
 
 export { apiKeyEnv } from './credentials.js';
@@ -10,18 +10,18 @@ export { QuotaError };
 
 /** Session options when openSession() is not given them */
 const SESSION_DEFAULTS = {
-  proxyCountry: null, // null: the provider's default egress
-  idleTimeoutSec: 60, // a session whose client is gone (its process was killed) ends this long after at the latest
+  proxyCountry: null,
+  idleTimeoutSec: 60,
   maxDurationMs: 15 * 60_000,
 };
 
 /**
- * The session options of openSession() with the defaults filled in (SESSION_DEFAULTS); throws when one is unknown
- * or out of range, so that a program can check its configuration before it opens any session:
+ * The session options of openSession() with the defaults filled in; throws when one is unknown or out of range,
+ * so that a program can check its configuration before it opens any session:
  *   proxyCountry     country code: the provider's proxy there; null: its default egress
- *   idleTimeoutSec   a session whose client is gone ends this long after at the latest; at least twice the
- *                    keep-alive interval (session.js)
- *   maxDurationMs    the session ends this long after it was opened at the latest
+ *   idleTimeoutSec   a session whose client is gone ends this long after at the latest, or after the provider's
+ *                    minIdleTimeoutSec if longer (≥ 2 × KEEP_ALIVE_MS)
+ *   maxDurationMs    a session ends this long after it was opened at the latest
  */
 export function sessionOptions(options = {}) {
   const unknown = Object.keys(options).filter((k) => !Object.hasOwn(SESSION_DEFAULTS, k));
@@ -34,38 +34,24 @@ export function sessionOptions(options = {}) {
   return o;
 }
 
-/**
- * How long a session with these options (sessionOptions) lasts at most, whatever becomes of its process: this
- * process ends it at maxDurationMs, and its provider idleTimeoutSec after its client left, should the process die
- * or its release fail before
- */
-const sessionMsAtMost = (o) => o.maxDurationMs + o.idleTimeoutSec * 1000;
+/** How long a session lasts at most, whatever becomes of its process: closed at maxDurationMs, else ended by its provider once idle */
+const sessionMsAtMost = (o, settings) => o.maxDurationMs + Math.max(o.idleTimeoutSec, settings.minIdleTimeoutSec) * 1000;
 
 /**
- * Remote browsers from several providers behind one interface: a session is asked for by provider name, the way
- * an LLM request names its model. Every session is recorded in a ledger (ledger.js), which the usage of each
- * provider account and, for providers that cannot report it themselves, its quota are read from.
- *
- * What is left of an account's quota is what its provider reads, less what the sessions it has not billed yet
- * cost (quota()): the ledger knows those, and each provider's price (cost.js) what they cost. So a program can
- * tell, before it opens a session, whether the account can pay for it.
+ * Remote browsers from several providers behind one interface: a session is asked for by provider name. Every
+ * session is recorded in a ledger (ledger.js) shared by the programs on the machine, so that each provider
+ * account's usage, and what its quota has left at any moment, are known. Which provider to use, and when to
+ * stop using one, are the caller's decisions.
  *
- * Which provider to use, how many sessions to hold and when to stop using one are the caller's decisions:
- * OneBrowser opens the sessions it is asked for.
- *
- * new OneBrowser({ client, ledgerPath, providers, adapters })
- *   client       the program using it, recorded with each session (several programs may share one ledger)
- *   ledgerPath   SQLite file of the ledger (default: defaultLedgerPath() in ledger.js; ':memory:' for tests),
- *                opened when first needed
- *   providers    settings per provider name: apiKey (else from the environment, see credentials.js), and the
- *                adapter's own settings on top of its defaults (providers/<name>.js)
- *   adapters     further adapters by provider name, or replacements of built-in ones (providers/index.js)
+ * client: the program using it, recorded with each session; ledgerPath: the ledger's SQLite file, opened when
+ * first needed; providers: settings per provider name on top of its adapter's defaults (providers/index.js),
+ * apiKey among them (else credentials.js); adapters: further or replacement adapters by provider name.
  */
 export class OneBrowser {
-  #providers = new Map(); // name → { adapter, settings: its defaults with the given ones on top, apiKey: the one given }
+  #providers = new Map(); // name → { adapter, settings, apiKey }
   #ledger = null;
   #open = new Set();
-  #readings = new Map(); // provider → its last quota reading (#reading)
+  #readings = new Map(); // provider → { latest, done }: its latest quota reading, and the latest one done
 
   constructor({ client, ledgerPath = defaultLedgerPath(), providers = {}, adapters = {} }) {
     if (!client?.trim()) throw new Error('onebrowser: client must name the program using it');
@@ -74,15 +60,12 @@ export class OneBrowser {
     for (const [name, adapter] of Object.entries({ ...ADAPTERS, ...adapters })) {
       checkAdapter(name, adapter);
       const { apiKey, ...given } = providers[name] ?? {};
-      const settings = { ...adapter.defaults, ...given };
-      checkSettings(name, settings);
-      this.#providers.set(name, { adapter, settings, apiKey });
+      this.#providers.set(name, { adapter, settings: fullSettings(name, { ...adapter.defaults, ...given }), apiKey });
     }
     const unknown = Object.keys(providers).filter((name) => !this.#providers.has(name));
     if (unknown.length) throw new Error(`onebrowser: no adapter for provider ${unknown.join(', ')}`);
   }
 
-  /** Names of the providers it can open sessions with */
   get providers() {
     return [...this.#providers.keys()];
   }
@@ -91,14 +74,12 @@ export class OneBrowser {
     return (this.#ledger ??= new Ledger(this.ledgerPath));
   }
 
-  /** The adapter, settings and the API key given of `provider`; throws when it is unknown */
   #known(provider) {
     const p = this.#providers.get(provider);
     if (!p) throw new Error(`unknown provider ${provider} (expected ${this.providers.join(', ')})`);
     return p;
   }
 
-  /** The adapter, settings and API key of `provider`; throws when it is unknown or has no API key */
   #ready(provider) {
     const p = this.#known(provider);
     return { ...p, apiKey: readApiKey(provider, p.apiKey) };
@@ -110,14 +91,13 @@ export class OneBrowser {
   }
 
   /**
-   * A new session with `provider`, recorded in the ledger once the provider has created it; options: see
-   * sessionOptions(). Throws when the provider does not create one; QuotaError when it refuses for the account's
-   * quota.
+   * A new session with `provider` (options: sessionOptions()), in the ledger from when its provider has created
+   * it. Throws when the provider creates none; QuotaError when it refuses for the account's quota.
    */
   async openSession({ provider, ...options }) {
     const { adapter, settings, apiKey } = this.#ready(provider);
     const o = sessionOptions(options);
-    const openedAt = Date.now(); // the provider bills the session from some time after this
+    const openedAt = Date.now();
     let remote;
     try {
       remote = await adapter.createSession(settings, apiKey, o);
@@ -125,79 +105,91 @@ export class OneBrowser {
       if (e instanceof QuotaError) throw e;
       throw new Error(`failed to create a ${provider} session: ${e.message}`);
     }
-    const session = new Session({
-      provider, remote, openedAt, maxDurationMs: o.maxDurationMs,
-      release: async (s) => {
-        this.#open.delete(s);
-        this.#store.closed(s);
-        await adapter.releaseSession(settings, apiKey, s);
-      },
-    });
+    const session = new Session({ provider, remote, openedAt, maxDurationMs: o.maxDurationMs, release: (s) => this.#release(adapter, settings, apiKey, s) });
     try {
-      this.#store.opened({ provider, id: session.id, client: this.client, openedAt, endsBy: openedAt + sessionMsAtMost(o) });
+      this.#store.opened({ provider, id: session.id, client: this.client, openedAt, endsBy: openedAt + sessionMsAtMost(o, settings) });
     } catch (e) {
-      await session.close().catch(() => {}); // a session the ledger has no record of is not handed out
+      await session.close().catch(() => {}); // a session the ledger does not know is not handed out
       throw e;
     }
     this.#open.add(session);
     return session;
   }
 
+  /** Releases `session` at its provider and records it closed: when it was released, so its whole billed time counts */
+  async #release(adapter, settings, apiKey, session) {
+    try {
+      await adapter.releaseSession(settings, apiKey, session);
+      const closedAt = Date.now();
+      this.#store.closed({ provider: session.provider, id: session.id, closedAt });
+      return closedAt;
+    } finally {
+      this.#open.delete(session);
+    }
+  }
+
   /**
-   * What is left of the account's quota with `provider`, in the provider's own unit: { remaining, unbilled, unit,
-   * renewsAt }. remaining: what the provider reads, less `unbilled`: what the sessions in the ledger that the
-   * reading may not show yet cost, each at the provider's price (cost.js). Those are the sessions that had not
-   * ended billingDelayMs before the reading: open ones as if they lasted as long as they can, ended ones as long
-   * as they lasted. renewsAt (ms) when the quota renews by itself, null when only a top-up renews it.
-   *
-   * The provider is read anew unless a reading started at most maxAgeMs ago, or still in progress, can be used
-   * (a failed one too: it throws again); what is unbilled is worked out from the ledger every time, so it includes
-   * the sessions opened since, by any program sharing the ledger. Throws when the provider cannot be read.
+   * Reads the account's quota with `provider` from the provider, unless a reading in progress or started at most
+   * maxAgeMs ago can be used (a failed one throws again); then answers as quota().
    */
-  async quota(provider, { maxAgeMs = 0 } = {}) {
-    const { settings } = this.#known(provider);
+  async readQuota(provider, { maxAgeMs = 0 } = {}) {
     const reading = this.#reading(provider, maxAgeMs);
-    const answer = await reading.answer;
-    const sessions = this.#store.openAfter(provider, reading.startedAt - settings.billingDelayMs);
-    const unbilled = sessions.reduce((cost, s) => cost + sessionCost(settings.price, s.durationMs), 0);
-    return { remaining: answer.remaining - unbilled, unbilled, unit: answer.unit, renewsAt: answer.renewsAt ?? null };
+    await reading.settled;
+    if (reading.error) throw reading.error;
+    return this.quota(provider);
   }
 
   /**
-   * The provider's quota reading, { startedAt, answer: a promise of the adapter's answer }: the last one if it
-   * started at most maxAgeMs ago or is still in progress, else a new one. A failed reading counts as one too: its
-   * error is the answer until maxAgeMs have passed.
+   * What is left of the account's quota now, in the provider's unit: { remaining, unbilled, unit, renewsAt }. The
+   * last reading shows the sessions that ended billingDelayMs before it; `unbilled` is what the ledger's others
+   * cost at the provider's price, open ones as if they lasted as long as they can, and remaining the reading less
+   * that. renewsAt (ms): when the quota renews by itself; null: only a top-up renews it. Throws until the
+   * provider has been read, and while its last reading failed.
    */
+  quota(provider) {
+    const { settings } = this.#known(provider);
+    const reading = this.#readings.get(provider)?.done;
+    if (!reading) throw new Error(`the quota of ${provider} has not been read yet (readQuota)`);
+    if (reading.error) throw reading.error;
+    const unbilled = this.#store.openSince(provider, reading.billedBefore).reduce((cost, s) => cost + sessionCost(settings.price, s.durationMs), 0);
+    const { remaining, unit, renewsAt = null } = reading.value;
+    return { remaining: remaining - unbilled, unbilled, unit, renewsAt };
+  }
+
+  /** The latest reading of the provider's quota if it is in progress or at most maxAgeMs old, else a new one */
   #reading(provider, maxAgeMs) {
-    const last = this.#readings.get(provider);
-    if (last && (!last.done || Date.now() - last.startedAt <= maxAgeMs)) return last;
+    const readings = this.#readings.get(provider) ?? { latest: null, done: null };
+    this.#readings.set(provider, readings);
+    const { latest } = readings;
+    const inProgress = latest && latest !== readings.done;
+    if (inProgress || (latest && Date.now() - latest.startedAt <= maxAgeMs)) return latest;
     const { adapter, settings, apiKey } = this.#ready(provider);
-    const reading = { startedAt: Date.now(), done: false };
-    reading.answer = adapter
-      .quota(settings, apiKey, this.#store.history(provider))
-      .then((q) => {
+    const startedAt = Date.now();
+    const reading = { startedAt, billedBefore: startedAt - settings.billingDelayMs, value: null, error: null };
+    readings.latest = reading;
+    reading.settled = (async () => {
+      try {
+        const q = await adapter.quota(settings, apiKey, this.#store.history(provider, reading.billedBefore));
         if (!(Number.isFinite(q?.remaining) && typeof q.unit === 'string')) throw new Error(`${provider} answered no quota: ${JSON.stringify(q)}`);
-        return q;
-      })
-      .finally(() => (reading.done = true));
-    reading.answer.catch(() => {}); // awaited by the callers; not an unhandled rejection while cached
-    this.#readings.set(provider, reading);
+        reading.value = q;
+      } catch (e) {
+        reading.error = e;
+      }
+      readings.done = reading;
+    })();
     return reading;
   }
 
-  /**
-   * What a session with `provider` and these session options (sessionOptions) costs at most, in the unit of its
-   * quota: as if it lasted as long as it can, at the provider's price
-   */
+  /** What a session with these options costs at most, in the unit of the provider's quota */
   maxSessionCost(provider, options) {
-    return sessionCost(this.#known(provider).settings.price, sessionMsAtMost(sessionOptions(options)));
+    const { settings } = this.#known(provider);
+    return sessionCost(settings.price, sessionMsAtMost(sessionOptions(options), settings));
   }
 
   /**
-   * Stores each provider's record (duration, proxy traffic) of the sessions in the ledger that have ended and have
-   * none yet; sessions still running wait for a later call. A provider that cannot be reached, or has no API key,
-   * is left for a later call too. Sessions of a provider it has no adapter for (another program's own) are left
-   * to the programs that have one. Returns { reported: sessions completed, failed: [{ provider, error }] }.
+   * Stores the providers' records (duration, proxy traffic) of the ledger's ended sessions that have none yet:
+   * { reported, failed: [{ provider, error }] }. What cannot be fetched now, and the sessions of providers it has
+   * no adapter for, are left for a later call.
    */
   async syncUsage() {
     const store = this.#store;
@@ -218,10 +210,8 @@ export class OneBrowser {
 
   /**
    * Sessions opened since `since` (ms), per UTC day, provider and client:
-   * [{ day, provider, client, sessions, minutes, untimed, unsynced, proxyBytes }]. Minutes are the provider's
-   * record where syncUsage has stored it, otherwise the open-to-close timing of the process that opened the
-   * session; untimed: sessions with neither (their process ended before closing them and the provider has not
-   * reported them yet); unsynced: sessions without the provider's record.
+   * [{ day, provider, client, sessions, minutes, untimed, unsynced, proxyBytes }]. minutes: the provider's record
+   * (syncUsage), else the open-to-close timing; untimed: sessions with neither; unsynced: those without the record.
    */
   usage({ since }) {
     return this.#store.usage(since);
@@ -234,7 +224,6 @@ export class OneBrowser {
     this.#ledger = null;
   }
 
-  /** close(), for `await using browsers = new OneBrowser(…)` */
   [Symbol.asyncDispose]() {
     return this.close();
   }

package/src/ledger.js

@@ -14,20 +14,15 @@ export function defaultLedgerPath() {
   return path.join(data, 'onebrowser', 'sessions.db');
 }
 
-/**
- * sessions   every remote browser session: recorded when it is asked for, once its provider has created it (it
- *            is billed from then on, even if connecting fails), closed when released, and completed with the
- *            provider's own record (duration, proxy traffic) once the session has ended and syncUsage has
- *            fetched it
- */
-const SESSIONS = `
+/** Every remote browser session, from when its provider has created it: it is billed from then on, even if connecting fails */
+const SCHEMA = `
 CREATE TABLE sessions (
   provider      TEXT NOT NULL,
   id            TEXT NOT NULL,            -- the session id its provider gave it
   client        TEXT NOT NULL,            -- the program that opened it (OneBrowser's client)
   opened_at     TEXT NOT NULL,            -- when it was asked for; its provider created it right after
   ends_by       TEXT NOT NULL,            -- when it has ended at the latest, whatever becomes of its process
-  closed_at     TEXT,                     -- when it was released; empty if its process ended first
+  closed_at     TEXT,                     -- when its provider released it; empty until then, and if it never was
   duration_ms   INTEGER,                  -- the provider's record, once the session has ended
   proxy_bytes   INTEGER,                  -- proxy traffic in the provider's record
   synced_at     TEXT,                     -- when the provider's record was stored; empty = not yet
@@ -37,25 +32,25 @@ CREATE INDEX idx_sessions_opened ON sessions(provider, opened_at);
 `;
 
 /**
- * The schema's versions, each the step from the one before (PRAGMA user_version counts the steps taken). A ledger
- * is shared by every program on the machine and outlives the onebrowser version that created it, so an older
- * ledger is brought up to date when it is opened.
+ * The version of SCHEMA (PRAGMA user_version), and the step to it from each earlier one: a ledger outlives the
+ * onebrowser that made it. onebrowser 0.1–0.3 made version 1 and left user_version 0.
  */
-const MIGRATIONS = [
-  // 1: the sessions, as onebrowser 0.1–0.3 kept them
-  `CREATE TABLE IF NOT EXISTS sessions (
-     provider TEXT NOT NULL, id TEXT NOT NULL, client TEXT NOT NULL, opened_at TEXT NOT NULL, closed_at TEXT,
-     duration_ms INTEGER, proxy_bytes INTEGER, synced_at TEXT, PRIMARY KEY (provider, id)
-   );`,
-  // 2: ends_by; the sessions of 1 were all opened with the session options' defaults: 15 min, then 60 s idle
-  `ALTER TABLE sessions RENAME TO sessions_1;
-   DROP INDEX IF EXISTS idx_sessions_opened;
-   ${SESSIONS}
-   INSERT INTO sessions (provider, id, client, opened_at, ends_by, closed_at, duration_ms, proxy_bytes, synced_at)
-     SELECT provider, id, client, opened_at, strftime('%Y-%m-%dT%H:%M:%fZ', opened_at, '+16 minutes'), closed_at, duration_ms, proxy_bytes, synced_at
-     FROM sessions_1;
-   DROP TABLE sessions_1;`,
-];
+const VERSION = 2;
+const UPGRADES = {
+  // 1 → 2: ends_by, as if the sessions of 1 had the default session options (15 min, then 60 s idle). Each step
+  // makes its version as that version was, whatever SCHEMA has become since.
+  1: `ALTER TABLE sessions RENAME TO sessions_1;
+      DROP INDEX idx_sessions_opened;
+      CREATE TABLE sessions (
+        provider TEXT NOT NULL, id TEXT NOT NULL, client TEXT NOT NULL, opened_at TEXT NOT NULL, ends_by TEXT NOT NULL,
+        closed_at TEXT, duration_ms INTEGER, proxy_bytes INTEGER, synced_at TEXT, PRIMARY KEY (provider, id)
+      );
+      CREATE INDEX idx_sessions_opened ON sessions(provider, opened_at);
+      INSERT INTO sessions (provider, id, client, opened_at, ends_by, closed_at, duration_ms, proxy_bytes, synced_at)
+        SELECT provider, id, client, opened_at, strftime('%Y-%m-%dT%H:%M:%fZ', opened_at, '+16 minutes'), closed_at, duration_ms, proxy_bytes, synced_at
+        FROM sessions_1;
+      DROP TABLE sessions_1;`,
+};
 
 /** ms from one ISO time to another */
 const msBetween = (from, to) => `CAST(ROUND((julianday(${to}) - julianday(${from})) * 86400000) AS INTEGER)`;
@@ -73,29 +68,31 @@ const iso = (ms) => new Date(ms).toISOString();
 const int = (x) => (x === null || x === undefined || !Number.isFinite(Number(x)) ? null : Math.trunc(Number(x)));
 
 export class Ledger {
+  #file;
   #db;
   #stmts = new Map();
 
   constructor(file) {
     if (file !== ':memory:') fs.mkdirSync(path.dirname(file), { recursive: true });
+    this.#file = file;
     this.#db = new DatabaseSync(file);
     this.#db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;'); // several processes share it
     this.#migrate();
   }
 
-  /** Takes the steps of MIGRATIONS the ledger has not taken, in one transaction: another process may be at it too */
+  /** Makes the ledger, or brings an earlier one up to date, in one transaction: another process may be opening it too */
   #migrate() {
     const version = () => this.#db.prepare('PRAGMA user_version').get().user_version;
-    if (version() === MIGRATIONS.length) return;
-    this.#db.exec('BEGIN IMMEDIATE');
-    try {
-      for (let v = version(); v < MIGRATIONS.length; v++) this.#db.exec(MIGRATIONS[v]);
-      this.#db.exec(`PRAGMA user_version = ${MIGRATIONS.length}`);
-      this.#db.exec('COMMIT');
-    } catch (e) {
-      this.#db.exec('ROLLBACK');
-      throw e;
-    }
+    if (version() === VERSION) return;
+    this.tx(() => {
+      if (!this.#db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'sessions'").get()) this.#db.exec(SCHEMA);
+      else {
+        const from = version() || 1;
+        if (from > VERSION) throw new Error(`onebrowser: the ledger ${this.#file} was made by a later onebrowser (schema ${from}; this one knows ${VERSION})`);
+        for (let v = from; v < VERSION; v++) this.#db.exec(UPGRADES[v]);
+      }
+      this.#db.exec(`PRAGMA user_version = ${VERSION}`);
+    });
   }
 
   #q(sql) {
@@ -112,24 +109,21 @@ export class Ledger {
     this.#q('UPDATE sessions SET closed_at=? WHERE provider=? AND id=? AND closed_at IS NULL').run(iso(closedAt), provider, id);
   }
 
-  /** The record of one provider's sessions, as a provider adapter reads it for its quota (providers/index.js) */
-  history(provider) {
+  /** The provider's sessions that a quota reading shows, those that ended before `billedBefore` (ms); openSince() has the rest */
+  history(provider, billedBefore) {
     return {
-      /** Session time (ms) of the sessions opened since `since` (ms) that have ended, each at most as long as it can have lasted */
+      /** Their session time (ms) since `since` (ms), each as long as it can have lasted while it has no timing */
       endedSessionMsSince: (since) =>
-        this.#q(`SELECT COALESCE(SUM(${SESSION_MS_AT_MOST}), 0) ms FROM sessions WHERE provider=? AND opened_at >= ? AND ${ENDED_AT} < ?`).get(provider, iso(since), iso(Date.now())).ms,
+        this.#q(`SELECT COALESCE(SUM(${SESSION_MS_AT_MOST}), 0) ms FROM sessions WHERE provider=? AND opened_at >= ? AND ${ENDED_AT} < ?`).get(provider, iso(since), iso(billedBefore)).ms,
     };
   }
 
-  /**
-   * The sessions of `provider` still open at `at` (ms): those open now, and those that have ended since.
-   * [{ durationMs }]: each as long as it lasted, or can last at most while it has no timing
-   */
-  openAfter(provider, at) {
+  /** The provider's sessions open at any time since `at` (ms): [{ durationMs }], as long as they can last while untimed */
+  openSince(provider, at) {
     return this.#q(`SELECT ${SESSION_MS_AT_MOST} durationMs FROM sessions WHERE provider=? AND ${ENDED_AT} >= ?`).all(provider, iso(at));
   }
 
-  /** Sessions with one of `providers` whose provider's record has not been stored yet: [{ provider, id, openedAt, closedAt }] (ISO times) */
+  /** Sessions of `providers` without their provider's record yet: [{ provider, id, openedAt, closedAt }] (ISO times) */
   awaitingUsage(providers) {
     return this.#q(
       'SELECT provider, id, opened_at openedAt, closed_at closedAt FROM sessions WHERE synced_at IS NULL AND provider IN (SELECT value FROM json_each(?)) ORDER BY opened_at',
@@ -140,8 +134,9 @@ export class Ledger {
     this.#q('UPDATE sessions SET duration_ms=?, proxy_bytes=?, synced_at=? WHERE provider=? AND id=?').run(int(durationMs), int(proxyBytes), iso(Date.now()), provider, id);
   }
 
+  /** Runs fn in a transaction that takes the write lock at once: another process may be writing too */
   tx(fn) {
-    this.#db.exec('BEGIN');
+    this.#db.exec('BEGIN IMMEDIATE');
     try {
       const r = fn();
       this.#db.exec('COMMIT');

package/src/providers/anchor.js

@@ -16,6 +16,7 @@ export const defaults = {
   // (credits_used) bill more, about $0.06 an hour and a step of $0.003 in the second minute, which this covers
   price: { perSession: 0.01, perHour: 0.15, stepSec: 60 },
   billingDelayMs: 5 * 60_000, // seen within 10 s
+  minIdleTimeoutSec: 60, // idle_timeout is in whole minutes, at least 1
 };
 
 const headers = (apiKey) => ({ 'anchor-api-key': apiKey });

package/src/providers/index.js

@@ -1,4 +1,4 @@
-import { checkPrice } from '../cost.js';
+import { fullPrice } from '../cost.js';
 import * as anchor from './anchor.js';
 import * as firecrawl from './firecrawl.js';
 import * as hyperbrowser from './hyperbrowser.js';
@@ -8,28 +8,22 @@ import * as steel from './steel.js';
 import * as tinyfish from './tinyfish.js';
 
 /**
- * Provider adapters, by provider name: the only provider-specific code. Each exports:
- *   defaults                 its settings; OneBrowser's `providers` option overrides them per provider (the API
- *                            key is not among them: each function gets it as its own argument):
- *       price                what its sessions cost, in the unit of its quota (cost.js)
- *       billingDelayMs       how long after a session has ended its quota reading shows its cost, at the latest
- *       and its own          API base URLs, plan facts such as monthlyHours
- *   createSession(settings, apiKey, options) → { id, cdpUrl, egress }
- *       options: { proxyCountry, idleTimeoutSec, maxDurationMs } (OneBrowser.openSession), mapped onto the
- *       provider's own parameters. Throws on failure; QuotaError (errors.js) when the provider refuses the
- *       session because the account's quota is used up
- *   releaseSession(settings, apiKey, session)   ends the session; throws on failure
+ * Provider adapters by name: the only provider-specific code. Each exports:
+ *   defaults   its settings, which OneBrowser's `providers` option overrides:
+ *     price               what its sessions cost, in the unit of its quota (cost.js)
+ *     billingDelayMs      how long after a session has ended its quota reading shows it, at the latest
+ *     minIdleTimeoutSec   the shortest idle timeout it takes (default 0)
+ *     and its own         API base URLs, plan facts such as monthlyHours
+ *   createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) → { id, cdpUrl, egress }
+ *       throws QuotaError (errors.js) when the provider refuses the session for the account's quota
+ *   releaseSession(settings, apiKey, session)
  *   sessionUsage(settings, apiKey, [{ id, openedAt, closedAt }]) → [{ id, durationMs, proxyBytes }]
- *       the record of those sessions that have ended: the provider's own, or, for a provider whose records the
- *       API key cannot read, the ledger's timing (closedAt is empty for a session no process closed); throws on
- *       failure
+ *       the provider's record of those that have ended, or the ledger's timing where its API key cannot read one
  *   quota(settings, apiKey, history) → { remaining, unit, renewsAt? }
- *       what is left of the account's quota, in the provider's own unit (USD, credits, hours, …), and when it
- *       renews if it does by itself (ms); history: the ledger's record of the provider's sessions
- *       (Ledger.history). Throws when it cannot be read
- *
- * Their requests go through http.js, which turns every status other than 2xx into an HttpError: an adapter
- * handles only the statuses that mean something of their own.
+ *       what the account has left in the provider's unit, and when it renews by itself (ms); history: the
+ *       ledger's sessions that the reading shows (Ledger.history), for a provider that cannot count its usage
+ * Every function throws when it fails. Requests go through http.js, which throws HttpError for a status other
+ * than 2xx.
  */
 export const ADAPTERS = { tinyfish, steel, hyperbrowser, lightpanda, kernel, anchor, firecrawl };
 
@@ -41,12 +35,15 @@ export function checkAdapter(name, adapter) {
   if (missing.length) throw new Error(`provider ${name}: its adapter lacks ${missing.join(', ')}`);
 }
 
-/** Throws unless `settings` (an adapter's defaults with a program's settings on top) have a price and a billing delay */
-export function checkSettings(name, settings) {
+/** An adapter's settings with the defaults of those every adapter has; throws when one of them is missing or wrong */
+export function fullSettings(name, { price, billingDelayMs, minIdleTimeoutSec = 0, ...own }) {
+  const atLeast0 = (x) => Number.isFinite(x) && x >= 0;
   try {
-    checkPrice(settings.price);
+    const full = fullPrice(price);
+    if (!atLeast0(billingDelayMs)) throw new Error(`billingDelayMs must be a number ≥ 0, not ${billingDelayMs}`);
+    if (!atLeast0(minIdleTimeoutSec)) throw new Error(`minIdleTimeoutSec must be a number ≥ 0, not ${minIdleTimeoutSec}`);
+    return { ...own, price: full, billingDelayMs, minIdleTimeoutSec };
   } catch (e) {
     throw new Error(`provider ${name}: ${e.message}`);
   }
-  if (!(Number.isFinite(settings.billingDelayMs) && settings.billingDelayMs >= 0)) throw new Error(`provider ${name}: billingDelayMs must be a number ≥ 0, not ${settings.billingDelayMs}`);
 }

package/src/session.js

@@ -1,31 +1,24 @@
-/**
- * A CDP command this often while connected keeps a provider's idle timeout from ending a session that is in use
- * (also while a page waits long for an answer). OneBrowser requires idleTimeoutSec to be at least twice as long.
- */
+/** A CDP command this often keeps a provider's idle timeout from ending a session in use; idleTimeoutSec must be at least twice as long */
 export const KEEP_ALIVE_MS = 15_000;
 
 /** Playwright errors carry a multi-line call log; the first line says what failed */
 const firstLine = (e) => String(e.message).split('\n')[0];
 
 /**
- * One remote browser session, as OneBrowser.openSession() opened it: created by its provider and recorded in the
- * ledger. Use it over CDP: through cdpUrl with any CDP client, or through connect() / newPage() with Playwright.
- * It ends at the latest maxDurationMs after it was opened: this process closes it then (a client using it sees
- * its connection drop). close() releases it; one never closed (its process was killed) is ended by its provider
- * idleTimeoutSec after its client left.
- *
- *   id, provider, egress     the provider's session id, its name, and the egress the session uses
- *   cdpUrl                   CDP WebSocket URL (it may carry the API key: never log it)
- *   openedAt, closedAt       ms: when it was asked for (its provider created it right after), when it was
- *                            closed; closedAt is null while open
+ * A remote browser session (OneBrowser.openSession), used over CDP: cdpUrl with any client (it may carry the API
+ * key: never log it), or connect() / newPage() with Playwright. This process closes it maxDurationMs after it was
+ * opened; one whose process died is ended by its provider idleTimeoutSec (at least its minIdleTimeoutSec) after
+ * its client left.
+ * openedAt: when it was asked for; closedAt: when its provider released it, null until then.
  */
 export class Session {
   #release;
-  #browser = null; // the connection in progress or made: a promise of Playwright's Browser
+  #closing = null;
+  #browser = null; // a promise of Playwright's Browser
   #keepAlive = null;
   #deadline;
 
-  /** release(session): records the session closed and releases it at its provider (OneBrowser) */
+  /** release(session) → closedAt: releases it at its provider and records it closed (OneBrowser) */
   constructor({ provider, remote, openedAt, maxDurationMs, release }) {
     this.provider = provider;
     this.id = remote.id;
@@ -34,13 +27,13 @@ export class Session {
     this.openedAt = openedAt;
     this.closedAt = null;
     this.#release = release;
-    this.#deadline = setTimeout(() => this.close().catch(() => {}), openedAt + maxDurationMs - Date.now()); // a release that fails here leaves the session to the provider's idle timeout
+    this.#deadline = setTimeout(() => this.close().catch(() => {}), openedAt + maxDurationMs - Date.now());
     this.#deadline.unref();
   }
 
-  /** Playwright's Browser over this session's CDP connection, made once; the keep-alive runs while it is connected */
+  /** Playwright's Browser over this session's CDP connection, made once; a keep-alive runs while it is connected */
   connect() {
-    if (this.closedAt) return Promise.reject(new Error(`${this.provider} session ${this.id} is closed`));
+    if (this.#closing) return Promise.reject(new Error(`${this.provider} session ${this.id} is closed`));
     this.#browser ??= this.#connect();
     return this.#browser;
   }
@@ -55,7 +48,7 @@ export class Session {
     }
     try {
       const cdp = await browser.newBrowserCDPSession();
-      if (this.closedAt) throw new Error(`${this.provider} session ${this.id} is closed`); // closed while connecting
+      if (this.#closing) throw new Error(`${this.provider} session ${this.id} is closed`);
       this.#keepAlive = setInterval(() => cdp.send('Browser.getVersion').catch(() => {}), KEEP_ALIVE_MS);
       this.#keepAlive.unref();
     } catch (e) {
@@ -65,10 +58,7 @@ export class Session {
     return browser;
   }
 
-  /**
-   * A new page in the browser's default context. Always a new one: the page a remote browser starts with is not
-   * always one that can be navigated.
-   */
+  /** A new page in the default context: the page a remote browser starts with cannot always be navigated */
   async newPage() {
     const browser = await this.connect();
     const context = browser.contexts()[0] ?? (await browser.newContext());
@@ -76,22 +66,20 @@ export class Session {
   }
 
   /**
-   * Disconnects and releases the session at its provider; only the first call does. The ledger records it closed
-   * in any case. Throws when the provider could not release it: the provider then ends it by itself,
-   * idleTimeoutSec after the disconnect.
+   * Disconnects and releases the session; every call answers as the first. Throws when its provider could not
+   * release it: the ledger then counts it as lasting as long as it can, as its provider ends it by itself.
    */
-  async close() {
-    if (this.closedAt) return;
-    this.closedAt = Date.now();
+  close() {
+    return (this.#closing ??= this.#close());
+  }
+
+  async #close() {
     clearTimeout(this.#deadline);
     clearInterval(this.#keepAlive);
-    const browser = this.#browser;
-    this.#browser = null;
-    await browser?.then((b) => b.close()).catch(() => {});
-    await this.#release(this);
+    await this.#browser?.then((b) => b.close()).catch(() => {});
+    this.closedAt = await this.#release(this);
   }
 
-  /** close(): `await using session = await browsers.openSession(…)` releases it at the end of the block */
   [Symbol.asyncDispose]() {
     return this.close();
   }