@askalf/dario 6.0.33 → 6.0.35

package/dist/analytics.js

@@ -17,6 +17,7 @@
  * each subscriber listens for `'record'` and writes one SSE frame.
  */
 import { EventEmitter } from 'node:events';
+import { createHash } from 'node:crypto';
 /**
  * Map the raw `representative-claim` header value to a human-friendly
  * billing bucket. Pure function; no state; safe to call from any context.
@@ -99,14 +100,14 @@ export function cachedPromptPercent(inputTokens, cacheReadTokens, cacheCreateTok
     const promptTotal = inputTokens + cacheReadTokens + cacheCreateTokens;
     return promptTotal > 0 ? Math.round((cacheReadTokens / promptTotal) * 10000) / 100 : 0;
 }
-export function formatUsageLogLine(requestCount, u) {
+export function formatUsageLogLine(requestCount, u, consumer) {
     const inp = u.inputTokens ?? 0;
     const out = u.outputTokens ?? 0;
     const cr = u.cacheReadTokens ?? 0;
     const cc = u.cacheCreateTokens ?? 0;
     const promptTotal = inp + cr + cc;
     const pct = promptTotal > 0 ? Math.round((cr / promptTotal) * 100) : 0;
-    return `[dario] #${requestCount} usage: in=${inp} out=${out} cache_read=${cr} cache_create=${cc} (${pct}% of prompt from cache)`;
+    return `[dario] #${requestCount} usage: in=${inp} out=${out} cache_read=${cr} cache_create=${cc} (${pct}% of prompt from cache)${consumer ? ` consumer=${consumer}` : ''}`;
 }
 /**
  * The sentinel `claim` dario assigns when a response carried no rate-limit
@@ -115,6 +116,40 @@ export function formatUsageLogLine(requestCount, u) {
  * so the overage-guard must never halt on it.
  */
 export const NO_BILLING_CLAIM = 'unknown';
+/** Request header naming the consumer a request is for. */
+export const CONSUMER_HEADER = 'x-dario-consumer';
+/**
+ * The consumer named by the `x-dario-consumer` header: one printable-ASCII
+ * token, no spaces, at most 64 characters — anything else is treated as
+ * absent rather than becoming an analytics key.
+ */
+export function consumerFromHeader(value) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (typeof raw !== 'string')
+        return undefined;
+    const token = raw.trim();
+    return token.length > 0 && token.length <= 64 && /^[\x21-\x7e]+$/.test(token) ? token : undefined;
+}
+/**
+ * A consumer derived from the request body when no header named one: the
+ * Anthropic `metadata.user_id` (Claude Code sends
+ * `user_<hash>_account_<uuid>_session_<uuid>`; the session part is dropped
+ * so one person is one key across sessions) or the OpenAI `user` field.
+ * Hashed, so no account id or raw user id becomes an analytics key.
+ */
+export function consumerFromBody(body) {
+    if (!body)
+        return undefined;
+    const meta = body.metadata;
+    const userId = meta && typeof meta === 'object' ? meta.user_id : undefined;
+    const raw = typeof userId === 'string' && userId.length > 0 ? userId
+        : typeof body.user === 'string' && body.user.length > 0 ? body.user
+            : undefined;
+    if (!raw)
+        return undefined;
+    const person = raw.match(/^(user_[0-9a-f]+_account_[0-9a-f-]+)_session_/i)?.[1] ?? raw;
+    return 'u_' + createHash('sha256').update(person).digest('hex').slice(0, 12);
+}
 /**
  * True when a claim represents real *non-subscription* billing — the
  * condition the overage-guard halts on (see `overage-guard.ts`, #288).
@@ -276,6 +311,7 @@ export class Analytics extends EventEmitter {
                 ...this.computeStats(allTime),
             },
             perAccount: this.perAccountStats(recent),
+            perConsumer: this.perConsumerStats(recent),
             perModel: this.perModelStats(recent),
             utilization: this.currentUtilization(recent),
             predictions: this.predict(recent),
@@ -364,6 +400,33 @@ export class Analytics extends EventEmitter {
         }
         return result;
     }
+    /** Per-consumer usage — only records that carry a consumer take part. */
+    perConsumerStats(records) {
+        const grouped = {};
+        for (const r of records) {
+            if (!r.consumer)
+                continue;
+            (grouped[r.consumer] ??= []).push(r);
+        }
+        const result = {};
+        for (const [consumer, recs] of Object.entries(grouped)) {
+            const inputTokens = recs.reduce((s, r) => s + r.inputTokens, 0);
+            const cacheReadTokens = recs.reduce((s, r) => s + r.cacheReadTokens, 0);
+            const cacheCreateTokens = recs.reduce((s, r) => s + r.cacheCreateTokens, 0);
+            result[consumer] = {
+                requests: recs.length,
+                inputTokens,
+                outputTokens: recs.reduce((s, r) => s + r.outputTokens, 0),
+                cacheReadTokens,
+                cacheCreateTokens,
+                cachedPromptPercent: cachedPromptPercent(inputTokens, cacheReadTokens, cacheCreateTokens),
+                estimatedCost: Math.round(recs.reduce((s, r) => s + estimateCost(r), 0) * 10000) / 10000,
+                accounts: [...new Set(recs.map((r) => r.account))].sort(),
+                lastModel: recs[recs.length - 1].model,
+            };
+        }
+        return result;
+    }
     perModelStats(records) {
         const grouped = {};
         for (const r of records) {

package/dist/cli.js

@@ -444,6 +444,11 @@ async function proxy() {
         ?? parsePositiveIntEnv(process.env['DARIO_MAX_QUEUED']);
     const queueTimeoutMs = parsePositiveIntFlag('--queue-timeout=')
         ?? parsePositiveIntEnv(process.env['DARIO_QUEUE_TIMEOUT_MS']);
+    // --max-concurrent-per-consumer=N — a per-consumer in-flight ceiling keyed
+    // by the x-dario-consumer header, for a proxy shared by a team: one heavy
+    // user waits at the cap while everyone else keeps flowing. 0 = off.
+    const maxConcurrentPerConsumer = parsePositiveIntFlag('--max-concurrent-per-consumer=')
+        ?? parsePositiveIntEnv(process.env['DARIO_MAX_CONCURRENT_PER_CONSUMER']);
     // --pool-strategy=headroom|fill-first — where UNBOUND (new) conversations
     // land. `headroom` (default) spreads them to the seat with the most slack;
     // `fill-first` concentrates them on the alphabetically-first eligible seat
@@ -459,6 +464,13 @@ async function proxy() {
     const poolStrategy = poolStrategyFromFlag
         ?? process.env['DARIO_POOL_STRATEGY']
         ?? fileCfg.pool?.strategy;
+    // --pool-shared-state — share rate-limit readings and sticky bindings with
+    // the other instances through the refresh-lock service (docs/multi-instance.md).
+    const poolSharedState = args.includes('--pool-shared-state')
+        || process.env['DARIO_POOL_SHARED_STATE'] === '1'
+        || process.env['DARIO_POOL_SHARED_STATE'] === 'true';
+    const poolSharedStateIntervalMs = parsePositiveIntFlag('--pool-shared-state-interval=')
+        ?? parsePositiveIntEnv(process.env['DARIO_POOL_SHARED_STATE_INTERVAL_MS']);
     // --effort=low|medium|high|xhigh|ultracode|max|client — pin the outbound
     // output_config.effort (dario#87). Default (unset) forwards the client's
     // own effort — it's a user knob, real CC wires whatever the user tuned —
@@ -635,7 +647,7 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, poolStrategy, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat });
+    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, poolStrategy, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat });
 }
 /**
  * Parse `--system-prompt=<verbatim|partial|aggressive|filepath>` (or the
@@ -882,8 +894,78 @@ function parsePositiveIntFlag(prefix) {
     }
     return n;
 }
+/**
+ * `dario accounts list --live` — the running proxy's view of the pool
+ * (dario#1244): status with its countdown, the reading and its age, 429s
+ * answered, the organization, and which seats share a window. The on-disk
+ * listing knows none of that. Returns false when no proxy answered, so the
+ * caller falls back to the on-disk listing.
+ */
+async function accountsListLive() {
+    const { loadConfig } = await import('./config-file.js');
+    const fileCfg = loadConfig().config;
+    const portArg = args.find(a => a.startsWith('--port='));
+    const port = (portArg ? parseInt(portArg.split('=')[1], 10) : undefined)
+        ?? (process.env['DARIO_PORT'] ? parseInt(process.env['DARIO_PORT'], 10) : undefined)
+        ?? fileCfg.port ?? 3456;
+    const headers = {};
+    if (process.env['DARIO_API_KEY'])
+        headers['x-api-key'] = process.env['DARIO_API_KEY'];
+    let payload = null;
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/accounts`, { headers, signal: AbortSignal.timeout(3000) });
+        if (res.ok)
+            payload = await res.json();
+        else
+            console.log(`  (proxy on http://127.0.0.1:${port} answered ${res.status} to /accounts — showing the on-disk listing)`);
+    }
+    catch (err) {
+        console.log(`  (no proxy on http://127.0.0.1:${port}: ${err instanceof Error ? err.message : String(err)} — showing the on-disk listing)`);
+    }
+    if (!payload || payload.mode !== 'pool' || !Array.isArray(payload.accounts))
+        return false;
+    const seats = payload.accounts;
+    const now = Date.now();
+    const pct = (n) => `${Math.round(n * 100)}%`;
+    const mins = (ms) => {
+        const m = Math.max(1, Math.round(ms / 60_000));
+        return m >= 60 ? `${Math.floor(m / 60)}h ${m % 60}m` : `${m}m`;
+    };
+    const age = (ms) => ms === null ? 'never measured' : ms < 60_000 ? `read ${Math.round(ms / 1000)}s ago` : `read ${mins(ms)} ago`;
+    console.log('');
+    console.log(`  dario — Accounts (live, from http://127.0.0.1:${port})`);
+    console.log('  ────────────────');
+    console.log('');
+    const windows = payload.distinctWindows ?? seats.length;
+    console.log(`  Pool of ${seats.length} (${seats.length === 1 ? '1 seat' : seats.length + ' seats'} on ${windows} distinct window${windows === 1 ? '' : 's'})`);
+    console.log('');
+    for (const s of seats) {
+        const status = s.status === 'rejected' && typeof s.resetInMs === 'number' ? `rejected, back in ${mins(s.resetInMs)}` : s.status;
+        console.log(`    ${s.alias.padEnd(20)} ${status.padEnd(26)} 5h ${pct(s.util5h).padEnd(6)} 7d ${pct(s.util7d).padEnd(6)} ${age(s.utilAgeMs)}`);
+        // The one-word next step (dario#1244): a parked seat wants nothing from
+        // the operator; an auth-failure streak wants a re-grant.
+        const next = s.action === 'regrant' ? 'next: re-grant this seat (dario accounts remove + add)'
+            : s.action === 'wait' ? 'next: nothing, it comes back on its own'
+                : null;
+        const facts = [
+            `served ${s.requestCount}`,
+            `429s ${s.rejectedCount}`,
+            ...(next ? [next] : []),
+            s.organizationId ? `org ${s.organizationId.slice(0, 8)}…` : 'org not yet observed',
+            ...(s.sharesWindowWith.length > 0 ? [`shares its window with ${s.sharesWindowWith.join(', ')}`] : []),
+        ];
+        console.log(`    ${''.padEnd(20)} ${facts.join('  ·  ')}`);
+        console.log(`    ${''.padEnd(20)} ${describeGrantAge(grantAge(s.grantedAt ?? undefined, now))}`);
+    }
+    console.log('');
+    return true;
+}
 async function accounts() {
     const sub = args[1];
+    if ((!sub || sub === 'list') && args.includes('--live')) {
+        if (await accountsListLive())
+            return;
+    }
     if (!sub || sub === 'list') {
         const aliases = await listAccountAliases();
         console.log('');
@@ -1372,6 +1454,8 @@ async function help() {
                              POSTs /admin/resume on the local proxy. (dario#288)
     dario logout             Remove saved credentials
     dario accounts list      List accounts in the multi-account pool
+                             (--live: the running proxy's view — status,
+                             window, 429s, organization, shared windows)
     dario accounts add NAME [--manual] [--from-keychain[=<target>]]
                              Add a new account to the pool (runs OAuth flow).
                              --manual (alias: --headless) prints an authorize
@@ -1629,6 +1713,21 @@ async function help() {
                              concurrency slot before dario returns
                              429 "queue-full" (default: 128).
                              Env: DARIO_MAX_QUEUED. (dario#80)
+    --max-concurrent-per-consumer=N
+                             Max in-flight requests per consumer, keyed
+                             by the x-dario-consumer request header; a
+                             consumer at the cap waits while others keep
+                             flowing (default: 0 = off).
+                             Env: DARIO_MAX_CONCURRENT_PER_CONSUMER.
+    --pool-shared-state      Share rate-limit readings and sticky bindings
+                             with the other dario instances through the
+                             refresh-lock service (needs
+                             DARIO_REFRESH_LOCK_URL / _TOKEN). Fails open.
+                             Env: DARIO_POOL_SHARED_STATE=1.
+    --pool-shared-state-interval=MS
+                             How often to pull peers' readings
+                             (default: 2000). Env:
+                             DARIO_POOL_SHARED_STATE_INTERVAL_MS.
     --queue-timeout=MS       Max ms a queued request waits before
                              dario returns 504 "queue-timeout"
                              (default: 60000).

package/dist/doctor-core.d.ts

@@ -141,6 +141,21 @@ export declare function checkRefreshGrant(input: {
     now: number;
     thresholds?: GrantThresholds;
 }): Check[];
+export interface OrganizationsInput {
+    accounts: Array<{
+        alias: string;
+        organizationId?: string;
+    }>;
+}
+/**
+ * The Organizations doctor row (dario#1244): which seats sit on which
+ * Anthropic organization, from the id each seat's responses carried. Two
+ * seats on one organization MAY be one subscription counted twice — the
+ * proxy's `/accounts` says for sure via `sharesWindowWith`, because the
+ * window, not the organization, is what two seats can share. Nothing to say
+ * until at least two seats have been observed.
+ */
+export declare function checkOrganizations(input: OrganizationsInput): Check[];
 export declare function checkIdentityDrift(input: IdentityDriftInput): Check[];
 export declare function probeNpmLatestCC(): string | null;
 /**

package/dist/doctor-core.js

@@ -191,6 +191,39 @@ export function checkRefreshGrant(input) {
     const fix = worst === 'ok' ? '' : REGRANT_FIX;
     return [{ status, label: 'Refresh grant', detail: `${perSeat}${fix}` }];
 }
+/**
+ * The Organizations doctor row (dario#1244): which seats sit on which
+ * Anthropic organization, from the id each seat's responses carried. Two
+ * seats on one organization MAY be one subscription counted twice — the
+ * proxy's `/accounts` says for sure via `sharesWindowWith`, because the
+ * window, not the organization, is what two seats can share. Nothing to say
+ * until at least two seats have been observed.
+ */
+export function checkOrganizations(input) {
+    const seen = input.accounts.filter((a) => typeof a.organizationId === 'string' && a.organizationId.length > 0);
+    if (seen.length < 2)
+        return [];
+    const byOrg = new Map();
+    for (const a of seen) {
+        const list = byOrg.get(a.organizationId);
+        if (list)
+            list.push(a.alias);
+        else
+            byOrg.set(a.organizationId, [a.alias]);
+    }
+    const shared = [...byOrg.entries()].filter(([, aliases]) => aliases.length > 1);
+    const unseen = input.accounts.length - seen.length;
+    const head = `${seen.length} seat${seen.length === 1 ? '' : 's'} on ${byOrg.size} organization${byOrg.size === 1 ? '' : 's'}` + (unseen > 0 ? ` (${unseen} not yet observed)` : '');
+    if (shared.length === 0) {
+        return [{ status: 'ok', label: 'Organizations', detail: `${head} — every observed seat is on its own organization` }];
+    }
+    const pairs = shared.map(([org, aliases]) => `${aliases.join(' + ')} share ${org.slice(0, 8)}…`).join('; ');
+    return [{
+            status: 'info',
+            label: 'Organizations',
+            detail: `${head} — ${pairs}. Seats on one organization may be one subscription counted twice: \`sharesWindowWith\` on GET /accounts says so when they report the same window`,
+        }];
+}
 const REGRANT_FIX = " — re-grant with `dario accounts add <alias>` (or `dario login --force-reauth` for the login seat); the new grant restarts the clock";
 export function checkIdentityDrift(input) {
     const { live, poolAccounts } = input;
@@ -935,6 +968,7 @@ export async function runChecks(opts = {}) {
                     (aliases.length === 1 ? ' (a pool of one — `dario accounts add <alias>` to load-balance)' : ''),
             });
             checks.push(...checkRefreshGrant({ accounts: loaded.map((a) => ({ alias: a.alias, grantedAt: a.grantedAt })), now }));
+            checks.push(...checkOrganizations({ accounts: loaded.map((a) => ({ alias: a.alias, organizationId: a.organizationId })) }));
             // Next-account-in-rotation surfacing. The proxy's per-request
             // selector picks by max headroom (with 7d_<family> per-model
             // bucket considered when a request's model family is known);

package/dist/pool-sync.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Shared pool state across dario instances — the two things
+ * docs/multi-instance.md called "not solved": rate-limit accounting and
+ * session stickiness both lived in one process's memory, so two replicas
+ * behind one Service each believed a seat had full headroom, each ate its own
+ * 429 to learn otherwise, and a conversation re-cached its prefix on a
+ * different seat per replica.
+ *
+ * This rides the refresh-lock service (dario#993) — the coordination point
+ * two instances already share, reached through `DARIO_REFRESH_LOCK_URL` /
+ * `DARIO_REFRESH_LOCK_TOKEN` — under three more endpoints, implemented by
+ * both reference backends (redis-lock/, cloudflare/refresh-lock/):
+ *
+ *   POST /pool/seat/<alias>        { instance, at, snapshot, rejected }  → { ok }
+ *   POST /pool/seats               { instance }                          → { seats: { alias: SharedSeat } }
+ *   POST /pool/sticky/<key>/bind   { alias, ttlMs }                      → { ok }
+ *   POST /pool/sticky/<key>/get    {}                                    → { alias | null }
+ *
+ * An instance reports every reading it takes itself, pulls the others'
+ * readings on an interval and adopts any that is newer than its own, and
+ * consults the shared sticky bindings before binding a conversation locally.
+ * Everything fails open: with the service unreachable an instance behaves
+ * exactly as it does with the feature off, and says so once per outage.
+ *
+ * What crosses the wire is rate-limit snapshots and sticky-key → alias
+ * bindings. No token, no message content: the sticky key is a hash of the
+ * first user message, the same one the proxy already keeps in memory.
+ */
+import type { AccountPool, RateLimitSnapshot } from './pool.js';
+/** One instance's last reading of one seat, as the service stores it. */
+export interface SharedSeat {
+    instance: string;
+    /** Epoch ms the reading was taken (the snapshot's own `updatedAt`). */
+    at: number;
+    snapshot: RateLimitSnapshot;
+    /** Whether that instance holds the seat parked on this reading. */
+    rejected: boolean;
+}
+export interface PoolSyncStatus {
+    enabled: true;
+    instance: string;
+    intervalMs: number;
+    lastPullAt: number | null;
+    lastOkAt: number | null;
+    /** Readings taken from peers, cumulative. */
+    adopted: number;
+    /** Own readings pushed, cumulative. */
+    reported: number;
+    stickyPushed: number;
+    stickyAdopted: number;
+    errors: number;
+    lastError: string | null;
+}
+export interface PoolSyncOptions {
+    baseUrl: string;
+    token: string;
+    /** Identity of this instance in the shared state; random when omitted. */
+    instance?: string;
+    /** Pull interval, ms. Default 2000. */
+    intervalMs?: number;
+    /** Sticky binding lifetime on the service, ms. Default 6h (the local TTL). */
+    stickyTtlMs?: number;
+    log?: (line: string) => void;
+}
+export declare const DEFAULT_POOL_SYNC_INTERVAL_MS = 2000;
+/** A peer reading older than this describes windows that have long rolled. */
+export declare const SHARED_SEAT_MAX_AGE_MS: number;
+/**
+ * Whether a peer's reading should replace ours: a different instance, a
+ * complete record, not stale, and strictly newer than what we hold. A
+ * reading we adopted carries the peer's `at` as its `updatedAt`, so the
+ * same record is never adopted twice, and our own later reading (newer
+ * `updatedAt`) wins until a peer reports something newer still.
+ */
+export declare function shouldAdopt(local: RateLimitSnapshot, remote: SharedSeat, me: string, now: number): boolean;
+export declare class PoolSync {
+    private readonly pool;
+    readonly instance: string;
+    readonly intervalMs: number;
+    private readonly stickyTtlMs;
+    private readonly baseUrl;
+    private readonly token;
+    private readonly log;
+    private timer;
+    private reporting;
+    private dirty;
+    private down;
+    private stats;
+    constructor(pool: AccountPool, opts: PoolSyncOptions);
+    /** Start pulling peers' readings on the interval. The timer never keeps the process alive. */
+    start(): void;
+    stop(): void;
+    status(): PoolSyncStatus;
+    /**
+     * Push our reading of `alias`. Fire-and-forget and coalesced: while one
+     * push for the alias is in flight, further calls mark it dirty and one
+     * more push follows with whatever the seat reads then — the latest reading
+     * is the only one worth having.
+     */
+    reportSeat(alias: string): void;
+    /** Pull every peer's readings and adopt the newer ones. Returns how many were adopted. */
+    pullOnce(): Promise<number>;
+    /** The alias a peer bound this conversation to, or null. */
+    lookupSticky(key: string): Promise<string | null>;
+    /** Publish a binding so a peer that sees the conversation next lands on the same seat. A null key (no conversation) is a no-op. */
+    bindSticky(key: string | null, alias: string): void;
+    /**
+     * One POST to the service. Null on any failure — the caller carries on
+     * with local state, which is the whole contract: an outage of the
+     * coordination point must never stop the proxy serving. Logged once per
+     * transition into and out of the failed state, not per call.
+     */
+    private call;
+}

package/dist/pool-sync.js

@@ -0,0 +1,200 @@
+/**
+ * Shared pool state across dario instances — the two things
+ * docs/multi-instance.md called "not solved": rate-limit accounting and
+ * session stickiness both lived in one process's memory, so two replicas
+ * behind one Service each believed a seat had full headroom, each ate its own
+ * 429 to learn otherwise, and a conversation re-cached its prefix on a
+ * different seat per replica.
+ *
+ * This rides the refresh-lock service (dario#993) — the coordination point
+ * two instances already share, reached through `DARIO_REFRESH_LOCK_URL` /
+ * `DARIO_REFRESH_LOCK_TOKEN` — under three more endpoints, implemented by
+ * both reference backends (redis-lock/, cloudflare/refresh-lock/):
+ *
+ *   POST /pool/seat/<alias>        { instance, at, snapshot, rejected }  → { ok }
+ *   POST /pool/seats               { instance }                          → { seats: { alias: SharedSeat } }
+ *   POST /pool/sticky/<key>/bind   { alias, ttlMs }                      → { ok }
+ *   POST /pool/sticky/<key>/get    {}                                    → { alias | null }
+ *
+ * An instance reports every reading it takes itself, pulls the others'
+ * readings on an interval and adopts any that is newer than its own, and
+ * consults the shared sticky bindings before binding a conversation locally.
+ * Everything fails open: with the service unreachable an instance behaves
+ * exactly as it does with the feature off, and says so once per outage.
+ *
+ * What crosses the wire is rate-limit snapshots and sticky-key → alias
+ * bindings. No token, no message content: the sticky key is a hash of the
+ * first user message, the same one the proxy already keeps in memory.
+ */
+import { randomUUID } from 'node:crypto';
+import { describeRateLimitSnapshot, rateLimitWindowPassed } from './pool.js';
+export const DEFAULT_POOL_SYNC_INTERVAL_MS = 2_000;
+/** A peer reading older than this describes windows that have long rolled. */
+export const SHARED_SEAT_MAX_AGE_MS = 6 * 3_600_000;
+const CALL_TIMEOUT_MS = 3_000;
+/**
+ * Whether a peer's reading should replace ours: a different instance, a
+ * complete record, not stale, and strictly newer than what we hold. A
+ * reading we adopted carries the peer's `at` as its `updatedAt`, so the
+ * same record is never adopted twice, and our own later reading (newer
+ * `updatedAt`) wins until a peer reports something newer still.
+ */
+export function shouldAdopt(local, remote, me, now) {
+    if (!remote || remote.instance === me)
+        return false;
+    if (!remote.snapshot || typeof remote.at !== 'number' || !(remote.at > 0))
+        return false;
+    if (now - remote.at > SHARED_SEAT_MAX_AGE_MS)
+        return false;
+    return remote.at > (local.updatedAt || 0);
+}
+export class PoolSync {
+    pool;
+    instance;
+    intervalMs;
+    stickyTtlMs;
+    baseUrl;
+    token;
+    log;
+    timer = null;
+    reporting = new Map();
+    dirty = new Set();
+    down = false;
+    stats = { lastPullAt: null, lastOkAt: null, adopted: 0, reported: 0, stickyPushed: 0, stickyAdopted: 0, errors: 0, lastError: null };
+    constructor(pool, opts) {
+        this.pool = pool;
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.token = opts.token;
+        this.instance = opts.instance ?? randomUUID();
+        this.intervalMs = Math.max(200, opts.intervalMs ?? DEFAULT_POOL_SYNC_INTERVAL_MS);
+        this.stickyTtlMs = opts.stickyTtlMs ?? 6 * 3_600_000;
+        this.log = opts.log ?? ((line) => console.error(line));
+    }
+    /** Start pulling peers' readings on the interval. The timer never keeps the process alive. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => { void this.pullOnce(); }, this.intervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    status() {
+        return { enabled: true, instance: this.instance, intervalMs: this.intervalMs, ...this.stats };
+    }
+    /**
+     * Push our reading of `alias`. Fire-and-forget and coalesced: while one
+     * push for the alias is in flight, further calls mark it dirty and one
+     * more push follows with whatever the seat reads then — the latest reading
+     * is the only one worth having.
+     */
+    reportSeat(alias) {
+        if (this.reporting.has(alias)) {
+            this.dirty.add(alias);
+            return;
+        }
+        const run = async () => {
+            const seat = this.pool.get(alias);
+            if (!seat)
+                return;
+            const body = {
+                instance: this.instance,
+                at: seat.rateLimit.updatedAt || Date.now(),
+                snapshot: seat.rateLimit,
+                rejected: seat.rateLimit.status === 'rejected',
+            };
+            const res = await this.call(`/pool/seat/${encodeURIComponent(alias)}`, body);
+            if (res)
+                this.stats.reported++;
+        };
+        const p = run().finally(() => {
+            this.reporting.delete(alias);
+            if (this.dirty.delete(alias))
+                this.reportSeat(alias);
+        });
+        this.reporting.set(alias, p);
+    }
+    /** Pull every peer's readings and adopt the newer ones. Returns how many were adopted. */
+    async pullOnce() {
+        const now = Date.now();
+        this.stats.lastPullAt = now;
+        const res = await this.call('/pool/seats', { instance: this.instance });
+        if (!res || !res.seats || typeof res.seats !== 'object')
+            return 0;
+        let adopted = 0;
+        for (const [alias, remote] of Object.entries(res.seats)) {
+            const seat = this.pool.get(alias);
+            if (!seat)
+                continue;
+            if (!shouldAdopt(seat.rateLimit, remote, this.instance, now))
+                continue;
+            const wasParked = seat.rateLimit.status === 'rejected' && !rateLimitWindowPassed(seat.rateLimit, now);
+            if (!this.pool.adoptSnapshot(alias, remote.snapshot, remote.rejected, remote.instance))
+                continue;
+            adopted++;
+            // Same event the proxy logs for its own 429s (dario#1244), so a seat
+            // leaving rotation is visible on every instance, not only the one that
+            // took the 429.
+            if (remote.rejected && !wasParked) {
+                this.log(`[dario] seat "${alias}" parked by peer ${remote.instance}'s reading: ${describeRateLimitSnapshot(remote.snapshot, now)} — parked until the window rolls`);
+            }
+        }
+        this.stats.adopted += adopted;
+        return adopted;
+    }
+    /** The alias a peer bound this conversation to, or null. */
+    async lookupSticky(key) {
+        const res = await this.call(`/pool/sticky/${encodeURIComponent(key)}/get`, {});
+        const alias = res?.alias;
+        if (typeof alias === 'string' && alias.length > 0) {
+            this.stats.stickyAdopted++;
+            return alias;
+        }
+        return null;
+    }
+    /** Publish a binding so a peer that sees the conversation next lands on the same seat. A null key (no conversation) is a no-op. */
+    bindSticky(key, alias) {
+        if (!key)
+            return;
+        void this.call(`/pool/sticky/${encodeURIComponent(key)}/bind`, { alias, ttlMs: this.stickyTtlMs })
+            .then((res) => { if (res)
+            this.stats.stickyPushed++; });
+    }
+    /**
+     * One POST to the service. Null on any failure — the caller carries on
+     * with local state, which is the whole contract: an outage of the
+     * coordination point must never stop the proxy serving. Logged once per
+     * transition into and out of the failed state, not per call.
+     */
+    async call(path, body) {
+        try {
+            const res = await fetch(`${this.baseUrl}${path}`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${this.token}` },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const out = (await res.json());
+            this.stats.lastOkAt = Date.now();
+            if (this.down) {
+                this.down = false;
+                this.log(`[dario] pool shared state: service reachable again (${this.baseUrl})`);
+            }
+            return out;
+        }
+        catch (err) {
+            this.stats.errors++;
+            this.stats.lastError = err instanceof Error ? err.message : String(err);
+            if (!this.down) {
+                this.down = true;
+                this.log(`[dario] pool shared state: ${this.baseUrl} unreachable (${this.stats.lastError}) — carrying on with this instance's own state until it answers again`);
+            }
+            return null;
+        }
+    }
+}