@sigrun/sigrun 0.0.0-stage → 0.1.1

package/dist/harness/providers/auth-bridge.js

@@ -0,0 +1,60 @@
+/**
+ * The auth.json → pi-ai credential bridge (provider plugins Task 2).
+ *
+ * pi-ai's `Models` resolves auth through a `CredentialStore` (stored
+ * credentials own the provider; ambient env is consulted only when nothing
+ * is stored) plus an `AuthContext` (ambient `env`/`fileExists` access).
+ * Sigrun's credentials are operator-provisioned through auth.json (the
+ * 2026-10-13 config-surface ruling), so the bridge is READ-ONLY: reads
+ * project the file into `api_key` credentials, with the `"default"`
+ * entry scoped to the default model's provider only (one key must never
+ * leak across plugin providers), and every write path refuses loudly
+ * rather than pretending the harness owns credential lifecycle.
+ *
+ * The `CredentialStore`/`AuthContext`/credential shapes below are
+ * structural re-declarations of pi-ai's, narrowed to the `api_key` subset
+ * this bridge produces (sigrun stores no OAuth credentials). The narrowed
+ * shapes stay assignable to pi-ai's full interfaces at the `createModels`
+ * call site in `collectProviders`.
+ */
+import { DEFAULT_AUTH_KEY } from "../auth.js";
+/** The refusal every write attempt gets: auth.json is operator-owned. */
+export function operatorProvisionedError() {
+    return new Error("sigrun credentials are operator-provisioned; edit auth.json");
+}
+/**
+ * Adapt an {@link AuthStore} into a pi-ai `CredentialStore`.
+ *
+ * `read(providerId)` returns `{type:"api_key", key}` from auth.json.
+ * The `"default"` entry applies ONLY when `providerId` is the resolved
+ * default model's provider (`defaultProviderId()`, consulted per read,
+ * never cached); for it the order is `"default"` → own entry. Every
+ * other provider reads only its own entry; `undefined` when nothing
+ * matches. `list()` maps the file's provider keys. `modify`/`delete`
+ * throw: credentials are operator-provisioned.
+ */
+export function authStoreCredentialStore(auth, defaultProviderId) {
+    return {
+        read: async (providerId) => {
+            const file = auth.read();
+            if (providerId === defaultProviderId()) {
+                const fromDefault = file[DEFAULT_AUTH_KEY]?.apiKey;
+                if (fromDefault !== undefined) {
+                    return { type: "api_key", key: fromDefault };
+                }
+            }
+            const fromProvider = file[providerId]?.apiKey;
+            if (fromProvider !== undefined) {
+                return { type: "api_key", key: fromProvider };
+            }
+            return undefined;
+        },
+        list: async () => Object.keys(auth.read()).map((providerId) => ({ providerId, type: "api_key" })),
+        modify: async () => {
+            throw operatorProvisionedError();
+        },
+        delete: async () => {
+            throw operatorProvisionedError();
+        },
+    };
+}

package/dist/harness/providers/index.js

@@ -0,0 +1,277 @@
+/**
+ * The provider-contributor contract (spec §3 "Model providers").
+ *
+ * Extensions may contribute pi-ai `createProvider()` results plus a default
+ * model at boot; the core merges all contributions into one `Models` store
+ * before `Harness.open()`. Merge semantics are deterministic,
+ * **last-registered-wins** on provider-id/model-id collision, and every
+ * collision is recorded in a {@link ProviderMergeSink} — never silent — so
+ * `GET /v1/meta` (Task 9) can surface it.
+ *
+ * `SIGRUN_DEFAULT_MODEL` (or the file's `defaultModel`) overrides any
+ * contributor default. When no extension contributes a provider for the
+ * pinned namespace, the env-driven OpenAI-compat degenerate provider
+ * serves it — its credentials resolve from `auth.json` (the `"default"`
+ * key, or the resolved provider's own entry) with `OPENAI_API_KEY` as
+ * the compat fallback. Each contributor's §3 `health()` producer is
+ * retained on the collected result for the §5 meta `health.providers`
+ * aggregation (Task 9e); the degenerate provider reports `"ok"` by
+ * absence.
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { createModels, createProvider, } from "@earendil-works/pi-ai/models";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import { parseModelSpec } from "../../config.js";
+import { DEFAULT_AUTH_KEY } from "../auth.js";
+import { authStoreCredentialStore, } from "./auth-bridge.js";
+export function createProviderMergeSink() {
+    const collisions = [];
+    return {
+        record: (collision) => {
+            collisions.push(collision);
+            console.warn(`provider collision: ${collision.contributor} replaces ${collision.previous} ` +
+                `provider "${collision.provider}"` +
+                (collision.modelIds.length > 0
+                    ? ` (models: ${collision.modelIds.join(", ")})`
+                    : ""));
+        },
+        get collisions() {
+            return collisions;
+        },
+    };
+}
+/** Environment keys the degenerate env provider reads. */
+export const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+export const OPENAI_BASE_URL_ENV = "OPENAI_BASE_URL";
+/** Fallback when `OPENAI_BASE_URL` is unset: OpenAI's public API. */
+export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+/**
+ * Conservative defaults for an unknown OpenAI-compat model. Context
+ * management (Task 8) tunes its policy against the default model's window;
+ * these placeholders keep that deterministic before tuning.
+ */
+export const DEFAULT_OPENAI_CONTEXT_WINDOW = 128_000;
+export const DEFAULT_OPENAI_MAX_TOKENS = 16_384;
+/**
+ * Merge contributor providers into one `Models` store, then install the
+ * env-driven degenerate `openai` provider when no contributor contributed
+ * one. Deterministic order: contributors in array order, each provider
+ * upserting by id (last-registered-wins), then the env default — a designed
+ * fallback, never a collision.
+ *
+ * @param env raw environment (`process.env`); a set `SIGRUN_DEFAULT_MODEL`
+ * overrides every contributor default and names the model the env provider
+ * serves.
+ * @param sink receives collisions; defaults to a fresh sink. Boot passes the
+ * sink it returns so `GET /v1/meta` reads the same list.
+ *
+ * @throws Error naming `SIGRUN_DEFAULT_MODEL` when no default model is
+ * configured and no contributor proposed one — there would be no boot
+ * default at all.
+ */
+export function collectProviders(extensions, env, sink = createProviderMergeSink(), options) {
+    // The auth bridge: with a credential store present, auth.json owns
+    // stored credentials for every contributed + degenerate provider —
+    // except `"default"`, which applies only to the provider of the
+    // resolved default model (the closure reads `defaultModel` as it
+    // stands at each `read()`, so the post-loop resolution governs); the
+    // auth context keeps ambient env/file lookups on the operator-provided
+    // environment (the options.env seam first, then the raw env).
+    const authContext = {
+        env: async (name) => options?.env?.[name] ?? env[name],
+        fileExists: (path) => Promise.resolve(existsSync(path.startsWith("~") ? homedir() + path.slice(1) : path)),
+    };
+    const models = createModels({
+        ...(options?.auth === undefined
+            ? {}
+            : {
+                credentials: authStoreCredentialStore(options.auth, () => defaultModel?.provider),
+            }),
+        ...(options?.modelsStore === undefined
+            ? {}
+            : { modelsStore: options.modelsStore }),
+        authContext,
+    });
+    let defaultModel;
+    const ownership = new Map();
+    const readinessTrackers = new Map();
+    const healthProducers = [];
+    for (const extension of extensions) {
+        // §3 producers are collected from every contributor that defines one,
+        // independent of its provider contributions (a health-only contributor
+        // still reports its surface's health).
+        if (extension.health !== undefined) {
+            healthProducers.push({
+                name: extension.name,
+                health: extension.health,
+            });
+        }
+        for (const contribution of extension.providers ?? []) {
+            const provider = contribution.provider;
+            const previous = ownership.get(provider.id);
+            if (previous !== undefined) {
+                const replaced = modelIdsOf(models, provider.id);
+                sink.record({
+                    kind: "provider",
+                    provider: provider.id,
+                    // Record every model the replaced provider served, not just the ids the
+                    // incoming one re-declares — a contributor replacing `{m1,m2}` with `{m2}`
+                    // silently drops `m1`; meta must surface the full set that changed.
+                    modelIds: replaced,
+                    previous,
+                    contributor: extension.name,
+                });
+            }
+            ownership.set(provider.id, extension.name);
+            // Task 6: the OWNING contributor's tracker is authoritative — a
+            // replacing contribution without one clears a replaced
+            // contributor's tracker (last-registered-wins, like ownership).
+            if (contribution.readiness !== undefined) {
+                readinessTrackers.set(provider.id, contribution.readiness);
+            }
+            else {
+                readinessTrackers.delete(provider.id);
+            }
+            models.setProvider(provider);
+            if (contribution.defaultModel !== undefined) {
+                defaultModel = contribution.defaultModel;
+            }
+        }
+    }
+    // A configured default model (env `SIGRUN_DEFAULT_MODEL` / deprecated
+    // alias `SIGRUN_MODEL`, or the file's `defaultModel` — the caller
+    // restates the resolution into the env seam) overrides any contributor
+    // default.
+    const envSpec = env.SIGRUN_DEFAULT_MODEL?.trim() || env.SIGRUN_MODEL?.trim();
+    if (envSpec) {
+        defaultModel = parseModelSpec(envSpec);
+    }
+    if (defaultModel === undefined) {
+        throw new Error("SIGRUN_DEFAULT_MODEL or settings.json defaultModel is required when no provider contributor proposes a default model " +
+            "(format: provider/model-id, e.g. openai/gpt-4o)");
+    }
+    // Degenerate fallback: when no extension contributed a provider for the
+    // pinned default model's namespace, register the env-driven OpenAI-compat
+    // provider there (any namespace), so a zero-extension boot still serves its
+    // pin instead of leaving the catalog empty and failing loud at submit.
+    if (!models.getProvider(defaultModel.provider)) {
+        models.setProvider(envDegenerateProvider(env, defaultModel.provider, defaultModel.modelId, options));
+    }
+    return {
+        models,
+        defaultModel,
+        healthProducers,
+        providerOwnership: ownership,
+        readinessTrackers,
+    };
+}
+/**
+ * Resolve the env-driven degenerate provider's API key (ruling 6). Order:
+ * auth.json `"default".apiKey`, then the resolved provider's own auth.json
+ * entry, then the `OPENAI_API_KEY` env var (compat fallback, still
+ * honored). Key material is never logged — this function returns it
+ * opaquely.
+ */
+function resolveDegenerateApiKey(env, providerId, auth) {
+    if (auth !== undefined) {
+        const file = auth.read();
+        const fromDefault = file[DEFAULT_AUTH_KEY]?.apiKey;
+        if (fromDefault !== undefined)
+            return fromDefault;
+        const fromProvider = file[providerId]?.apiKey;
+        if (fromProvider !== undefined)
+            return fromProvider;
+    }
+    return env[OPENAI_API_KEY_ENV]?.trim() || undefined;
+}
+function modelIdsOf(models, providerId) {
+    return models.getModels(providerId).map((model) => model.id);
+}
+function modelIdsOfProvider(provider) {
+    try {
+        return provider.getModels().map((model) => model.id);
+    }
+    catch {
+        // Best-effort collision detail (matches `Models.getModels` semantics).
+        return [];
+    }
+}
+/**
+ * The degenerate env-driven OpenAI-compat provider: exactly one model — the
+ * id the default-model spec selected — streamed over `openai-completions`,
+ * with auth resolved from `auth.json` (`"default"` key or the provider's
+ * own entry) falling back to `OPENAI_API_KEY`, and the endpoint from
+ * `OPENAI_BASE_URL` over `options.baseUrl` (the file's
+ * `defaultProvider.baseUrl`, projected by `openHarness`) over the OpenAI
+ * public default (verified shape, App C: `{ auth: { apiKey, baseUrl } }`).
+ * Credentials resolve to `undefined` when no key exists anywhere, so the
+ * provider registers unconfigured and requests fail loud instead of boot
+ * failing.
+ *
+ * `cost` is required by the `Model` shape but unknown for an arbitrary
+ * gateway model, so it is zeroed; usage tracking stays structural.
+ */
+export function envDegenerateProvider(env, providerId, modelId, options) {
+    const apiKey = resolveDegenerateApiKey(env, providerId, options?.auth);
+    const baseUrl = env[OPENAI_BASE_URL_ENV]?.trim() ||
+        options?.baseUrl ||
+        DEFAULT_OPENAI_BASE_URL;
+    const model = {
+        id: modelId,
+        name: modelId,
+        api: "openai-completions",
+        provider: providerId,
+        baseUrl,
+        input: ["text", "image"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        reasoning: false,
+        contextWindow: DEFAULT_OPENAI_CONTEXT_WINDOW,
+        maxTokens: DEFAULT_OPENAI_MAX_TOKENS,
+    };
+    return createProvider({
+        id: providerId,
+        name: `OpenAI-compatible (env, ${providerId})`,
+        baseUrl,
+        auth: {
+            apiKey: {
+                name: "OpenAI-compatible API key (auth.json or OPENAI_API_KEY)",
+                resolve: async () => apiKey === undefined
+                    ? undefined
+                    : { auth: { apiKey, baseUrl }, source: OPENAI_API_KEY_ENV },
+            },
+        },
+        models: [model],
+        api: openAICompletionsApi(),
+    });
+}
+/** Error thrown when a referenced model is served by no contributed provider. */
+export class UnservedModelError extends Error {
+    ref;
+    /** Every served `provider/model-id` at the time of the check. */
+    available;
+    constructor(ref, available) {
+        super(`Model ${ref.provider}/${ref.modelId} is not available. Available models: ` +
+            `${available.length > 0 ? available.join(", ") : "(none)"}.`);
+        this.name = "UnservedModelError";
+        this.ref = ref;
+        this.available = available;
+    }
+}
+/**
+ * Resolve a model reference against the merged catalog, failing loud with
+ * the available ids when no contributor serves it — never a silent
+ * fallback. Task 9 maps this to the submit-time 4xx; the harness's own
+ * generation path fails independently (`no_model`, run unanswered).
+ */
+export function requireServedModel(models, ref) {
+    const model = models.getModel(ref.provider, ref.modelId);
+    if (model === undefined) {
+        throw new UnservedModelError(ref, listServedModelIds(models));
+    }
+    return model;
+}
+/** Every served chat model as `provider/model-id`, in catalog order. */
+export function listServedModelIds(models) {
+    return models.getModels().map((model) => `${model.provider}/${model.id}`);
+}

package/dist/harness/providers/models-store.js

@@ -0,0 +1,105 @@
+/**
+ * The file-backed pi-ai `ModelsStore` (provider plugins Task 3).
+ *
+ * Dynamic providers (`refreshModels`) publish their catalogs through the
+ * store `createModels` was built with; pi-ai writes every publication via
+ * `write` and restores it via `read` at the next boot's offline init. This
+ * implementation persists one JSON file per provider under
+ * `<dir>/models/<sanitized-provider-id>.json`, so a restart serves the
+ * last known catalog without network access.
+ *
+ * Poison resistance: a catalog file that fails to parse (or parses without
+ * a `models` array) is logged — the path, never the content — deleted, and
+ * reported as absent. A poisoned catalog degrades to "fetch it again",
+ * never a boot crash.
+ */
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/** Characters a flattened provider id keeps; everything else becomes `_`. */
+const SAFE_FILENAME = /[^A-Za-z0-9-]/g;
+/** Monotonic scratch-file counter: concurrent writes never share a tmp name. */
+let scratchCounter = 0;
+/**
+ * Flatten a provider id into a safe filename component. Dots are NOT in the
+ * safe set, so no flattened id can form `.`, `..`, or a hidden file, and a
+ * `/`-shaped id (e.g. `acme/gw`) stays inside the models dir as `acme_gw`.
+ * Flattening is many-to-one: provider ids differing only in unsafe
+ * characters share a file — sigrun provider ids are slugs, so this never
+ * happens in practice, and the collision costs one re-fetch, not data loss.
+ */
+function flattenProviderId(providerId) {
+    const flat = providerId.replace(SAFE_FILENAME, "_");
+    return flat.length > 0 ? flat : "_";
+}
+/** Is a parsed catalog file shaped like a `ModelsStoreEntry`? */
+function isEntryShape(parsed) {
+    return (typeof parsed === "object" &&
+        parsed !== null &&
+        Array.isArray(parsed.models));
+}
+/**
+ * Build a `ModelsStore` rooted at `dir`: one JSON file per provider under
+ * `<dir>/models/`.
+ *
+ * Writes are atomic — the serialized entry lands in a uniquely named
+ * `<file>.<pid>-<n>.tmp` first, then `rename` swaps it in — so a crash
+ * mid-write can never leave a half-written catalog, and failed writes
+ * unlink their scratch file. The `AbortSignal` parameters of pi-ai's store
+ * contract are accepted but unused: operations are tiny local-file writes
+ * and reads, not cancellable network work.
+ */
+export function fileModelsStore(dir) {
+    const modelsDir = join(dir, "models");
+    const providerPath = (providerId) => join(modelsDir, `${flattenProviderId(providerId)}.json`);
+    /** Warn (path, never content), delete the poisoned file, report absent. */
+    const discardCorrupt = async (path, why) => {
+        console.warn(`models-store: corrupt catalog file ${path} (${why}); deleting — it will be re-fetched`);
+        await rm(path, { force: true });
+    };
+    return {
+        read: async (providerId) => {
+            const path = providerPath(providerId);
+            let raw;
+            try {
+                raw = await readFile(path, "utf8");
+            }
+            catch (error) {
+                if (typeof error === "object" &&
+                    error !== null &&
+                    error.code === "ENOENT") {
+                    return undefined;
+                }
+                throw error;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                await discardCorrupt(path, "not valid JSON");
+                return undefined;
+            }
+            if (!isEntryShape(parsed)) {
+                await discardCorrupt(path, "models must be an array");
+                return undefined;
+            }
+            return parsed;
+        },
+        write: async (providerId, entry) => {
+            await mkdir(modelsDir, { recursive: true });
+            const path = providerPath(providerId);
+            const scratch = `${path}.${process.pid}-${scratchCounter++}.tmp`;
+            try {
+                await writeFile(scratch, JSON.stringify(entry), "utf8");
+                await rename(scratch, path);
+            }
+            catch (error) {
+                await rm(scratch, { force: true });
+                throw error;
+            }
+        },
+        delete: async (providerId) => {
+            await rm(providerPath(providerId), { force: true });
+        },
+    };
+}

package/dist/harness/providers/refresh.js

@@ -0,0 +1,161 @@
+/**
+ * Core-owned refresh policy (spec §"Core: refresh policy"): WHEN pi-ai's
+ * refresh runs. The protocol is pi-ai's — `Models.refresh({providers,
+ * allowNetwork, signal})` drives every dynamic provider, per-provider
+ * failures land in `ModelsRefreshResult.errors` without rejecting, and a
+ * failed refresh retains the previous catalog by contract. This module
+ * owns the two policy call sites:
+ *
+ * 1. {@link bootRefresh} — one network-allowed refresh started by boot
+ *    fire-and-tracked (never awaited on the boot path — it runs
+ *    concurrently with `Harness.open` and listen), bounded by a deadline
+ *    (default {@link DEFAULT_REFRESH_TIMEOUT_MS}) so a wedged upstream
+ *    cannot stall deploy readiness. Timeout/failure only warns
+ *    (`console.warn` — repo convention, no shared logger): the server
+ *    starts, readiness reports the provider's state, the interval
+ *    refresh heals.
+ * 2. {@link resolveServedModelRefreshing} — refresh-on-miss at the submit
+ *    call site: ONE bounded refresh of the named provider + re-resolve
+ *    when `requireServedModel` reports a miss, so a model added upstream
+ *    five minutes after the last interval tick is immediately usable
+ *    instead of a 4xx. Still absent → the ORIGINAL
+ *    {@link UnservedModelError} rethrows (the available-ids snapshot the
+ *    caller surfaces is the one from the first check). The auto-namer's
+ *    model resolution deliberately does NOT go through this wrapper —
+ *    naming is a background lane (spec ruling).
+ */
+import { requireServedModel, UnservedModelError } from "./index.js";
+/**
+ * The refresh deadline default (boot and refresh-on-miss share it): long
+ * enough for a real catalog fetch, short enough that a wedged upstream
+ * cannot stall deploy readiness or hang a submit.
+ */
+export const DEFAULT_REFRESH_TIMEOUT_MS = 30_000;
+/**
+ * The fallback readiness snapshot (no derivation wired): provider id →
+ * `"ready"` for every catalog provider. Boot always wires
+ * `snapshotReadiness`; this keeps the option structurally optional.
+ */
+export function refreshReadinessSnapshot(models) {
+    const snapshot = new Map();
+    for (const provider of models.getProviders()) {
+        snapshot.set(provider.id, "ready");
+    }
+    return snapshot;
+}
+/**
+ * One network-allowed refresh of every dynamic provider, bounded by
+ * `opts.timeoutMs`. Never rejects and never blocks boot beyond the
+ * deadline: an aborted (deadline/cancelled) or failed refresh logs ONE
+ * `console.warn` naming what did not complete — the catalogs simply stay
+ * at their last-known state. Boot starts this fire-and-tracked; the
+ * tracked promise rides on `OpenedHarness.bootRefresh`.
+ */
+export async function bootRefresh(models, opts) {
+    await refreshBounded(models, { label: "boot refresh", ...opts });
+}
+/**
+ * One bounded single-provider refresh (core hardening W3 Task 6, spec
+ * §7.6): the exact refresh {@link resolveServedModelRefreshing} runs on
+ * a miss, exposed for the provider ROUTES (`POST
+ * /v1/providers/:id/refresh` and the credential write paths) — never a
+ * second policy. Accepts the same {@link RefreshBound} fields the boot
+ * and interval refreshes take (boot wiring passes its readiness
+ * observer so a flipped provider publishes `providers.changed`); every
+ * field is optional with the policy defaults applying. Like every
+ * policy refresh: never rejects — failures/aborts warn once and the
+ * catalog holds its last-known state.
+ */
+export async function refreshProvider(models, providerId, opts = {}) {
+    await refreshBounded(models, {
+        label: `provider refresh (${providerId})`,
+        ...opts,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_REFRESH_TIMEOUT_MS,
+        providers: [providerId],
+    });
+}
+/**
+ * `requireServedModel` with ONE refresh+retry: on an
+ * {@link UnservedModelError}, refresh the named provider (bounded; its
+ * failures only warn — a failed refresh is not a submit error) and
+ * re-resolve. Still absent after the retry → the ORIGINAL miss rethrows,
+ * available ids attached. The submit call site wraps its resolution in
+ * this; the auto-namer's resolution stays on bare `requireServedModel`.
+ */
+export async function resolveServedModelRefreshing(models, ref, opts = {}) {
+    let miss;
+    try {
+        return requireServedModel(models, ref);
+    }
+    catch (error) {
+        if (!(error instanceof UnservedModelError))
+            throw error;
+        miss = error;
+    }
+    await refreshBounded(models, {
+        label: `refresh-on-miss (${ref.provider})`,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_REFRESH_TIMEOUT_MS,
+        ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+        providers: [ref.provider],
+    });
+    try {
+        return requireServedModel(models, ref);
+    }
+    catch {
+        // Still absent: rethrow the ORIGINAL miss. `requireServedModel`
+        // only ever throws UnservedModelError, and the available-ids list
+        // the caller surfaces is deliberately the first check's snapshot.
+        throw miss;
+    }
+}
+/**
+ * The shared bounded refresh: `allowNetwork: true`, an abort controller
+ * armed at `timeoutMs` (unref'd — a bare boot never holds the process
+ * open) and OR-ed with any caller signal, errors/aborts collapsed into
+ * one `console.warn`. `refresh()` itself reports per-provider failures
+ * through its result rather than rejecting; the catch is the belt for the
+ * unexpected throw — either way this resolves, never rejects.
+ */
+async function refreshBounded(models, opts) {
+    const controller = new AbortController();
+    const signal = opts.signal === undefined
+        ? controller.signal
+        : AbortSignal.any([opts.signal, controller.signal]);
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    timer.unref?.();
+    try {
+        const result = await models.refresh({
+            allowNetwork: true,
+            ...(opts.providers === undefined ? {} : { providers: opts.providers }),
+            signal,
+        });
+        if (result.aborted) {
+            console.warn(`${opts.label} aborted before completing (deadline ${opts.timeoutMs}ms) — ` +
+                `provider catalogs stay at their last-known state`);
+            return;
+        }
+        if (result.errors.size > 0) {
+            const failed = [...result.errors]
+                .map(([id, error]) => `${id} (${error instanceof Error ? error.message : String(error)})`)
+                .join("; ");
+            console.warn(`${opts.label} failed for ${result.errors.size} provider(s): ${failed}`);
+        }
+        // The readiness observation runs for EVERY completed refresh
+        // (success or partial failure) so a provider that flips either way
+        // is observed; a refresh that threw before completing holds the
+        // previous snapshot (the catch below skips the observer).
+        try {
+            const snapshot = (opts.snapshotReadiness ?? refreshReadinessSnapshot)(models);
+            opts.onReadinessChange?.(snapshot);
+        }
+        catch (error) {
+            console.warn(`${opts.label}: readiness observation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    catch (error) {
+        console.warn(`${opts.label} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}