@edgehero/pi-dispatch 2.1.0 → 3.0.0

package/src/init.mjs

@@ -14,6 +14,7 @@ import { parseBackendList, venuesOf } from "./backends.mjs";
 import { deploymentVenueEnv } from "./deployment-venue.mjs";
 import { setEnvKeyIfEmpty } from "./env-file.mjs";
 import { PACKAGED_EGRESS_PROXY_CONF } from "./egress-conf-copy.mjs";
+import { EMPTY_MODEL_ENDPOINTS, MODEL_ENDPOINTS_FILE_NAME, MODEL_ENDPOINTS_INCLUDE_NAME, renderEndpointsInclude } from "./model-endpoints.mjs";
 import { VALKEY_PASSWORD_KEY, newValkeyPassword } from "./valkey-auth.mjs";
 
 const EMPTY_TRIGGERS = `${JSON.stringify({ triggers: [] }, null, 2)}\n`;
@@ -34,6 +35,9 @@ const EMPTY_SUBSCRIPTIONS = `${JSON.stringify({ version: 1, subscriptions: [] },
 // Versioned for the subscriptions reason, sharpened: this is enforcement config, and a silently
 // down-read newer file would be a silently widened spend limit.
 export const EMPTY_SCOPED_LIMITS = `${JSON.stringify({ version: 1, limits: [] }, null, 2)}\n`;
+// Projects (issue #499): named groups of repos and folders, recorded per run. Empty is inert: every run records no
+// project. Versioned for the scoped-limits reason, since part B of the issue caps a project as one.
+export const EMPTY_PROJECTS = `${JSON.stringify({ version: 1, projects: [] }, null, 2)}\n`;
 /**
  * The egress allowlist (REQ-EGRESS-ALLOWLIST): the hosts a job container may reach, one bare hostname per
  * line. Scaffolded with the three a job cannot work without, and NOT empty -- unlike every other scaffold
@@ -105,6 +109,10 @@ export function runInit(cwd = process.cwd(), deps = {}) {
 			// Issue #468: the new file carries this deployment's own Valkey password (the example's `# VALKEY_PASSWORD=` line
 			// filled in, never shown) and is created readable by this account alone: it holds that password and, soon, the
 			// provider key. `wx`: a file that appeared since the check above is never overwritten (init's contract).
+			// Its GROUP is the folder's choice and left so (issue #522): on macOS a new file takes the folder's group (`wheel`
+			// under `/private/tmp`), and on Linux a setgid folder's, which is how a shared deployment gives the service its
+			// group. Setting this account's group here was considered and rejected: it would undo that shared layout, and the
+			// writer `up` uses keeps whatever group a new file there gets, so the fresh file is never refused for it.
 			const text = setEnvKeyIfEmpty(String(fs.readFileSync(source, "utf8")), VALKEY_PASSWORD_KEY, newPassword(), { platform });
 			if (createOnly(fs, envPath, text, { mode: 0o600 })) results.push(["created", ".env", `from .env.example, mode 0600, with a generated ${VALKEY_PASSWORD_KEY} (value not shown): set your provider key next`]);
 			else results.push(["kept", ".env", KEPT]);
@@ -115,7 +123,17 @@ export function runInit(cwd = process.cwd(), deps = {}) {
 		scaffold(fs, results, join(cwd, "pi-packages.json"), EMPTY_PACKAGES, "empty pi package list (stage with import-pi --with-packages)");
 		scaffold(fs, results, join(cwd, "subscriptions.json"), EMPTY_SUBSCRIPTIONS, "empty subscription list (declare plan prices for the admin's cost analytics)");
 		scaffold(fs, results, join(cwd, "scoped-limits.json"), EMPTY_SCOPED_LIMITS, "empty scoped-limits list (per repo/folder caps; the folder mutex needs no file)");
+		scaffold(fs, results, join(cwd, "projects.json"), EMPTY_PROJECTS, "empty projects list (group repos and folders into a project, recorded per run)");
+		// Issue #504 part B: NO envelope.json. Unset is no delegation, the safe default, and an envelope is a decision (a
+		// total, a floor per project, the delegation rules) with no neutral empty form: a scaffold would either govern every
+		// job or refuse the boot. The .env written above documents PI_ENVELOPE_FILE (from .env.example), and
+		// docs/allocation.md the file.
 		scaffold(fs, results, join(cwd, "egress-allowlist.conf"), DEFAULT_EGRESS_ALLOWLIST, "egress allowlist (provider + forge + registry; the egress policy is on unless PI_EGRESS=0)");
+		// Issue #503: the declared model endpoints, empty, and the proxy include rendered from them, which is the empty
+		// render (its header only). squid refuses to start on a missing include file and starts on a comments-only one
+		// (measured), so the include exists from the first init even with nothing declared.
+		scaffold(fs, results, join(cwd, MODEL_ENDPOINTS_FILE_NAME), EMPTY_MODEL_ENDPOINTS, "empty model endpoints list (local or LAN model servers a job may reach through the proxy)");
+		scaffold(fs, results, join(cwd, MODEL_ENDPOINTS_INCLUDE_NAME), renderEndpointsInclude([]), "the proxy's rules for those endpoints, none yet (generated: do not edit)");
 		// Issue #480: the proxy's rules, the file beside the allowlist that the docker proxy mounts. Create-only like every
 		// scaffold here, so a clone's own deploy/egress-proxy.conf is reported and kept. The one scaffold whose content is
 		// not this module's: it is the package's file verbatim, read from the package and never through `fs` (the

package/src/job-id.mjs

@@ -6,17 +6,40 @@ import { forgeSpec } from "./forges.mjs";
  * A deterministic jobId for a local job. BullMQ's dedup is `EXISTS jobId`, so a double-invoke of
  * the same task within the same minute produces the same id and the duplicate is ignored -- the
  * local equivalent of REQ-DEDUP-BY-DELIVERY-GUID, guarding against a hasty second Enter
- * double-spending, without blocking a deliberate re-run a minute later.
+ * double-spending, without blocking a deliberate re-run a minute later. The model fields (provider, model,
+ * models) are part of the task's identity: the same task on another model is a different run.
  *
  * Kept free of any bullmq import so the dedup logic is testable everywhere, not only where the
  * queue's dependencies are installed.
  */
-export function localJobId({ folder, flow, task, minute }) {
+export function localJobId({ folder, flow, task, minute, provider, model, models }) {
+	// The model fields join the key (issue #544): two runs that differ only in the model are two runs, and with the
+	// key blind to them the second was dropped as a duplicate. Appended only when one is set, so a job that names no
+	// model keeps the id it always had. `models` is JSON so a list cannot collide with a differently split one.
+	const modelFields = provider === undefined && model === undefined && models === undefined ? [] : [provider ?? "", model ?? "", models === undefined ? "" : JSON.stringify(models)];
 	// NUL-delimited so {folder:'a',task:'bc'} and {folder:'ab',task:'c'} cannot collide.
-	const digest = createHash("sha256").update([folder, flow ?? "", task ?? "", minute].join("\0")).digest("hex");
+	const digest = createHash("sha256").update([folder, flow ?? "", task ?? "", minute, ...modelFields].join("\0")).digest("hex");
 	return `local-${digest.slice(0, 16)}`;
 }
 
+/**
+ * The jobId of a cron trigger fired by hand (`pi-dispatch run --trigger <id>`, issue #505): `manual:<id>:<millis>`,
+ * the millis floored to the minute. Floored so the same command twice inside one minute is the same id, and the
+ * queue keeps the first: the dedup `localJobId` gives `pi-dispatch run`, for the same reason (a hasty second Enter
+ * must not pay twice). A later minute is a new id, so a deliberate re-run is never blocked.
+ *
+ * The shape is BullMQ's, not a choice: a custom id that holds a `:` is refused unless it splits into exactly three
+ * parts (bullmq `Job.addJob`, "Custom Id cannot contain :"), which is how its own `repeat:<id>:<millis>` passes. A cron
+ * id can hold no `:` (the triggers loader refuses one), so this always splits into three. An ISO time would add two
+ * more. The `manual:` prefix keeps it apart from a scheduled run's `repeat:` id, which is what tells the event writer
+ * (`localEventContext`) there is no scheduled instant to report.
+ */
+export function manualTriggerJobId({ triggerId, now }) {
+	if (typeof triggerId !== "string" || triggerId === "" || triggerId.includes(":")) throw new TypeError("a cron trigger id is a non-empty string with no ':'");
+	const millis = Math.floor(now.getTime() / 60_000) * 60_000;
+	return `manual:${triggerId}:${millis}`;
+}
+
 /**
  * The retry-idempotent jobId for a chained (outbox-requested) child job: `parent id + content-hash of
  * (flow, task)`, with NO time component. BullMQ's dedup is `EXISTS jobId`, so a retried parent

package/src/live-probes.mjs

@@ -452,10 +452,11 @@ export function imagePinningVerdict({ code, output, stillAbsent, bin = "docker"
 }
 
 /**
- * EGRESS, folded in from `doctor.mjs`'s canary: two containers on a job-shaped network behind the proxy, one that
- * must reach the provider and one that must not reach an unlisted host. `results` is `[{ want, reached }]` from the
- * canary's `readBack`; anything short of both readings -- the policy off, the proxy down, the canary skipped -- is
- * "not read back", never a pass.
+ * EGRESS, folded in from `doctor.mjs`'s canary: three containers on a job-shaped network behind the proxy, one that
+ * must reach the provider, one that must not reach an unlisted host, and one that must not get plain HTTP through to a
+ * listed host on a port other than 80 (issue #508). `results` is `[{ want, reached, probe }]` from the canary's
+ * `readBack`, `probe` naming which of the three it is; anything short of all three readings -- the policy off, the
+ * proxy down, the canary skipped -- is "not read back", never a pass.
  *
  * Each venue hands in its OWN canary's readings: docker's from doctor's egress lines, the podman venue's from the canary
  * its `--live` runs under Podman (issue #431), so "see the egress lines above" names lines about the proxy that venue's
@@ -466,15 +467,29 @@ export function egressVerdict({ armed, results, keeperBlocked = null }) {
 	if (armed !== true) return notReadBack("egress", "PI_EGRESS is off, so there is no policy to read back");
 	// Issue #458: the podman venue on Podman 4.x without its keeper runs no canary, since its teardown would break the proxy.
 	if (keeperBlocked) return notReadBack("egress", `the egress canary was not run, because ${keeperBlocked} (see the keeper line above)`);
-	if (!Array.isArray(results) || results.length < 2) return notReadBack("egress", "the egress canary did not run both probes (see the egress lines above)");
-	// A WRONG reading fails first, whatever else is missing: an unlisted host that was reached is a finding even when
-	// the provider probe did not run, and reporting it as merely unread would pass doctor over it.
+	// Each of the three probes exactly once, by NAME (issue #508, gate round 1): a count alone read two unlisted readings,
+	// or three with no probe named, as a canary that ran all three.
+	const probes = Array.isArray(results) ? results.map((r) => r?.probe) : [];
+	if (probes.length !== EGRESS_PROBES.length || !EGRESS_PROBES.every((p) => probes.includes(p))) return notReadBack("egress", "the egress canary did not run all three probes (see the egress lines above)");
+	// With all three probes present, a WRONG reading fails first, whatever else did not run to an answer: an unlisted
+	// host that was reached is a finding even when the provider probe did not run, and reporting it as merely unread
+	// would pass doctor over it. A probe missing altogether is "not read back" above, before any reading is judged.
 	const wrong = results.filter((r) => typeof r.reached === "boolean" && r.reached !== r.want);
-	if (wrong.length > 0) return verdict("egress", false, wrong.map((r) => (r.want ? "the provider was not reached" : "an unlisted host was reached")).join("; "));
+	if (wrong.length > 0) return verdict("egress", false, wrong.map((r) => EGRESS_WRONG[r.probe]).join("; "));
 	if (results.some((r) => typeof r.reached !== "boolean")) return notReadBack("egress", "an egress probe did not run to an answer (see the egress lines above)");
-	return verdict("egress", true, "the provider was reached and an unlisted host was not");
+	return verdict("egress", true, "the provider was reached, an unlisted host was not, and plain HTTP off port 80 was refused");
 }
 
+/** The canary's probes: `CANARY_PROBE_SLUGS` in doctor.mjs, which imports this module, so a test pins the two equal. */
+export const EGRESS_PROBES = Object.freeze(["provider", "unlisted", "plainhttp"]);
+
+/** What a wrong reading says, by the canary probe it came from. */
+const EGRESS_WRONG = Object.freeze({
+	provider: "the provider was not reached",
+	unlisted: "an unlisted host was reached",
+	plainhttp: "plain HTTP to a listed host off port 80 was let through",
+});
+
 /**
  * EPHEMERAL (issue #344): two runs under ONE name, each detached with `--rm`, each waited on until `docker ps -a` no
  * longer lists it. `first`/`second` are `{ started, id, removal: { state, ms } }` (`state` one of `gone`, `exited`

package/src/model-catalog.mjs

@@ -0,0 +1,297 @@
+/**
+ * Does this model exist (issue #502)? The worker's answer, asked among the free gates before any token mint,
+ * clone or reservation, so a typo in a model id costs nothing instead of a paid container that exits 2.
+ *
+ * Two sources, the two pi itself reads at the 0.99.1 pin:
+ *   - the builtin catalog, every provider's chat, image and classifier models (`getAllBuiltinModels`), so a
+ *     classifier or image model on an allowed-model list is found too. `getPricedModel` (pricing.mjs) answers
+ *     chat models only, which is why this module does not reuse it;
+ *   - the overlay `models.json` (`readOverlayModels`, model-endpoints.mjs), whose `providers.<name>.models[].id`
+ *     declares a custom model, under a custom provider or a builtin one (an Ollama model under `openai`).
+ *
+ * Imports only `@earendil-works/pi-ai/providers/all`, which pi-ai's package.json declares side-effect-free. Never
+ * the root or `compat`: a lookup must not register providers as a side effect of being asked a question.
+ *
+ * Matching is EXACT and case-sensitive on both the provider and the id, because that is how pi resolves a model;
+ * an id differing only in case is a model pi would not find, and saying "known" would let the job spend a
+ * container to learn that.
+ *
+ * What this cannot see, by design and named in REQ-MODEL-POLICY: a provider an extension registers
+ * (`pi.registerProvider`) and a virtual model (`pi.registerVirtualModel`) exist only inside the job. A flow that
+ * needs one declares the physical models it routes to in the overlay `models.json`, which this module reads.
+ */
+
+import { getAllBuiltinModels, getBuiltinModels, getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
+
+let builtinIndex = null;
+
+/**
+ * Two `provider -> Set(id)` maps over the builtin catalog, built ONCE per process: `any` (chat, image and classifier
+ * models, `getAllBuiltinModels`) and `chat` (`getBuiltinModels`). The catalog is generated data inside the pinned
+ * package, so it cannot change while the worker runs; walking ~1,600 ids per job would be work with no answer it
+ * could change. `Map`s of own entries, so `__proto__` or `constructor` is never a provider.
+ */
+function builtins() {
+	if (builtinIndex !== null) return builtinIndex;
+	const any = new Map();
+	const chat = new Map();
+	for (const provider of getBuiltinProviders()) {
+		any.set(provider, new Set(getAllBuiltinModels(provider).map((m) => m?.id).filter((id) => typeof id === "string")));
+		chat.set(provider, new Set(getBuiltinModels(provider).map((m) => m?.id).filter((id) => typeof id === "string")));
+	}
+	builtinIndex = { any, chat };
+	return builtinIndex;
+}
+
+/**
+ * Is `provider`/`id` a builtin model at the pin? `chatOnly` for a job's MAIN model (PR #536's review): the runner
+ * resolves it with `modelRuntime.getModel`, which answers chat models only, so an image or classifier model as the
+ * main model passes a catalog-wide check and then exits 2 in a paid container. A LIST entry may be any kind, since a
+ * flow may call a classifier or an image model through the registry.
+ */
+export function isBuiltinModel(provider, id, { chatOnly = false } = {}) {
+	if (typeof provider !== "string" || typeof id !== "string") return false;
+	return builtins()[chatOnly ? "chat" : "any"].get(provider)?.has(id) === true;
+}
+
+/**
+ * The builtin catalog's model object for `provider`/`id` (chat, image or classifier), or null (issue #503 part 7). The
+ * zero-rated check (`zeroRatedVerdict`, model-endpoints.mjs) reads its `cost` and `type` for a model the overlay does
+ * not redefine; that module never imports pi, so this is handed to it. Own entries only, exact match, like the rest.
+ */
+export function builtinModel(provider, id) {
+	if (typeof provider !== "string" || typeof id !== "string") return null;
+	if (!getBuiltinProviders().includes(provider)) return null;
+	return getAllBuiltinModels(provider).find((m) => m?.id === id) ?? null;
+}
+
+/**
+ * The builtin catalog's CHAT models of `provider` (the ones pi applies an overlay's provider `compat` and `modelOverrides`
+ * to), or [] for a provider the catalog does not know (issue #571: doctor's no-usage check reads their api, compat and
+ * cost). Copies of the list, never the catalog's own array.
+ */
+export function builtinChatModels(provider) {
+	if (typeof provider !== "string" || !getBuiltinProviders().includes(provider)) return [];
+	return [...getBuiltinModels(provider)];
+}
+
+/** Does the overlay `models.json` (already parsed, or null) declare `provider`/`id`? Own keys only. */
+export function isOverlayModel(overlay, provider, id) {
+	return overlayDeclares(overlay, provider, id) && overlayProviderProblem(overlay.providers[provider], provider) === null;
+}
+
+/** Does the overlay's entry for `provider` list `id`, whether or not pi would compose it? */
+function overlayDeclares(overlay, provider, id) {
+	const providers = overlay?.providers;
+	if (providers === null || typeof providers !== "object" || Array.isArray(providers)) return false;
+	if (!Object.hasOwn(providers, provider)) return false;
+	const models = providers[provider]?.models;
+	return Array.isArray(models) && models.some((m) => m !== null && typeof m === "object" && m.id === id);
+}
+
+/**
+ * Would pi COMPOSE this overlay provider (PR #536's review)? A file that passes pi's schema can still lose a provider
+ * at the next step: pi 0.99.1's `applyModelsJson` and `modelFromJson` (`pi-coding-agent/dist/core/provider-composer.js`)
+ * throw for `oauth` with no `baseUrl`, and per model no resolvable `api` or
+ * `baseUrl`, or a `contextWindow` or `maxTokens` at or below zero. pi then keeps the provider's BUILTIN models
+ * (`ModelRuntime.composeProvider` falls back to the base) and drops every model the overlay added, so such a model
+ * does not exist in the job. Mirrored here, the defaults search included: a model's missing `api` or `baseUrl` comes
+ * from a chat model already in the provider's list (the same id, else the same api, else an `openai-completions`
+ * one, else the first), which starts as the builtin chat models and grows with each overlay model in order. A null
+ * return is "composes"; a string names the first rule broken. Held to pi by the differential test in
+ * `models-json.test.mjs`, which asks pi's own `ModelRuntime` for every model in its corpus.
+ */
+export function overlayProviderProblem(config, providerId) {
+	if (config === null || typeof config !== "object" || Array.isArray(config)) return null;
+	if (config.oauth && !config.baseUrl) return "oauth-without-baseUrl";
+	// NOT mirrored: pi's "must specify baseUrl, headers, compat, modelOverrides or models" throw. An entry that sets none
+	// of those carries nothing pi could drop (no model, no endpoint, no header), so the provider pi falls back to is the
+	// one the entry describes, and refusing its builtin models would be a false refusal. Mirroring it changed no verdict
+	// while only overlay models counted (PR #536's review, round 3, mutant H6), and would now refuse wrongly.
+	// With `oauth` set, pi's defaults search sees no base models at the pin (measured: a `radius` entry with `oauth` and
+	// no `api` loses its custom models to "no api specified" though radius has builtin chat models). Mirrored. Radius
+	// itself, pi's OAuth gateway, is otherwise not modelled: its models need an OAuth login, which a job never has.
+	const builtinChat = !config.oauth && getBuiltinProviders().includes(providerId) ? getBuiltinModels(providerId) : [];
+	// pi keeps a builtin model's own baseUrl under `oauth: "radius"`; that branch is not mirrored, because with `oauth`
+	// set the list above is empty (mutant H5 found it dead).
+	const models = builtinChat.map((m) => ({ id: m.id, api: m.api, baseUrl: config.baseUrl ?? m.baseUrl }));
+	for (const def of config.models ?? []) {
+		// Kept for fidelity to pi's defaults search, though at the pin it cannot change a verdict (mutant H8): every
+		// builtin chat model has an api and a baseUrl, so whichever default is found supplies both, and only WHICH
+		// default is found depends on `wantApi`. It decides once pi gains a builtin model lacking one of them.
+		const wantApi = def.api ?? config.api;
+		const defaults = models.find((m) => m.id === def.id) ?? (wantApi ? models.find((m) => m.api === wantApi) : undefined) ?? models.find((m) => m.api === "openai-completions") ?? models[0];
+		const api = def.api ?? config.api ?? defaults?.api;
+		if (!api) return "no-api";
+		const baseUrl = def.baseUrl ?? config.baseUrl ?? defaults?.baseUrl;
+		if (!baseUrl) return "no-baseUrl";
+		if (def.contextWindow !== undefined && def.contextWindow <= 0) return "contextWindow";
+		if (def.maxTokens !== undefined && def.maxTokens <= 0) return "maxTokens";
+		const composed = { id: def.id, api, baseUrl };
+		const at = models.findIndex((m) => m.id === def.id);
+		if (at >= 0) models[at] = composed;
+		else models.push(composed);
+	}
+	return null;
+}
+
+/**
+ * Is this model in the catalog or the overlay? `overlay` is the parsed overlay `models.json` or null. (The job gate,
+ * `checkModelsKnown`, also refuses a builtin model whose provider entry pi would not compose.)
+ */
+export function knownModel({ provider, id, overlay = null, chatOnly = false }) {
+	return isBuiltinModel(provider, id, { chatOnly }) || isOverlayModel(overlay, provider, id);
+}
+
+/**
+ * The errnos a read of the overlay `models.json` may fail with and then succeed a moment later (issue #552): a disk or
+ * network filesystem error (EIO), a busy resource (EAGAIN), and the process or system out of file handles (EMFILE,
+ * ENFILE). An ALLOW-LIST, the other way round from `transient.mjs`: here the harmful direction is the false
+ * transient. An errno `readOverlayModels` does not read as absence and this list does not name is a file the operator
+ * wrote that pi in the job loads none of (the existence check in image/runner/run-job.mjs, or pi's own
+ * read, fails), and a builtin provider the file routes would then go to its public endpoint. So the model gate
+ * refuses every job on it.
+ */
+export const OVERLAY_TRANSIENT_READ_CODES = new Set(["EIO", "EAGAIN", "EMFILE", "ENFILE"]);
+
+/** True when a failed read of the overlay `models.json` with this errno may succeed if asked again. */
+export function isTransientOverlayRead(code) {
+	return OVERLAY_TRANSIENT_READ_CODES.has(code);
+}
+
+/**
+ * The gate's question for one job (issue #502): are its main model and every model on its list known? `refs` is
+ * `[{ provider, id, main? }]`, main first. `readOverlay` is called AT MOST ONCE per job.
+ *
+ * A BUILTIN model is judged by the overlay too (PR #536's review, round 3): when its provider has an overlay entry pi
+ * would not compose (`overlayProviderProblem`), pi drops that WHOLE entry, its `baseUrl`, `headers`, `apiKey` and
+ * `compat` included, and the builtin model then runs against the provider's public endpoint while the operator's
+ * file reads as though it routed it. Refused as `overlay-provider-invalid`.
+ *
+ * A file pi drops WHOLE refuses EVERY job (issue #539, PR #546's review, the simpler rule after its third round). pi
+ * drops an overlay that exists and fails to load for any reason (a schema error under one provider, a block comment,
+ * a truncated write, a UTF-16 save, an empty file, a directory: all measured against pi 0.99.1's `ModelConfig.load`),
+ * and every provider entry goes with it, so `openai: { baseUrl: <proxy> }` stops applying and `openai/gpt-4o` runs
+ * against `api.openai.com`. Which providers the broken file meant to route cannot be read from a file that does not
+ * load, and three rounds of reading it anyway kept finding cases, so the gate does not try: every main and listed
+ * ref, builtin or overlay, is refused (`overlay-unparseable`, or `overlay-is-a-directory`) until the operator fixes
+ * the file. Louder than needed for a job whose provider the file never mentions, and safe in direction. An absent
+ * file is no overlay, as for pi.
+ *
+ * A file the worker cannot READ is judged by its errno (issue #552). The job reads it through the same read-only
+ * mount, as the worker's own uid on native Linux, and pi in the job loads none of the file (the runner's existence
+ * check in image/runner/run-job.mjs, or pi's own read, fails). `readOverlayModels` reads what the job reads as no
+ * file as absence (ENOENT, and ELOOP, ENOTDIR or ENAMETOOLONG on the folder's path: no content is lost). Any other errno (EACCES or
+ * EPERM on the file or its folder, and any errno nobody listed) is a file the operator wrote and the job loses, so
+ * every job is refused (`overlay-unreadable`) until the worker's user can read it. Only the errnos
+ * `isTransientOverlayRead` names are retried, and then for EVERY job, builtin ones included: whether the file routes
+ * the job's provider cannot be known without reading it. A retried job gets the queue's second attempt, then fails.
+ *
+ * A `models.json` that is a link of any kind, dangling included (PR #553's review), refuses every job (`overlay-link`):
+ * the job's read-only mount does not resolve a link the way the host does, so the host may read the routing while the
+ * job runs with no overlay. The file itself is read; the overlay folder may be a link. A `models.json` that is a named
+ * pipe, a socket or a device (issue #556) refuses every job too (`overlay-not-a-file`), never opened: a FIFO with no
+ * writer would block the read on every pickup.
+ *
+ * Returns one of:
+ *   - `{ ok: true }`;
+ *   - `{ unknown: { provider, id }, why }`: the first unknown ref. `why` is `"not-in-catalog"`,
+ *     `"overlay-unparseable"` for every ref when pi would not load the overlay, `"overlay-is-a-directory"` for every
+ *     ref when it is a directory (pi fails the same way), `"overlay-unreadable"` for every ref when it cannot be read
+ *     for a reason no retry changes, `"overlay-link"` for every ref when `models.json` is a link, `"overlay-not-a-file"` for every ref when it is a named pipe,
+ *     socket or device (issue #556), or `"overlay-provider-invalid"` when the ref's provider has an overlay entry pi
+ *     would not compose, so the operator learns the file is the problem rather than the id;
+ *   - `{ fallbackUnlisted: { provider, id }, why: "fallback-unlisted" }`: the job has a list, every ref is known, and
+ *     a listed model declares a server-side fallback (`declaredFallbacks`) that is not on the list under its provider;
+ *   - `{ unavailable: code }`: the overlay could not be READ for a transient reason (`isTransientOverlayRead`). The
+ *     caller retries rather than refusing, because a refusal is permanent and public and the next attempt may read
+ *     the file.
+ */
+export function checkModelsKnown(refs, { readOverlay = () => null } = {}) {
+	let overlay = null;
+	let overlayRead = false;
+	let unavailable = null; // the errno of a transient read, else null
+	let unparseable = null; // the `why` when the overlay could not be used, else null
+	const load = () => {
+		if (overlayRead) return;
+		overlayRead = true;
+		try {
+			overlay = readOverlay();
+		} catch (err) {
+			// A configError (pi would not load the text, or `models.json` is a link) is the file itself, which no
+			// retry changes. An errno is judged by what the job then loads (issue #552): EISDIR is named as a directory
+			// (PR #536's review), the few errnos a moment can clear are retried, and every other one, EACCES and any
+			// errno nobody listed, is a file the job loads none of, so every job is refused. Fail closed: an unknown
+			// errno never lets a job run.
+			if (err?.overlayLink === true) unparseable = "overlay-link";
+			else if (err?.overlayNotAFile === true) unparseable = "overlay-not-a-file";
+			else if (err?.code === "EISDIR") unparseable = "overlay-is-a-directory";
+			else if (isTransientOverlayRead(err?.code)) unavailable = err.code;
+			else if (typeof err?.code === "string") unparseable = "overlay-unreadable";
+			else if (err?.piDispatchConfig !== true) throw err; // a defect, not a state: never a permanent refusal
+			else unparseable = "overlay-unparseable";
+			overlay = null;
+		}
+	};
+	for (const ref of refs) {
+		load();
+		// pi drops the whole file, every provider entry with it: no job runs until it is fixed (see above).
+		if (unparseable !== null) return { unknown: { provider: ref.provider, id: ref.id }, why: unparseable };
+		// A transient read retries every job (issue #552): the file may route this ref's provider, builtin or not.
+		if (unavailable !== null) return { unavailable };
+		// The provider's overlay entry, when the file was read and has one: pi drops all of it if it cannot compose it.
+		const providers = overlay?.providers;
+		const entry = providers !== null && typeof providers === "object" && Object.hasOwn(providers, ref.provider) ? providers[ref.provider] : undefined;
+		if (entry !== undefined && overlayProviderProblem(entry, ref.provider) !== null) return { unknown: { provider: ref.provider, id: ref.id }, why: "overlay-provider-invalid" };
+		// `main: true` marks the job's main model, which must be a CHAT model (see `isBuiltinModel`). The overlay's
+		// models are chat models: pi registers every models.json entry as one.
+		if (isBuiltinModel(ref.provider, ref.id, { chatOnly: ref.main === true })) continue;
+		if (!isOverlayModel(overlay, ref.provider, ref.id)) return { unknown: { provider: ref.provider, id: ref.id }, why: "not-in-catalog" };
+	}
+	// A job WITH a list (any ref beyond the main one): every listed model's server-side fallbacks must be listed too.
+	const listed = refs.filter((ref) => ref.main !== true);
+	if (listed.length > 0) {
+		const allowed = new Set(listed.map((ref) => `${ref.provider}\u0000${ref.id}`));
+		for (const ref of listed) {
+			for (const fallback of declaredFallbacks(ref.provider, ref.id, overlay)) {
+				if (!allowed.has(`${ref.provider}\u0000${fallback}`)) return { fallbackUnlisted: { provider: ref.provider, id: ref.id }, why: "fallback-unlisted" };
+			}
+		}
+	}
+	return { ok: true };
+}
+
+/**
+ * The server-side fallback ids a model declares (`compat.allowedFallbackModels`), as pi 0.99.1 composes them
+ * (provider-composer.js): the builtin model's own compat, then the overlay provider entry's `compat`, then an
+ * overlay model definition's (which replaces the builtin model of that id, with the provider's compat beneath it),
+ * then `modelOverrides[id].compat`; each later layer that sets the key replaces it (`mergeCompat` is shallow for it).
+ *
+ * Why the worker asks (issue #502, PR #538's review): pi sends these ids with EVERY call on the model
+ * (anthropic-messages `params.fallbacks`) and the provider may answer with any of them, so the runner's model guard
+ * refuses a listed model whose fallbacks are not listed under its provider. In pi's builtin catalog exactly one model
+ * declares any, anthropic/claude-fable-5 (claude-opus-4-8 and claude-opus-5). A list naming it alone would pass every
+ * free gate and then have every call refused inside a paid container; refused here instead, before any spend. Read
+ * for every api, which is stricter than the runner: only anthropic-messages sends fallbacks, and the runner judges them
+ * there only. Accepted (PR #538's review, round 3): a list is the operator saying which models may be named, and the
+ * refusal says only that the model declares fallbacks not on the list, which is true on every api.
+ */
+export function declaredFallbacks(provider, id, overlay = null) {
+	const fallbackIds = (compat) => (Array.isArray(compat?.allowedFallbackModels) ? compat.allowedFallbackModels.map((entry) => entry?.model) : undefined);
+	const has = (compat) => compat !== null && typeof compat === "object" && Object.hasOwn(compat, "allowedFallbackModels");
+	let found;
+	if (getBuiltinProviders().includes(provider)) {
+		const model = getAllBuiltinModels(provider).find((m) => m?.id === id);
+		if (model) found = fallbackIds(model.compat);
+	}
+	const providers = overlay?.providers;
+	const entry = providers !== null && typeof providers === "object" && !Array.isArray(providers) && Object.hasOwn(providers, provider) ? providers[provider] : null;
+	if (entry !== null && typeof entry === "object") {
+		if (has(entry.compat)) found = fallbackIds(entry.compat);
+		const definition = Array.isArray(entry.models) ? entry.models.find((m) => m !== null && typeof m === "object" && m.id === id) : undefined;
+		if (definition !== undefined) found = has(definition.compat) ? fallbackIds(definition.compat) : has(entry.compat) ? fallbackIds(entry.compat) : undefined;
+		const override = entry.modelOverrides !== null && typeof entry.modelOverrides === "object" && Object.hasOwn(entry.modelOverrides, id) ? entry.modelOverrides[id] : null;
+		if (has(override?.compat)) found = fallbackIds(override.compat);
+	}
+	return found ?? [];
+}