@edgehero/pi-dispatch 2.1.0 → 3.1.0

package/src/doctor.mjs

@@ -11,7 +11,7 @@
  * operator's FULL-scope gh login, which then reaches every token-carrying job container — the opposite of
  * the App path's per-repo short-lived tokens (CONST-TOKEN-SCOPED-PER-JOB) — so doctor names the scopes it
  * carries; and gh is preflighted inside the job image, since a token that works host-side but not
- * in-container fails jobs mid-run, not at submit. Token values travel via the spawn env only, never argv.
+ * in-container fails jobs mid-run, not at submit. Token values travel via the spawn env or stdin, never argv.
  *
  * Issue #80 adds the RECEIVER's half of the preflight. Doctor runs on the worker host, but the triggers
  * file names forges whose deliveries only ever arrive if the receiver can boot -- and the receiver is
@@ -57,10 +57,18 @@ import { basename, dirname, isAbsolute, join, delimiter, posix, resolve, win32 }
 import { fileURLToPath } from "node:url";
 import { spawn as nodeSpawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { accountTempRoot, defaultLogsDir, defaultSandboxDir, defaultSettingsFile, defaultWorkerName, globalExtensionsEnabled, jobsDirOwnerFix, jobsDirPath, sandboxDirOwnerFix, legacyTempStateDir, logsDirPath, pauseWindowsFilePath, safeHomeDir, scopedLimitsFilePath, settingsFilePath, underOsTempDir } from "./config.mjs";
+import { DEFAULT_MODEL, DEFAULT_PROVIDER, DEFAULT_VALKEY_URL, accountTempRoot, allowedModelsFrom, defaultLogsDir, defaultSandboxDir, defaultSettingsFile, defaultWorkerName, globalExtensionsEnabled, jobsDirOwnerFix, jobsDirPath, sandboxDirOwnerFix, legacyTempStateDir, logsDirPath, modelEndpointsFilePath, delimitedList, envelopeFilePath, pauseWindowsFilePath, projectsFilePath, safeHomeDir, scopedLimitsFilePath, settingsFilePath, underOsTempDir } from "./config.mjs";
 import { SYSTEMD_HAZARD_SHAPES, decodeEnvFile, envFileHazard, envValueShown, quotedRegions, readEnvAssignments, renderEnvValue, envFileWrapperInternal, wrapperInternalSentence } from "./env-file.mjs";
-import { canonicalScope, loadScopedLimits, parseScopedLimits } from "./scoped-limits.mjs";
-import { loadPauseWindows } from "./pause-windows.mjs";
+import { canonicalScope, danglingProjectRows, dollarRowsBelowJobCap, dollarRowsWithoutCap, isModelScope, isProjectScope, loadScopedLimits, parseScopedLimits } from "./scoped-limits.mjs";
+import { EMPTY_PROJECTS_FINGERPRINT, loadProjects, projectsFingerprint } from "./projects.mjs";
+import { parseModelsJson, stripBom, stripJsonComments } from "./models-json.mjs";
+import { isTransientOverlayRead, overlayProviderProblem } from "./model-catalog.mjs";
+import { EMPTY_USD_FINGERPRINT, usdFingerprint } from "./dollar-fingerprint.mjs";
+import { splitModelEntry } from "./model-ref.mjs";
+import { ignoredOutputCapModels, outputCapView, outputUnboundable } from "./output-cap.mjs";
+import { KEYLESS_API_KEY, KEYLESS_HOW, MODEL_ENDPOINTS_FILE_NAME, MODEL_ENDPOINTS_INCLUDE_NAME, MODEL_ENDPOINT_ID_RE, OVERLAY_LINK_FIX, OVERLAY_NOT_A_FILE_FIX, RENAMED_PROVIDERS, baseUrlTarget, keylessVerdict, loadModelEndpoints, providerRenameHint, readOverlayModels, renderEndpointsInclude, unreportedUsageModels } from "./model-endpoints.mjs";
+import { declaredEndpointsIn, endpointsDeclaredIn, reloadCommand, rulesFileIncludes, rulesPredateEndpointsLine } from "./egress-cli.mjs";
+import { loadPauseWindows, parseScopeString } from "./pause-windows.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, afterInstantMs, parseWaitProfiles } from "./wait-for.mjs";
 import { isForgeKind } from "./forges.mjs";
 import { findLiteralSecret, ADMIN_RE } from "./import-pi.mjs";
@@ -72,15 +80,15 @@ import { GIT_READ_FLAGS } from "./git-hardening.mjs";
 import { resolveBackendName } from "./backend-registry.mjs";
 import { deploymentVenueEnv, sharedShellIgnored } from "./deployment-venue.mjs";
 import { readDeploymentEnv, resolveServiceEnv, serviceEnvFileOf, serviceEnvLoader } from "./service-env.mjs";
-import { imageRefProblem } from "./image-ref.mjs";
-import { PROXY_STATE_FORMAT, parseProxyState, shippedProxyDrift } from "./egress-proxy-state.mjs";
+import { imageRefProblem, jobImageFix, pullOffered } from "./image-ref.mjs";
+import { PROXY_STATE_FORMAT, parseProxyState, rulesIncludeEndpoints, shippedProxyDrift } from "./egress-proxy-state.mjs";
 import { PACKAGED_EGRESS_PROXY_CONF, judgeProxyConfCopy, packageCopyName, readPackagedProxyConf } from "./egress-conf-copy.mjs";
-import { ABSENT, ASSERTED, DAEMON_APPLIES_BOUNDS, DEFAULT_BACKEND, DOCKER_ENDPOINT_LOCAL, OBSERVATION_FIX, OBSERVATIONS, PODMAN_ADDS_NO_MOUNTS, PODMAN_BACKEND, PODMAN_BOUNDS_DELEGATED, PODMAN_ROOTFUL_WIDENING_KEYS, PODMAN_SERVICE_LOCAL, PROPERTY_NAMES, RUNTIME_ADDS_NO_MOUNTS, declarationOf, floorShortfall, parseBackendFloor, parseBackendList, unarmedFloor, unobservedFloor, venuesOf } from "./backends.mjs";
-import { PODMAN_BOOT_REFUSING_CAUSES, PODMAN_FIRST_START_TIMEOUT_MS, PODMAN_INFO_TIMEOUT_MS, PODMAN_JOB_USER_FIX, decidePodmanJobUser, makePodmanInfoReader, observePodman, podmanConfFix, podmanConfWidening, resolvePodmanImageUser } from "./backend-podman.mjs";
+import { ABSENT, ASSERTED, DAEMON_APPLIES_BOUNDS, DEFAULT_BACKEND, DOCKER_ENDPOINT_LOCAL, OBSERVATION_FIX, OBSERVATIONS, PODMAN_ADDS_NO_MOUNTS, PODMAN_BACKEND, PODMAN_BOUNDS_DELEGATED, PODMAN_ROOTFUL_WIDENING_KEYS, PODMAN_SERVICE_LOCAL, PROPERTY_NAMES, RUNTIME_ADDS_NO_MOUNTS, HOST_ROUTE_LAN, HOST_ROUTE_REFUTED, HOST_ROUTE_WORKS, declarationOf, floorShortfall, hostRouteFor, isProxyLocalHost, parseBackendFloor, parseBackendList, unarmedFloor, unobservedFloor, venuesOf } from "./backends.mjs";
+import { PODMAN_BOOT_REFUSING_CAUSES, PODMAN_FIRST_START_TIMEOUT_MS, PODMAN_INFO_TIMEOUT_MS, PODMAN_JOB_USER_FIX, decidePodmanJobUser, makePodmanInfoReader, observePodman, observeRootlessNetns, podmanConfFix, podmanConfWidening, resolvePodmanImageUser } from "./backend-podman.mjs";
 import { PODMAN_PINNED_FLAGS, buildPodmanRunArgs, containerSpec, podmanArgsFromSpec } from "./docker-run.mjs";
 import { PODMAN_SERVICE_TIMEOUT_MS, PODMAN_SERVICE_UNIT, makePodmanServiceReader, observeHost, observeRootfulConf, readRootfulService, rootfulConfFix, rootfulConfRetries, rootfulConfResidual, rootfulUnreadList } from "./runtime-observations.mjs";
 import { endpointShown, makeDockerEndpointResolver, quotedShown } from "./backend-local.mjs";
-import { DEFAULT_EGRESS_PROXY, STOPPED_PROXY_STATES, EGRESS_CANARY_NET_PREFIX, EGRESS_CANARY_PROBE_PREFIX, egressArmed, egressCanaryNetwork, egressCanaryProbe, egressEnv, egressProxyName, networkEndpoints, removeNetworkOrSay } from "./egress.mjs";
+import { DEFAULT_EGRESS_PROXY, STOPPED_PROXY_STATES, EGRESS_CANARY_NET_PREFIX, EGRESS_CANARY_PROBE_PREFIX, EGRESS_ENDPOINT_PROBE_PREFIX, egressArmed, egressCanaryNetwork, egressCanaryProbe, egressEndpointProbe, egressEnv, egressProxyName, egressProxyUrl, networkEndpoints, removeNetworkOrSay } from "./egress.mjs";
 import { detachBlockedSentence, makeDetachGate, runtimeFromFacts } from "./netns-keeper.mjs";
 import { runLiveProbes } from "./live-probes.mjs";
 import { VALKEY_PASSWORD_KEY, VALKEY_PASSWORD_HOWTO, VALKEY_PORT_KEY, isLoopbackHost, valkeyPasswordProblem, valkeyPortConflict } from "./valkey-auth.mjs";
@@ -95,7 +103,14 @@ import { parseSecretProfiles } from "./secret-profiles.mjs";
 // can share them: doctor NAMES a variable and env-allowlist WRITES one, and they must never differ.
 import { apiKeyVariable, nonApiKeyKind } from "./provider-key.mjs";
 import { parseTriggers } from "./triggers.mjs";
-import { cronPlacement } from "./schedules.mjs";
+import { readOverlay, resolveSettings } from "./runtime-settings.mjs";
+import { DOLLAR_KEY_PREFIX } from "./dollar-budget.mjs";
+import { dayKey, monthKey, weekKey } from "./budget.mjs";
+import { DOLLAR_ENV_NAMES, DOLLAR_SETTING_KEYS, checkDollarInvariant, effectiveCostCapMicros, formatMicros, optionalUsdMicros, parseUsdMicros } from "./money.mjs";
+import { cronPlacement, envelopeJobPaths } from "./schedules.mjs";
+import { envelopeDigest, loadEnvelopeChecked } from "./envelope.mjs";
+import { OTHER } from "./priorities.mjs";
+import { ALLOC_PLAN_KEY, NO_ENVELOPE_FINGERPRINT } from "./allocation.mjs";
 
 const NODE_FLOOR = [22, 19]; // pi's engine floor (22.19.0)
 
@@ -117,15 +132,28 @@ const PODMAN_BOUNDS_FIX = Object.freeze({
 
 // The podman venue's pull of the deployment's default job image into this account's store (issue #433): the fix line's
 // words and `--fix`'s prompt, one string so the two cannot name different commands.
-const PODMAN_JOB_IMAGE_PULL = "podman pull ghcr.io/edgehero/pi-job:latest && podman tag ghcr.io/edgehero/pi-job:latest pi-job:latest";
+const PODMAN_JOB_IMAGE_PULL = jobImageFix("podman", "pi-job:latest");
 
 // The fix for a trigger-named image without the runner entrypoint, one sentence for either runtime (issue #433).
 const TRIGGER_IMAGE_ENTRYPOINT_FIX = "build your job image FROM this repo's image/Dockerfile so it keeps /entrypoint.sh -- an image without the runner can exit 0 without ever starting the agent, and the queue records that as success (docs/job-image.md)";
 
 // The in-image gh probe's argv after the runtime's name, shared by docker and podman (issue #433) so the two cannot
-// drift: the token rides value-less `-e` flags, which the CLI fills from the spawn env, so it never enters argv
-// (visible in `ps`) and never reaches doctor's output. Not the job builder's argv: the probe asks whether the image's gh
-// can reach the forge with this token, which is a question about the image and the network, not about a job's bounds.
+// drift. Not the job builder's argv: the probe asks whether the image's gh can reach the forge with this token, which is
+// a question about the image and the network, not about a job's bounds.
+//
+// The token rides STDIN (issue #521), never the container's environment. It used to ride value-less `-e` flags, which
+// kept it out of argv and out of doctor's output but put it in the container create request, and Docker Desktop's
+// backend log (`~/Library/Containers/com.docker.docker/Data/log/host/com.docker.backend.log`) writes that request,
+// environment included, to disk in plain text. Measured on 2026-10-02 (Docker Desktop 4.37.2, engine 27.4.0): one
+// doctor run left a dummy token in that log twice (GH_TOKEN and GITHUB_TOKEN) with `-e`, and zero times with stdin.
+// This token is the operator's own, so unlike a job's minted one it does not expire within the hour. `-i` attaches
+// stdin, the entrypoint becomes `sh`, and the script reads one line and exports it to the `gh auth status` it execs,
+// so the value lives only in that process's memory. Rejected: `--env-file` (the CLI expands it into the same create
+// request) and a mounted file (a host temp file that must be written, protected and removed, and on rootless Podman
+// made readable across a uid map, to say what one pipe says). An image without `sh` (or `gh`) fails the probe with
+// exit 126 or 127, and the line says gh could not be run inside the job image; an image built FROM image/Dockerfile
+// has both. `gh auth status` stays separate argv words after the script's `$0`, so the probe still reads as what it
+// runs.
 //
 // EXCEPT the venue's pins, on podman (review round 1): the account's containers.conf may default what the argv does not
 // name, and two of those defaults hand the probe far more than the token. `env_host = true` (which the podman venue
@@ -133,8 +161,9 @@ const TRIGGER_IMAGE_ENTRYPOINT_FIX = "build your job image FROM this repo's imag
 // provider keys, GITHUB_PAT and WEBHOOK_SECRET with it, and `http_proxy` copies the proxy variables. So a podman probe
 // carries `PODMAN_PINNED_FLAGS` whole, the same array every podman job carries: `--env-host=false` and
 // `--http-proxy=false` for that, and the private namespaces so the probe is no less contained than a job. docker has no
-// such defaults to pin (its CLI forwards only what `-e` names), so its argv is what it always was.
-const ghProbeArgs = (image, bin) => ["run", "--rm", "--pull=never", ...(bin === "podman" ? PODMAN_PINNED_FLAGS : []), "-e", "GH_TOKEN", "-e", "GITHUB_TOKEN", "--entrypoint", "gh", image, "auth", "status"];
+// such defaults to pin (its CLI forwards only what `-e` names, and the probe names nothing), so its argv carries no pins.
+const GH_PROBE_SCRIPT = 'read -r t; export GH_TOKEN="$t" GITHUB_TOKEN="$t"; exec "$@"';
+const ghProbeArgs = (image, bin) => ["run", "--rm", "-i", "--pull=never", ...(bin === "podman" ? PODMAN_PINNED_FLAGS : []), "--entrypoint", "sh", image, "-c", GH_PROBE_SCRIPT, "sh", "gh", "auth", "status"];
 
 
 // Issue #471: `shellVars` is THIS shell's environment and is read in exactly the places a test pins (the venue and
@@ -179,6 +208,13 @@ export async function runDoctor(shellVars = process.env, deps = {}) {
 		// without uninstalling a dependency. Threaded like every other seam: a seam collectChecks honours
 		// and runDoctor silently drops is a seam that cannot pin an EXIT CODE, only a check object.
 		providerOracle = defaultProviderOracle,
+		// Issues #501 and #502: the worker's model catalog and pi's own model loader, both imported lazily. Seams, so a test
+		// can drive the not-installed arm and a disagreement without editing pi. Undefined means the defaults.
+		modelCatalog,
+		piModelLoader,
+		dollarKeysExist,
+		// Issue #504 part B: the applied split's envelope digest (`alloc:plan`), read once. Undefined means the default.
+		readAppliedSplit,
 		// --live (issue #278, INT-LIVE-PROBE-CONTRACT): read the backend declarations back off short-lived real containers.
 		// STRICTLY `=== true`, so only the CLI's own flag arms it: a truthy string from a caller that forwarded an
 		// option bag runs nothing. The fs, PID-liveness and nonce are seams so the sequence is driven without Docker.
@@ -214,6 +250,17 @@ export async function runDoctor(shellVars = process.env, deps = {}) {
 		proxyFilesExist,
 		// PR #488's review: whether a path of the proxy's two files is a DIRECTORY, which docker would mount as the file.
 		proxyFileIsDirectory,
+		// Issue #503: whether the shipped proxy's third mount is needed (`proxyIncludeNeeds`), for tests.
+		includeNeeds,
+		// Issue #503 (part 6): the declared model endpoints as the service reads them, and this host's own LAN IPv4
+		// addresses for the measured route table, both for tests. The real reads are the defaults where they are used.
+		declaredEndpoints,
+		hostAddresses,
+		// Issue #552: the overlay models.json's read for the credential-free line, for tests that need an errno a real
+		// file cannot give (EIO, EMFILE). The real read is the default where it is used.
+		readOverlayFile,
+		// Issue #556: the overlay models.json's lstat, for tests that need a socket or a device a test cannot make.
+		lstatOverlayFile,
 		// Issue #484: how a copy of the proxy's rules is read, and the installed package's copy it is compared with.
 		readProxyConf,
 		readPackagedProxyConf: readPackagedConf,
@@ -328,7 +375,7 @@ export async function runDoctor(shellVars = process.env, deps = {}) {
 						return { ...(await valkeyAuthState(url, { context, withoutPassword })), passwordSet: Boolean(sent.password), from: sent.from };
 					}
 				: null;
-	const seams = { cwd, out, spawn, probeValkey, valkeyAuth: valkeyAuthSeam, readHosts, fileExists, nodeVersion, mkdir, chmod, rm, agentDir, platform, home, providerOracle, facts, jobUserIdentity, stat, passwd, readUnit, readEnvFile: readEnvFileShared, observationFs, jobsDirFs, jobsDirUid, valkeyOwner: valkeyOwnerSeam, isAlive, pid, runTimeouts, live: live === true, wallClock, venueChecks, userName, proxyFilesExist, proxyFileIsDirectory, ...(readProxyConf ? { readProxyConf } : {}), ...(readPackagedConf ? { readPackagedProxyConf: readPackagedConf } : {}), ...(readPodmanService ? { readPodmanService } : {}), serviceEnvFile: envValues === null ? null : serviceEnvFileOf(envValues, envPath, serviceEnvLoader(platform)) };
+	const seams = { cwd, out, spawn, probeValkey, valkeyAuth: valkeyAuthSeam, readHosts, ...(modelCatalog ? { modelCatalog } : {}), ...(piModelLoader ? { piModelLoader } : {}), ...(dollarKeysExist ? { dollarKeysExist } : {}), ...(readAppliedSplit ? { readAppliedSplit } : {}), fileExists, nodeVersion, mkdir, chmod, rm, agentDir, platform, home, providerOracle, facts, jobUserIdentity, stat, passwd, readUnit, readEnvFile: readEnvFileShared, observationFs, jobsDirFs, jobsDirUid, valkeyOwner: valkeyOwnerSeam, isAlive, pid, runTimeouts, live: live === true, wallClock, venueChecks, userName, proxyFilesExist, proxyFileIsDirectory, ...(includeNeeds ? { includeNeeds } : {}), ...(declaredEndpoints ? { declaredEndpoints } : {}), ...(readOverlayFile ? { readOverlayFile } : {}), ...(lstatOverlayFile ? { lstatOverlayFile } : {}), ...(hostAddresses ? { hostAddresses } : {}), ...(readProxyConf ? { readProxyConf } : {}), ...(readPackagedConf ? { readPackagedProxyConf: readPackagedConf } : {}), ...(readPodmanService ? { readPodmanService } : {}), serviceEnvFile: envValues === null ? null : serviceEnvFileOf(envValues, envPath, serviceEnvLoader(platform)) };
 	// Issue #471: every other service key, resolved ONCE for the whole run (the fix pass's re-collect and `--live` judge the
 	// same resolution). THE RULE (PR #474's round cap, after three rounds of trust patches): no program doctor starts is
 	// handed anything from `.env`. Every child gets this shell's own environment, the one it had before #471; a `.env`
@@ -518,7 +565,7 @@ function asText(content, enc) {
  * set is a key the other reads back the same way -- and it is asked for THIS PLATFORM's loader, because
  * the three loaders of this file disagree and a blended reading is wrong for every deployment at once.
  */
-export const ENV_FILE_READABLE_KEYS = Object.freeze(["PI_PAUSE_WINDOWS_FILE", "PI_SCOPED_LIMITS_FILE"]);
+export const ENV_FILE_READABLE_KEYS = Object.freeze(["PI_PAUSE_WINDOWS_FILE", "PI_SCOPED_LIMITS_FILE", "PI_PROJECTS_FILE", "PI_MODEL_ENDPOINTS_FILE", "PI_ENVELOPE_FILE"]);
 
 /**
  * The keys doctor takes from the deployment's `.env` as the SERVICE's values (issue #453, and since issue #471 every key
@@ -540,7 +587,7 @@ export const ENV_FILE_READABLE_KEYS = Object.freeze(["PI_PAUSE_WINDOWS_FILE", "P
 export const GITHUB_SERVICE_KEYS = Object.freeze(["GITHUB_AUTH_SOURCE", "GITHUB_APP_ID", "GITHUB_APP_INSTALLATION_ID", "GITHUB_APP_PRIVATE_KEY_PATH", "GITHUB_APP_PRIVATE_KEY"]);
 /** Issue #471: the worker's settings doctor judges, which it read from this shell alone while the service read them from
  *  `.env`. TEMP is TMPDIR's twin in the worker's temp root; PI_CODING_AGENT_DIR is where the worker reads auth.json. */
-export const WORKER_SERVICE_KEYS = Object.freeze(["PI_JOB_IMAGE", "PI_TRIGGERS_FILE", "PI_LOGS_DIR", "PI_SETTINGS_FILE", "PI_SESSIONS_DIR", "PI_SESSIONS_TTL_DAYS", "PI_SESSION_MAX_AGE_DAYS", "PI_SESSION_MAX_CONTEXT_PCT", "PI_SESSION_MAX_RESUME_CHAIN", "PI_GLOBAL_PI_DIR", "PI_GLOBAL_ALLOW_EXTENSIONS", "PI_FORWARD_ENV", "PI_AUTH_FROM_PI", "PI_CODING_AGENT_DIR", "PI_BACKEND_FLOOR", "PI_SECRET_PROFILES", "PI_SECRET_RESOLVER_ROOTS", "PI_WAIT_PROFILES", "PI_WAIT_AFTER_MAX_MS", "PI_SANDBOX_RETENTION_HOURS", "GITHUB_PAT_VAR", "TEMP"]);
+export const WORKER_SERVICE_KEYS = Object.freeze(["PI_JOB_IMAGE", "PI_TRIGGERS_FILE", "PI_LOGS_DIR", "PI_SETTINGS_FILE", "PI_SESSIONS_DIR", "PI_SESSIONS_TTL_DAYS", "PI_SESSION_MAX_AGE_DAYS", "PI_SESSION_MAX_CONTEXT_PCT", "PI_SESSION_MAX_RESUME_CHAIN", "PI_GLOBAL_PI_DIR", "PI_GLOBAL_ALLOW_EXTENSIONS", "PI_FORWARD_ENV", "PI_AUTH_FROM_PI", "PI_CODING_AGENT_DIR", "PI_BACKEND_FLOOR", "PI_SECRET_PROFILES", "PI_SECRET_RESOLVER_ROOTS", "PI_WAIT_PROFILES", "PI_WAIT_AFTER_MAX_MS", "PI_SANDBOX_RETENTION_HOURS", "PI_ALLOWED_MODELS", "PI_DISPATCH_RUN_ROOTS", "GITHUB_PAT_VAR", "TEMP", ...Object.values(DOLLAR_ENV_NAMES)]);
 /** Issue #471: the receiver's keys doctor judges its boot by (the receiver's unit reads the same `.env`). */
 export const RECEIVER_SERVICE_KEYS = Object.freeze(["WEBHOOK_SECRET", "RECEIVER_PORT", "GITLAB_TOKEN", "GITLAB_URL", "GITLAB_WEBHOOK_MODE", "GITLAB_WEBHOOK_SECRET", "FORGEJO_URL", "FORGEJO_TOKEN", "FORGEJO_WEBHOOK_SECRET", "AZURE_ORG_URL", "AZURE_TOKEN", "AZURE_WEBHOOK_MODE", "AZURE_WEBHOOK_SECRET", "AZURE_WEBHOOK_HEADER"]);
 /**
@@ -564,7 +611,7 @@ export const CLI_SERVICE_KEYS = Object.freeze({
 	gh: Object.freeze(["GH_TOKEN", "GITHUB_TOKEN", "GH_CONFIG_DIR", "GH_HOST", "XDG_CONFIG_HOME", "HOME"]),
 });
 const CLI_KEY_NAMES = [...new Set(Object.values(CLI_SERVICE_KEYS).flat())];
-export const SERVICE_ENV_KEYS = Object.freeze([...STACK_KEYS, "VALKEY_URL", VALKEY_SHARED_KEY, VALKEY_PASSWORD_KEY, VALKEY_PORT_KEY, "PI_PROVIDER", ...GITHUB_SERVICE_KEYS, "PI_JOBS_DIR", "PI_SANDBOX_DIR", "TMPDIR", "PI_WORKER_NAME", ...WORKER_SERVICE_KEYS, ...RECEIVER_SERVICE_KEYS, ...CLI_KEY_NAMES]);
+export const SERVICE_ENV_KEYS = Object.freeze([...STACK_KEYS, "VALKEY_URL", VALKEY_SHARED_KEY, VALKEY_PASSWORD_KEY, VALKEY_PORT_KEY, "PI_PROVIDER", "PI_MODEL", ...GITHUB_SERVICE_KEYS, "PI_JOBS_DIR", "PI_SANDBOX_DIR", "TMPDIR", "PI_WORKER_NAME", ...WORKER_SERVICE_KEYS, ...RECEIVER_SERVICE_KEYS, ...CLI_KEY_NAMES]);
 
 /** Issue #471 (gate round 1): what a service manager gives every service itself, so a `.env` need not carry it. */
 const AMBIENT_SERVICE_KEYS = Object.freeze(["TMPDIR", "TEMP", "XDG_RUNTIME_DIR", "HOME"]);
@@ -633,7 +680,7 @@ export const STEERING_SERVICE_KEYS = Object.freeze({
 	PI_JOB_IMAGE: "the image doctor inspects and runs (the canary, the gh probe, --live): the worker's `||` default and the one image rule its boot applies (image-ref.mjs: blank, padded, a leading dash, a control character), a refused value named and not used",
 	GITHUB_AUTH_SOURCE: "whether doctor runs gh on this host: the worker's own three values",
 	GITHUB_PAT_VAR: "which variable is the service's PAT: resolved and never printed; set by the file (or its PAT only in the file), the in-image gh probe is not run, since no program doctor starts is handed anything from .env",
-	PI_GLOBAL_PI_DIR: "the directory `--fix` restages into and removes auth.json from (prompt tier, the command shown first): the worker's rule, unset or empty is off, set must exist",
+	PI_GLOBAL_PI_DIR: "the directory `--fix` restages into and removes auth.json from (prompt tier, the command shown first): the worker's rule, unset or empty is off, set must be an absolute path that exists",
 	PI_TRIGGERS_FILE: "the file whose images, repos and folders doctor probes: a regular file only, parsed by the worker's own parser before any of its values is used",
 	PI_SESSIONS_DIR: "the directory `--fix` creates: silent only for this shell's own value; a value from .env is offered at the prompt tier, shown first",
 	PI_JOBS_DIR: "where --live makes its fixture: the jobs dir owner rule the worker applies at boot (#464)",
@@ -657,6 +704,9 @@ export const DOCTOR_SHELL_KEYS = Object.freeze({
 	DOCKER_CONTENT_TRUST: "a docker CLI setting of this shell, named for the --live probes this shell's CLI runs",
 	PI_PAUSE_WINDOWS_FILE: "read from .env by its own two-subject rule (ENV_FILE_READABLE_KEYS): the service judged from the file, this shell judged as itself",
 	PI_SCOPED_LIMITS_FILE: "read from .env by its own two-subject rule (ENV_FILE_READABLE_KEYS)",
+	PI_PROJECTS_FILE: "read from .env by its own two-subject rule (ENV_FILE_READABLE_KEYS), #499",
+	PI_MODEL_ENDPOINTS_FILE: "read from .env by its own two-subject rule (ENV_FILE_READABLE_KEYS), #503",
+	PI_ENVELOPE_FILE: "read from .env by its own two-subject rule (ENV_FILE_READABLE_KEYS), #504",
 	[VALKEY_SHARED_KEY]: "read from .env ONLY (#464); a value in this shell is named as ignored",
 });
 
@@ -947,7 +997,8 @@ export function envFileKeys(path, keys, { fileExists, readEnvFile, statFile = st
 }
 
 /**
- * The two files a worker LOADS AT BOOT, and the one place that knows what each is and how to ask.
+ * The files a worker LOADS at boot, and the one place that knows what each is and how to ask. The model endpoints file
+ * (issue #503) defaults to the deployment folder's copy where the other three are off when unset.
  *
  * `load` calls the worker's own loader (issue #384). Doctor used to carry its own parse for scoped limits
  * and nothing at all for pause windows, so "will the worker start" had two answers and one silence. The
@@ -963,6 +1014,10 @@ const BOOT_FILES = Object.freeze([
 		unsetMeans: "the worker loads no windows at all",
 		unit: "window",
 		nothing: "quiet hours",
+		fails: "REFUSES TO START",
+		whenDeleted: "turns scoped pauses off",
+		whenEmpty: "turns the worker off",
+		emptyCost: "refuses the boot",
 		resolve: pauseWindowsFilePath,
 		load: (path, io) => loadPauseWindows({ pauseWindowsFile: path }, io),
 	}),
@@ -974,11 +1029,134 @@ const BOOT_FILES = Object.freeze([
 		unsetMeans: "the worker enforces no scoped limits at all",
 		unit: "limit",
 		nothing: "scoped limits",
+		fails: "REFUSES TO START",
+		whenDeleted: "turns scoped limits off",
+		whenEmpty: "turns the worker off",
+		emptyCost: "refuses the boot",
 		resolve: scopedLimitsFilePath,
 		load: (path, io) => loadScopedLimits({ scopedLimitsFile: path }, io),
 	}),
+	// Issue #499. Off when unset, like the two above: no projects, and every run records `project: null`. The worker
+	// loads it at boot (start.mjs, `loadProjects`), so a file that does not load and an empty value refuse the start.
+	Object.freeze({
+		key: "PI_PROJECTS_FILE",
+		noun: "projects",
+		scaffold: "projects.json",
+		off: "projects are OFF (every run records no project)",
+		unsetMeans: "the worker groups no run into a project",
+		unit: "project",
+		nothing: "projects",
+		// No panel writes this file yet (the project tools come with part C of issue #499), so the unset fix line must
+		// not say the panel reports a project it wrote as applied live.
+		panelWrites: false,
+		fails: "REFUSES TO START",
+		whenDeleted: "turns projects off",
+		whenEmpty: "turns the worker off",
+		emptyCost: "refuses the boot",
+		resolve: projectsFilePath,
+		load: (path, io) => loadProjects({ projectsFile: path }, io),
+	}),
+	// Issue #503. Not off when unset: the worker then reads the scaffold in the deployment folder, so `defaultsToScaffold`
+	// swaps the "exists but unset" warning for a load of that file. The worker loads it at boot exactly like the two
+	// above (start.mjs, `loadModelEndpoints`), so a file that does not load, a named file that is missing and an empty
+	// value all REFUSE THE START; a live edit that does not load keeps the last good declaration instead
+	// (`model_endpoints_reload_invalid`), which is a running worker's posture and not the one predicted here. A valid
+	// `{"version":1,"endpoints":[]}` declares none, and only a missing DEFAULT file means the same. The file decides the
+	// proxy include, the slot leases at pickup and the keyless credential gate, so a start on a bad one would be a
+	// deployment whose rules and bounds the operator believes in and does not have.
+	Object.freeze({
+		key: "PI_MODEL_ENDPOINTS_FILE",
+		noun: "declared model endpoints",
+		scaffold: MODEL_ENDPOINTS_FILE_NAME,
+		defaultsToScaffold: true,
+		unsetMeans: `the worker reads ${MODEL_ENDPOINTS_FILE_NAME} in the deployment folder`,
+		unit: "endpoint",
+		nothing: "model endpoints",
+		fails: "REFUSES TO START",
+		whenDeleted: `reads ${MODEL_ENDPOINTS_FILE_NAME} in the deployment folder instead`,
+		whenEmpty: "turns the worker off",
+		emptyCost: "refuses the boot",
+		resolve: modelEndpointsFilePath,
+		// The worker's own default when VALKEY_URL is unset, so both refuse an endpoint on 6379 alike.
+		load: (path, io, env) => loadModelEndpoints({ modelEndpointsFile: path, valkeyUrl: env?.VALKEY_URL ?? DEFAULT_VALKEY_URL }, io),
+	}),
+	// Issue #504 part B. Off when unset: no envelope and no delegation, and every cap is what the operator's rows and
+	// windows set. The worker loads it at boot (start.mjs, `loadEnvelopeChecked`) against the projects and scoped limits
+	// it loaded, with the merged per-job cap, and refuses the start when it lies inside a job path, so this load asks the
+	// same three questions through the same function (`loadEnvelopeAsTheWorker`).
+	Object.freeze({
+		key: "PI_ENVELOPE_FILE",
+		noun: "the allocation envelope",
+		scaffold: "envelope.json",
+		off: "delegated allocation is OFF (every dollar cap is the operator's own)",
+		unsetMeans: "no envelope governs any job and no priorities plan applies",
+		unit: "envelope",
+		nothing: "allocation envelope",
+		// The admin writes this file (`dispatch_envelope_set`, issue #504 part C), but only at the path the key names: it
+		// has no default path, so the fix line's "the admin panel defaults to this same file" sentence does not apply.
+		panelWrites: false,
+		fails: "REFUSES TO START",
+		whenDeleted: "turns delegated allocation off",
+		whenEmpty: "turns the worker off",
+		emptyCost: "refuses the boot",
+		resolve: envelopeFilePath,
+		load: (path, io, env) => loadEnvelopeAsTheWorker(path, io, env),
+	}),
 ]);
 
+/** A key's value when it is a non-empty string, else null: the boot reads an unset key as off. */
+function nonEmpty(value) {
+	return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+/**
+ * The envelope as the WORKER would load it (issue #504 part B): against the projects and scoped limits the service
+ * names (each loaded by its own loader; one that does not load is its own BOOT_FILES line, so here it counts as none),
+ * with the merged per-job cap, and with the containment check against the triggers file's cron folders and skills
+ * dirs, the run roots and the global pi dir. Throws what the worker's boot would throw.
+ */
+export function loadEnvelopeAsTheWorker(path, io = {}, env = {}) {
+	return loadEnvelopeChecked({ envelopeFile: path }, { ...envelopeContextOf(env, io), jobPaths: envelopeJobPaths({ triggersFile: nonEmpty(env.PI_TRIGGERS_FILE), dispatchRunRoots: delimitedList(env.PI_DISPATCH_RUN_ROOTS), globalPiDir: nonEmpty(env.PI_GLOBAL_PI_DIR) }, io) }, { io });
+}
+
+/** The projects, the scoped limits and the merged per-job cap (micro-dollars, or null) the envelope is judged against. */
+function envelopeContextOf(env, io = {}) {
+	const quiet = (load) => {
+		try {
+			return load();
+		} catch {
+			return [];
+		}
+	};
+	const projects = quiet(() => loadProjects({ projectsFile: nonEmpty(env.PI_PROJECTS_FILE) }, io));
+	const limits = quiet(() => loadScopedLimits({ scopedLimitsFile: nonEmpty(env.PI_SCOPED_LIMITS_FILE) }, io));
+	let maxCostMicros = null;
+	try {
+		const settings = deploymentSettingsOf(env, settingsFilePath(env), (p) => (io.existsSync ?? existsSync)(p));
+		maxCostMicros = optionalUsdMicros(settings.maxCostUsd, "maxCostUsd");
+	} catch {
+		// A malformed cap is its own line; the envelope then reads as having none, which it refuses.
+	}
+	return { projects, limits, maxCostMicros };
+}
+
+/**
+ * Is anything at `path`, by `statFile`: ENOENT is absence, so a directory or an unreadable entry is judged. A stat that
+ * cannot say what the entry is (no `isFile`: a seam answering only an owner) is no evidence of a file either.
+ */
+function presentAt(statFile, path) {
+	try {
+		return typeof statFile(path)?.isFile === "function";
+	} catch (err) {
+		return err?.code !== "ENOENT";
+	}
+}
+
+/** The number of boot files in words, for the one sentence that counts them. */
+function countWord(n) {
+	return ["zero", "one", "two", "three", "four", "five"][n] ?? String(n);
+}
+
 /**
  * Would the worker load this path? The loader answers, with two guards doctor owes it.
  *
@@ -1029,7 +1207,7 @@ function loadVerdict(spec, rawPath, cwd, io, platform = process.platform) {
 		return { ok: false, reason: err?.code === "ENOENT" ? `${shown} does not exist` : `${shown} cannot be read: ${envValueShown(err?.message ?? String(err))}` };
 	}
 	try {
-		spec.load(path, io.loaderIo);
+		spec.load(path, io.loaderIo, io.env);
 		return { ok: true };
 	} catch (err) {
 		return { ok: false, reason: envValueShown(err?.message ?? String(err)) };
@@ -1078,7 +1256,7 @@ export async function collectChecks(shellVars, seams) {
 	const valkeyUnread = service.unread.find((u) => u.key === "VALKEY_URL" && !u.shellSet);
 	const unreadValkey = valkeyUnread ? readValkeyKeys(serviceEnvFile.text, { loader: serviceEnvFile.loader, path: serviceEnvFile.path }).error : null;
 	if (unreadValkey) valkeyUnread.skip = true;
-	const valkeyUrl = env.VALKEY_URL ?? "redis://127.0.0.1:6379";
+	const valkeyUrl = env.VALKEY_URL ?? DEFAULT_VALKEY_URL;
 	// PR #478's gate: a VALKEY_URL path that names no database (`/abc`) crashed doctor with an unhandled rejection from
 	// ioredis's SELECT. It is a ✗ of its own, the worker's refusal (exit 2), and nothing below contacts a Valkey.
 	const valkeyDbProblem = unreadValkey ? null : valkeyUrlProblem(valkeyUrl);
@@ -1253,8 +1431,9 @@ export async function collectChecks(shellVars, seams) {
 	// image checks just below, and `optingOut`/`requiring` colour the staged-packages lines further down.
 	// `optingOut` counts the only value that withholds the staged set; `requiring` counts an explicit
 	// run.packages: true, which arms nothing any more but is still an operator statement of intent.
-	const { requiring, waiting, waitProfiles, waitAfters, optingOut, resuming, replicating, instructing, commands, secreting, onceArmed, onceSpent, secretProfiles, localSecretFolders, secretNames, folders, images, imageRoutes, namedBackends, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd, declaredWorkerName);
+	const { requiring, waiting, listing, waitProfiles, waitAfters, optingOut, resuming, replicating, instructing, commands, secreting, onceArmed, onceSpent, secretProfiles, localSecretFolders, secretNames, folders, images, imageRoutes, namedBackends, skillsDirs, forges, repositories, flows, costCaps, modelRuns, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd, declaredWorkerName);
 	const scopedLimitFacts = readScopedLimitFacts(env, fileExists);
+	const pauseWindowFacts = readPauseWindowFacts(env, fileExists);
 	// FIRST, and fail rather than warn: every check below this line reads counts that a parse failure
 	// zeroed, so a green run here would be reporting on a file nobody could read. The receiver loads this
 	// file unconditionally and refuses to start without it, which is the consequence worth naming.
@@ -1285,6 +1464,7 @@ export async function collectChecks(shellVars, seams) {
 			fix: `fix ${triggersFilePath} so it loads (the message above names the entry and the reason), then re-run doctor -- every trigger-derived check below is skipped until it loads`,
 		});
 	}
+	checks.push(...dollarChecks(env, costCaps, triggersSet !== undefined));
 
 	// Only meaningful if docker itself responds; otherwise the image check is noise on top of a down daemon. Issue #433:
 	// and never without `local`, where the podman section's line (the image in THIS ACCOUNT'S store) is the image check.
@@ -1298,7 +1478,11 @@ export async function collectChecks(shellVars, seams) {
 		fix:
 			imageRun.ended === "timeout"
 				? "restart Docker first: this asked the same daemon that did not answer above, so whether the image is present is unknown rather than false"
-				: "docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest  (or build image/Dockerfile)",
+				: jobImage === "pi-job:latest"
+					? `${jobImageFix("docker", jobImage)}  (or build image/Dockerfile)`
+					: // Issue #523 (review): the image the worker runs, by the rule `up` follows, never ghcr's latest for an
+						// overriding name (which would not make THEIR image exist) and never a pull of a short name.
+						jobImageFix("docker", jobImage),
 		// Prompt tier, and ONLY for the deployment default: a PI_JOB_IMAGE the operator overrode is a trust
 		// choice this command cannot honestly satisfy (pulling ghcr's pi-job would not make THEIR image
 		// exist), so an overridden name keeps the plain fix line -- the same never-tier reasoning as the
@@ -1458,7 +1642,7 @@ export async function collectChecks(shellVars, seams) {
 	// is advisory and carries no fixAction (triggers content is the never tier). A deployment with no
 	// command triggers adds no line at all, so its output is byte-identical.
 	if (commands > 0) {
-		checks.push({ ok: true, label: `${commands} command trigger(s): a command is only verifiable in-container -- the runner refuses an unregistered one pre-spend (command-unregistered)` });
+		checks.push({ ok: true, label: `${commands} command trigger(s): a command is only verifiable in-container -- the runner refuses an unregistered one before the prompt is sent (command-unregistered)` });
 	}
 
 	// Issue #41: every DISTINCT image a trigger names in run.image, minus the deployment default already
@@ -1573,6 +1757,32 @@ export async function collectChecks(shellVars, seams) {
 	const readFactsOnce = () => (factsRead ??= makeDaemonFactsReader({ run: dockerRunVia(spawn, DAEMON_FACTS_TIMEOUT_MS) })());
 	const egress = localUsed ? await egressChecks(env, { ...seams, readFactsOnce }, { dockerCode, imageCode, jobImage, endpoint }) : [];
 	checks.push(...egress);
+	// Issue #503: an allowlist naming a host alias, once for every venue (both mount this folder's allowlist). Read only with
+	// the policy armed, which is when the file is a policy at all; a file that is not there or cannot be read says nothing.
+	let allowlistArmed = false;
+	try {
+		allowlistArmed = egressArmed(env) === true;
+	} catch {
+		// A malformed PI_EGRESS: the .env check reports it.
+	}
+	if (allowlistArmed) {
+		let aliases = [];
+		try {
+			aliases = allowlistHostAliases(readFileSync(join(seams.cwd, "egress-allowlist.conf"), "utf8"));
+		} catch {
+			// No allowlist in this folder.
+		}
+		for (const { alias, entry } of aliases) {
+			// The entry as written, when it is not the alias itself, is quoted: it is the operator's own file, but still text.
+			const named = entry.toLowerCase().replace(/^\./, "") === alias ? alias : `${quotedShown(entry)}, which admits ${alias}`;
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `egress-allowlist.conf lists ${named}, which lets a job open a CONNECT to that host's port 443 and send plain HTTP to its port 80, and reaches no model server's port`,
+				fix: `remove it, and declare the model server in model-endpoints.json instead, which opens a tunnel to exactly its host and port: docs/egress.md, "Local model servers"`,
+			});
+		}
+	}
 	if (facts) {
 		let armed;
 		try {
@@ -1733,6 +1943,9 @@ export async function collectChecks(shellVars, seams) {
 		}
 	}
 
+	// Issue #508: with the egress policy on, a job reaches a forge only over https on port 443.
+	checks.push(...forgeUrlEgressChecks(env, forges));
+
 	// Azure DevOps, when the triggers file names it (issue #80) -- same shape, mirrored from
 	// receiver/src/config.mjs loadAzureConfig. AZURE_WEBHOOK_MODE gets its own line because it is
 	// required-UNDEFAULTED: Azure offers no HMAC at all, so both modes are shared-secret compares, and
@@ -2027,7 +2240,7 @@ export async function collectChecks(shellVars, seams) {
 			}
 			if (token && ghProbeBin === "docker" && endpoint.local !== true) {
 				// NOT RUN on a daemon that is not observed on this host (#278). The probe hands the operator's own gh
-				// token -- full scope and non-expiring by default -- to `docker run -e`, and on a redirected CLI that
+				// token -- full scope and non-expiring by default -- to `docker run` (on stdin since #521), and on a redirected CLI that
 				// token rides to another machine. A check must not do the thing the credentialTransit line warns
 				// about. Only once there IS a token: app mode and an unset PAT never run the probe at all.
 				checks.push({
@@ -2037,8 +2250,11 @@ export async function collectChecks(shellVars, seams) {
 					fix: "point the docker CLI at this host and re-run doctor to check it",
 				});
 			} else if (token) {
-				// Value-less `-e` flags: the CLI forwards GH_TOKEN/GITHUB_TOKEN from the spawn env, so the
-				// token value never enters argv (visible in `ps`) and never reaches doctor's output.
+				// On stdin (issue #521, `ghProbeArgs`): the token never enters argv (visible in `ps`), the container
+				// create request (which Docker Desktop logs) or doctor's output, and doctor adds no copy of it to the
+				// CLI's environment. That environment may already hold it (a PAT source reads it from this shell's
+				// GITHUB_PAT), and that copy stays out of the container because docker forwards nothing `-e` does not
+				// name and podman's probe carries `--env-host=false`.
 				//
 				// The CLI's own environment stays doctor's whole one on both runtimes, and that is deliberate rather than
 				// left over (review round 1 asked): what keeps it OUT of the container is the pinned argv above, while
@@ -2046,16 +2262,25 @@ export async function collectChecks(shellVars, seams) {
 				// variables) is what decides WHICH Podman and which store answer. The podman section read that service
 				// with this same environment, so a trimmed one could send the token to a service nothing here checked.
 				// An allowlist of what Podman needs was rejected for that reason: it is a list nothing derives.
-				const probe = await runCmdCapture(spawn, ghProbeBin, ghProbeArgs(jobImage, ghProbeBin), { env: { ...spawnEnv, GH_TOKEN: token, GITHUB_TOKEN: token } });
+				const probe = await runCmdCapture(spawn, ghProbeBin, ghProbeArgs(jobImage, ghProbeBin), { env: spawnEnv, input: `${token}\n` });
 				const where = ghProbeBin === "podman" ? "podman: " : "";
+				// 126 and 127 are the runtime's and the shell's "could not run that program" (measured on docker 27.4: a
+				// missing entrypoint and a missing exec target both exit 127, a non-executable one 126); `gh auth status`
+				// itself exits 0, 1, 2, 4 or 8. Since the probe's entrypoint became `sh` (#521), an image without one
+				// lands here, and naming it as an auth failure would send the operator to check egress for nothing.
+				const cannotRun = probe.code === 126 || probe.code === 127;
 				checks.push({
 					ok: probe.code === 0,
 					warn: true,
 					label:
 						probe.code === 0
 							? `${where}gh authenticates inside the job image (${jobImage})`
-							: `${where}gh cannot authenticate inside the job image (${jobImage})`,
-					fix: "check network egress from containers or rebuild/pull the job image -- jobs that use gh will fail mid-run",
+							: cannotRun
+								? `${where}gh could not be run inside the job image (${jobImage}): it has no sh or no gh (exit ${probe.code})`
+								: `${where}gh cannot authenticate inside the job image (${jobImage})`,
+					fix: cannotRun
+						? "rebuild or pull the job image: every image built FROM this repo's image/Dockerfile has both -- jobs that use gh will fail mid-run"
+						: "check network egress from containers or rebuild/pull the job image -- jobs that use gh will fail mid-run",
 				});
 			} else if (patFromFile) {
 				// The service's PAT is in `.env`, which hands no program anything (PR #474's round cap): named, not run.
@@ -2174,6 +2399,11 @@ export async function collectChecks(shellVars, seams) {
 	// Valkey doctor reads, a host row is another party's text, and a control byte in a name or zone must not reach the
 	// terminal. The registry's own charset already refuses them at the source; this is the reader not relying on it.
 	const peers = (fleet.hosts ?? []).map((h) => ({ ...h, name: printable(h.name), tz: h.tz ? printable(h.tz) : h.tz })).filter((h) => h.name !== workerNameOf(declaredWorkerName));
+	// The applied split (issue #504 part B): one GET whenever this command may talk to the Valkey, so a single host with
+	// no envelope that refuses every job is told why. `{ digest }`, `{ undecodable: true }` for a key that exists and does
+	// not decode (the worker's EXISTS still counts it as governed), or null (no split, or no answer: nothing is said).
+	const valkeyUsable = !(unreadValkey || valkeyRefused || valkeyDbProblem || valkeyAuthVerdict?.state === "dbrange");
+	const appliedSplit = valkeyUsable ? await (seams.readAppliedSplit ?? defaultReadAppliedSplit)(valkeyTalkUrl) : null;
 	// Read only when there is a peer to compare against. Every line below is gated on a peer existing, and
 	// the SUBPROCESS has to be too: otherwise every `doctor` run on every single-host deployment spawns an
 	// extra docker call whose answer nothing reads.
@@ -2244,10 +2474,42 @@ export async function collectChecks(shellVars, seams) {
 				fix: "check that those workers are running and that the clocks agree -- a stale row is either a dead worker or a skewed clock, and both matter",
 			});
 		}
+
+		// Issue #501 part 6: the dollar counters are shared, the caps they are judged against are per host. This host's
+		// fingerprint is computed here from the service's own settings, by the worker's function, never read back from
+		// its registry row: doctor answers for the configuration, which a worker that has not restarted may not run yet.
+		// The scoped-limits rows are the parsed file's, or none when it does not load (the worker refuses to boot then).
+		const dollarsHere = deploymentSettingsOf(env, settingsFilePath(env, home), fileExists);
+		let envListHere = null;
+		try {
+			envListHere = allowedModelsFrom(env);
+		} catch {
+			// A malformed list is its own line below; the worker refuses to boot on it.
+		}
+		const usdHere = usdFingerprint(dollarsHere, scopedLimitFacts.parseError === null ? scopedLimitFacts.limits : [], envListHere);
+		checks.push(...(await fleetDollarChecks(usdHere, peers, { dollarKeysExist: () => (seams.dollarKeysExist ?? defaultDollarKeysExist)(valkeyTalkUrl) })));
+		// Issue #499 part C: each host resolves its jobs' project from its OWN projects.json, while the project rows' counters
+		// are shared. This host's `fpProjects` from the file the service names, against every peer's published one. SKIPPED
+		// when this host's file does not load (PR #569's review): the BOOT_FILES line already fails on it, and comparing
+		// "no projects" against healthy peers would send the operator to the wrong host.
+		const projectFactsHere = readProjectFacts(env, fileExists);
+		if (projectFactsHere.parseError === null) checks.push(...fleetProjectsChecks(projectsFingerprint(projectFactsHere.projects), peers));
+		// Issue #504 part B: one applied split, judged on every host against its own envelope. A host whose envelope digest
+		// differs refuses every governed job as `envelope-mismatch`. SKIPPED when this host's file does not load, for the
+		// projects check's reason above.
+		const envelopeHere = readEnvelopeFacts(env);
+		if (envelopeHere.parseError === null && appliedSplit === null) checks.push(...fleetEnvelopeChecks(envelopeHere.envelope ? envelopeDigest(envelopeHere.envelope) : NO_ENVELOPE_FINGERPRINT, peers));
 	} else if (fleet.unreachable) {
 		// Said, rather than silently absent: "no peers" and "could not ask" are different facts.
 		checks.push({ ok: true, label: `Fleet: could not read the host registry (${printable(fleet.unreachable)})` });
 	}
+	// Issue #504 part B: the APPLIED split names the envelope it was made for, and every host
+	// whose envelope differs refuses its governed jobs. Read whenever this command may talk to the Valkey (above), from
+	// the same Valkey the fleet was read from; with no split there, or no answer, nothing is said.
+	if (appliedSplit !== null) {
+		const envelopeHere = readEnvelopeFacts(env);
+		if (envelopeHere.parseError === null) checks.push(...appliedSplitChecks(appliedSplit, envelopeHere.envelope ? envelopeDigest(envelopeHere.envelope) : NO_ENVELOPE_FINGERPRINT, workerNameOf(declaredWorkerName), peers));
+	}
 
 	// Which variable holds a provider's key is PI'S fact, asked of pi rather than copied (issue #286).
 	// The copy this replaced had anthropic's two variables in the WRONG precedence order, invented
@@ -2268,7 +2530,41 @@ export async function collectChecks(shellVars, seams) {
 	const keyFromFile = keyCandidates.some((name) => (env[name] ?? "") !== "") ? {} : keyRes.fromFile;
 	// And auth.json where the SERVICE's worker reads it: the agent dir the file names, where this shell names none.
 	const keyAgentDir = fileSays("PI_CODING_AGENT_DIR").length > 0 ? agentDirFrom(env) : agentDir;
-	const keyCheck = providerKeyCheck({ provider, env: { ...env, ...keyFromFile }, agentDir: keyAgentDir, oracle, nodeOk: checks[0]?.ok });
+	// Issue #503: a provider pi does not know may be keyless, judged by the worker's own verdict on the declared endpoints
+	// and the overlay models.json, read here as the service reads them. Read only for such a provider, and only when an
+	// endpoint is declared, which is the worker's own rule (index.mjs reads the overlay only then).
+	const unknownToPi = keyCandidates.length === 0 && typeof oracle?.piProviders === "function" && !oracle.piProviders().includes(provider);
+	// Through doctor's own seams (the boot-file loader's io), and with the queue port the worker refuses: an endpoint on
+	// it refuses the worker's boot, so it must not read as keyless here.
+	const keylessIo = { existsSync: (p) => fileExists(p), readFileSync: readEnvFile ? (p, enc) => asText(readEnvFile(p), enc) : readFileSync };
+	const keylessValkey = env.VALKEY_URL ?? DEFAULT_VALKEY_URL;
+	const keylessEndpoints = unknownToPi ? (seams.declaredEndpoints ?? ((a) => declaredEndpointsIn({ ...a, fs: keylessIo })))({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform, valkeyUrl: keylessValkey }) : [];
+	let keylessModels = null;
+	let keylessUnreadable = null;
+	// The worker's rule (config.mjs `resolveGlobalPiDir`, PR #553's review): only an absolute PI_GLOBAL_PI_DIR is an
+	// overlay; a relative one refuses the worker's boot, and the overlay section below says so. Both reads take the
+	// value as it is, so they read the same folder.
+	if (keylessEndpoints.length > 0 && typeof env.PI_GLOBAL_PI_DIR === "string" && isAbsolute(env.PI_GLOBAL_PI_DIR)) {
+		try {
+			keylessModels = readOverlayModels(env.PI_GLOBAL_PI_DIR, keylessIo);
+		} catch (error) {
+			// The reader's one rule (PR #520 round 2): an errno it rethrows is not a verdict on the provider, so doctor
+			// names the code rather than calling the provider unknown (retried or refused by `isTransientOverlayRead`).
+			// Invalid JSON is the overlay check's line below; here it only means nothing is keyless.
+			if (typeof error?.code === "string") keylessUnreadable = error.code;
+		}
+	}
+	// Issue #587's review: the rename hint is judged on the overlay itself, read whenever there is one, endpoint or not.
+	let hintModels = keylessModels;
+	let hintUnread = false;
+	if (unknownToPi && hintModels === null && Object.hasOwn(RENAMED_PROVIDERS, provider) && typeof env.PI_GLOBAL_PI_DIR === "string" && isAbsolute(env.PI_GLOBAL_PI_DIR)) {
+		try {
+			hintModels = readOverlayModels(env.PI_GLOBAL_PI_DIR, keylessIo);
+		} catch {
+			hintUnread = true;
+		}
+	}
+	const keyCheck = providerKeyCheck({ provider, env: { ...env, ...keyFromFile }, agentDir: keyAgentDir, oracle, nodeOk: checks[0]?.ok, keyless: { endpoints: keylessEndpoints, models: keylessModels, unreadable: keylessUnreadable, hintModels, hintUnread } });
 	const keyNamed = Object.keys(keyFromFile).filter((name) => keyCheck.label?.includes(`: ${name})`));
 	// Issue #481 (PR #485 review round 2): a key found nowhere doctor can look is one an env-setup script may export, which
 	// is the documented home for a provider key fetched from a secrets manager (docs/secrets.md).
@@ -2302,7 +2598,15 @@ export async function collectChecks(shellVars, seams) {
 	// Global pi overlay (REQ-GLOBAL-PI-OVERLAY), only when configured. The overlay is mounted :ro into an
 	// adversarial-input container, so the load-bearing checks are that it holds NO credential.
 	const overlay = env.PI_GLOBAL_PI_DIR;
-	if (overlay) {
+	if (overlay && !isAbsolute(overlay)) {
+		// PR #553's review: the worker refuses to boot on it (config.mjs `resolveGlobalPiDir`), since a relative value is
+		// resolved differently by the worker and the container runtime.
+		checks.push({
+			ok: false,
+			label: `PI_GLOBAL_PI_DIR is ${JSON.stringify(overlay)}, which is not an absolute path, so the worker refuses to boot${fromFileNote(fileSays("PI_GLOBAL_PI_DIR"))}`,
+			fix: "set PI_GLOBAL_PI_DIR to the overlay folder's absolute path; a relative value is resolved differently by the worker and the container runtime",
+		});
+	} else if (overlay) {
 		const dirOk = fileExists(overlay);
 		checks.push({ ok: dirOk, label: `Global overlay dir exists (${envValueShown(overlay)})${fromFileNote(fileSays("PI_GLOBAL_PI_DIR"))}`, fix: "run `pi-dispatch import-pi`, or fix PI_GLOBAL_PI_DIR" });
 		if (dirOk) {
@@ -2324,21 +2628,165 @@ export async function collectChecks(shellVars, seams) {
 				},
 			});
 			const modelsPath = join(overlay, "models.json");
-			let modelsOk = true;
-			let modelsFix = "";
-			if (fileExists(modelsPath)) {
-				try {
-					const leak = findLiteralSecret(JSON.parse(readFileSync(modelsPath, "utf8")));
+			// Through the one reader (`readOverlayModels`, PR #520): an exists test answered false for a file under an
+			// unreadable directory, so this line passed in silence on a file nobody had read. Absent is a pass (nothing to
+			// leak); a transient errno (`isTransientOverlayRead`) is ⚠ naming the code, a read the worker retries once; any
+			// other errno, EACCES among them, is ✗, since the job loads none of the file and the worker refuses every job
+			// (issue #552); so is a models.json that is a link (PR #553's review) or a named pipe, socket or device, which
+			// the reader judges from its `lstat` and never opens (issue #556); text that does not parse, or is not an
+			// object, is ✗.
+			let overlayModels = null;
+			let modelsRead = null;
+			try {
+				overlayModels = readOverlayModels(overlay, { readFileSync: seams.readOverlayFile ?? ((p, enc) => readFileSync(p, enc)), ...(seams.lstatOverlayFile ? { lstatSync: seams.lstatOverlayFile } : {}) });
+			} catch (error) {
+				modelsRead = error;
+			}
+			if (modelsRead?.overlayLink === true) {
+				// PR #553's review: the job's read-only mount does not resolve a link the way the host does.
+				checks.push({
+					ok: false,
+					label: "Overlay models.json is a link, so every job is refused as model-unknown (overlay-link)",
+					fix: `${OVERLAY_LINK_FIX}: ${modelsPath}; no job runs until then`,
+				});
+			} else if (modelsRead?.overlayNotAFile === true) {
+				// Issue #556: judged by the reader's `lstat` and never opened, so doctor cannot hang on a FIFO with no writer.
+				checks.push({
+					ok: false,
+					label: "Overlay models.json is not a regular file (a named pipe, socket or device), so every job is refused as model-unknown (overlay-not-a-file)",
+					fix: `${OVERLAY_NOT_A_FILE_FIX}: ${modelsPath}; no job runs until then`,
+				});
+			} else if (modelsRead?.code === "EISDIR") {
+				// Issue #539: pi fails to read a directory the same way, so it loads no models.json, and the worker refuses
+				// every job (not retried: no retry turns a directory into a file).
+				checks.push({
+					ok: false,
+					label: "Overlay models.json is a directory, so pi loads none of it and every job is refused as model-unknown (overlay-is-a-directory)",
+					fix: `replace ${modelsPath} with a models.json file, or remove it; no job runs until then`,
+				});
+			} else if (isTransientOverlayRead(modelsRead?.code)) {
+				checks.push({
+					ok: false,
+					warn: true,
+					label: `Overlay models.json could not be read just now (${modelsRead.code}), so whether it is credential-free is not known; the worker retries each job once, then fails it`,
+					fix: `check the disk or file handles behind ${modelsPath}, then re-run doctor`,
+				});
+			} else if (typeof modelsRead?.code === "string") {
+				// Issue #552: the job reads the file through the read-only mount, and pi in the job loads none of it (the
+				// existence check in image/runner/run-job.mjs, or pi's own read, fails), so a builtin provider the
+				// file routes would go to its public endpoint. The worker refuses every job instead.
+				const permission = modelsRead.code === "EACCES" || modelsRead.code === "EPERM";
+				checks.push({
+					ok: false,
+					label: `Overlay models.json cannot be read by the worker (${modelsRead.code}), so a job loads none of it and every job is refused as model-unknown (overlay-unreadable)`,
+					fix: permission ? `make ${modelsPath} and its folder readable by the account the worker runs as; every job is refused until then` : `check ${modelsPath} on the worker host (the read failed with ${modelsRead.code}); every job is refused until the worker can read it`,
+				});
+			} else {
+				let modelsOk = true;
+				let modelsFix = "";
+				if (modelsRead !== null) {
+					modelsOk = false;
+					// Issue #539: pi then drops every entry, so a builtin model of a provider the file routes would run against
+					// that provider's public endpoint. The worker refuses every job until the file is fixed, for either cause.
+					const cause = /not valid JSON/.test(String(modelsRead?.message)) ? "is not valid JSON" : "does not match pi's models.json schema";
+					modelsFix = `overlay models.json ${cause}, so pi loads none of it: every job is refused as model-unknown (overlay-unparseable) until the file is fixed, since pi would run even a builtin model against its provider's public endpoint instead of the route the file sets`;
+				} else if (overlayModels !== null) {
+					const leak = findLiteralSecret(overlayModels);
 					if (leak) {
 						modelsOk = false;
 						modelsFix = `literal secret at ${leak} — move it to env/auth.json or a "$VAR" reference`;
 					}
-				} catch {
-					modelsOk = false;
-					modelsFix = "overlay models.json is not valid JSON";
+				}
+				checks.push({ ok: modelsOk, label: "Overlay models.json is credential-free", fix: modelsFix });
+				// Issue #539: an entry the file loads with but pi will not compose (the model gate's own rule,
+				// `overlayProviderProblem`). pi drops that whole entry, so the worker refuses every job on the provider.
+				const providers = overlayModels?.providers;
+				for (const name of providers !== null && typeof providers === "object" && !Array.isArray(providers) ? Object.keys(providers) : []) {
+					// Issue #587: an entry under an id pi renamed that lacks what a provider of its own needs (an api, a baseUrl
+					// and models). It was an override of the builtin provider; under the new pi it is a custom provider with no
+					// models, so it overrides nothing, and the builtin models it meant run with their own (empty) baseUrl.
+					const entry = providers[name];
+					if (Object.hasOwn(RENAMED_PROVIDERS, name) && entry !== null && typeof entry === "object" && !Array.isArray(entry) && (entry.api === undefined || entry.baseUrl === undefined || !Array.isArray(entry.models))) {
+						const renamedTo = RENAMED_PROVIDERS[name];
+						checks.push({
+							ok: false,
+							warn: true,
+							label: `Overlay models.json entry ${JSON.stringify(name)} no longer overrides anything: pi 1.0.3 renamed that provider to ${JSON.stringify(renamedTo)}, so this entry is now a provider of its own, holding only what it declares itself, and the ${renamedTo} models do not get its settings`,
+							fix: `rename the entry to ${JSON.stringify(renamedTo)} in ${modelsPath} (and every ${name}/ model reference in the triggers to ${renamedTo}/), then re-run doctor`,
+						});
+					}
+					const problem = overlayProviderProblem(entry, name);
+					if (problem === null) continue;
+					checks.push({
+						ok: false,
+						label: `Overlay models.json entry ${JSON.stringify(name)} is one pi will not compose (${problem}), so pi drops all of it, its baseUrl and headers included`,
+						fix: `every job that runs or lists a model of ${JSON.stringify(name)} is refused as model-unknown (overlay-provider-invalid): give each model an api and a baseUrl (its own or the provider's), a contextWindow and maxTokens above zero, and set a baseUrl beside oauth`,
+					});
+				}
+			}
+			// Issue #502's open question: pi's own loader against the worker's catalog, on the file as it is, whenever the reader
+			// found one (a file the worker refuses is the first case worth comparing). `pi-model-loader.mjs` says why it is
+			// the pi beside the worker rather than a container of the job image. Only a file that was READ: one the worker
+			// refuses for its text (unparseable, or against pi's schema) is compared, while a link, an unreadable file or
+			// anything else the reader refuses before reading (PR #553: overlay-link, overlay-unreadable; PR #557:
+			// overlay-not-a-file) is not, since the job never loads it and the line above already says every job is refused.
+			const refusedForText = modelsRead?.piDispatchConfig === true && typeof modelsRead.code !== "string" && modelsRead.overlayLink !== true && modelsRead.overlayNotAFile !== true && /^overlay models\.json (is not valid JSON|does not match)/.test(String(modelsRead.message));
+			if (overlayModels !== null || refusedForText) {
+				const catalog = await (seams.modelCatalog ?? defaultModelCatalog)();
+				if (catalog) checks.push(...(await overlayLoaderParityChecks(modelsPath, { pi: await (seams.piModelLoader ?? defaultPiModelLoader)(), checkModelsKnown: catalog.checkModelsKnown })));
+			}
+			// Issue #503: a model whose baseUrl is localhost or a loopback literal can never be reached from a job, egress on
+			// or off, because inside a job that address is the job's own container. Said whatever is declared: an overlay
+			// pointed at localhost is the first thing an operator tries, and the fix is the declaration. Nothing when the file
+			// is absent, does not parse, or is a file the job does not load (the line above names that): judged on the one
+			// reader's result, so a models.json link is not read here around it.
+			if (overlayModels !== null) {
+				const loopback = overlayLoopbackModels(overlayModels);
+				if (loopback.length > 0) {
+					checks.push({
+						ok: false,
+						warn: true,
+						label: `Overlay models.json points ${loopback.join(", ")} at a loopback address, which inside a job is the job's own container, so no job reaches that server`,
+						fix: "serve the model on an address the egress proxy reaches, declare it in model-endpoints.json (host.docker.internal on Docker, host.containers.internal on Podman), and point the baseUrl there: docs/egress.md, \"Local model servers\"",
+					});
+				}
+				// Issue #571: a model that costs money but asks for no usage in the stream. pi records each of its calls as
+				// zeros, so the meter counts it `costUnreported` and every job on it settles at the floor (`≥` in the cost
+				// views). Judged on the same reader's result: the overlay's own models, and the builtin models a provider-level
+				// compat or a modelOverrides entry turns off, priced from the worker's catalog (none when it cannot load).
+				const usageCatalog = await (seams.modelCatalog ?? defaultModelCatalog)();
+				const unreported = unreportedUsageModels(overlayModels, { builtinModel: usageCatalog?.builtinModel, builtinChatModels: usageCatalog?.builtinChatModels });
+				if (unreported.length > 0) {
+					const SHOWN = 5;
+					const named = unreported.slice(0, SHOWN).map((m) => `${quotedShown(m.provider)}/${quotedShown(m.modelId)}`).join(", ");
+					const more = unreported.length > SHOWN ? ` and ${unreported.length - SHOWN} more` : "";
+					checks.push({
+						ok: false,
+						warn: true,
+						label: `Overlay models.json sets compat.supportsUsageInStreaming to false on ${named}${more} with a nonzero cost table, so those calls report no usage: each counts as costUnreported, and every job that calls one settles at the floor`,
+						fix: "remove supportsUsageInStreaming: false if the server sends usage when asked (stream_options.include_usage), or set the model's cost to zeros if it is free: docs/costs.md, \"A call that reports no usage\"",
+					});
+				}
+				// Issue #507: a priced model on a declared endpoint whose output cap would travel as max_completion_tokens,
+				// which Ollama ignores. The runner's cost guard counts every such call unboundable, so a job under a dollar
+				// cap is refused at its first call. The endpoints as the service reads them, through the keyless line's io.
+				// A model a capped job may use is named by the cost-cap line below (`costCapFitChecks`), which runs on the
+				// same catalog seam, so this line names only the rest: one line per model.
+				const capEndpoints = (seams.declaredEndpoints ?? ((a) => declaredEndpointsIn({ ...a, fs: keylessIo })))({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform, valkeyUrl: keylessValkey });
+				const capped = usageCatalog ? cappedModelNames(env, { runs: parseError ? [] : modelRuns, deployment: deploymentSettingsOf(env, settingsFilePath(env, home), fileExists) }) : new Set();
+				const uncapped = ignoredOutputCapModels({ models: overlayModels, endpoints: capEndpoints, builtinModel: usageCatalog?.builtinModel, builtinChatModels: usageCatalog?.builtinChatModels }).filter((m) => !capped.has(`${m.provider}/${m.modelId}`));
+				if (uncapped.length > 0) {
+					const SHOWN = 5;
+					const named = uncapped.slice(0, SHOWN).map((m) => `${quotedShown(m.provider)}/${quotedShown(m.modelId)}`).join(", ");
+					const more = uncapped.length > SHOWN ? ` and ${uncapped.length - SHOWN} more` : "";
+					checks.push({
+						ok: false,
+						warn: true,
+						label: `Overlay models.json sends the output cap of ${named}${more} as max_completion_tokens to a declared model endpoint, which a local server may ignore (Ollama does), so under a dollar cap every call to it is refused as unboundable`,
+						fix: "set \"compat\": { \"maxTokensField\": \"max_tokens\" } on the model or its provider in models.json, or set its cost to zeros if it is free: docs/egress.md, \"Local model servers\"",
+					});
 				}
 			}
-			checks.push({ ok: modelsOk, label: "Overlay models.json is credential-free", fix: modelsFix });
 			// Staged extensions load unless the operator opted out, so this pair reports what WILL run, not
 			// what is switched on. The ⚠ sits on the loading case: it is the one where code the operator may
 			// have staged months ago is executing against adversarial input right now. It stays a warning and
@@ -2599,6 +3047,77 @@ export async function collectChecks(shellVars, seams) {
 		});
 	}
 
+	// Issue #502, allowed-model lists. The deployment list is judged unconditionally, `PI_WAIT_PROFILES`' rule: a
+	// malformed or spaced value is a worker that will not boot. Its grammar is the worker's own (`allowedModelsFrom`).
+	// The value doctor reads is the SERVICE's (`WORKER_SERVICE_KEYS`), so a spaced value in a `.env` a shell sources is
+	// already named above as a line that loader reads differently, which is the case where the list silently vanishes.
+	if (typeof env.PI_ALLOWED_MODELS === "string" && env.PI_ALLOWED_MODELS !== "") {
+		let list = null;
+		let why = null;
+		try {
+			list = allowedModelsFrom(env);
+		} catch (err) {
+			why = err?.message ?? "invalid";
+		}
+		checks.push(
+			why === null
+				? { ok: true, label: `PI_ALLOWED_MODELS limits every job whose trigger names no run.models to ${list.length} model(s): ${list.join(", ")}` }
+				: { ok: false, label: "PI_ALLOWED_MODELS is not a valid list", fix: `${why} -- the worker refuses to boot until this is fixed` },
+		);
+	}
+	if (listing > 0) {
+		// The version-floor disclosure, the run.waitFor line's twin and for its reason: doctor cannot see the
+		// receiver's version from here, and the worker's own skew check refuses a job that arrives without its list.
+		checks.push({
+			ok: true,
+			label: `${listing} trigger(s) name run.models, which needs a worker and a receiver that carry issue #502 (a service below that drops the list silently; the worker refuses such a job as trigger-skew rather than running it unrestricted, and only when it can read the triggers file itself)`,
+		});
+	}
+	if (costCaps.length > 0) {
+		// Issue #540: the run.models line's twin for run.maxCostUsd (#501), for its reason. A service below the floor
+		// tolerated the key as unknown and dropped it, so the job would run under the deployment's cap, or none.
+		checks.push({
+			ok: true,
+			label: `${costCaps.length} trigger(s) set run.maxCostUsd, which needs a worker and a receiver that carry issue #501 (a service below that drops the cap silently; the worker refuses such a job as trigger-skew rather than running it under the deployment's cap or none, and only when it can read the triggers file itself)`,
+		});
+	}
+
+	// Issues #501 and #502 (the round's doctor half): three lines about the models a job may use, asked of the worker's
+	// own catalog (model-catalog.mjs, imported lazily: it loads pi-ai, which this module never does at load) with the
+	// overlay models.json the worker reads and the deployment's settings resolved as a job resolves them. Nothing when
+	// pi-ai does not load: the provider key line below already fails on that. A triggers file that did not load
+	// contributes no trigger (its own line says so), and the deployment's default is still judged for its cap.
+	{
+		const catalog = await (seams.modelCatalog ?? defaultModelCatalog)();
+		if (catalog) {
+			const overlayDir = typeof env.PI_GLOBAL_PI_DIR === "string" && env.PI_GLOBAL_PI_DIR !== "" ? resolve(cwd, env.PI_GLOBAL_PI_DIR) : null;
+			const readOverlayDoc = () => (overlayDir === null ? null : readOverlayModels(overlayDir, { readFileSync: seams.readOverlayFile ?? ((p, enc) => readFileSync(p, enc)), ...(seams.lstatOverlayFile ? { lstatSync: seams.lstatOverlayFile } : {}) }));
+			let overlayDoc = null;
+			try {
+				overlayDoc = readOverlayDoc();
+			} catch {
+				// Unreadable or refused: the overlay lines say which. The checks below then judge builtin models only.
+			}
+			let envList = null;
+			try {
+				envList = allowedModelsFrom(env);
+			} catch {
+				// A malformed PI_ALLOWED_MODELS is its own line above (the worker refuses to boot on it).
+			}
+			const subjects = modelSubjects({ runs: parseError ? [] : modelRuns, deployment: deploymentSettingsOf(env, settingsFilePath(env, home), fileExists), envList });
+			checks.push(...unknownModelChecks(subjects, catalog.checkModelsKnown, readOverlayDoc));
+			checks.push(...costCapFitChecks(subjects, (ref) => boundModelOf(ref, { builtinModel: catalog.builtinModel, overlay: overlayDoc }), { unboundable: (ref) => outputUnboundable(outputCapView({ models: overlayDoc, provider: ref.provider, modelId: ref.id, builtinModel: catalog.builtinModel, builtinChatModels: catalog.builtinChatModels })) }));
+			checks.push(
+				...listedProviderCredentialChecks(subjects, {
+					candidatesOf: (name) => (typeof oracle?.providerKeyCandidates === "function" ? oracle.providerKeyCandidates(name) : []),
+					forwarded: (env.PI_FORWARD_ENV ?? "").split(",").map((name) => name.trim()).filter((name) => name !== ""),
+					env,
+					overlay: overlayDoc,
+				}),
+			);
+		}
+	}
+
 	// REQ-TRIGGER-SECRETS. Only reported when a trigger actually binds one, on the run.resume block's
 	// reasoning below: a deployment that uses no secrets should not be told about a variable it has no
 	// reason to set.
@@ -2853,7 +3372,7 @@ export async function collectChecks(shellVars, seams) {
 	// a deployment whose unit exits 1 in a restart loop is not a deployment that is merely unconfigured in
 	// this shell. Where the file merely configures what this shell does not, the line still says which
 	// process would honour it, and is still a warning.
-	const envFile = envFileKeys(join(cwd, ".env"), ["PI_PAUSE_WINDOWS_FILE", "PI_SCOPED_LIMITS_FILE"], { fileExists, readEnvFile, platform });
+	const envFile = envFileKeys(join(cwd, ".env"), BOOT_FILES.map((spec) => spec.key), { fileExists, readEnvFile, platform });
 	// ONE RULE FOR BOTH BOOT FILES, and it asks the worker's own loader rather than a second opinion
 	// (issue #384). Before this there were two hand-written copies of a shell-shaped check for
 	// `PI_PAUSE_WINDOWS_FILE`, a THIRD rule for a scoped-limits file that does not parse, and no rule at all
@@ -2873,7 +3392,7 @@ export async function collectChecks(shellVars, seams) {
 	// The IO the load verdict uses, injected like everything else this file touches: `statFile` for the
 	// regular-file guard and the loaders' own two reads. A test drives a whole deployment through these
 	// without a real file, which is how the fixtures below stay honest about content.
-	const seamsForLoad = { statFile: statSeam, loaderIo: { existsSync: (p) => fileExists(p), readFileSync: readEnvFile ? (p, enc) => asText(readEnvFile(p), enc) : readFileSync } };
+	const seamsForLoad = { env, statFile: statSeam, loaderIo: { existsSync: (p) => fileExists(p), readFileSync: readEnvFile ? (p, enc) => asText(readEnvFile(p), enc) : readFileSync } };
 	// ONCE PER FILE, not once per key (issue #396). This is a fact about the FILE -- one line the reader
 	// cannot model -- and it was announced inside the per-key loop, so a `.env` with one such line produced
 	// two near-identical warnings differing only in which key they named. The keys it prevents a verdict
@@ -2893,7 +3412,7 @@ export async function collectChecks(shellVars, seams) {
 		// A SHAPE comes from systemd's own line structure (issue #447): the line is one systemd reads differently from
 		// this command, and the table names it and what to change -- the same words `service install` refuses with.
 		const shape = envFile.hazard.shape ? SYSTEMD_HAZARD_SHAPES[envFile.hazard.shape] : null;
-		const limit = "Other keys in the same file are affected too and are not checked here: this command reads only the two it names";
+		const limit = `Other keys in the same file are affected too and are not checked here: this command reads only the ${countWord(BOOT_FILES.length)} it names`;
 		// A file systemd will not LOAD is a service that does not start (measured on systemd 259), which is a failure
 		// rather than a doubt about one reading (issue #447, gate round 1).
 		const unloadable = envFile.hazard.shape === "nul" || envFile.hazard.shape === "invalid-utf8" || envFile.hazard.shape === "exec-too-large";
@@ -2951,10 +3470,10 @@ export async function collectChecks(shellVars, seams) {
 			checks.push({
 				ok: false,
 				warn: envSetup !== null,
-				label: `${spec.key} is assigned an EMPTY value in ${join(cwd, ".env")}, which is not unset: ${loaderName} keeps it, the worker tries to load "" and REFUSES TO START${alsoExported === undefined ? "" : `, while ${otherName} would take ${envValueShown(alsoExported)}, so two deployments of this one file disagree`}`,
+				label: `${spec.key} is assigned an EMPTY value in ${join(cwd, ".env")}, which is not unset: ${loaderName} keeps it, the worker tries to load "" and ${spec.fails}${alsoExported === undefined ? "" : `, while ${otherName} would take ${envValueShown(alsoExported)}, so two deployments of this one file disagree`}`,
 				fix: envSetup !== null
 					? `${envSetup} runs after that file and may replace it, which is why this is a warning: if it does not, delete the ${spec.key} line, or give it the absolute path (${scaffolded})`
-					: `delete the ${spec.key} line from that .env, or give it a path: ${fixLineFor(spec.key, scaffolded)}. Deleting it turns ${spec.noun} off; an empty value turns the worker off`,
+					: `delete the ${spec.key} line from that .env, or give it a path: ${fixLineFor(spec.key, scaffolded)}. Deleting it ${spec.whenDeleted}; an empty value ${spec.whenEmpty}`,
 			});
 		} else if (envFile.hazard == null && notPlainLine !== undefined) {
 			// NAMED, NEVER QUOTED. The value is outside the grammar every loader reads the same way, so this
@@ -2983,7 +3502,7 @@ export async function collectChecks(shellVars, seams) {
 			checks.push({
 				ok: false,
 				warn: true,
-				label: `${spec.key} is assigned TWICE in ${join(cwd, ".env")} with different values: ${loaderName} takes ${envValueShown(fileRaw)}, ${otherName} would take ${alsoExported === "" ? "an EMPTY value, which refuses the boot" : envValueShown(alsoExported)}`,
+				label: `${spec.key} is assigned TWICE in ${join(cwd, ".env")} with different values: ${loaderName} takes ${envValueShown(fileRaw)}, ${otherName} would take ${alsoExported === "" ? `an EMPTY value, which ${spec.emptyCost}` : envValueShown(alsoExported)}`,
 				fix: `keep one assignment. Which one is in force depends on how the worker starts, so two of them means two deployments of the same file disagree`,
 			});
 		}
@@ -3004,7 +3523,7 @@ export async function collectChecks(shellVars, seams) {
 					: {
 							ok: false,
 							warn: envSetup !== null,
-							label: `${spec.key} is set in ${join(cwd, ".env")} (${envValueShown(fileRaw)}) to a file the worker cannot load, so a service started from it REFUSES TO START: ${verdict.reason}`,
+							label: `${spec.key} is set in ${join(cwd, ".env")} (${envValueShown(fileRaw)}) to a file the worker cannot load, so a service started from it ${spec.fails}: ${verdict.reason}`,
 							fix: envSetup !== null ? `${envSetup} runs after that file and may replace it; if it does not, fix ${envValueShown(fileRaw)} or point the key at a file that loads` : `fix ${envValueShown(fileRaw)}, or point ${spec.key} at a file that loads`,
 						},
 			);
@@ -3014,18 +3533,35 @@ export async function collectChecks(shellVars, seams) {
 		if (typeof shellRaw === "string" && shellRaw.trim() === "") {
 			checks.push({
 				ok: false,
-				label: `${spec.key} is set to an EMPTY value in this shell, which is not unset: the worker keeps it, tries to load "" and REFUSES TO START`,
-				fix: `unset ${spec.key} in this shell (that turns ${spec.noun} off), or give it the absolute path: export ${fixLineFor(spec.key, scaffolded)}`,
+				label: `${spec.key} is set to an EMPTY value in this shell, which is not unset: the worker keeps it, tries to load "" and ${spec.fails}`,
+				fix: `unset ${spec.key} in this shell (that ${spec.whenDeleted}), or give it the absolute path: export ${fixLineFor(spec.key, scaffolded)}`,
 			});
 		} else if (typeof shellRaw === "string") {
 			const verdict = loadVerdict(spec, shellRaw, cwd, seamsForLoad, platform);
 			if (!verdict.ok) {
 				checks.push({
 					ok: false,
-					label: `${spec.key} is set in this shell to a file the worker cannot load, so it REFUSES TO START: ${verdict.reason}`,
+					label: `${spec.key} is set in this shell to a file the worker cannot load, so it ${spec.fails}: ${verdict.reason}`,
 					fix: `fix ${envValueShown(shellRaw)}, or point ${spec.key} at a file that loads`,
 				});
 			}
+		} else if (spec.defaultsToScaffold) {
+			// Issue #503: unset is the scaffold, so it is that file which is judged, when nothing in .env says otherwise and it
+			// is there at all (a missing default file declares nothing, which is valid). Silent when it loads. Before the
+			// unreadable-.env line, which asks whether the service is configured for a feature unset turns off: unset turns
+			// nothing off here.
+			// Asked of `statFile`, the seam the load itself uses, so "missing" is ENOENT from the same place and a missing
+			// default stays silent however `fileExists` is seamed.
+			if (fileRaw === undefined && onlyExported === undefined && alsoExported === undefined && notPlainLine === undefined && !blankInFile && envFile.hazard == null && presentAt(statSeam, scaffolded)) {
+				const verdict = loadVerdict(spec, scaffolded, cwd, seamsForLoad, platform);
+				if (!verdict.ok) {
+					checks.push({
+						ok: false,
+						label: `${spec.key} is unset, so ${spec.unsetMeans}, and it does not load: the worker ${spec.fails}: ${verdict.reason}`,
+						fix: `fix ${envValueShown(scaffolded)}, or empty its "endpoints" list`,
+					});
+				}
+			}
 		} else if (envFile.unreadable === true) {
 			// COULD NOT READ, said as itself. The alternative -- the "unset" line below -- is a positive claim
 			// about a key in a file nobody could open.
@@ -3044,11 +3580,17 @@ export async function collectChecks(shellVars, seams) {
 				ok: false,
 				warn: true,
 				label: `${scaffolded} exists but ${spec.key} is unset -- the worker ignores it, so ${spec.off}`,
-				fix: `set ${fixLineFor(spec.key, scaffolded)} in .env and restart the worker -- unset means ${spec.unsetMeans}, while the admin panel defaults to this same file and reports each ${spec.unit} it writes as applied live; delete the file if this deployment has no ${spec.nothing}`,
+				fix: `set ${fixLineFor(spec.key, scaffolded)} in .env and restart the worker -- unset means ${spec.unsetMeans}${spec.panelWrites === false ? "" : `, while the admin panel defaults to this same file and reports each ${spec.unit} it writes as applied live`}; delete the file if this deployment has no ${spec.nothing}`,
 			});
 		}
 	}
 
+	// A scope that can only ever be a folder (issue #242's dead-scope rule): a forge repo always contains "/" and never
+	// begins "/", "./" or "../" or carries a backslash. A forge-qualified row (issue #498) names a repo by construction,
+	// so it is never one. Shared by the dead-scope advisory and the bare-repo one below, so one row is never called a
+	// dead folder by one line and a bare repo by the other.
+	const folderOnly = (s) => scopeFormOf(s) !== "qualified" && (s.startsWith("/") || s.startsWith("./") || s.startsWith("../") || s.includes("\\") || !s.includes("/") || /^[A-Za-z]:/.test(s));
+
 	// The dead-scope advisory (issue #242), honest about what doctor can actually judge. A forge repo
 	// always contains "/" and never begins "/", "./" or "../" or carries a backslash, so a scope in any
 	// of THOSE shapes can only ever be a folder -- and a folder row that matches no trigger's canonical
@@ -3062,18 +3604,51 @@ export async function collectChecks(shellVars, seams) {
 	// shape `render` prints the fix line too, which the old `ok: true` never did.
 	if (scopedLimitFacts.parseError === null && scopedLimitFacts.limits.length > 0 && parseError === null && triggersFilePath !== null) {
 		const folderSet = new Set(folders);
-		const folderOnly = (s) => s.startsWith("/") || s.startsWith("./") || s.startsWith("../") || s.includes("\\") || !s.includes("/") || /^[A-Za-z]:/.test(s);
-		const dead = scopedLimitFacts.limits.map((l) => l.scope).filter((s) => folderOnly(s) && !folderSet.has(s));
+		// A model row (version 2) names a model, never a folder, so it is never "a folder no trigger runs in"; nor is a
+		// project row (issue #499 part B), which names a project.
+		const dead = scopedLimitFacts.limits.map((l) => l.scope).filter((s) => !isModelScope(s) && !isProjectScope(s) && folderOnly(s) && !folderSet.has(s));
 		if (dead.length > 0) {
 			checks.push({
 				ok: false,
 				warn: true,
-				label: `${dead.length} scoped limit(s) name a folder no trigger runs in (${dead.join(", ")}) -- the cap guards nothing; scopes match exactly (no globs, folders by resolved ABSOLUTE path), so check the spelling against triggers.json run.folder or delete the entry`,
+				label: `${dead.length} scoped limit(s) name a folder no trigger runs in (${dead.join(", ")}) -- no trigger runs there, so unless a CLI or local job does, the cap guards nothing; scopes match exactly (no globs, folders by resolved ABSOLUTE path), so check the spelling against triggers.json run.folder or delete the entry`,
 				fix: `edit ${scopedLimitFacts.path} by hand or via dispatch_limit_edit/_delete -- repo-shaped scopes are never flagged here, because a webhook job's repo comes from the delivery, which triggers.json cannot enumerate`,
 			});
 		}
 	}
 
+	// Issue #499 part B: a `project:<id>` row whose id is not in projects.json. The worker refuses to start on it
+	// (start.mjs, `checkProjectRows`), so this is a FAILURE naming the row and the id. Skipped when either file does not
+	// load: that is the BOOT_FILES line's, and a zeroed list here would name every project row as dangling.
+	if (scopedLimitFacts.parseError === null && scopedLimitFacts.limits.length > 0) {
+		const projectFacts = readProjectFacts(env, fileExists);
+		if (projectFacts.parseError === null) checks.push(...projectRowChecks(scopedLimitFacts.limits, projectFacts.projects, scopedLimitFacts.path));
+	}
+
+	// Issue #504 part B: the envelope's advisories, on the file the service names, when it loads (a file that does not is
+	// the BOOT_FILES line's). Warnings only: the worker boots on both.
+	const envelopeFactsHere = readEnvelopeFacts(env);
+	if (envelopeFactsHere.envelope) checks.push(...envelopeChecks(envelopeFactsHere.envelope, envelopeFactsHere.projects, envelopeFactsHere.maxCostMicros));
+
+	// Issue #498: a BARE repo scope (`acme/web`) matches that repo on every forge, so with triggers on more than one forge
+	// kind a bare row is one cap (one lease, one count) shared by GitHub's acme/web and Forgejo's, and a bare pause window
+	// pauses both. That may be meant, so this is a WARNING naming the qualified spellings, never a failure: refusing bare
+	// rows would stop existing workers from booting. Guarded like the dead-scope advisory, on readable triggers.
+	if (parseError === null && triggersFilePath !== null && forges.length > 1) {
+		const bareRows = scopedLimitFacts.parseError === null ? scopedLimitFacts.limits.map((l) => l.scope).filter((s) => !isModelScope(s) && !isProjectScope(s) && scopeFormOf(s) === "bare" && !folderOnly(s)) : [];
+		const bareWindows = pauseWindowFacts.parseError === null ? [...new Set(pauseWindowFacts.windows.map((w) => w.scope).filter((s) => s !== "*" && scopeFormOf(s) === "bare" && !folderOnly(s)))] : [];
+		const named = [...new Set([...bareRows, ...bareWindows])];
+		if (named.length > 0) {
+			const what = [bareRows.length > 0 ? `${bareRows.length} scoped limit(s)` : null, bareWindows.length > 0 ? `${bareWindows.length} pause window(s)` : null].filter(Boolean).join(" and ");
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `${what} name a bare repo (${named.join(", ")}) while triggers run on ${forges.join(" and ")}: a bare scope matches that repo on EVERY forge, so one cap, lease or pause covers all of them`,
+				fix: `if each forge should count on its own, write the scope forge-qualified: ${named.map((s) => forges.map((k) => `${k}:${s}`).join(" or ")).join("; ")} (a qualified row starts a new count, and a bare and a qualified row for one repo cannot both exist); keep the bare form if one shared cap is what you meant`,
+			});
+		}
+	}
+
 	// Issue #464: the jobs dir is this account's to write. PI_JOBS_DIR, PI_SANDBOX_DIR and TMPDIR as the service reads them
 	// (TMPDIR in .env is a documented way out of a squatted default root, so doctor judges the root the service will use).
 	let dirRefused = false;
@@ -3192,6 +3767,37 @@ export async function collectChecks(shellVars, seams) {
 			const refused = inRoot.length > 0 && !said ? accountRootRefusal(root, { uid, fs: seams.jobsDirFs, ownerName: (id) => ownerNameFromPasswd(seams.passwd, id), what: `this account's ${inRoot.map((st) => (st.key === "PI_LOGS_DIR" ? "run history" : "settings overlay")).join(" and ")} (no home directory, so the default is here)` }) : null;
 			if (refused) checks.push({ ok: false, label: refused.label, fix: `${refused.fix}; or set ${inRoot.map((st) => st.key).join(" and ")} to a path this account owns` });
 		}
+		// Issue #501: the overlay itself, read by the worker's own reader. A present-but-invalid file refuses EVERY job
+		// (`settings-overlay-invalid`) while the worker otherwise runs clean, and since #501 a file that loaded before can
+		// become invalid on upgrade: a duplicate key, which used to take the last value, is now refused. The reason names
+		// keys only, never values. Absent is the normal empty overlay and says nothing.
+		if (fileExists(settingsFile)) {
+			const overlay = readOverlay(settingsFile);
+			if (overlay.invalid) {
+				checks.push({
+					ok: false,
+					label: `settings overlay ${settingsFile} is invalid (${overlay.invalid}) -- the worker refuses every job as settings-overlay-invalid until it is fixed, and the panel refuses to write over it`,
+					// The fix follows the reason: only a duplicate key gets the upgrade note, since only it loaded before #501.
+					fix: /duplicate key/.test(overlay.invalid)
+						? "remove the repeated key from that file, keeping the value you mean (a duplicate key is refused since issue #501; it used to take the last value), or delete the file to start from an empty overlay"
+						: "fix what the reason names in that file, or delete the file to start from an empty overlay",
+				});
+			} else {
+				// Issue #501 (PR #542's review): a VALID overlay can still break the dollar invariant once merged over env
+				// (a window in one, no maxCostUsd in either), which the worker checks per job and answers by refusing every
+				// job. The env-only half is `dollarChecks`; this is the merged half, said only when env alone is fine.
+				const merged = overlayDollarProblem(overlay.overlay, env);
+				if (merged) checks.push({ ok: false, label: `settings overlay ${settingsFile}: ${merged} -- the worker refuses every job as settings-overlay-invalid`, fix: "set maxCostUsd in the overlay (or PI_MAX_COST_USD in .env), or remove the dollar window" });
+			}
+		}
+		// PR #549's review: the scoped-limits dollar rows against the deployment's per-job cap, env and overlay merged
+		// the worker's way (an overlay value wins; an invalid overlay leaves env).
+		if (scopedLimitFacts.parseError === null && scopedLimitFacts.limits.length > 0) {
+			const overlay = fileExists(settingsFile) ? readOverlay(settingsFile) : { overlay: {} };
+			const fromOverlay = overlay.invalid ? undefined : overlay.overlay?.maxCostUsd;
+			const envCap = env.PI_MAX_COST_USD === undefined || env.PI_MAX_COST_USD === "" ? undefined : env.PI_MAX_COST_USD;
+			checks.push(...scopedDollarRowChecks(scopedLimitFacts.limits, fromOverlay ?? envCap, scopedLimitFacts.path));
+		}
 		if (noHome) {
 			checks.push({
 				ok: false,
@@ -3433,7 +4039,7 @@ async function defaultProviderOracle() {
  * Never carries a fixAction (the never tier): doctor cannot know which provider an operator meant, and
  * never mints a credential.
  */
-function providerKeyCheck({ provider, env, agentDir, oracle, nodeOk }) {
+function providerKeyCheck({ provider, env, agentDir, oracle, nodeOk, keyless = null }) {
 	if (!oracle?.providerKeyCandidates) {
 		// pi did not load: below-floor Node, or a tree with no dependencies installed.
 		//
@@ -3459,7 +4065,7 @@ function providerKeyCheck({ provider, env, agentDir, oracle, nodeOk }) {
 		};
 	}
 	const candidates = oracle.providerKeyCandidates(provider);
-	if (candidates.length === 0) return noKeyVariableCheck(provider, oracle);
+	if (candidates.length === 0) return noKeyVariableCheck(provider, oracle, keyless);
 
 	// Presence by PI'S truthiness, not a stricter one. This used to trim, and trimming made doctor pick a
 	// DIFFERENT variable than the worker will: with a whitespace `ANTHROPIC_OAUTH_TOKEN` beside a real
@@ -3622,7 +4228,7 @@ function usablePiLoginKey(agentDir, provider) {
  * the distinction `findEnvKeys`'s single `undefined` cannot make, and the reason issue #286 needed a
  * second question at all.
  */
-function noKeyVariableCheck(provider, oracle) {
+function noKeyVariableCheck(provider, oracle, keyless = null) {
 	if (oracle.piProviders().includes(provider)) {
 		// `amazon-bedrock` wants AWS credentials or a profile, `openai-codex` an OAuth login. Both are
 		// credential SOURCES the closed container env has no door for, so buildContainerEnv refuses every
@@ -3637,14 +4243,37 @@ function noKeyVariableCheck(provider, oracle) {
 	// `<PROVIDER>_API_KEY`. For the case that motivated this -- PI_PROVIDER=gemini -- GEMINI_API_KEY is
 	// `google`'s variable, so the answer is exact. Nothing edit-distance-based would find it (gemini and
 	// google differ by five characters), which is why this matches on the VARIABLE, not on the name.
+	// Issue #503: the worker's own keyless verdict (model-endpoints.mjs), on the same predicate and in the same order as
+	// the credential gate (no key variable, not in pi's catalog), so this line and the worker cannot disagree.
+	const endpoints = Array.isArray(keyless?.endpoints) ? keyless.endpoints : [];
+	if (endpoints.length > 0 && typeof keyless?.unreadable === "string") {
+		// Issue #552: only a transient errno is retried; any other refuses every job at the model gate, before this one.
+		const retried = isTransientOverlayRead(keyless.unreadable);
+		return {
+			ok: false,
+			warn: retried,
+			label: `Provider key: could not read models.json (${keyless.unreadable}), so whether ${JSON.stringify(provider)} is keyless is not known; ${retried ? "the worker retries such a job once, then fails it" : "the worker refuses every job until it can read it (overlay-unreadable)"}`,
+			fix: "make the overlay's models.json readable by the account the worker runs as, then re-run doctor",
+		};
+	}
+	const verdict = endpoints.length > 0 ? keylessVerdict({ models: keyless.models, provider, endpoints }) : { keyless: false, why: null };
+	if (verdict.keyless) {
+		return { ok: true, label: `Provider key: none needed (${provider} is keyless: served by declared endpoint ${verdict.endpoints.join(", ")})` };
+	}
 	const wanted = `${provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
 	const owner = oracle.piProviders().find((id) => oracle.providerKeyCandidates(id).includes(wanted));
+	// Why a custom provider the overlay defines is not keyless, when it is one: the one fact the operator has to change.
+	const why = verdict.why ? `; it is not keyless because ${verdict.why}` : "";
+	// Issue #587: an id pi renamed (azure-openai-responses is `azure` since pi 1.0.3), named, unless the overlay declares it.
+	const renamed = providerRenameHint(provider, { models: keyless?.hintModels ?? keyless?.models ?? null, overlayUnread: keyless?.hintUnread === true, piProviders: oracle.piProviders() });
 	return {
 		ok: false,
-		label: `PI_PROVIDER is ${JSON.stringify(provider)}, which is not a provider pi has`,
-		fix: owner
-			? `set PI_PROVIDER=${owner}, the provider pi reads ${wanted} from -- or unset it for the default \`anthropic\``
-			: `set PI_PROVIDER to a provider id pi has, or unset it for the default \`anthropic\`: ${oracle.piProviders().join(", ")}`,
+		label: `PI_PROVIDER is ${JSON.stringify(provider)}, which is not a provider pi has${why}${renamed ? `;${renamed}` : ""}`,
+		fix: renamed
+			? `set PI_PROVIDER=${RENAMED_PROVIDERS[provider]}, and rename the provider in every trigger's model and allowed-models entries and in models.json the same way (docs/triggers.md)`
+			: owner
+			? `set PI_PROVIDER=${owner}, the provider pi reads ${wanted} from -- or unset it for the default \`anthropic\`; or, ${KEYLESS_HOW}`
+			: `set PI_PROVIDER to a provider id pi has, or unset it for the default \`anthropic\`: ${oracle.piProviders().join(", ")}; or, ${KEYLESS_HOW}`,
 	};
 }
 
@@ -3848,102 +4477,887 @@ function readScopedLimitFacts(env, fileExists) {
 }
 
 /**
- * How a line names its trigger: cron entries by their id, id-less webhook entries by raw file position (the admin's
- * trigger:<index> identity). One function, because the flow lines and the venue lines must name a trigger alike.
+ * The projects facts (issue #499 part B): the parsed projects when PI_PROJECTS_FILE is set, `[]` when it is unset (no
+ * projects, so every project row dangles), or a parse error when it is set and does not load (the BOOT_FILES line's).
  */
-function triggerLabel(t, index) {
-	return t.on.type === "cron" ? `cron "${t.on.id}"` : `${t.on.type} trigger #${index}`;
+function readProjectFacts(env, fileExists) {
+	const path = env.PI_PROJECTS_FILE;
+	if (typeof path !== "string" || path.trim() === "") return { projects: [], parseError: null };
+	try {
+		if (!fileExists(path) || !statSync(path).isFile()) return { projects: [], parseError: "unreadable" };
+		return { projects: loadProjects({ projectsFile: path }, { readFileSync, existsSync: fileExists }), parseError: null };
+	} catch (e) {
+		return { projects: [], parseError: e?.message ?? String(e) };
+	}
 }
 
-function readTriggerFacts(env, fileExists, cwd, declaredWorkerName) {
-	const none = { requiring: 0, waiting: 0, waitProfiles: [], waitAfters: [], optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, onceArmed: 0, onceSpent: 0, secretProfiles: [], localSecretFolders: [], secretNames: [], folders: [], images: [], imageRoutes: [], namedBackends: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
+/**
+ * The envelope facts (issue #504 part B): the envelope as the worker would load it, the projects and the per-job cap it
+ * was judged against, or a parse error when `PI_ENVELOPE_FILE` is set and does not load (the BOOT_FILES line's).
+ * `envelope` is null when the key is unset.
+ */
+function readEnvelopeFacts(env) {
+	const path = nonEmpty(env.PI_ENVELOPE_FILE);
+	if (path === null) return { envelope: null, projects: [], maxCostMicros: null, parseError: null };
+	const io = { readFileSync, existsSync };
 	try {
-		// Unset falls back to ./triggers.json in cwd, MIRRORING the receiver's own default
-		// (receiver/src/config.mjs) -- the two must read the same file, or doctor preflights a deployment
-		// the receiver will not boot. An absent file still means "no triggers at all", exactly as before.
-		const path = triggersPath(env, cwd);
-		if (!fileExists(path)) return none;
-		// The same regular-file guard, for the same reason: this read is unbounded too, and a triggers path
-		// naming a FIFO hangs the command with no output and no timeout that can reach it.
-		if (!statSync(path).isFile()) return { ...none, parseError: `triggers file is not a regular file: ${path}`, path };
-		const text = readFileSync(path, "utf8");
-		const triggers = parseTriggers(text, path);
-		// The one-shot facts are counted from the RAW entries, not the parsed records, because the
-		// validator collapses a disarmed entry to a sentinel that carries neither `once` nor
-		// `disarmed` -- exactly so nothing can match it -- which also erases it from every parsed
-		// count above. Doctor is the surface that must still SEE the spent entry: "why did nothing
-		// fire" is answered by a spent row, and only the raw file still holds it. Safe unguarded:
-		// parseTriggers just accepted this same text, so JSON.parse cannot throw here.
-		const rawEntries = JSON.parse(text)?.triggers ?? [];
-		// Issue #433 review rounds 2 and 3: whether THIS HOST'S WORKER schedules a cron trigger, for the unblessed-venue
-		// line, by the worker's two conditions and nothing else. (a) The worker schedules cron only from a PI_TRIGGERS_FILE
-		// it was given (`config.triggersFile` is null without one, and `loadSchedules` then returns []), while doctor
-		// falls back to ./triggers.json for everything else it reads; so without the variable no cron trigger is judged.
-		// (b) Its placement, by the worker's own predicate (`cronPlacement`): judged unless it is `"elsewhere"`, another
-		// machine's folder on a fleet. A single host's absent folder is `"refused"`, the worker's boot refusal, and is
-		// still judged. Round 2 ran the whole `loadSchedules` instead and caught its throw as "judge everything", which let
-		// one served trigger's bad skillsDir bring back the false line for another machine's trigger: a predicate per
-		// trigger cannot be derailed by a sibling.
-		// The name collectChecks resolved (issue #464), never this shell's alone.
-		const fleet = Boolean(declaredWorkerName);
-		const cronScheduledHere = (t) => env.PI_TRIGGERS_FILE !== undefined && cronPlacement(t.run, { existsSync: fileExists, fleet }) !== "elsewhere";
-		return {
-			onceArmed: rawEntries.filter((t) => t?.on?.once === true && t.on.disarmed === undefined).length,
-			onceSpent: rawEntries.filter((t) => t?.on?.disarmed !== undefined).length,
-			requiring: triggers.filter((t) => t.run.packages === true).length,
-			resuming: triggers.filter((t) => t.run.resume === true).length,
-			// REQ-PER-TRIGGER-INSTRUCTION. Counted beside `resuming` for the same reason: it is a per-trigger
-			// choice that changes what every job of it is told, and an operator should see it before it fires.
-			instructing: triggers.filter((t) => typeof t.run.instructions === "string").length,
-			// REQ-REPLICA-RUNS. `> 1` rather than `!== undefined` because the loader already refuses anything
-			// else -- this counts triggers that will actually multiply spend, which is the only reason to say so.
-			replicating: triggers.filter((t) => t.run.replicas > 1).length,
-			// run.command triggers (issue #189), counted for the one advisory line below. The `flows`
-			// tuple list already filters to `typeof f.flow === "string"`, so a command trigger drops out
-			// of the flow-tier probes naturally -- no exclusion needed there.
-			commands: triggers.filter((t) => typeof t.run.command === "string").length,
-			// REQ-TRIGGER-SECRETS. Counted beside `instructing` for its reason: a per-trigger choice that
-			// changes what every job of it can reach, and one that lives only in triggers.json.
-			secreting: triggers.filter((t) => t.run.secrets !== undefined).length,
-			// The distinct profile NAMES the file selects, deduped like `images`/`skillsDirs`: the checks below
-			// cost a stat each, and two triggers naming one profile are one question. `default` is substituted
-			// for an absent field so the table answers what the worker will actually look up.
-			secretProfiles: [...new Set(triggers.filter((t) => t.run.secrets !== undefined).map((t) => t.run.secretsProfile ?? "default"))].sort(),
-			// LOCAL triggers that bind secrets, by folder. A local job's /workspace IS this folder, bind-mounted
-			// read-write with no clone, so a credential an agent writes into .env lands in the operator's real
-			// repository rather than a temp dir that gets swept. Deduped for skillsDirs' reason.
-			localSecretFolders: [...new Set(triggers.filter((t) => t.run.secrets !== undefined && t.run.kind === "local" && typeof t.run.folder === "string").map((t) => t.run.folder))].sort(),
-			// Issue #309. The distinct variable NAMES the file binds, deduped like the profiles above. The
-			// pre-spend gate refuses a name pi reads for the job's provider, and unlike the version that gate
-			// replaced, that question no longer needs host state to answer -- so doctor can answer it at setup
-			// rather than leaving the operator to meet it as a public refusal on a live job.
-			secretNames: [...new Set(triggers.filter((t) => t.run.secrets !== undefined).flatMap((t) => Object.keys(t.run.secrets)))].sort(),
-			// Issue #242: every local run.folder, CANONICALIZED the way the scoped-limits matcher
-			// canonicalizes a job's folder (one derivation -- canonicalScope, never re-spelled here), so
-			// the unreferenced-scope advisory compares like with like across spelling variants.
-			folders: [...new Set(triggers.filter((t) => t.run.kind === "local" && typeof t.run.folder === "string").map((t) => canonicalScope({ kind: "local", folder: t.run.folder })))].sort(),
-			// Issue #230. How many triggers hold their jobs, and the distinct profile NAMES they select --
-			// deduped like `secretProfiles` and for its reason: each name costs a lookup, and two triggers
-			// waiting on one profile are one question.
-			waiting: triggers.filter((t) => Array.isArray(t.run.waitFor) && t.run.waitFor.length > 0).length,
-			// The `after` instants as WRITTEN, deduped. Not parsed here: `readTriggerFacts` is a fact reader and
-			// the ceiling it is measured against is env, which belongs at the check. Two triggers naming one
-			// instant are one finding, and the raw string is what the operator has to go and edit.
-			waitAfters: [...new Set(triggers.flatMap((t) => (Array.isArray(t.run.waitFor) ? t.run.waitFor : [])).map((c) => c?.after).filter((v) => typeof v === "string"))].sort(),
-			waitProfiles: [
-				...new Set(
-					triggers
-						.filter((t) => Array.isArray(t.run.waitFor))
-						.flatMap((t) => t.run.waitFor.map((c) => c?.profile).filter((n) => typeof n === "string")),
-				),
-			].sort(),
-			optingOut: triggers.filter((t) => t.run.packages === false).length,
-			images: [...new Set(triggers.map((t) => t.run.image).filter((i) => typeof i === "string"))].sort(),
-			// Issue #433: each image with the venue its trigger names (undefined: the deployment default), so the image is
-			// asked of the runtime its jobs start on. The worker's own shape (`{ backend }`), for `resolveBackendName`.
-			imageRoutes: triggers.filter((t) => typeof t.run.image === "string").map((t) => ({ image: t.run.image, backend: t.run.backend })),
-			// Issue #433 review round 1: every trigger that NAMES a venue, with the label the lines below name it by, so
-			// doctor can say which of them this deployment does not bless (the worker refuses each of their jobs).
+		const context = envelopeContextOf(env, io);
+		return { envelope: loadEnvelopeAsTheWorker(path, io, env), projects: context.projects, maxCostMicros: context.maxCostMicros, parseError: null };
+	} catch (e) {
+		return { envelope: null, projects: [], maxCostMicros: null, parseError: e?.message ?? String(e) };
+	}
+}
+
+/**
+ * The envelope's advisories (issue #504 part B, INT-ENVELOPE-FILE-CONTRACT), WARNINGS the worker boots on:
+ *   - a floor above 0 and below the per-job cost cap: every governed job reserves its per-job cap against its share, so a
+ *     floor that small admits no job of its own (it still counts toward the total);
+ *   - a project in projects.json that the envelope does not name: its jobs count in `_other`'s share.
+ * Plus one line of facts: the digest (what `fpEnvelope` and `alloc:envelope:expected` hold), the window, the total and
+ * whether delegation is on. Ids and amounts only.
+ */
+export function envelopeChecks(envelope, projects, maxCostMicros) {
+	const checks = [{ ok: true, label: `Allocation envelope ${envelopeDigest(envelope)}: ${formatMicros(envelope.totalMicros)} a ${envelope.window}, ${Object.keys(envelope.floors).length} entries, delegation ${envelope.delegation?.enabled ? `ON (writers ${envelope.delegation.writers.join(", ")}, step ${envelope.delegation.maxStepPct}%, interval ${envelope.delegation.minIntervalHours}h)` : "OFF"}` }];
+	const low = Object.entries(envelope.floors).filter(([, floor]) => floor > 0 && Number.isSafeInteger(maxCostMicros) && floor < maxCostMicros);
+	if (low.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `envelope floor(s) ${low.map(([id, floor]) => `${id} (${formatMicros(floor)})`).join(", ")} are below the per-job cost cap (${formatMicros(maxCostMicros)}): each governed job reserves its whole cap against its share, so a floor that small admits no job of its own`,
+			fix: "raise the floor to at least the per-job cap (PI_MAX_COST_USD), lower the cap, or set the floor to 0 if the project needs no guaranteed share",
+		});
+	}
+	const absent = (Array.isArray(projects) ? projects : []).map((p) => p?.id).filter((id) => typeof id === "string" && id !== OTHER && envelope.floors[id] === undefined);
+	if (absent.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `project(s) ${absent.join(", ")} are in projects.json and not in the envelope, so their jobs count in ${OTHER}'s share of the split`,
+			fix: "add each to the envelope's floorsUsd (0 is a floor) if it should have a share of its own; leave it out if counting it with the work in no project is what you meant",
+		});
+	}
+	return checks;
+}
+
+/**
+ * Issue #504 part B: do this host's envelope and its peers' agree? `mine` is this host's `fpEnvelope` as doctor computes
+ * it from the service's envelope file (`envelopeDigest`, or `none`), `peers` the registry rows of every OTHER host.
+ * WARNINGS only, the fleet block's rule, but the consequence is named: a host whose digest is not the applied split's
+ * refuses every governed job as `envelope-mismatch`.
+ *
+ *   - A peer whose `fpEnvelope` differs: the hosts judge one shared split against two envelopes, so one side refuses.
+ *   - A peer with no `fpEnvelope`: a worker from before the envelope, which enforces no split at all. Said only when an
+ *     envelope is in use somewhere, so a fleet without one hears nothing new on upgrade.
+ * Hosts are named, never a value: the registry carries a digest.
+ */
+export function fleetEnvelopeChecks(mine, peers) {
+	const checks = [];
+	const opinions = peers.filter((h) => typeof h.fpEnvelope === "string" && h.fpEnvelope !== "");
+	const differing = opinions.filter((h) => h.fpEnvelope !== mine);
+	if (differing.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `Hosts disagree about the allocation envelope: ${differing.map((h) => h.name).join(", ")} ${differing.length === 1 ? "has" : "have"} ${differing.every((h) => h.fpEnvelope === NO_ENVELOPE_FINGERPRINT) ? "no envelope" : "an envelope with other numbers"}, and this host ${mine === NO_ENVELOPE_FINGERPRINT ? "has none" : `has ${mine}`}, so the hosts whose envelope is not the applied split's refuse every governed job as envelope-mismatch`,
+			fix: "copy the same envelope.json to every host (PI_ENVELOPE_FILE), or unset it on every host and DEL alloc:plan alloc:envelope:expected; to make a hand edit the fleet's, copy it to every host and SET alloc:envelope:expected to its digest (doctor prints it)",
+		});
+	}
+	const silent = peers.filter((h) => typeof h.fpEnvelope !== "string" || h.fpEnvelope === "");
+	const inUse = mine !== NO_ENVELOPE_FINGERPRINT || opinions.some((h) => h.fpEnvelope !== NO_ENVELOPE_FINGERPRINT);
+	if (silent.length > 0 && inUse) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `${silent.map((h) => h.name).join(", ")} ${silent.length === 1 ? "publishes" : "publish"} no envelope digest, so ${silent.length === 1 ? "it enforces" : "they enforce"} no allocation split while the rest of the fleet does`,
+			fix: "upgrade every worker on this Valkey to the same release: a worker from before the envelope reserves against the operator's caps alone",
+		});
+	}
+	return checks;
+}
+
+/**
+ * The applied split against every host (issue #504 part B). `applied` is `{ digest }`, the
+ * envelope digest `alloc:plan` was made for; `mine` this host's (`none` without an envelope); `peers` the registry rows.
+ * One line of facts naming the hosts that match it, and a FAILURE for this host and for each peer that does not: such a
+ * host refuses every governed job as `envelope-mismatch` (a host with no envelope in a governed fleet included).
+ */
+export function appliedSplitChecks(applied, mine, myName, peers) {
+	const TURN_OFF = "remove PI_ENVELOPE_FILE from every host, then `valkey-cli DEL alloc:plan alloc:envelope:expected`";
+	// Named as the peer lines name theirs (issue #507): on a fleet each host's doctor says "this host", and the line read
+	// beside another host's output did not say which host refuses.
+	const me = typeof myName === "string" && myName !== "" ? `this host (${myName})` : "this host";
+	const noEnvelopeHere = { ok: false, label: `${me} has no envelope while the fleet has an applied budget split (alloc:plan), so it refuses every job as envelope-mismatch`, fix: `install the fleet's envelope here (PI_ENVELOPE_FILE), or turn delegation off for the whole fleet: ${TURN_OFF}` };
+	if (applied.undecodable) {
+		// The key exists and is no split this build can read: a host with an envelope replaces it with the neutral split at
+		// its next job, while a host without one counts it as governed and refuses.
+		const checks = [{ ok: false, warn: true, label: "alloc:plan exists but is not a budget split this build can read; a host with an envelope replaces it with the neutral split at its next job", fix: `if delegation is meant to be off: ${TURN_OFF}` }];
+		if (mine === NO_ENVELOPE_FINGERPRINT) checks.push(noEnvelopeHere);
+		return checks;
+	}
+	const d = applied.digest;
+	const matching = [...(mine === d ? [myName] : []), ...peers.filter((h) => h.fpEnvelope === d).map((h) => h.name)].sort();
+	// Green only while some host matches: a split no host carries the envelope of refuses every governed job everywhere.
+	const checks = [
+		matching.length > 0
+			? { ok: true, label: `Applied budget split (alloc:plan) was made for envelope ${d}: ${matching.join(", ")} ${matching.length === 1 ? "matches" : "match"} it` }
+			: { ok: false, warn: true, label: `Applied budget split (alloc:plan) was made for envelope ${d}, and no host matches it`, fix: `copy that envelope to the hosts, or make another one the fleet's (copy it to every host, then \`valkey-cli SET alloc:envelope:expected <its digest>\`), or turn delegation off: ${TURN_OFF}` },
+	];
+	if (mine !== d) {
+		checks.push(
+			mine === NO_ENVELOPE_FINGERPRINT
+				? noEnvelopeHere
+				: { ok: false, label: `${me} carries envelope ${mine}, not the one the applied budget split was made for (${d}), so it refuses every governed job as envelope-mismatch`, fix: `copy the fleet's envelope here; or, to make this one the fleet's, copy it to every host and run \`valkey-cli SET alloc:envelope:expected ${mine}\`` },
+		);
+	}
+	const off = peers.filter((h) => typeof h.fpEnvelope === "string" && h.fpEnvelope !== "" && h.fpEnvelope !== d);
+	if (off.length > 0) {
+		checks.push({
+			ok: false,
+			label: `${off.map((h) => h.name).join(", ")} ${off.length === 1 ? "carries" : "carry"} ${off.every((h) => h.fpEnvelope === NO_ENVELOPE_FINGERPRINT) ? "no envelope" : "another envelope"}, not the one the applied budget split was made for (${d}), so ${off.length === 1 ? "it refuses" : "they refuse"} every governed job as envelope-mismatch`,
+			fix: `copy the fleet's envelope to those hosts (PI_ENVELOPE_FILE), or turn delegation off for the whole fleet: ${TURN_OFF}`,
+		});
+	}
+	return checks;
+}
+
+/**
+ * The applied split from Valkey (`alloc:plan`): `{ digest }`, `{ undecodable: true }` when the key exists and holds no
+ * readable split, or null with no key or no answer.
+ */
+export async function defaultReadAppliedSplit(url) {
+	try {
+		const { makeRedisClient } = await import("./connection.mjs");
+		const client = makeRedisClient(url, { failFast: true, lazyConnect: true });
+		client.on("error", () => {});
+		try {
+			await client.connect();
+			const text = await client.get(ALLOC_PLAN_KEY);
+			if (text === null || text === undefined) return null;
+			let digest = null;
+			try {
+				digest = JSON.parse(text)?.envelopeDigest;
+			} catch {}
+			return typeof digest === "string" && /^[0-9a-f]{16}$/.test(digest) ? { digest } : { undecodable: true };
+		} finally {
+			client.disconnect();
+		}
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * A FAILURE per scoped-limits file that holds a `project:<id>` row whose id is not a project in `projects` (issue #499
+ * part B): the worker refuses to start on it, and a live reload that would create one is kept out. Rows are named by
+ * index and their scope (`project:<id>`, an operator id, never a path or a name).
+ */
+export function projectRowChecks(limits, projects, path) {
+	const dangling = danglingProjectRows(limits, projects);
+	if (dangling.length === 0) return [];
+	return [
+		{
+			ok: false,
+			label: `scoped limit(s) ${dangling.map((d) => `#${d.index} (project:${d.id})`).join(", ")} in ${path} name a project that is not in the projects file -- the worker refuses to start`,
+			fix: "add the project to the file PI_PROJECTS_FILE names (set the key if it is unset), or remove the row",
+		},
+	];
+}
+
+/**
+ * The pause-windows facts (issue #498): the parsed windows when PI_PAUSE_WINDOWS_FILE is set, else none. A file that
+ * does not load is the BOOT_FILES check's line, so here it only silences the advisories that read the windows.
+ */
+function readPauseWindowFacts(env, fileExists) {
+	const path = env.PI_PAUSE_WINDOWS_FILE;
+	if (typeof path !== "string" || path.trim() === "") return { windows: [], parseError: null };
+	try {
+		if (!fileExists(path) || !statSync(path).isFile()) return { windows: [], parseError: "unreadable" };
+		return { windows: loadPauseWindows({ pauseWindowsFile: path }, { readFileSync, existsSync: fileExists }), parseError: null };
+	} catch (e) {
+		return { windows: [], parseError: e?.message ?? String(e) };
+	}
+}
+
+/** A written scope's form (`parseScopeString`), or null for one it refuses: a fact reader classifies, never throws. */
+function scopeFormOf(scope) {
+	try {
+		return parseScopeString(scope).type;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The dollar settings (issue #501), read from env with the worker's own parser (`money.mjs`), so doctor and
+ * the boot refusal cannot disagree. Silent when nothing is set. Each setting that does not parse, a window
+ * without the per-job cap, and every trigger
+ * whose `run.maxCostUsd` is above `PI_MAX_COST_USD`: a FAILURE when the worker loads the triggers file
+ * (`workerReadsTriggers`, it refuses to start on it), a warning otherwise (the job still runs under the
+ * smaller cap, so the higher one is a value that reads as allowed and is not).
+ */
+/**
+ * The merged-values half of the dollar invariant (issue #501, PR #542's review): `overlay` over `env`, the worker's
+ * own merge, checked by the worker's own rule. Returns the reason, or null when it holds, or when env ALONE already
+ * breaks it (that is `dollarChecks`' line, and the worker refuses to start on it).
+ */
+export function overlayDollarProblem(overlay, env) {
+	const fromEnv = {};
+	for (const key of DOLLAR_SETTING_KEYS) {
+		const raw = env?.[DOLLAR_ENV_NAMES[key]];
+		if (raw !== undefined && raw !== "") fromEnv[key] = raw;
+	}
+	if (checkDollarInvariant(fromEnv) !== null) return null;
+	const merged = { ...fromEnv };
+	for (const key of DOLLAR_SETTING_KEYS) if (overlay?.[key] !== undefined && overlay[key] !== null) merged[key] = overlay[key];
+	return checkDollarInvariant(merged)?.invalid ?? null;
+}
+
+/**
+ * The scoped-limits dollar rows (issues #501 part 5, #502 part 6) against the deployment's per-job cap, WARNINGS only
+ * (PR #549's review). With no per-job cap, a dollar row refuses every job it applies to as `config-refused` unless the
+ * job's trigger sets `run.maxCostUsd`. With one, a row window BELOW it refuses every job it applies to, every time
+ * (a job reserves its whole cap), until one of the two changes. Rows are named by index and kind, and only the caps
+ * are compared, never a scope string (a folder scope is a host path). `maxCostUsd` is the merged value or undefined;
+ * one that does not parse is `dollarChecks`' line, so this says nothing more.
+ */
+export function scopedDollarRowChecks(limits, maxCostUsd, path) {
+	const checks = [];
+	const label = (r) => `#${r.index} (${r.kind === "model" ? "a model row" : r.kind === "project" ? "a project row" : "a repo or folder row"})`;
+	const missing = dollarRowsWithoutCap(limits, maxCostUsd);
+	if (missing.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `scoped limit(s) ${missing.map(label).join(", ")} in ${path} set a dollar window, but the deployment has no per-job cost cap (maxCostUsd) -- every job such a row applies to is refused as config-refused unless its trigger sets run.maxCostUsd`,
+			fix: "set PI_MAX_COST_USD in .env (or maxCostUsd in the overlay), or give each trigger that reaches the row a run.maxCostUsd",
+		});
+	}
+	let below = [];
+	try {
+		below = dollarRowsBelowJobCap(limits, maxCostUsd);
+	} catch {
+		return checks;
+	}
+	if (below.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `scoped limit window(s) ${below.map((r) => `${label(r)} ${r.window}`).join(", ")} in ${path} are below the per-job cost cap (maxCostUsd) -- a job reserves its whole cap, so every job that reaches such a window is refused dollar-cap, every time`,
+			fix: "raise the window to at least maxCostUsd, or lower maxCostUsd (a trigger's smaller run.maxCostUsd also fits)",
+		});
+	}
+	return checks;
+}
+
+export function dollarChecks(env, costCaps, workerReadsTriggers) {
+	const envName = DOLLAR_ENV_NAMES;
+	const checks = [];
+	const values = {};
+	for (const key of DOLLAR_SETTING_KEYS) {
+		const raw = env[envName[key]];
+		if (raw === undefined || raw === "") continue;
+		try {
+			optionalUsdMicros(raw, envName[key]);
+			values[key] = raw;
+		} catch (error) {
+			checks.push({ ok: false, label: `${error.message} -- the worker refuses to start`, fix: `set ${envName[key]} to a plain dollar amount such as 2.50, or remove it` });
+		}
+	}
+	const broken = checkDollarInvariant(values);
+	if (broken) {
+		const window = DOLLAR_SETTING_KEYS.find((key) => key !== "maxCostUsd" && values[key] !== undefined);
+		checks.push({ ok: false, label: `${envName[window]} is set without PI_MAX_COST_USD -- the worker refuses to start`, fix: "a dollar window reserves each job's per-job cap, so set PI_MAX_COST_USD too" });
+	}
+	if (values.maxCostUsd !== undefined) {
+		const deployment = parseUsdMicros(values.maxCostUsd, "PI_MAX_COST_USD");
+		for (const cap of costCaps.filter((c) => parseUsdMicros(c.maxCostUsd, "run.maxCostUsd") > deployment)) {
+			checks.push({
+				ok: false,
+				...(workerReadsTriggers ? {} : { warn: true }),
+				label: workerReadsTriggers
+					? `${cap.label}: run.maxCostUsd is above PI_MAX_COST_USD -- the worker refuses to start (a trigger can only narrow the per-job cost cap)`
+					: `${cap.label}: run.maxCostUsd is above PI_MAX_COST_USD -- its jobs run under PI_MAX_COST_USD anyway (a trigger can only narrow the per-job cost cap)`,
+				fix: "lower that trigger's run.maxCostUsd to PI_MAX_COST_USD or below, or remove it",
+			});
+		}
+	}
+	return checks;
+}
+
+/**
+ * Issue #501 part 6: do this host's dollar caps match its peers'? `mine` is this host's `fpUsd` as doctor computes it
+ * from the service's settings (`deploymentSettingsOf`, `usdFingerprint`), `peers` the registry rows of every OTHER
+ * host. WARNINGS only, never a failure, the fleet block's rule: this command runs on one machine and must not refuse
+ * a deployment for a condition that machine cannot fix.
+ *
+ *   - A peer whose `fpUsd` differs: the dollar counters are shared, so the host with the larger cap admits a job the
+ *     other would refuse, and each host's view of "full" is its own.
+ *   - A peer with no `fpUsd` (or an empty one): it runs a worker from before hosts published one, so whether it holds
+ *     the same caps is unknown. Said only when dollar caps are in use somewhere: this host's fingerprint, or any
+ *     peer's, is not the empty one, or else a dollar counter (`budget:usd:*`) exists on this Valkey
+ *     (`dollarKeysExist`, asked only then). The counters are the one trace a capped host that publishes nothing
+ *     leaves (PR #551's review: an old capped host beside a new uncapped one was silent). A fleet that never used a
+ *     dollar setting hears nothing new on upgrade.
+ *
+ * Hosts are named, never their caps: the registry carries a digest, so "different" is all a reader can know.
+ */
+export async function fleetDollarChecks(mine, peers, { dollarKeysExist = async () => false } = {}) {
+	const checks = [];
+	const opinions = peers.filter((h) => typeof h.fpUsd === "string" && h.fpUsd !== "");
+	const differing = opinions.filter((h) => h.fpUsd !== mine);
+	if (differing.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `Hosts disagree about the dollar caps: ${differing.map((h) => h.name).join(", ")} ${differing.length === 1 ? "judges" : "judge"} the shared dollar counters against a different per-job cap, dollar windows, scoped-limits dollar rows or PI_ALLOWED_MODELS than this host's settings`,
+			fix: "set PI_MAX_COST_USD, PI_DAILY_COST_USD, PI_WEEKLY_COST_USD, PI_MONTHLY_COST_USD, the overlay's dollar keys, the scoped-limits file's dollar rows and PI_ALLOWED_MODELS (it picks the model rows a job without its own list reserves in) alike on every host: the counters are shared, so a host with a larger cap admits a job another would refuse. An env change needs a restart; an overlay or scoped-limits edit shows within one beat",
+		});
+	}
+	const silent = peers.filter((h) => typeof h.fpUsd !== "string" || h.fpUsd === "");
+	if (silent.length === 0) return checks;
+	let inUse = mine !== EMPTY_USD_FINGERPRINT || opinions.some((h) => h.fpUsd !== EMPTY_USD_FINGERPRINT);
+	let byCounters = false;
+	if (!inUse) {
+		byCounters = (await Promise.resolve().then(dollarKeysExist).catch(() => false)) === true;
+		inUse = byCounters;
+	}
+	if (inUse) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `${silent.map((h) => h.name).join(", ")} ${silent.length === 1 ? "publishes no fingerprint of its" : "publish no fingerprint of their"} dollar caps, so whether ${silent.length === 1 ? "it holds" : "they hold"} the same caps as this host is unknown${byCounters ? " (no host that publishes one sets a dollar cap, but dollar counters exist on this Valkey, so some host reserved dollars recently)" : ""}`,
+			fix: "upgrade every worker on this Valkey to the same release: a worker from before hosts compared their dollar caps may judge the shared dollar counters against other caps, or reserve no dollars at all",
+		});
+	}
+	return checks;
+}
+
+/**
+ * Issue #499 part C: do this host's projects match its peers'? `mine` is this host's `fpProjects` as doctor computes it
+ * from the service's projects file (`projectsFingerprint`), `peers` the registry rows of every OTHER host. WARNINGS
+ * only, the fleet block's rule.
+ *
+ *   - A peer whose `fpProjects` differs: each host resolves a job's project from its own copy, so one repo can be in
+ *     two projects, or in a project on one host and in none on another, depending on which host ran the job. Its runs
+ *     are then recorded under two ids and counted against two project rows (or none), while the counters are shared.
+ *   - A peer with no `fpProjects` (or an empty one): it runs a worker from before hosts published one. Said only when
+ *     projects are in use somewhere (this host's fingerprint, or any peer's, is not the one of no projects), so a
+ *     fleet that never used a projects file hears nothing new on upgrade.
+ *
+ * Hosts are named, never a project's members or name: the registry carries a digest, so "different" is all a reader
+ * can know.
+ */
+export function fleetProjectsChecks(mine, peers) {
+	const checks = [];
+	const opinions = peers.filter((h) => typeof h.fpProjects === "string" && h.fpProjects !== "");
+	const differing = opinions.filter((h) => h.fpProjects !== mine);
+	if (differing.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `Hosts disagree about the projects: ${differing.map((h) => h.name).join(", ")} ${differing.length === 1 ? "reads" : "read"} a projects.json with other ids or members than this host's, so a run is recorded under, and counted against, a different project depending on which host ran it`,
+			fix: "copy the same projects.json to every host (PI_PROJECTS_FILE): the project rows' counters are shared, and each host decides a job's project from its own copy. An edit shows within one beat",
+		});
+	}
+	const silent = peers.filter((h) => typeof h.fpProjects !== "string" || h.fpProjects === "");
+	const inUse = mine !== EMPTY_PROJECTS_FINGERPRINT || opinions.some((h) => h.fpProjects !== EMPTY_PROJECTS_FINGERPRINT);
+	if (silent.length > 0 && inUse) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `${silent.map((h) => h.name).join(", ")} ${silent.length === 1 ? "publishes no fingerprint of its" : "publish no fingerprint of their"} projects, so whether ${silent.length === 1 ? "it reads" : "they read"} the same projects.json as this host is unknown`,
+			fix: "upgrade every worker on this Valkey to the same release: a worker from before hosts compared their projects records no project and counts no project row",
+		});
+	}
+	return checks;
+}
+
+/**
+ * The runner's own input overhead (`BOUND_OVERHEAD_TOKENS`, image/runner/src/usage-meter.mjs), which its bound adds to
+ * every call. Copied, because the worker package does not ship the runner; `doctor.test.mjs` holds the two equal.
+ */
+export const FIRST_CALL_OVERHEAD_TOKENS = 8192;
+/**
+ * The least a job's FIRST call carries before its task, in bytes: pi 0.99.1's default system prompt (1,753 bytes) and
+ * the schemas of its four default tools (2,712 bytes) serialise to 4,465 bytes, and PR #542's lab measured 10,667 for
+ * a short task. 4,096 is below both, so the bound below stays a lower bound for a job that adds nothing.
+ */
+export const FIRST_CALL_MIN_CONTEXT_BYTES = 4096;
+
+/**
+ * A LOWER BOUND, in integer micro-dollars, on what the runner's cost guard (`callCostBound`) reserves for a job's
+ * first call on `model`, or null when this cannot say. The guard refuses a call when its bound would pass the cap, so
+ * a per-job cap below this number can never admit a call on the model: with the main model, the job makes no call at
+ * all (PR #542's lab: the default model's first call was bounded at $1.03 under a $1 cap).
+ *
+ * The guard's bound is (request bytes + 8,192) x the dearest input rate + the output limit x the dearest output rate,
+ * times a service-tier multiplier, over the model's table, its tiers and its fallbacks. This takes the parts of that
+ * which cannot be smaller: the model's own table (not its tiers or fallbacks, which only raise the bound), the output
+ * limit `model.maxTokens` (pi sends none of its own, so the guard uses the model's), an input of the overhead plus
+ * `FIRST_CALL_MIN_CONTEXT_BYTES`, and the runner's own service-tier multiplier (`serviceTierMultiplier`). The input
+ * rate is the guard's: the highest of input, cache read and cache write (not the 1h write, which needs long
+ * retention). Null for a table or limit it cannot read.
+ */
+export function firstCallFloorMicros(model) {
+	const cost = model?.cost;
+	const usable = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0;
+	if (!cost || !["input", "output", "cacheRead", "cacheWrite"].every((field) => usable(cost[field]))) return null;
+	const maxTokens = model.maxTokens;
+	if (!(typeof maxTokens === "number" && Number.isFinite(maxTokens) && maxTokens > 0)) return null;
+	const inputRate = Math.max(cost.input, cost.cacheRead, cost.cacheWrite);
+	return Math.ceil(((FIRST_CALL_OVERHEAD_TOKENS + FIRST_CALL_MIN_CONTEXT_BYTES) * inputRate + maxTokens * cost.output) * serviceTierMultiplier(model));
+}
+
+/**
+ * The runner's service-tier multiplier (`callCostBound` step 7, image/runner/src/usage-meter.mjs), copied like the
+ * overhead above: pi multiplies a settled cost by the tier the RESPONSE reports on these two apis, which can be the
+ * account's default rather than the request's, so the runner always bounds at the dearest tier. Leaving it out
+ * (PR #551's review) let doctor stay silent on a cap the runner refuses every call under: openai/gpt-5.5 under $5.
+ * `fleet-dollars.test.mjs` derives the runner's multiplier from its own bound for every priced api and holds this
+ * equal to it.
+ */
+export function serviceTierMultiplier(model) {
+	if (model?.api !== "openai-responses" && model?.api !== "openai-codex-responses") return 1;
+	return model.id === "gpt-5.5" ? 2.5 : 2;
+}
+
+/**
+ * The model object the floor above is computed from: the builtin catalog's (`builtinModel`, model-catalog.mjs), or a
+ * CUSTOM model the overlay `models.json` defines (its own `cost` and `maxTokens`). Null, so the model is not judged,
+ * when the overlay redefines or overrides a builtin model: pi composes the two, and this does not copy that rule.
+ */
+export function boundModelOf({ provider, id }, { builtinModel, overlay = null }) {
+	const providers = overlay?.providers;
+	const entry = providers !== null && typeof providers === "object" && !Array.isArray(providers) && Object.hasOwn(providers, provider) ? providers[provider] : null;
+	const builtin = builtinModel(provider, id);
+	if (entry !== null && typeof entry === "object") {
+		const overrides = entry.modelOverrides;
+		if (overrides !== null && typeof overrides === "object" && Object.hasOwn(overrides, id)) return null;
+		const definition = Array.isArray(entry.models) ? entry.models.find((m) => m !== null && typeof m === "object" && m.id === id) : undefined;
+		if (definition !== undefined) return builtin ? null : definition;
+	}
+	return builtin;
+}
+
+/**
+ * Who runs on which models under which cap (issues #501 and #502), as the worker resolves a job: the deployment's own
+ * default, then every trigger. `deployment` is `{ provider, model, maxCostUsd }` (overlay over env,
+ * `deploymentSettingsOf`); `runs` the trigger facts; `envList` the parsed `PI_ALLOWED_MODELS`, or null. Each subject
+ * is `{ label, main, list, cap, secretNames, named }`: `main` and `list` are `{ provider, id }`, `list` is the
+ * trigger's `run.models` or else the env list, `cap` the effective per-job cap in micro-dollars (the smaller of the
+ * trigger's and the deployment's, `effectiveCostCapMicros`) or null, and `named` says the trigger names a provider, a
+ * model or a list of its own.
+ */
+export function modelSubjects({ runs = [], deployment, envList = null }) {
+	const listOf = (list) => (Array.isArray(list) ? list.map(splitModelEntry).filter((ref) => ref !== null).map((ref) => ({ provider: ref.provider, id: ref.model })) : []);
+	const capOf = (triggerValue) => {
+		try {
+			return effectiveCostCapMicros(triggerValue, deployment.maxCostUsd);
+		} catch {
+			return null; // a deployment cap that does not parse is `dollarChecks`' line
+		}
+	};
+	const subjects = [{ label: "the deployment default", main: { provider: deployment.provider, id: deployment.model }, list: listOf(envList), cap: capOf(undefined), secretNames: [], named: false, deployment: true }];
+	for (const run of runs) {
+		subjects.push({
+			label: run.label,
+			main: { provider: run.provider ?? deployment.provider, id: run.model ?? deployment.model },
+			list: listOf(run.models ?? envList),
+			cap: capOf(run.maxCostUsd),
+			secretNames: run.secretNames ?? [],
+			named: run.provider !== undefined || run.model !== undefined || run.models !== undefined,
+		});
+	}
+	return subjects;
+}
+
+/**
+ * The `provider/id` of every model a job under a per-job dollar cap may use (the main model and the list, as
+ * `modelSubjects` resolves them), for the overlay's output-cap line to leave to `costCapFitChecks` (issue #507). Empty
+ * when the settings cannot be read.
+ */
+export function cappedModelNames(env, { runs, deployment }) {
+	let envList = null;
+	try {
+		envList = allowedModelsFrom(env);
+	} catch {
+		// A malformed PI_ALLOWED_MODELS is its own line.
+	}
+	const names = new Set();
+	for (const s of modelSubjects({ runs, deployment, envList })) {
+		if (s.cap === null || s.cap === undefined) continue;
+		for (const ref of [s.main, ...s.list]) names.add(`${ref.provider}/${ref.id}`);
+	}
+	return names;
+}
+
+/**
+ * Issue #501's open question, answered with a warning: a per-job cap below one full-output call of the main model,
+ * or of a listed model, is a cap the runner can never admit that call under (`firstCallFloorMicros`). One line,
+ * grouped by model and cap so a deployment default every trigger inherits is named once.
+ *
+ * Issue #507: `unboundable(ref)` says the runner cannot bound the model's output at all (`outputUnboundable`,
+ * output-cap.mjs: openai-completions to a server off the trusted hosts without `compat.maxTokensField: "max_tokens"`),
+ * so every call to it is refused under any cap. Such a model gets a line of its own, grouped by model, and no floor.
+ */
+export function costCapFitChecks(subjects, modelOf, { unboundable = () => false } = {}) {
+	const groups = new Map();
+	const unbounded = new Map();
+	for (const s of subjects) {
+		if (s.cap === null || s.cap === undefined) continue;
+		const seen = new Set();
+		for (const ref of [s.main, ...s.list]) {
+			const name = `${ref.provider}/${ref.id}`;
+			if (seen.has(name)) continue;
+			seen.add(name);
+			if (unboundable(ref)) {
+				if (!unbounded.has(name)) unbounded.set(name, { main: false, labels: [] });
+				const u = unbounded.get(name);
+				u.main ||= ref === s.main;
+				u.labels.push(s.label);
+				continue;
+			}
+			const floor = firstCallFloorMicros(modelOf(ref));
+			if (floor === null || s.cap >= floor) continue;
+			const main = ref === s.main;
+			const key = `${name}\u0000${s.cap}\u0000${main}`;
+			if (!groups.has(key)) groups.set(key, { name, floor, cap: s.cap, main, labels: [] });
+			groups.get(key).labels.push(s.label);
+		}
+	}
+	const out = [];
+	if (unbounded.size > 0) {
+		const items = [...unbounded].map(([name, u]) => `${printable(name)}${u.main ? " (the main model, so such a job makes no call at all)" : ""} (${u.labels.join(", ")})`);
+		out.push({
+			ok: false,
+			warn: true,
+			label: `A job under a per-job cost cap may use a model whose output cap travels as max_completion_tokens to a server that may ignore it (one outside pi's own hosted providers), so the runner counts every call to it unboundable and refuses it under the cap: ${items.join("; ")}`,
+			fix: "set \"compat\": { \"maxTokensField\": \"max_tokens\" } on the model or its provider in models.json, or set its cost to zeros if it is free: docs/egress.md, \"Local model servers\"",
+		});
+	}
+	if (groups.size === 0) return out;
+	const items = [...groups.values()].map((g) => `${printable(g.name)}${g.main ? " (the main model, so such a job makes no call at all)" : ""} needs at least $${formatMicros(g.floor)} a call under a $${formatMicros(g.cap)} cap (${g.labels.join(", ")})`);
+	return [
+		...out,
+		{
+			ok: false,
+			warn: true,
+			label: `The per-job cost cap is below one full-output call of a model a job may use, so the runner refuses every call to that model before it is sent: ${items.join("; ")}`,
+			fix: "raise PI_MAX_COST_USD (or the trigger's run.maxCostUsd) above the amount named, or use a model with a smaller output limit. The amount is a lower bound: the runner's own bound adds the whole request, so a cap just above it can still refuse a call",
+		},
+	];
+}
+
+/**
+ * Issue #502 part 2: a trigger whose model, or a model on its list, the worker's free gate would refuse, asked of the
+ * worker's own gate (`checkModelsKnown`, model-catalog.mjs) with the overlay `models.json` it reads. Every trigger kind,
+ * cron included, and only triggers that name a provider, a model or a list of their own: a trigger that names none
+ * runs on the deployment's settings, which get one line of their own (the deployment subject). An overlay that cannot be read just now
+ * (`unavailable`) says nothing: the worker retries such a job.
+ */
+export function unknownModelChecks(subjects, checkModelsKnown, readOverlay) {
+	const unknown = [];
+	const fallbacks = [];
+	const checks = [];
+	// The deployment's own default model and PI_ALLOWED_MODELS (PR #551's review): a typo there refuses every job
+	// whose trigger names neither, so it gets a line of its own, worded for the settings that hold it.
+	for (const s of subjects.filter((x) => x.deployment === true)) {
+		const verdict = checkModelsKnown([{ ...s.main, main: true }, ...s.list], { readOverlay });
+		const ref = verdict?.unknown ?? verdict?.fallbackUnlisted;
+		if (!ref) continue;
+		// A broken overlay is the overlay lines' to name (they say every job is refused); blaming .env here would send
+		// the operator to the wrong file (PR #551's review, round 2).
+		if (verdict.unknown && typeof verdict.why === "string" && verdict.why.startsWith("overlay-")) continue;
+		checks.push({
+			ok: false,
+			warn: true,
+			label: verdict.unknown
+				? `The deployment's default model (PI_PROVIDER/PI_MODEL, or the panel's provider/model) or a model on PI_ALLOWED_MODELS is one this deployment does not know: ${printable(`${ref.provider}/${ref.id}`)} (${verdict.why}), so every job whose trigger names no model of its own is refused before it starts (model-unknown)`
+				: `A model on PI_ALLOWED_MODELS declares server-side fallbacks the list does not name: ${printable(`${ref.provider}/${ref.id}`)}, so every job whose trigger names no list of its own is refused before it starts (model-not-allowed)`,
+			fix: verdict.unknown ? "fix the id in .env (or the panel's model setting): the worker knows pi's builtin catalog at its pin and the models the overlay models.json declares" : "add that model's fallback models to PI_ALLOWED_MODELS, under the same provider, or remove it",
+		});
+	}
+	for (const s of subjects) {
+		if (!s.named) continue;
+		const verdict = checkModelsKnown([{ ...s.main, main: true }, ...s.list], { readOverlay });
+		if (verdict?.unknown) unknown.push(`${s.label}: ${printable(`${verdict.unknown.provider}/${verdict.unknown.id}`)} (${verdict.why})`);
+		else if (verdict?.fallbackUnlisted) fallbacks.push(`${s.label}: ${printable(`${verdict.fallbackUnlisted.provider}/${verdict.fallbackUnlisted.id}`)}`);
+	}
+	if (unknown.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `${unknown.length} trigger(s) name a model this deployment does not know, so every job of them is refused before it starts (model-unknown): ${unknown.join("; ")}`,
+			fix: "fix the provider or model id: the worker knows pi's builtin catalog at its pin and the models the overlay models.json declares. not-in-catalog is a typo or a model only an extension defines (declare it in the overlay models.json); an overlay reason names the file as the problem",
+		});
+	}
+	if (fallbacks.length > 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `${fallbacks.length} trigger(s) list a model whose server-side fallbacks are not on the list, so every job of them is refused before it starts (model-not-allowed): ${fallbacks.join("; ")}`,
+			fix: "list that model's fallback models too, under the same provider, or remove it from the list",
+		});
+	}
+	return checks;
+}
+
+/**
+ * Issue #502's open question, answered with a warning: only the main provider's key is resolved for a job; any other
+ * provider on its list needs a key that arrives by `run.secrets` or `PI_FORWARD_ENV`. A listed provider with neither
+ * starts the job and then fails the first call to it, after the budget is reserved. The names looked for are pi's
+ * own (`candidatesOf`, the provider oracle), or the variable the overlay's `apiKey` for that provider references.
+ * Said nothing about a provider it cannot judge: no names at all (Bedrock reads the AWS chain), the keyless marker
+ * (#503), or an `apiKey` that is not a variable reference.
+ */
+export function listedProviderCredentialChecks(subjects, { candidatesOf, forwarded = [], env = {}, overlay = null }) {
+	const providers = overlay?.providers;
+	const namesFor = (provider) => {
+		const entry = providers !== null && typeof providers === "object" && !Array.isArray(providers) && Object.hasOwn(providers, provider) ? providers[provider] : null;
+		const apiKey = entry !== null && typeof entry === "object" ? entry.apiKey : undefined;
+		if (typeof apiKey === "string" && apiKey !== "") {
+			if (apiKey === KEYLESS_API_KEY) return [];
+			const ref = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/.exec(apiKey);
+			return ref ? [ref[1]] : [];
+		}
+		return candidatesOf(provider) ?? [];
+	};
+	const missing = new Map();
+	for (const s of subjects) {
+		for (const provider of new Set(s.list.map((ref) => ref.provider))) {
+			if (provider === s.main.provider) continue;
+			const names = namesFor(provider);
+			if (names.length === 0) continue;
+			if (names.some((n) => s.secretNames.includes(n) || (forwarded.includes(n) && typeof env[n] === "string" && env[n] !== ""))) continue;
+			if (!missing.has(provider)) missing.set(provider, { names, labels: [] });
+			missing.get(provider).labels.push(s.label);
+		}
+	}
+	if (missing.size === 0) return [];
+	const items = [...missing.entries()].map(([provider, m]) => `${printable(provider)} (${m.labels.join(", ")}; looked for ${m.names.join(" or ")})`);
+	return [
+		{
+			ok: false,
+			warn: true,
+			label: `A provider on an allowed-model list, other than the job's main one, has no credential this deployment hands its jobs, so a call to it fails inside the container, after the job started: ${items.join("; ")}`,
+			fix: "only the main provider's key is resolved for a job. Bind another provider's key with run.secrets on the trigger, or name it in PI_FORWARD_ENV and set it in .env; or take the provider off the list",
+		},
+	];
+}
+
+/**
+ * The deployment's provider, model and dollar settings as the worker resolves them for a job: the overlay over env
+ * (`resolveSettings`), falling back to env when the overlay is invalid or the merged dollar values break the
+ * invariant, which is the fallback `start.mjs` takes for its slot count and its `fpUsd`. Values as written; nothing
+ * here throws.
+ */
+export function deploymentSettingsOf(env, settingsFile, fileExists) {
+	const fromEnv = { provider: env.PI_PROVIDER ?? DEFAULT_PROVIDER, model: env.PI_MODEL ?? DEFAULT_MODEL };
+	for (const key of DOLLAR_SETTING_KEYS) {
+		const raw = env[DOLLAR_ENV_NAMES[key]];
+		fromEnv[key] = raw === undefined || raw === "" ? null : raw;
+	}
+	let read;
+	try {
+		read = fileExists(settingsFile) ? readOverlay(settingsFile) : { overlay: {} };
+	} catch {
+		return fromEnv;
+	}
+	const resolved = resolveSettings(fromEnv, read);
+	if (resolved.invalid) return fromEnv;
+	return Object.fromEntries(Object.keys(fromEnv).map((key) => [key, resolved[key] ?? null]));
+}
+
+/** The worker's model catalog (model-catalog.mjs), imported lazily for `defaultProviderOracle`'s reason, or null. */
+async function defaultModelCatalog() {
+	try {
+		return await import("./model-catalog.mjs");
+	} catch {
+		return null;
+	}
+}
+
+/** pi's own model loader (pi-model-loader.mjs), imported lazily like the catalog, or null. */
+async function defaultPiModelLoader() {
+	try {
+		const { loadPiModelLoader } = await import("./pi-model-loader.mjs");
+		return await loadPiModelLoader();
+	} catch {
+		return null;
+	}
+}
+
+/** The `provider/id` pairs a models.json text declares, read leniently: a file pi drops still names ids worth asking about. */
+function declaredOverlayModels(text) {
+	// Read as pi reads text (BOM, comments and trailing commas stripped; PR #551's review: plain JSON.parse found no
+	// model in a JSONC overlay), without pi's schema, so a file pi refuses still names ids worth asking about.
+	let doc = parseModelsJson(text).value;
+	if (doc === undefined || doc === null) {
+		try {
+			doc = JSON.parse(stripJsonComments(stripBom(text)));
+		} catch {
+			return [];
+		}
+	}
+	const out = [];
+	const providers = doc?.providers;
+	if (providers === null || typeof providers !== "object" || Array.isArray(providers)) return out;
+	for (const [provider, entry] of Object.entries(providers)) {
+		if (entry === null || typeof entry !== "object") continue;
+		for (const m of Array.isArray(entry.models) ? entry.models : []) if (typeof m?.id === "string" && m.id !== "") out.push([provider, m.id]);
+	}
+	return out;
+}
+
+/**
+ * Issue #502's open question: does pi's own loader read the overlay `models.json` as the worker's catalog does? The
+ * worker admits or refuses a job by its copy of pi's rules (`parseModelsJson`, `checkModelsKnown`); pi decides what
+ * runs. A disagreement is a model the worker calls known that pi lacks (a paid job that exits 2) or the reverse (a
+ * working model refused), and either is a defect in the copy or a pi beside the worker that is not the image's. Asked
+ * per file (loads or not) and per declared model. `pi` is `defaultPiModelLoader`'s answer, or null.
+ */
+export async function overlayLoaderParityChecks(modelsPath, { pi, checkModelsKnown, readText = (p) => readFileSync(p, "utf8") }) {
+	if (pi === null || pi === undefined) {
+		return [{ ok: true, label: "Overlay models.json was not compared with pi's own loader: pi-coding-agent is not installed beside the worker (a checkout of this repository has it after npm ci)" }];
+	}
+	// Only the pinned pi speaks for the job image (PR #551's review): a global layout can put any pi beside the worker.
+	if (typeof pi.pinned !== "string" || pi.version !== pi.pinned) {
+		return [{ ok: true, label: `Overlay models.json was not compared with pi's own loader: pi ${printable(String(pi.version))} beside the worker is not the worker's pinned pi-ai ${typeof pi.pinned === "string" ? printable(pi.pinned) : "(pin unknown)"}` }];
+	}
+	let text;
+	let theirs;
+	try {
+		text = readText(modelsPath);
+		theirs = await pi.read(modelsPath);
+	} catch (error) {
+		return [{ ok: false, warn: true, label: `Overlay models.json could not be compared with pi ${printable(String(pi.version))}'s own loader (${printable(String(error?.code ?? error?.message ?? "error"))})`, fix: "re-run doctor; if it persists, report it with the error" }];
+	}
+	const parsed = parseModelsJson(text);
+	const ours = parsed.error === undefined;
+	const readOverlay = () => {
+		if (parsed.error !== undefined) throw Object.assign(new Error(parsed.error), { piDispatchConfig: true });
+		return parsed.value;
+	};
+	const items = [];
+	if (theirs.loads !== ours) items.push(`pi ${theirs.loads ? "loads the file and the worker refuses it" : "drops the file and the worker reads it"}`);
+	const declared = declaredOverlayModels(text);
+	for (const [provider, id] of declared) {
+		const piHas = theirs.has(provider, id) === true;
+		const workerHas = checkModelsKnown([{ provider, id, main: true }], { readOverlay })?.ok === true;
+		if (piHas !== workerHas) items.push(`${printable(`${provider}/${id}`)}: pi ${piHas ? "has it" : "lacks it"}, the worker calls it ${workerHas ? "known" : "unknown"}`);
+	}
+	if (items.length > 0) {
+		return [
+			{
+				ok: false,
+				warn: true,
+				label: `pi ${printable(String(pi.version))}'s own loader and the worker's model catalog disagree about overlay models.json: ${items.join("; ")}`,
+				fix: "the worker gates jobs by its own reading of this file and pi decides what runs, so a model the worker knows and pi lacks is a paid job that exits 2, and the reverse is a working model refused. Report it with the file's shape (not its keys); until then, avoid the construct named",
+			},
+		];
+	}
+	return [{ ok: true, label: `Overlay models.json reads the same in pi ${printable(String(pi.version))}'s own loader as in the worker's model catalog (${declared.length} declared model(s))` }];
+}
+
+/**
+ * How a line names its trigger: cron entries by their id, id-less webhook entries by raw file position (the admin's
+ * trigger:<index> identity). One function, because the flow lines and the venue lines must name a trigger alike.
+ */
+function triggerLabel(t, index) {
+	return t.on.type === "cron" ? `cron "${t.on.id}"` : `${t.on.type} trigger #${index}`;
+}
+
+function readTriggerFacts(env, fileExists, cwd, declaredWorkerName) {
+	const none = { requiring: 0, waiting: 0, listing: 0, waitProfiles: [], waitAfters: [], optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, onceArmed: 0, onceSpent: 0, secretProfiles: [], localSecretFolders: [], secretNames: [], folders: [], images: [], imageRoutes: [], namedBackends: [], skillsDirs: [], forges: [], repositories: [], flows: [], costCaps: [], modelRuns: [], parseError: null, path: null };
+	try {
+		// Unset falls back to ./triggers.json in cwd, MIRRORING the receiver's own default
+		// (receiver/src/config.mjs) -- the two must read the same file, or doctor preflights a deployment
+		// the receiver will not boot. An absent file still means "no triggers at all", exactly as before.
+		const path = triggersPath(env, cwd);
+		if (!fileExists(path)) return none;
+		// The same regular-file guard, for the same reason: this read is unbounded too, and a triggers path
+		// naming a FIFO hangs the command with no output and no timeout that can reach it.
+		if (!statSync(path).isFile()) return { ...none, parseError: `triggers file is not a regular file: ${path}`, path };
+		const text = readFileSync(path, "utf8");
+		const triggers = parseTriggers(text, path);
+		// The one-shot facts are counted from the RAW entries, not the parsed records, because the
+		// validator collapses a disarmed entry to a sentinel that carries neither `once` nor
+		// `disarmed` -- exactly so nothing can match it -- which also erases it from every parsed
+		// count above. Doctor is the surface that must still SEE the spent entry: "why did nothing
+		// fire" is answered by a spent row, and only the raw file still holds it. Safe unguarded:
+		// parseTriggers just accepted this same text, so JSON.parse cannot throw here.
+		const rawEntries = JSON.parse(text)?.triggers ?? [];
+		// Issue #433 review rounds 2 and 3: whether THIS HOST'S WORKER schedules a cron trigger, for the unblessed-venue
+		// line, by the worker's two conditions and nothing else. (a) The worker schedules cron only from a PI_TRIGGERS_FILE
+		// it was given (`config.triggersFile` is null without one, and `loadSchedules` then returns []), while doctor
+		// falls back to ./triggers.json for everything else it reads; so without the variable no cron trigger is judged.
+		// (b) Its placement, by the worker's own predicate (`cronPlacement`): judged unless it is `"elsewhere"`, another
+		// machine's folder on a fleet. A single host's absent folder is `"refused"`, the worker's boot refusal, and is
+		// still judged. Round 2 ran the whole `loadSchedules` instead and caught its throw as "judge everything", which let
+		// one served trigger's bad skillsDir bring back the false line for another machine's trigger: a predicate per
+		// trigger cannot be derailed by a sibling.
+		// The name collectChecks resolved (issue #464), never this shell's alone.
+		const fleet = Boolean(declaredWorkerName);
+		const cronScheduledHere = (t) => env.PI_TRIGGERS_FILE !== undefined && cronPlacement(t.run, { existsSync: fileExists, fleet }) !== "elsewhere";
+		return {
+			onceArmed: rawEntries.filter((t) => t?.on?.once === true && t.on.disarmed === undefined).length,
+			onceSpent: rawEntries.filter((t) => t?.on?.disarmed !== undefined).length,
+			requiring: triggers.filter((t) => t.run.packages === true).length,
+			resuming: triggers.filter((t) => t.run.resume === true).length,
+			// REQ-PER-TRIGGER-INSTRUCTION. Counted beside `resuming` for the same reason: it is a per-trigger
+			// choice that changes what every job of it is told, and an operator should see it before it fires.
+			instructing: triggers.filter((t) => typeof t.run.instructions === "string").length,
+			// REQ-REPLICA-RUNS. `> 1` rather than `!== undefined` because the loader already refuses anything
+			// else -- this counts triggers that will actually multiply spend, which is the only reason to say so.
+			replicating: triggers.filter((t) => t.run.replicas > 1).length,
+			// run.command triggers (issue #189), counted for the one advisory line below. The `flows`
+			// tuple list already filters to `typeof f.flow === "string"`, so a command trigger drops out
+			// of the flow-tier probes naturally -- no exclusion needed there.
+			commands: triggers.filter((t) => typeof t.run.command === "string").length,
+			// REQ-TRIGGER-SECRETS. Counted beside `instructing` for its reason: a per-trigger choice that
+			// changes what every job of it can reach, and one that lives only in triggers.json.
+			secreting: triggers.filter((t) => t.run.secrets !== undefined).length,
+			// The distinct profile NAMES the file selects, deduped like `images`/`skillsDirs`: the checks below
+			// cost a stat each, and two triggers naming one profile are one question. `default` is substituted
+			// for an absent field so the table answers what the worker will actually look up.
+			secretProfiles: [...new Set(triggers.filter((t) => t.run.secrets !== undefined).map((t) => t.run.secretsProfile ?? "default"))].sort(),
+			// LOCAL triggers that bind secrets, by folder. A local job's /workspace IS this folder, bind-mounted
+			// read-write with no clone, so a credential an agent writes into .env lands in the operator's real
+			// repository rather than a temp dir that gets swept. Deduped for skillsDirs' reason.
+			localSecretFolders: [...new Set(triggers.filter((t) => t.run.secrets !== undefined && t.run.kind === "local" && typeof t.run.folder === "string").map((t) => t.run.folder))].sort(),
+			// Issue #309. The distinct variable NAMES the file binds, deduped like the profiles above. The
+			// pre-spend gate refuses a name pi reads for the job's provider, and unlike the version that gate
+			// replaced, that question no longer needs host state to answer -- so doctor can answer it at setup
+			// rather than leaving the operator to meet it as a public refusal on a live job.
+			secretNames: [...new Set(triggers.filter((t) => t.run.secrets !== undefined).flatMap((t) => Object.keys(t.run.secrets)))].sort(),
+			// Issue #242: every local run.folder, CANONICALIZED the way the scoped-limits matcher
+			// canonicalizes a job's folder (one derivation -- canonicalScope, never re-spelled here), so
+			// the unreferenced-scope advisory compares like with like across spelling variants.
+			folders: [...new Set(triggers.filter((t) => t.run.kind === "local" && typeof t.run.folder === "string").map((t) => canonicalScope({ kind: "local", folder: t.run.folder })))].sort(),
+			// Issue #230. How many triggers hold their jobs, and the distinct profile NAMES they select --
+			// deduped like `secretProfiles` and for its reason: each name costs a lookup, and two triggers
+			// waiting on one profile are one question.
+			waiting: triggers.filter((t) => Array.isArray(t.run.waitFor) && t.run.waitFor.length > 0).length,
+			// Issue #502: how many triggers name an allowed-model list, for the version-floor line.
+			listing: triggers.filter((t) => Array.isArray(t.run.models) && t.run.models.length > 0).length,
+			// The `after` instants as WRITTEN, deduped. Not parsed here: `readTriggerFacts` is a fact reader and
+			// the ceiling it is measured against is env, which belongs at the check. Two triggers naming one
+			// instant are one finding, and the raw string is what the operator has to go and edit.
+			waitAfters: [...new Set(triggers.flatMap((t) => (Array.isArray(t.run.waitFor) ? t.run.waitFor : [])).map((c) => c?.after).filter((v) => typeof v === "string"))].sort(),
+			waitProfiles: [
+				...new Set(
+					triggers
+						.filter((t) => Array.isArray(t.run.waitFor))
+						.flatMap((t) => t.run.waitFor.map((c) => c?.profile).filter((n) => typeof n === "string")),
+				),
+			].sort(),
+			optingOut: triggers.filter((t) => t.run.packages === false).length,
+			images: [...new Set(triggers.map((t) => t.run.image).filter((i) => typeof i === "string"))].sort(),
+			// Issue #433: each image with the venue its trigger names (undefined: the deployment default), so the image is
+			// asked of the runtime its jobs start on. The worker's own shape (`{ backend }`), for `resolveBackendName`.
+			imageRoutes: triggers.filter((t) => typeof t.run.image === "string").map((t) => ({ image: t.run.image, backend: t.run.backend })),
+			// Issue #433 review round 1: every trigger that NAMES a venue, with the label the lines below name it by, so
+			// doctor can say which of them this deployment does not bless (the worker refuses each of their jobs).
 			namedBackends: triggers
 				.map((t, index) => ({ label: triggerLabel(t, index), backend: t.run.backend, served: t.on.type !== "cron" || cronScheduledHere(t) }))
 				.filter((r) => typeof r.backend === "string"),
@@ -3975,6 +5389,20 @@ function readTriggerFacts(env, fileExists, cwd, declaredWorkerName) {
 					packages: t.run.packages !== false,
 				}))
 				.filter((f) => typeof f.flow === "string"),
+			// Issue #501: every trigger that sets run.maxCostUsd, with the label the cap check names it by. The value
+			// already parsed (the loader validated it), so the check below only compares.
+			costCaps: triggers.map((t, index) => ({ label: triggerLabel(t, index), maxCostUsd: t.run.maxCostUsd })).filter((r) => r.maxCostUsd !== undefined && r.maxCostUsd !== null),
+			// Issues #501 and #502 (PR 9 of that round): every trigger's model choice, list, cap and bound secret NAMES, for the
+			// unknown-model, cap-fit and listed-provider credential lines. Every kind, cron included, whatever host serves it:
+			// a model the worker does not know is refused wherever the job runs.
+			modelRuns: triggers.map((t, index) => ({
+				label: triggerLabel(t, index),
+				provider: typeof t.run.provider === "string" ? t.run.provider : undefined,
+				model: typeof t.run.model === "string" ? t.run.model : undefined,
+				models: Array.isArray(t.run.models) ? t.run.models : undefined,
+				maxCostUsd: t.run.maxCostUsd ?? undefined,
+				secretNames: t.run.secrets !== undefined && t.run.secrets !== null ? Object.keys(t.run.secrets) : [],
+			})),
 			// Explicit on the success path too (issue #242): the dead-scope advisory distinguishes
 			// "facts read clean" (path set, no error) from the zeroed `none` -- an implicit undefined
 			// here made that test silently false for every deployment.
@@ -4190,11 +5618,15 @@ export async function sweepStaleCanaryNetworks({ run, pid, isAlive, endpoint, bi
 	// gets added to the producer and not to the reaper.
 	//
 	// ASYMMETRY ON PURPOSE, recorded because it looks like an oversight three characters apart: the OWNER is
-	// escaped and the slugs are interpolated raw. `CANARY_PROBE_SLUGS` is a frozen literal of two plain words
+	// escaped and the slugs are interpolated raw. `CANARY_PROBE_SLUGS` is a frozen literal of three plain words
 	// three lines below, so today there is nothing to escape and escaping it would say the set is untrusted
 	// when it is this file's own. It is here so that whoever adds a slug with a `.` or a `-` in it sees the
 	// obligation: a metacharacter there widens what this `rm -f` matches (issue #360, item 6).
-	const probeOf = (owner) => new RegExp(`^${EGRESS_CANARY_PROBE_PREFIX}(?:${CANARY_PROBE_SLUGS.join("|")})-${owner.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`);
+	//
+	// The model endpoint probes (issue #503) are matched the same way, their slugs from `ENDPOINT_PROBE_SLUGS` and the id
+	// by the parser's own rule (`MODEL_ENDPOINT_ID_RE`, its anchors dropped), never `\\S+`: a name that matches is one
+	// this file builds, and the class cannot drift from what the parser accepts.
+	const probeOf = (owner) => new RegExp(`^(?:${EGRESS_CANARY_PROBE_PREFIX}(?:${CANARY_PROBE_SLUGS.join("|")})|${EGRESS_ENDPOINT_PROBE_PREFIX}(?:${ENDPOINT_PROBE_SLUGS.join("|")})-${ENDPOINT_ID_CLASS})-${owner.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`);
 	const checks = [];
 	for (const name of String(listed.stdout ?? "").split("\n").map((n) => n.trim()).filter(Boolean)) {
 		const m = shape.exec(name);
@@ -4306,8 +5738,55 @@ export async function sweepStaleCanaryNetworks({ run, pid, isAlive, endpoint, bi
 	return checks;
 }
 
-/** The canary's two probe directions. ONE list: the loop names its containers from it and the sweep matches on it. */
-export const CANARY_PROBE_SLUGS = Object.freeze(["provider", "unlisted"]);
+/**
+ * Issue #508: with the egress policy on, a forge must be served over https on port 443, the one shape a job's git reaches
+ * it by. git never uses the job's proxy for an `http://` remote: the job gets the proxy variables in UPPERCASE only, and
+ * libcurl ignores `HTTP_PROXY` for `http://` (measured in the job image, git 2.39.5: `git ls-remote http://...` went to
+ * DNS, and the proxy saw nothing), so an http:// forge fails behind the `--internal` network on ANY port, 80 included.
+ * An `https://` remote is a CONNECT, which the proxy refuses to any port but 443 (a rule older than #508). The clone
+ * itself runs on the host before the container exists, so it is the job's git push and fetch that fail, and its API
+ * calls too unless the forge is on port 80: glab and tea (Go) do use `HTTP_PROXY` for `http://`, and the proxy passes
+ * plain HTTP to a listed host on port 80 (round 3 of #508's review). Any other scheme reaches nothing. One ⚠
+ * per such URL, for a forge the triggers file names; nothing with the policy off or unreadable (the .env check reports
+ * a malformed PI_EGRESS).
+ */
+export function forgeUrlEgressChecks(env, forges = []) {
+	let armed;
+	try {
+		armed = egressArmed(env);
+	} catch {
+		return [];
+	}
+	if (armed !== true) return [];
+	const checks = [];
+	for (const [forge, key] of [["gitlab", "GITLAB_URL"], ["forgejo", "FORGEJO_URL"]]) {
+		if (!forges.includes(forge) || typeof env[key] !== "string") continue;
+		let url;
+		try {
+			url = new URL(env[key].trim());
+		} catch {
+			continue;
+		}
+		// The WHATWG parser drops a default port, so an empty port on https: is 443.
+		if (url.protocol === "https:" && url.port === "") continue;
+		const why =
+			url.protocol === "https:"
+				? `https:// on port ${url.port}, and the egress proxy refuses a CONNECT to any port but 443, so with the egress policy on every job's push, fetch and API call to it fails`
+				: url.protocol === "http:"
+					? `http://, so with the egress policy on a job's git push and fetch fail (git never sends http:// through the proxy)${url.port === "" ? "" : `, and on port ${url.port}, not 80, its API calls fail too`}`
+					: "not an https:// URL, so with the egress policy on a job cannot reach it";
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `${key} (${urlShown(env[key])}) is ${why} (issue #508)`,
+			fix: `serve the forge over https:// on port 443 and point ${key} there, or set PI_EGRESS=0 if you accept jobs without the policy (docs/egress.md)`,
+		});
+	}
+	return checks;
+}
+
+/** The canary's three probes. ONE list: the loop names its containers from it and the sweep matches on it. */
+export const CANARY_PROBE_SLUGS = Object.freeze(["provider", "unlisted", "plainhttp"]);
 
 /** Where the job image's runner keeps the module its own provider call goes through (issue #427). */
 export const EGRESS_CANARY_RUNNER_MODULE = "/app/image/runner/src/env-proxy.mjs";
@@ -4331,6 +5810,21 @@ export function egressCanaryScript(url) {
 	return `import(${JSON.stringify(EGRESS_CANARY_RUNNER_MODULE)}).then(m=>m.loadPiThenRestore(),e=>{console.log("error",e.code??e.message);process.exit(e.code==="ERR_MODULE_NOT_FOUND"?${EGRESS_CANARY_STALE_RUNNER}:5)}).then(()=>fetch(${JSON.stringify(url)},{method:"POST"}).then(r=>{console.log("reached",r.status);process.exit(0)},e=>{console.log("blocked",e.cause?.code??e.message);process.exit(3)}),e=>{console.log("error",e.message);process.exit(5)})`;
 }
 
+/**
+ * The third probe's in-container script (issue #508): ONE plain forward request, `GET <absolute url>`, written straight
+ * to `proxyUrl`, which the caller passes as `egressProxyUrl(proxy)`: the value both venues' probe argv put in
+ * HTTPS_PROXY. Passed rather than read from the container's environment because this file's text is pinned to read no
+ * environment by name outside the resolver (issue #471), and a script string is text. Raw `node:http` with `agent: false`, and NOT the
+ * runner's route (`loadPiThenRestore`, `fetch`): those tunnel every origin, so they would send a CONNECT, which is
+ * the path the other two probes read, never the plain one a curl or a package manager takes. Exit 3 only for squid's
+ * own refusal (403 with an `X-Squid-Error` of ERR_ACCESS_DENIED), 0 for any other answer (the request went on: a 400
+ * from a TLS port spoken to in clear, or squid's 502 when the far end hung up, both mean the proxy let it through),
+ * and 5 for a proxy that could not be spoken to or never answered, which is no reading at all.
+ */
+export function egressCanaryPlainScript(url, { proxyUrl, timeoutMs = 15_000 } = {}) {
+	return `import("node:http").then(h=>{let p,u;try{p=new URL(${JSON.stringify(String(proxyUrl))});u=new URL(${JSON.stringify(url)})}catch(e){console.log("error",e.message);process.exit(5)}const q=h.request({host:p.hostname,port:p.port||80,method:"GET",path:u.href,headers:{Host:u.host},agent:false,timeout:${Number(timeoutMs)}},r=>{const x=String(r.headers["x-squid-error"]??"");r.resume();if(r.statusCode===403&&x.startsWith("ERR_ACCESS_DENIED")){console.log("blocked",r.statusCode,x);process.exit(3)}console.log("reached",r.statusCode,x);process.exit(0)});q.on("timeout",()=>{console.log("error","timeout");process.exit(5)});q.on("error",e=>{console.log("error",e.code??e.message);process.exit(5)});q.end()},e=>{console.log("error",e.message);process.exit(5)})`;
+}
+
 /**
  * The bound on one canary docker step. Shorter than the 30 s the PROBES get, because these are `network`
  * calls that either answer at once or are wedged, and the teardown must not be the slow part of a doctor run.
@@ -4442,7 +5936,7 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 			name: "deploy/egress-proxy.conf in this folder",
 			seams,
 			skip: () => proxyFileIsDirectory(join(seams.cwd, "deploy/egress-proxy.conf")),
-			refresh: `\`pi-dispatch up\` from this folder offers to replace it with the package's copy, keeping this one as a backup, and then to restart the proxy, since squid reads its rules only at start`,
+			refresh: `\`pi-dispatch up\` from this folder offers to replace it with the package's copy, keeping this one as a backup, and then to restart the proxy, since squid reads its rules only at start; a proxy made before #503, which lacks the model-endpoints.conf mount the new rules need, is REPLACED in the same step instead, asked once`,
 		});
 		if (stale) checks.push(stale);
 	}
@@ -4505,23 +5999,54 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 	// know which folder the service uses), and only where every bind source resolves on this host; otherwise that half
 	// is said to be unknown, never stale.
 	const inFolder = ["egress-allowlist.conf", "deploy/egress-proxy.conf"].every((f) => proxyFilesExist(join(seams.cwd, f)));
-	// A DIRECTORY at either path (PR #488's review): docker bind-mounts it where squid reads a file, and the proxy cannot
-	// start from it. Said for the shipped proxy, whose run and compose file mount this folder's two paths.
+	// A DIRECTORY at any of its paths (PR #488's review): docker bind-mounts it where squid reads a file, and the proxy
+	// cannot start from it. Said for the shipped proxy, whose run and compose file mount this folder's paths. The model
+	// endpoints' include (issue #503) is one of them: a directory there parses as NO rules with no warning (measured on
+	// Docker Desktop), and `egress render` refuses to write it.
 	if (!custom) {
-		for (const f of ["egress-allowlist.conf", "deploy/egress-proxy.conf"]) {
+		for (const f of ["egress-allowlist.conf", "deploy/egress-proxy.conf", MODEL_ENDPOINTS_INCLUDE_NAME]) {
 			if (proxyFileIsDirectory(join(seams.cwd, f))) {
 				checks.push({ ok: false, label: `${f} in this folder is a directory, not a file`, fix: `the egress proxy mounts it where squid reads a file, so it cannot start from this folder: remove the directory, then \`pi-dispatch init\` writes the file (create-only)` });
 			}
 		}
 	}
-	const judged = !custom && parsed ? shippedProxyDrift(parsed, { cwd: seams.cwd, platform: seams.platform ?? process.platform, realpath: (p) => realpathSync(p), compareMounts: inFolder }) : { drift: [], unknown: null };
+	// Issue #503's governing rule: what the third mount and the include file cost is decided by whether the rules this
+	// proxy runs (the folder's deploy/egress-proxy.conf) include the file. `includeNeeds` is a seam for tests.
+	const { includeNeeds = ({ env: e, cwd, platform }) => ({ rulesInclude: rulesFileIncludes(join(cwd, "deploy/egress-proxy.conf"), { readFileSync }), endpointsDeclared: endpointsDeclaredIn({ env: e, cwd, fs: { readFileSync, existsSync }, platform }) }) } = seams;
+	const needs = !custom && inFolder ? includeNeeds({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform }) : { rulesInclude: false, endpointsDeclared: false };
+	if (!custom && inFolder) {
+		// MISSING in a deployment folder: ✗ when the rules include it, since squid then refuses to start (measured); ⚠
+		// otherwise, since a proxy on rules from before #503 runs without it, and the rules refresh needs it.
+		if (!proxyFilesExist(join(seams.cwd, MODEL_ENDPOINTS_INCLUDE_NAME))) {
+			checks.push(
+				needs.rulesInclude
+					? { ok: false, label: `${MODEL_ENDPOINTS_INCLUDE_NAME} is not in this folder`, fix: `the egress proxy mounts it and its rules include it, and squid will not start without it: \`pi-dispatch init\` writes it (create-only), then \`pi-dispatch up\` starts the proxy` }
+					: { ok: false, warn: true, label: `${MODEL_ENDPOINTS_INCLUDE_NAME} is not in this folder`, fix: "the proxy's rules here predate #503 and run without it, but the next rules refresh includes it and the proxy will not start without it then: `pi-dispatch init` writes it (create-only)" },
+			);
+		}
+		// Endpoints declared under rules that predate #503: the one line up, doctor and egress render share.
+		if (needs.endpointsDeclared && !needs.rulesInclude) checks.push({ ok: false, warn: true, label: rulesPredateEndpointsLine("docker"), fix: "a reload or a proxy replace changes nothing here: the rules themselves must include the file, and the refresh `pi-dispatch up` offers replaces the proxy with them" });
+	}
+	// Issue #503: the declared model endpoints, read as the service reads them. None declared is no line and no container,
+	// so a deployment without them prints what it always did. Under rules that predate the include the line just above is
+	// the whole story (a probe would only fail it again), so nothing more is said there. A proxy PI_EGRESS_PROXY names
+	// must include the file itself, and is read like the shipped one.
+	const { declaredEndpoints = ({ env: e, cwd, platform }) => declaredEndpointsIn({ env: e, cwd, fs: { readFileSync, existsSync }, platform }), hostAddresses = () => lanIPv4Addresses(networkInterfaces()) } = seams;
+	const declared = declaredEndpoints({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform });
+	const endpoints = declared.length > 0 && !(!custom && inFolder && !needs.rulesInclude) ? declared : [];
+	if (endpoints.length > 0) {
+		const runtime = routeRuntimeFromFacts(seams.readFactsOnce ? await seams.readFactsOnce() : null, seams.platform ?? process.platform);
+		const addresses = hostAddresses();
+		checks.push(...endpointRouteChecks({ runtime: runtime && addresses ? { ...runtime, hostAddresses: addresses } : runtime, endpoints, prefix: "", proof: "The endpoint probes below are the proof, once the proxy runs and the job image is here." }));
+	}
+	const judged = !custom && parsed ? shippedProxyDrift(parsed, { cwd: seams.cwd, platform: seams.platform ?? process.platform, realpath: (p) => realpathSync(p), compareMounts: inFolder, rulesInclude: needs.rulesInclude }) : { drift: [], unknown: null };
 	// What `up` does with it, told the way `up` decides it (PR #456's final check): a proxy stale by its image, entrypoint
 	// or command is offered for replacement whatever its mounts; one stale on its mounts alone is not while one of its own
 	// two mounts is unknown, so the fix names the commands rather than an offer that `up` would not make.
 	const mountsOnly = judged.unknown !== null && judged.drift.length > 0 && shippedProxyDrift(parsed, { cwd: seams.cwd, compareMounts: false }).drift.length === 0;
 	const replaceFix = mountsOnly
-		? `check its mounts (\`docker inspect --format '{{json .Mounts}}' ${proxy}\`), then \`docker rm -f ${proxy}\` and \`pi-dispatch up\` from the deployment folder replace it with the shipped one; \`up\` does not offer to on its own while one of its mounts cannot be compared here`
-		: `\`pi-dispatch up\` from the deployment folder offers to replace it with the shipped one (docker rm -f ${proxy}, then the shipped run)`;
+		? `check its mounts (\`docker inspect --format '{{json .Mounts}}' ${proxy}\`), then \`docker rm -f -v ${proxy}\` and \`pi-dispatch up\` from the deployment folder replace it with the shipped one; \`up\` does not offer to on its own while one of its mounts cannot be compared here`
+		: `\`pi-dispatch up\` from the deployment folder offers to replace it with the shipped one (docker rm -f -v ${proxy}, then the shipped run)`;
 	// The worker's simple rule (egress.mjs): paused, exited, dead and created (`STOPPED_PROXY_STATES`) refuse every job,
 	// so ✗; any other state is one the worker retries through (restarting, stopping, removing, ...), so ⚠, and the fix
 	// says jobs wait rather than fail. `restarting` is a crash loop that fails every job (one retry, then failed), so ✗;
@@ -4549,7 +6074,7 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 			: custom
 			? `PI_EGRESS_PROXY names your own proxy, which neither compose nor \`pi-dispatch up\` starts: ${state.code === 0 ? `\`docker ${parsed?.status === "paused" ? "unpause" : "start"} ${proxy}\`` : `create and start ${proxy} yourself`} -- the egress policy refuses every job pre-spend while it is down, which costs no budget but runs nothing (PI_EGRESS=0 opts out)`
 			: judged.drift.length > 0
-				? `it is not this deployment's either (${judged.drift.join("; ")}): ${replaceFix} -- the egress policy refuses every job pre-spend while it is down, which costs no budget but runs nothing (PI_EGRESS=0 opts out)`
+				? `${judged.outOfDate ? "it is this deployment's proxy but out of date" : "it is not this deployment's either"} (${judged.drift.join("; ")}): ${replaceFix} -- the egress policy refuses every job pre-spend while it is down, which costs no budget but runs nothing (PI_EGRESS=0 opts out)`
 				: parsed?.status === "paused"
 					? `docker unpause ${proxy}  -- as \`pi-dispatch up\` offers; the egress policy refuses every job pre-spend while it is paused, which costs no budget but runs nothing (PI_EGRESS=0 opts out)`
 					: "`pi-dispatch up` from the deployment folder starts it  -- the egress policy refuses every job pre-spend while this is down, which costs no budget but runs nothing (PI_EGRESS=0 opts out)",
@@ -4563,7 +6088,7 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 		if (judged.drift.length > 0) {
 			checks.push({
 				ok: false,
-				label: `Egress proxy is running but is not this deployment's (${proxy}): ${judged.drift.join("; ")}`,
+				label: judged.outOfDate ? `Egress proxy is this deployment's proxy but out of date (${proxy}): ${judged.drift.join("; ")}` : `Egress proxy is running but is not this deployment's (${proxy}): ${judged.drift.join("; ")}`,
 				fix: `${replaceFix}; until then every job's egress runs through a policy this deployment did not ship`,
 				proxyState: proxyCheck.proxyState,
 			});
@@ -4573,7 +6098,7 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 				ok: false,
 				warn: true,
 				label: `Egress proxy's mounts could not be compared on this host (${proxy}): ${judged.unknown}`,
-				fix: "its image, entrypoint and command were compared; check its two mounts by hand (`docker inspect --format '{{json .Mounts}}' " + proxy + "`): /etc/squid/squid.conf must be this deployment's deploy/egress-proxy.conf and /etc/pi-dispatch/allowlist.conf its egress-allowlist.conf",
+				fix: "its image, entrypoint and command were compared; check its mounts by hand (`docker inspect --format '{{json .Mounts}}' " + proxy + "`): /etc/squid/squid.conf must be this deployment's deploy/egress-proxy.conf, /etc/pi-dispatch/allowlist.conf its egress-allowlist.conf, and /etc/pi-dispatch/model-endpoints.conf its model-endpoints.conf",
 			});
 		}
 	}
@@ -4592,7 +6117,7 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 	}
 
 	// The end-to-end probe, and the only place in this codebase that proves the policy rather than
-	// inspecting it. Two containers, on a throwaway network built exactly like a job's, gated on the image
+	// inspecting it. Three containers, on a throwaway network built exactly like a job's, gated on the image
 	// being present because it uses the job image's own node and runner module -- which is the point: it proves the
 	// operator's OWN image routes a request through the proxy the way its runner does (pi loaded, then the runner's
 	// restore), the property a stale image would silently lack and the one whose absence turns the whole policy into an
@@ -4601,12 +6126,21 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 	// Credential-free by construction: `api.anthropic.com` answers 401 to an unauthenticated request, so
 	// reaching the provider and being refused for the key proves the entire path and costs nothing. That is
 	// docs/egress.md's own method, promoted from prose to a check.
+	// Issue #503: the include as the running proxy sees it. Not for a shipped proxy already judged stale above: its mounts
+	// are that line's to name, and a two-mount proxy has no include to read.
+	if (endpoints.length > 0 && !(!custom && judged.drift.length > 0)) {
+		const inside = await runCmdCapture(spawn, "docker", ["exec", proxy, "cat", ENDPOINTS_INCLUDE_IN_PROXY], { stdoutOnly: true, timeoutMs: CANARY_STEP_TIMEOUT_MS });
+		// The file the proxy ACTUALLY mounts there, by its bind source from the inspect above, for the shipped proxy and
+		// an operator's alike: never this folder's, which may not be the one mounted (gate round 2).
+		const mounted = readIncludeBindSource(parsed?.mounts);
+		checks.push(endpointsIncludeCheck({ answer: inside, endpoints, bin: "docker", proxy, prefix: "", mounted, recreate: custom ? `recreate ${proxy} so it mounts the file anew` : `\`docker rm -f -v ${proxy}\`, then \`pi-dispatch up\` starts it on the file anew (a restart cuts running jobs' tunnels)` }));
+	}
 	if (imageCode !== 0) return checks;
 	// Issue #431: the canary itself is `runEgressCanary`, shared with the podman venue's `--live` and the conformance
 	// script. docker's probes keep `runCmdCapture` (its 30 s bound, stderr merged, SIGTERM at the bound) rather than the
 	// bounded step runner, so docker's spawns, and what a probe that never launched leaves for the teardown, are exactly
 	// what they were: pinned in doctor.test.mjs against the output and argv captured before the move.
-	const canary = await runEgressCanary({ run: liveRunVia(spawn), probeRun: (args) => runCmdCapture(spawn, "docker", args), proxy, image: jobImage, pid, gate });
+	const canary = await runEgressCanary({ run: liveRunVia(spawn), probeRun: (args) => runCmdCapture(spawn, "docker", args), proxy, image: jobImage, pid, gate, endpoints });
 	// Through a stale proxy the canary reads THAT proxy's policy (exec round 3): a failure is the proxy's to fix, never
 	// this deployment's allowlist, which it may not even mount.
 	checks.push(...(staleRunning ? canary.checks.map((c) => (c.ok ? c : { ...c, fix: `the canary ran through ${proxy}, which is not this deployment's proxy (above), so this says nothing about egress-allowlist.conf: ${replaceFix}, then re-run doctor` })) : canary.checks));
@@ -4619,6 +6153,10 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
  * docker's is what it always was: a plain `docker run` on the canary network with the two proxy variables, which is
  * pinned byte for byte and not widened here, because moving it is its own change with its own review.
  *
+ * `script` is what the container runs, the runner's route (`egressCanaryScript`) unless a probe says otherwise: the
+ * plain HTTP probe (issue #508) passes `egressCanaryPlainScript`, and its argv differs from the others in nothing else.
+ * A model endpoint's probe (issue #503) passes its own `name` and `httpProxy`, which adds the job's HTTP_PROXY on docker.
+ *
  * podman's is a JOB's, built by the podman venue's own builder (`podmanArgsFromSpec` over `containerSpec`, the path
  * `buildPodmanRunArgs` takes), never a hand-rolled argv: `ISOLATION_FLAGS`, the job's memory and cpu bounds,
  * the job user this host decides as `--user`, `--userns=keep-id` and `PODMAN_PINNED_FLAGS`, and a job's own egress
@@ -4635,8 +6173,7 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
  * then replaced by none; `CANARY_NO_WORKSPACE` is a path nothing creates, so if a later edit ever kept the mount, the
  * run would fail on a missing source rather than bind a real directory.
  */
-export function egressCanaryProbeArgs({ bin = "docker", slug, pid, network, proxy, image, url, user = null }) {
-	const name = egressCanaryProbe(slug, pid);
+export function egressCanaryProbeArgs({ bin = "docker", slug, pid, network, proxy, image, url, user = null, script = egressCanaryScript(url), name = egressCanaryProbe(slug, pid), httpProxy = false }) {
 	if (bin !== "podman") {
 		return [
 			"run",
@@ -4651,20 +6188,23 @@ export function egressCanaryProbeArgs({ bin = "docker", slug, pid, network, prox
 			`--network=${network}`,
 			"-e",
 			`HTTPS_PROXY=http://${proxy}:3128`,
+			// Only for a model endpoint's probe (issue #503), whose URL is `http://`: the runner's dispatcher sends that to
+			// HTTP_PROXY, as a job's does. The canary's own three argv are unchanged.
+			...(httpProxy ? ["-e", `HTTP_PROXY=http://${proxy}:3128`] : []),
 			"-e",
 			"NODE_USE_ENV_PROXY=1",
 			"--entrypoint",
 			"node",
 			image,
 			"-e",
-			egressCanaryScript(url),
+			script,
 		];
 	}
 	// HOME as a podman job gets it (`resolvePodmanImageUser` always answers CONTAINER_HOME): under keep-id the job user's
 	// passwd entry otherwise names this host's home path, which does not exist in the image, and the canary loads pi as
 	// that user. No credential rides along: the canary proves the route, and a 401 from the provider is its success.
 	const { mounts: _placeholder, ...spec } = containerSpec({ image, name, env: { HOME: CONTAINER_HOME, ...egressEnv({ proxy, armed: true }) }, workspace: CANARY_NO_WORKSPACE, network, user, userns: "keep-id", extraFlags: ["--entrypoint", "node"] });
-	return [...podmanArgsFromSpec({ ...spec, mounts: [] }), "-e", egressCanaryScript(url)];
+	return [...podmanArgsFromSpec({ ...spec, mounts: [] }), "-e", script];
 }
 
 /** The workspace `containerSpec` requires and the canary never mounts (see `egressCanaryProbeArgs`). */
@@ -4672,10 +6212,11 @@ const CANARY_NO_WORKSPACE = "/nonexistent/pi-dispatch-egress-canary-mounts-nothi
 
 /**
  * The egress canary (REQ-EGRESS-ALLOWLIST, issue #431): a throwaway `--internal` network built like a job's, the proxy
- * attached, two probe containers running `egressCanaryScript` (the runner's own route to the network, #427), one that
- * must reach the provider and one that must not reach an unlisted host, and a teardown that removes everything it made
- * or names what it could not. Returns `{ checks, results }`: the lines to print, and the `[{ property, want, reached }]`
- * readings `egressVerdict` folds into `--live`.
+ * attached, three probe containers, and a teardown that removes everything it made or names what it could not. Two run
+ * `egressCanaryScript` (the runner's own route to the network, #427): one must reach the provider and one must not reach
+ * an unlisted host. The third runs `egressCanaryPlainScript` and must not get plain HTTP through to a listed host on a
+ * port other than 80 (issue #508). Returns `{ checks, results }`: the lines to print, and the
+ * `[{ property, want, reached, probe }]` readings `egressVerdict` folds into `--live`, `probe` being the slug.
  *
  * ONE canary for every caller: docker's `doctor` (`egressChecks`), the podman venue's `doctor --live`
  * (`podmanLiveChecks`) and `.github/scripts/podman-conformance.mjs`. The conformance script used to carry a canary of
@@ -4688,8 +6229,11 @@ const CANARY_NO_WORKSPACE = "/nonexistent/pi-dispatch-egress-canary-mounts-nothi
  * measured), which a 30 s bound would read as a probe that did not run. `user` is the job user, required on podman,
  * whose builder refuses a keep-id argv without one. What it does NOT check is the proxy: every caller has read the
  * proxy's state on its own runtime first, and runs this only when it is up and the job image is present.
+ *
+ * `endpoints` (issue #503) are the declared model endpoints to prove on the same network after the three
+ * (`runEndpointProbes`), `[]` by default, so the conformance script and a deployment with none run exactly the three.
  */
-export async function runEgressCanary({ run, bin = "docker", proxy, image, pid = process.pid, user = null, probeRun = null, gate = makeDetachGate((args, opts) => run(args, { timeoutMs: opts?.timeoutMs ?? CANARY_STEP_TIMEOUT_MS }), { bin }) }) {
+export async function runEgressCanary({ run, bin = "docker", proxy, image, pid = process.pid, user = null, probeRun = null, endpoints = [], gate = makeDetachGate((args, opts) => run(args, { timeoutMs: opts?.timeoutMs ?? CANARY_STEP_TIMEOUT_MS }), { bin }) }) {
 	const venue = canaryVenueFor(bin);
 	const probe = probeRun ?? ((args) => run(args, { timeoutMs: bin === "podman" ? PODMAN_FIRST_START_TIMEOUT_MS : RUN_TIMEOUTS.cmd }));
 	const checks = [];
@@ -4702,6 +6246,8 @@ export async function runEgressCanary({ run, bin = "docker", proxy, image, pid =
 	// Probe containers this run may have left BEHIND its CLI, see the `code === null` branch below.
 	const unfinished = [];
 	let created = false;
+	// The canary stopped on an image with no runner module: the endpoint probes take the same route, so they are not run.
+	let staleRunner = false;
 	// FIRST, before anything exists (issue #452, gate round 3): this canary's own teardown detaches the running proxy, which
 	// on a rootless Podman 4.x without a holding keeper cuts its route out, through `podman`, `podman-docker` or the Docker
 	// API alike (measured). So the detach gate every teardown goes through is asked up front, and a refusal runs nothing:
@@ -4756,11 +6302,17 @@ export async function runEgressCanary({ run, bin = "docker", proxy, image, pid =
 		// which no proxy can reach, so a proxy allowing every host still read as denying this one (measured: an
 		// allow-all squid answered 503 for it and let `example.com` through). `example.com` is reserved for documentation
 		// (RFC 2606), answers everywhere, and is contacted only when the proxy lets the request out, which is the finding.
-		for (const [slug, host, url, want] of [
+		//
+		// The THIRD probe (issue #508) asks the proxy for plain HTTP to a LISTED host on a port other than 80, as a client
+		// that forwards rather than tunnels would (npm undici's EnvHttpProxyAgent without proxyTunnel, a package manager). Port 443 of the provider because it is a
+		// port that host certainly listens on, so a proxy that lets it through gets an answer (a 400 for clear text on a
+		// TLS port) rather than a timeout, and no second host has to be listed for the canary.
+		for (const [slug, host, url, want, script] of [
 			[CANARY_PROBE_SLUGS[0], "the provider", "https://api.anthropic.com/v1/messages", true],
 			[CANARY_PROBE_SLUGS[1], "an unlisted host", "https://example.com/", false],
+			[CANARY_PROBE_SLUGS[2], "plain HTTP to a listed host off port 80", "http://api.anthropic.com:443/", false, egressCanaryPlainScript("http://api.anthropic.com:443/", { proxyUrl: egressProxyUrl(proxy) })],
 		]) {
-			const answer = await probe(egressCanaryProbeArgs({ bin, slug, pid, network: net, proxy, image, url, user }));
+			const answer = await probe(egressCanaryProbeArgs({ bin, slug, pid, network: net, proxy, image, url, user, ...(script ? { script } : {}) }));
 			// The script exits 0 (reached) or 3 (blocked). Anything else is the container not running it -- a name clash,
 			// the image, the daemon -- which is no reading at all, and must not pass for a deny.
 			// `code === null` is the ONE case where a container may still be RUNNING under a name we chose: the
@@ -4772,7 +6324,7 @@ export async function runEgressCanary({ run, bin = "docker", proxy, image, pid =
 			// nothing of ours to remove. Harmless either way today (`docker rm -f <missing>` exits 0, measured),
 			// and written out because the conflation it removes is the one this item is about.
 			if (answer.code === null && answer.ended !== "error") unfinished.push(egressCanaryProbe(slug, pid));
-			// Said ONCE and the second probe not run: the unlisted host's "blocked" would come from the internal network
+			// Said ONCE and the later probes not run: the unlisted host's "blocked" would come from the internal network
 			// refusing a runner that never tried the proxy, which reads exactly like a policy that denies it.
 			if (answer.code === EGRESS_CANARY_STALE_RUNNER) {
 				checks.push({
@@ -4780,8 +6332,9 @@ export async function runEgressCanary({ run, bin = "docker", proxy, image, pid =
 					warn: true,
 					label: `${venue.prefix}Egress policy: not proved, because the job image could not find ${EGRESS_CANARY_RUNNER_MODULE} (or an import of it): its runner predates issue #427, whose provider call goes around the proxy so that with egress armed every job fails at its first turn, or the image is not built from this project's`,
 					fix: `use a job image built after issue #427 (ghcr.io/edgehero/pi-job:latest, or rebuild yours FROM it), or set PI_EGRESS=0 until you can`,
-					readBack: { property: "egress", want, reached: null },
+					readBack: { property: "egress", want, reached: null, probe: slug },
 				});
+				staleRunner = true;
 				break;
 			}
 			if (answer.code !== 0 && answer.code !== 3) {
@@ -4790,17 +6343,31 @@ export async function runEgressCanary({ run, bin = "docker", proxy, image, pid =
 					warn: true,
 					label: `${venue.prefix}Egress policy probe for ${host} did not run (${answer.code === null ? `${bin} run did not finish` : `${bin} run exited ${answer.code}`})`,
 					fix: "re-run doctor; if it persists, run the job image by hand to see why a container on this network will not start",
-					readBack: { property: "egress", want, reached: null },
+					readBack: { property: "egress", want, reached: null, probe: slug },
 				});
 				continue;
 			}
 			const reached = answer.code === 0;
+			if (slug === CANARY_PROBE_SLUGS[2]) {
+				checks.push({
+					ok: reached === want,
+					warn: true,
+					readBack: { property: "egress", want, reached, probe: slug },
+					label: `${venue.prefix}${
+						reached === want
+							? "Egress policy refuses plain HTTP to a listed host off port 80 (api.anthropic.com:443 without a tunnel; only a CONNECT reaches 443)"
+							: "Egress policy lets plain HTTP through to api.anthropic.com on port 443, so a client that does not tunnel reaches every port of a listed host"
+					}`,
+					fix: `the proxy runs rules from before issue #508: restart it on the current egress-proxy.conf (\`pi-dispatch up\`; on the podman venue \`pi-dispatch service install --force\`; for a proxy you started by hand, update the egress-proxy.conf it mounts, then \`${bin} restart ${proxy}\`); a copy you keep by hand must add "http_access deny !Safe_ports !CONNECT" right before "http_access allow allowed"`,
+				});
+				continue;
+			}
 			checks.push({
 				ok: reached === want,
 				warn: true,
 				// NOT rendered: what `doctor --live` folds into its egress read-back (live-probes.mjs), so the canary is
 				// run once and read twice rather than a second canary built beside it.
-				readBack: { property: "egress", want, reached },
+				readBack: { property: "egress", want, reached, probe: slug },
 				label: `${venue.prefix}${
 					reached === want
 						? want
@@ -4815,6 +6382,15 @@ export async function runEgressCanary({ run, bin = "docker", proxy, image, pid =
 					: `check egress-allowlist.conf: a rule wider than you meant (a bare domain where you wanted a subdomain) lets a job reach hosts you did not list`,
 			});
 		}
+		// Issue #503: each declared model endpoint, on this same network, after the canary's own three. Its lines carry no
+		// `readBack`, so `egressVerdict` reads exactly the three readings it always did.
+		if (endpoints.length > 0) {
+			if (staleRunner) {
+				checks.push({ ok: false, warn: true, label: `${venue.prefix}Model endpoints: not probed, because the job image has no runner module (above), and their probes take the runner's route`, fix: "use a job image built after issue #427, then re-run doctor" });
+			} else {
+				checks.push(...(await runEndpointProbes({ probe, bin, pid, network: net, proxy, image, user, endpoints, venue, unfinished })));
+			}
+		}
 	} finally {
 		// The probes FIRST, by the name carrying this pid, then the network: a member still attached is exactly
 		// why the old `network rm` failed, and it failed silently. `rm -f` of a name that is not there is docker
@@ -4852,6 +6428,407 @@ function readingsOf(checks) {
 	return checks.filter((c) => c.readBack?.property === "egress").map((c) => c.readBack);
 }
 
+/**
+ * The probes doctor runs per declared model endpoint (issue #503, REQ-EGRESS-ALLOWLIST), in this order, and ONE list:
+ * the loop names its containers from it and the dead-pid sweep matches on it, as `CANARY_PROBE_SLUGS` is shared. Not
+ * folded into `CANARY_PROBE_SLUGS`, whose three readings are what `egressVerdict` reads; these never reach it.
+ *   - `models`: `GET http://<host>:<port>/v1/models` by the runner's route, which tunnels it, as a job's provider call
+ *     goes. Must answer 200: Ollama, llama-server, vLLM and LM Studio all serve that path.
+ *   - `nextport`: the same, to the nearest port above that no declaration for that host uses and that the allowlist's
+ *     own rules do not open (`undeclaredPortNear`). Must get the proxy's 403 on the CONNECT, which proves the
+ *     endpoint's rule is port-exact.
+ *   - `plain`: a plain forward `GET` to the declared port. Must get squid's 403, which proves the include adds a tunnel
+ *     and nothing else.
+ */
+export const ENDPOINT_PROBE_SLUGS = Object.freeze(["models", "nextport", "plain"]);
+
+/** The parser's id rule without its anchors, for the sweep's pattern. */
+const ENDPOINT_ID_CLASS = MODEL_ENDPOINT_ID_RE.source.replace(/^\^/, "").replace(/\$$/, "");
+
+/** How long an endpoint probe waits for its answer inside the container: a server that takes the tunnel and never answers. */
+const ENDPOINT_PROBE_TIMEOUT_MS = 15_000;
+
+/** Where the proxy reads the include, in every venue's mount (compose, the Quadlet unit, the hand-started recipe). */
+export const ENDPOINTS_INCLUDE_IN_PROXY = "/etc/pi-dispatch/model-endpoints.conf";
+
+/**
+ * The tunnelled endpoint probes' in-container script: the runner's route (`loadPiThenRestore`), then one `GET`. It is
+ * `egressCanaryScript` with two differences. It sends a GET, the method a model list is read with. And it reports the
+ * PROXY's answer to the CONNECT when there is one: a refused or failed tunnel reaches the caller only as an error whose
+ * cause chain carries undici's `Proxy response (<status>) !== 200 when HTTP Tunneling` (measured on 2026-09-30, M9:
+ * a job sees squid's 503, "allowed but nothing answered", and its 403, "not declared", alike as "Connection error"). So
+ * the script walks the chain for that text, and doctor shows the status. The text is pinned at the 0.99.1 pin's undici
+ * 8.10.2 (`lib/dispatcher/proxy-agent.js`) by a test that runs this script against a fake proxy.
+ *
+ * Prints ONE line: `reached <status>` (exit 0), `tunnel <status>` (exit 3), `blocked <code>` (exit 6: no answer, and no
+ * proxy status, as for a request that went around the proxy or timed out), `error ...` (exit 5, or 4 for an image with
+ * no runner module).
+ */
+export function egressEndpointScript(url, { timeoutMs = ENDPOINT_PROBE_TIMEOUT_MS } = {}) {
+	return `import(${JSON.stringify(EGRESS_CANARY_RUNNER_MODULE)}).then(m=>m.loadPiThenRestore(),e=>{console.log("error",e.code??e.message);process.exit(e.code==="ERR_MODULE_NOT_FOUND"?${EGRESS_CANARY_STALE_RUNNER}:5)}).then(()=>fetch(${JSON.stringify(url)},{signal:AbortSignal.timeout(${Number(timeoutMs)})}).then(r=>{console.log("reached",r.status);process.exit(0)},e=>{let c=e,s=null;for(let i=0;c&&i<8&&s===null;i++){const m=/Proxy response \\((\\d{3})\\) !== 200 when HTTP Tunneling/.exec(String(c.message??""));if(m)s=m[1];c=c.cause}if(s!==null){console.log("tunnel",s);process.exit(3)}console.log("blocked",e.cause?.code??e.name??"error");process.exit(6)}),e=>{console.log("error",e.message);process.exit(5)})`;
+}
+
+/**
+ * What one endpoint probe printed, as `{ kind, status, detail }`, or null. Read from the LAST line of that shape, since
+ * a runtime may print its own lines first. `detail` is kept only when it is a short code word: the plain probe's is the
+ * `X-Squid-Error` header, which a server that answered instead of the proxy writes, and a terminal is not handed that.
+ */
+function endpointProbeReading(answer) {
+	const lines = String(answer?.output ?? answer?.stdout ?? "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const m = /^(reached|tunnel|blocked|error)(?: (\d{3}))?(?: (\S+))?/.exec(lines[i]);
+		if (m) return { kind: m[1], status: m[2] ? Number(m[2]) : null, detail: m[3] && /^[A-Za-z_]{1,40}$/.test(m[3]) ? m[3] : "" };
+	}
+	return null;
+}
+
+/** `host:port` as a URL writes it (an IPv6 host is stored in brackets already). */
+function endpointAddress(host, port) {
+	return `${host}:${port}`;
+}
+
+/** Endpoints in id order, the order the include is rendered in. */
+function endpointsById(endpoints) {
+	return [...endpoints].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/** The exits each probe's script ends a READING with; any other exit is a container that did not run it. */
+const ENDPOINT_PROBE_READ_EXITS = Object.freeze({ models: [0, 3, 6], nextport: [0, 3, 6], plain: [0, 3] });
+
+/**
+ * One endpoint probe's line. Every line names the endpoint id and shows the proxy's status, and every one is warn-tier,
+ * as the canary's are: each needs the network to answer. What passes, and nothing else:
+ *   - `models`: the server answered 200 through the tunnel;
+ *   - `nextport`: the proxy refused the TUNNEL with 403. A 503 there means the proxy let the CONNECT through and found
+ *     nothing listening, so the rule is not port-exact; a server's own 403 through a tunnel is the same finding;
+ *   - `plain`: a 403 carrying squid's `X-Squid-Error: ERR_ACCESS_DENIED`. A bare 403 may be the server's own answer to a
+ *     request the proxy forwarded.
+ */
+function endpointProbeCheck({ slug, endpoint, answer, venue, bin, proxy, next }) {
+	const head = `${venue.prefix}Model endpoint ${endpoint.id}`;
+	const at = endpointAddress(endpoint.host, endpoint.port);
+	const reading = endpointProbeReading(answer);
+	const tag = { id: endpoint.id, probe: slug, kind: reading?.kind ?? null, status: reading?.status ?? null };
+	if (!ENDPOINT_PROBE_READ_EXITS[slug].includes(answer?.code) || !reading || reading.kind === "error") {
+		return {
+			ok: false,
+			warn: true,
+			label: `${head}: the ${slug} probe did not run (${answer?.code === null || answer?.code === undefined ? `${bin} run did not finish` : `${bin} run exited ${answer.code}`})`,
+			fix: "re-run doctor; if it persists, run the job image by hand to see why a container on this network will not start",
+			endpointProbe: tag,
+		};
+	}
+	const reload = reloadCommand(bin, proxy);
+	if (slug === "models") {
+		if (reading.kind === "reached" && reading.status === 200) return { ok: true, warn: true, label: `${head} answers through the proxy (GET http://${at}/v1/models through a CONNECT tunnel: 200)`, endpointProbe: tag };
+		// The SERVER refused the request for want of a key (vLLM --api-key, a gateway in front): the route and the rule are
+		// proved, since only an open tunnel carries the server's own answer. Said apart from a fault, still warn-tier.
+		if (reading.kind === "reached" && (reading.status === 401 || reading.status === 403)) {
+			return {
+				ok: false,
+				warn: true,
+				label: `${head}: the route through the proxy works (the tunnel to ${at} opened), and the server wants a key (GET /v1/models answered ${reading.status})`,
+				fix: "declare it without \"keyless\" and give its provider its key, as for any provider that needs one; nothing about the egress proxy needs changing",
+				endpointProbe: tag,
+			};
+		}
+		// A server that took the connection and never answered is not one to start: say what was seen.
+		const timedOut = reading.kind === "blocked" && reading.detail === "TimeoutError";
+		const why =
+			reading.kind === "tunnel"
+				? reading.status === 503
+					? `the proxy allowed the tunnel to ${at} and answered 503, so nothing answered there`
+					: reading.status === 403
+						? `the proxy refused the tunnel to ${at} with 403, so the rules it runs do not allow this endpoint`
+						: `the proxy answered ${reading.status} to the CONNECT to ${at}`
+				: reading.kind === "reached"
+					? `the tunnel to ${at} was let through, but GET /v1/models answered ${reading.status}, not 200`
+					: timedOut
+						? `it accepted the connection but did not answer /v1/models within ${ENDPOINT_PROBE_TIMEOUT_MS / 1000} s`
+						: `no answer came back through the proxy (${reading.detail || "no reason given"})`;
+		const fix =
+			reading.kind === "tunnel" && reading.status === 403
+				? `\`pi-dispatch egress render\` in the deployment folder, then \`${reload}\`; the include line above says whether the proxy holds the declared rules`
+				: reading.kind === "reached"
+					? "check that this port is the model server's and that it serves the OpenAI-compatible API under /v1 (Ollama, llama-server, vLLM and LM Studio do)"
+					: timedOut
+						? "the server is there but stuck or busy (a model still loading, every slot taken): check its own log, then re-run doctor"
+						: bin === "podman"
+							? `start the model server, bound to this host's LAN address or 0.0.0.0 (never 127.0.0.1 alone), and declare a server on this host as host.containers.internal (docs/egress.md, "Local model servers"). A job meets this as "Connection error"`
+							: `start the model server, and check it listens where the proxy reaches it (docs/egress.md, "Local model servers"; on Docker Engine that is 172.17.0.1 or 0.0.0.0, never 127.0.0.1 alone). A job meets this as "Connection error"`;
+		return { ok: false, warn: true, label: `${head} does NOT answer: ${why}`, fix, endpointProbe: tag };
+	}
+	const wider = `the proxy's rules are wider than model-endpoints.conf renders: compare the include inside it (\`${bin} exec ${proxy} cat ${ENDPOINTS_INCLUDE_IN_PROXY}\`) with \`pi-dispatch egress render\`'s, check egress-allowlist.conf does not list ${endpoint.host}, then \`${reload}\``;
+	if (slug === "nextport") {
+		const nextAt = endpointAddress(endpoint.host, next);
+		if (reading.kind === "tunnel" && reading.status === 403) return { ok: true, warn: true, label: `${head}'s rule is port-exact (a CONNECT to ${nextAt}, a port nobody declared, got the proxy's 403)`, endpointProbe: tag };
+		const what =
+			reading.kind === "tunnel"
+				? reading.status === 503
+					? `the proxy let a CONNECT to ${nextAt}, a port nobody declared, through and answered 503 (nothing listens there)`
+					: `the proxy answered ${reading.status} to a CONNECT to ${nextAt}, not its 403`
+				: reading.kind === "reached"
+					? `a CONNECT to ${nextAt}, a port nobody declared, was let through, and something there answered ${reading.status}`
+					: `a CONNECT to ${nextAt} got no answer from the proxy (${reading.detail || "no reason given"}), so the refusal was not seen`;
+		return { ok: false, warn: true, label: `${head}'s rule is NOT shown to be port-exact: ${what}`, fix: wider, endpointProbe: tag };
+	}
+	if (reading.status === 403 && reading.detail.startsWith("ERR_ACCESS_DENIED")) return { ok: true, warn: true, label: `${head} admits no plain forward request (GET http://${at}/v1/models without a tunnel got the proxy's 403 ${reading.detail})`, endpointProbe: tag };
+	return {
+		ok: false,
+		warn: true,
+		label: `${head} admits a plain forward request: GET http://${at}/v1/models without a tunnel got ${reading.status ?? "no status"}${reading.detail ? ` ${reading.detail}` : ""}, not the proxy's 403 ERR_ACCESS_DENIED`,
+		fix: wider,
+		endpointProbe: tag,
+	};
+}
+
+/**
+ * The port the `nextport` probe asks for (issue #503): the first one above the declared port that no declaration for the
+ * same host uses, wrapping below the declared port past 65535. Never 443 or 80, which the allowlist admits for a listed
+ * host (a CONNECT to 443, plain HTTP to 80): a host that is also listed would pass there by that rule, and the line would
+ * blame the endpoint's. Skipped whether or not the host is listed, which costs nothing and reads no file. The port
+ * itself is shown on the line. `null` only when every other port of the host is declared, which no real file does.
+ */
+export function undeclaredPortNear(endpoint, endpoints) {
+	const taken = new Set((endpoints ?? []).filter((e) => e.host === endpoint.host).map((e) => e.port));
+	const free = (p) => p !== endpoint.port && !taken.has(p) && p !== 443 && p !== 80;
+	for (let p = endpoint.port + 1; p <= 65535; p++) if (free(p)) return p;
+	for (let p = endpoint.port - 1; p >= 1; p--) if (free(p)) return p;
+	return null;
+}
+
+/**
+ * The three probes for each declared endpoint (issue #503), in id order, on the canary's network and through the
+ * canary's own runner, so the teardown that removes the canary's probes removes these too (`unfinished` is the
+ * canary's list). Each container is built by `egressCanaryProbeArgs`, a job's shape, with the job's plain-HTTP proxy
+ * variable as well on docker: the runner's dispatcher sends an `http://` origin to HTTP_PROXY, which docker's canary
+ * argv does not otherwise carry (podman's is a job's environment and has it).
+ */
+async function runEndpointProbes({ probe, bin, pid, network, proxy, image, user, endpoints, venue, unfinished }) {
+	const checks = [];
+	for (const endpoint of endpointsById(endpoints)) {
+		const next = undeclaredPortNear(endpoint, endpoints);
+		const models = `http://${endpointAddress(endpoint.host, endpoint.port)}/v1/models`;
+		const nextUrl = `http://${endpointAddress(endpoint.host, next)}/v1/models`;
+		const runs = [
+			[ENDPOINT_PROBE_SLUGS[0], models, egressEndpointScript(models)],
+			...(next === null ? [] : [[ENDPOINT_PROBE_SLUGS[1], nextUrl, egressEndpointScript(nextUrl)]]),
+			[ENDPOINT_PROBE_SLUGS[2], models, egressCanaryPlainScript(models, { proxyUrl: egressProxyUrl(proxy) })],
+		];
+		for (const [slug, url, script] of runs) {
+			const name = egressEndpointProbe(slug, endpoint.id, pid);
+			const answer = await probe(egressCanaryProbeArgs({ bin, slug, name, pid, network, proxy, image, url, user, script, httpProxy: true }));
+			if (answer?.code === null && answer.ended !== "error") unfinished.push(name);
+			checks.push(endpointProbeCheck({ slug, endpoint, answer, venue, bin, proxy, next }));
+		}
+	}
+	return checks;
+}
+
+/**
+ * The include as the RUNNING proxy sees it, against what the declaration renders (issue #503). Read inside the
+ * container, never from this folder's file: a single-file bind mount holds the inode, so a file replaced by a rename
+ * leaves the container on the OLD one, and a reload then silently loads the old rules (measured on 2026-09-30, M3, on
+ * Docker and Podman on Linux). `answer` is the `<bin> exec <proxy> cat` capture; `recreate` is the venue's way to start
+ * the proxy on the file anew.
+ */
+function endpointsIncludeCheck({ answer, endpoints, bin, proxy, prefix, recreate, mounted = null }) {
+	const read = `${bin} exec ${proxy} cat ${ENDPOINTS_INCLUDE_IN_PROXY}`;
+	if (answer?.code !== 0) {
+		return {
+			ok: false,
+			warn: true,
+			label: `${prefix}Model endpoints: the include inside the running proxy could not be read (\`${read}\` ${answer?.code === null || answer?.code === undefined ? "did not finish" : `exited ${answer.code}`})`,
+			fix: `the proxy must mount this deployment's model-endpoints.conf at ${ENDPOINTS_INCLUDE_IN_PROXY}, as the shipped proxy does; run the command yourself to see why it fails`,
+		};
+	}
+	const ids = endpointsById(endpoints).map((e) => e.id).join(", ");
+	// The file the proxy mounts, by its bind source, against what the container holds, FIRST (issue #503, gate rounds 1
+	// and 2): a file replaced by a rename on the host leaves the container on the old inode, so the two differ, and no
+	// render or reload reaches the proxy until it is started on the file anew. Without this, a hand-replaced file whose
+	// JSON did not change read ✓. `mounted` is null when there is no such bind or it cannot be read here: no compare.
+	if (mounted && mounted.text !== String(answer.output)) {
+		return {
+			ok: false,
+			label: `${prefix}Model endpoints: the proxy is mounted on a replaced file: the file it mounts (${mounted.path}) differs from what ${proxy} reads at ${ENDPOINTS_INCLUDE_IN_PROXY}, so it was replaced (a rename, an editor's save) rather than written in place, and no reload reaches the proxy`,
+			fix: `recreate the proxy so it mounts the file anew: ${recreate}. From then on, change the file only with \`pi-dispatch egress render\`, which writes in place`,
+		};
+	}
+	if (String(answer.output) === renderEndpointsInclude(endpoints)) {
+		return { ok: true, label: `${prefix}Model endpoints: the include inside the running proxy matches model-endpoints.json (${ids})` };
+	}
+	return {
+		ok: false,
+		label: `${prefix}Model endpoints: the include inside the running proxy (${ENDPOINTS_INCLUDE_IN_PROXY} in ${proxy}) does not match model-endpoints.json (${ids}), so a reload would not load the declared rules`,
+		fix: `\`pi-dispatch egress render\` in the deployment folder, then \`${reloadCommand(bin, proxy)}\`. If the render says the file already matches and this line stays, the proxy holds an earlier copy of a file that was replaced rather than written in place, which a reload never sees: ${recreate}`,
+	};
+}
+
+/**
+ * The text of the host file a proxy bind-mounts at the include's path (issue #503, gate round 2), from its inspected
+ * `[{ type, source, destination }]`, or null: no such bind, or a source this host cannot read (Docker Desktop reports the
+ * real macOS path, so it reads there), and then the replaced-file compare is skipped rather than guessed.
+ */
+function readIncludeBindSource(mounts) {
+	const bind = (Array.isArray(mounts) ? mounts : []).find((m) => m?.type === "bind" && m.destination === ENDPOINTS_INCLUDE_IN_PROXY);
+	if (!bind || typeof bind.source !== "string" || !isAbsolute(bind.source)) return null;
+	const text = readTextOrNull(bind.source);
+	return text === null ? null : { path: bind.source, text };
+}
+
+/** `{{json .Mounts}}` as `[{ type, source, destination }]`, the shape `parseProxyState` gives docker's; `[]` when unreadable. */
+function mountsFromJson(output) {
+	try {
+		const list = JSON.parse(String(output ?? "").trim());
+		return (Array.isArray(list) ? list : []).filter((m) => m && typeof m === "object").map((m) => ({ type: String(m.Type ?? ""), source: String(m.Source ?? ""), destination: String(m.Destination ?? "") }));
+	} catch {
+		return [];
+	}
+}
+
+/** A regular file's text, or null for anything else or any failure: a compare that has nothing to compare says nothing. */
+function readTextOrNull(path) {
+	try {
+		return statSync(path).isFile() ? readFileSync(path, "utf8") : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The route from the egress proxy to each endpoint's host on THIS runtime (issue #503), from the measured table
+ * (`hostRouteFor`, `HOST_ROUTES` in backends.mjs). Only a REFUTED route fails: the proxy cannot reach that host here,
+ * whatever is listening. A measured route is a ✓ saying what it needs. One that is not measured on this runtime, or is
+ * another machine's ordinary outbound route, is said as information and NOT warned about: nearly every runtime version
+ * is unmeasured, so a ⚠ there would be on every run, and the endpoint probe is what proves the route.
+ */
+function endpointRouteChecks({ runtime, endpoints, prefix, proof }) {
+	return endpointsById(endpoints).map((endpoint) => {
+		const { status, sentence } = hostRouteFor(runtime, endpoint.host);
+		const head = `${prefix}Model endpoint ${endpoint.id} (${endpointAddress(endpoint.host, endpoint.port)})`;
+		if (status === HOST_ROUTE_REFUTED) {
+			return { ok: false, label: `${head} has no route from the egress proxy on this runtime: ${sentence}`, fix: "declare the host this runtime reaches (docs/backends.md lists the measured routes per venue: host.docker.internal on Docker, host.containers.internal on Podman), then `pi-dispatch egress render` and the reload it prints" };
+		}
+		if (status === HOST_ROUTE_WORKS) return { ok: true, label: `${head}: ${sentence}` };
+		// Another machine: an ordinary route out, said as such, never prefixed "not measured" before a sentence that names
+		// where it WAS measured.
+		if (status === HOST_ROUTE_LAN) return { ok: true, label: `${head}: ${sentence} ${proof}` };
+		// A rootless Podman that did not say which helper it runs: the table's rows are per helper, so none applies. Said as
+		// what this Podman did not report, never as a fault of the host or the endpoint.
+		if (runtime?.backend === "podman" && runtime.rootless === true && typeof runtime.helper !== "string") {
+			return { ok: true, label: `${head}: the rootless network helper was not reported by this Podman, so the route is not judged here. ${proof}` };
+		}
+		return { ok: true, label: `${head}: the route from the proxy is not measured here. ${sentence} ${proof}` };
+	});
+}
+
+/**
+ * The runtime `hostRouteFor` reads, from the `docker info` answer doctor already holds (`makeDaemonFactsReader`), or
+ * null. Docker Desktop is the daemon that calls its OS `Docker Desktop`, as the job-user line reads it; rootful Podman
+ * through its Docker API is `podman`. Nothing else is asked: a field doctor does not have stays missing and the route
+ * reads unmeasured.
+ */
+function routeRuntimeFromFacts(answer, platform) {
+	const facts = answer?.answered === true ? answer.facts : null;
+	if (!facts) return null;
+	const version = facts.serverVersion ?? "";
+	if (facts.podman === true) return { backend: "podman", version, ...(typeof facts.rootless === "boolean" ? { rootless: facts.rootless } : {}) };
+	const desktop = facts.os === "Docker Desktop";
+	return { backend: "docker", version, desktop, ...(desktop ? { os: platform } : {}) };
+}
+
+/**
+ * The rootless network helper this account is running (`slirp4netns` or `pasta`), from `observeRootlessNetns`, or null
+ * when none runs, the read fails, or two kinds run at once. Podman 4.9.3's `podman info` names no helper, so this is how
+ * its slirp4netns is known there; with no bridge container running there is no helper to see, and the route reads
+ * unjudged rather than guessed from the version.
+ */
+function runningNetnsHelper({ fs, euid, runRoot }) {
+	if (!fs || !Number.isInteger(euid)) return null;
+	try {
+		const seen = observeRootlessNetns({ fs, euid, runRoot });
+		const kinds = [...new Set((seen.helpers ?? []).map((h) => h.kind))];
+		return kinds.length === 1 ? kinds[0] : null;
+	} catch {
+		return null;
+	}
+}
+
+/** The interface names whose addresses are a runtime's own bridges or a VM's, never this host's LAN address. */
+const NOT_LAN_INTERFACE = /^(?:docker|br-|virbr|veth|cni|podman|flannel|cali|vmnet|vboxnet|utun|bridge|lima)/;
+
+/**
+ * This host's own IPv4 LAN addresses for `hostRouteFor` (`hostAddresses`), or undefined for none: plain dotted quads,
+ * not loopback, not link-local, and not on a container bridge (docker0, a compose `br-`, podman's), whose address a
+ * declaration naming it would reach by another route than the own-address row was measured on.
+ */
+export function lanIPv4Addresses(interfaces) {
+	const found = [];
+	for (const [name, list] of Object.entries(interfaces ?? {})) {
+		if (NOT_LAN_INTERFACE.test(name) || !Array.isArray(list)) continue;
+		for (const a of list) {
+			if ((a?.family !== "IPv4" && a?.family !== 4) || a.internal === true || typeof a.address !== "string") continue;
+			if (!/^(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)$/.test(a.address) || a.address.startsWith("169.254.") || a.address.startsWith("127.")) continue;
+			if (!found.includes(a.address)) found.push(a.address);
+		}
+	}
+	return found.length > 0 ? found : undefined;
+}
+
+/** Whether a host as `baseUrlTarget` gives it is loopback or host-local from inside a job (`PROXY_LOCAL_ADDRESSES`). */
+function loopbackTarget(host) {
+	if (host.startsWith("[") && host.endsWith("]")) return isProxyLocalHost("ipv6", host.slice(1, -1));
+	if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(host)) return isProxyLocalHost("ipv4", host);
+	return isProxyLocalHost("name", host);
+}
+
+/**
+ * The overlay models.json's models whose effective baseUrl (the model's own, else its provider's) names localhost or
+ * a loopback literal (issue #503), as `provider/model (host:port)` strings. Inside a job that address is the job's own
+ * container, egress on or off, so no job reaches the server. A provider that lists no models is named by itself.
+ */
+export function overlayLoopbackModels(models) {
+	const providers = models?.providers;
+	if (providers === null || typeof providers !== "object" || Array.isArray(providers)) return [];
+	const found = [];
+	for (const [name, entry] of Object.entries(providers)) {
+		if (entry === null || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const listed = Array.isArray(entry.models) ? entry.models.filter((m) => m !== null && typeof m === "object" && typeof m.id === "string") : [];
+		const check = (baseUrl, who) => {
+			const target = baseUrlTarget(baseUrl);
+			if (target && loopbackTarget(target.host)) found.push(`${who} (${target.host}:${target.port})`);
+		};
+		if (listed.length === 0) check(entry.baseUrl, quotedShown(name));
+		for (const m of listed) check(typeof m.baseUrl === "string" ? m.baseUrl : entry.baseUrl, `${quotedShown(name)}/${quotedShown(m.id)}`);
+	}
+	return found;
+}
+
+/** The two host aliases a model server on this machine is declared by, never listed in the allowlist. */
+const HOST_ALIASES = Object.freeze(["host.docker.internal", "host.containers.internal"]);
+
+/**
+ * Host aliases the allowlist admits (issue #503), from its text, as `[{ alias, entry }]` with the first entry that admits
+ * each: squid's `dstdomain` file, one entry per word, `#` comments, and an entry with a leading dot admitting that domain
+ * and every name under it, so `.internal` and `.docker.internal` admit `host.docker.internal` as surely as the name
+ * itself. Admitting one opens that host's port 443 by CONNECT and its port 80 by plain HTTP, and no model server's port,
+ * which is the confusion this names.
+ */
+export function allowlistHostAliases(text) {
+	const found = new Map();
+	for (const line of String(text ?? "").split(/\r?\n/)) {
+		for (const word of line.replace(/#.*/, "").trim().split(/\s+/)) {
+			const entry = word.toLowerCase();
+			if (entry === "") continue;
+			for (const alias of HOST_ALIASES) {
+				const admits = entry.startsWith(".") ? alias === entry.slice(1) || alias.endsWith(entry) : alias === entry;
+				if (admits && !found.has(alias)) found.set(alias, word);
+			}
+		}
+	}
+	return HOST_ALIASES.filter((a) => found.has(a)).map((alias) => ({ alias, entry: found.get(alias) }));
+}
+
 /**
  * The worker and receiver services installed for THIS folder, as `[{ which, source, setup }]` (`setup` null for a unit
  * rendered without `--env-setup`): an installed unit whose WorkingDirectory is this folder (systemd, launchd), or the
@@ -5219,15 +7196,23 @@ function buildScriptsOf(packageDir, fileExists) {
 function runCmdCapture(spawn, cmd, args, opts = {}) {
 	// `stdoutOnly` for a caller that PARSES the answer (issue #345): Podman's docker emulation prints a banner on
 	// stderr ("Emulate Docker CLI using podman ..."), which a merged capture puts in front of the value.
-	const { timeoutMs = 30000, stdoutOnly = false } = opts;
+	// `input` for a caller that hands the child a secret (issue #521): written to its stdin and closed, so the value is in
+	// neither argv nor any environment. Without it stdin stays ignored, as every other caller wants.
+	const { timeoutMs = 30000, stdoutOnly = false, input } = opts;
 	return new Promise((resolve) => {
 		let child;
 		try {
-			child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], ...(opts.env ? { env: opts.env } : {}), ...(opts.cwd ? { cwd: opts.cwd } : {}) });
+			child = spawn(cmd, args, { stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], ...(opts.env ? { env: opts.env } : {}), ...(opts.cwd ? { cwd: opts.cwd } : {}) });
 		} catch {
 			resolve({ code: null, output: "" });
 			return;
 		}
+		if (input !== undefined) {
+			// A child that exits before reading (a missing image, a CLI that refuses the argv) closes the pipe under the
+			// write: EPIPE is that child's answer, which its exit code already carries, not doctor's crash.
+			child.stdin?.on("error", () => {});
+			child.stdin?.end(input);
+		}
 		let output = "";
 		let done = false;
 		const finish = (code) => {
@@ -5302,6 +7287,63 @@ async function defaultReadHosts(url) {
 	}
 }
 
+/**
+ * Has any host reserved dollars on this Valkey recently? For `fleetDollarChecks`, asked only when a peer publishes no
+ * `fpUsd` and nothing else says dollar caps are in use. BEST EFFORT, and it says so wherever it is described:
+ *   1. EXISTS on the deployment's current day, week and month keys (`budget:usd:YYYY-MM-DD`, `:w:<Monday>`,
+ *      `:m:YYYY-MM`, `budget.mjs`'s key functions at `now`), the counters any host with a dollar window writes;
+ *   2. else a bounded SCAN for `budget:usd:*` (at most ten passes of COUNT 1000), for scope and model windows.
+ * The whole read is bounded by `deadlineMs`, so a large keyspace or a hung server answers "not seen". Any fault is
+ * false: the answer can add a warning, never remove one. A host whose only dollar setting is the per-job cap writes no
+ * counter at all, so it is not found this way (PR #551's review, round 2).
+ */
+export async function dollarKeysExistWith(client, { now = () => new Date(), deadlineMs = 2000 } = {}) {
+	let timer;
+	const deadline = new Promise((resolve) => {
+		// NOT unref'd, `host-registry.mjs`'s reason: an unref'd timer does not fire when the hung call is the last thing
+		// holding the loop, which is the case it is for. It is cleared as soon as the answer is in.
+		timer = setTimeout(() => resolve(false), deadlineMs);
+	});
+	const ask = (async () => {
+		const at = now();
+		const current = [dayKey(at, DOLLAR_KEY_PREFIX), weekKey(at, DOLLAR_KEY_PREFIX), monthKey(at, DOLLAR_KEY_PREFIX)];
+		if (Number(await client.exists(...current)) > 0) return true;
+		let cursor = "0";
+		for (let pass = 0; pass < 10; pass++) {
+			const [next, keys] = await client.scan(cursor, "MATCH", `${DOLLAR_KEY_PREFIX}:*`, "COUNT", 1000);
+			if (Array.isArray(keys) && keys.length > 0) return true;
+			cursor = String(next);
+			if (cursor === "0") return false;
+		}
+		return false;
+	})();
+	ask.catch(() => {});
+	try {
+		return (await Promise.race([ask, deadline])) === true;
+	} catch {
+		return false;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/** `dollarKeysExistWith` over a fail-fast client on `url`, always disconnected. */
+export async function defaultDollarKeysExist(url) {
+	try {
+		const { makeRedisClient } = await import("./connection.mjs");
+		const client = makeRedisClient(url, { failFast: true, lazyConnect: true });
+		client.on("error", () => {});
+		try {
+			await client.connect();
+			return await dollarKeysExistWith(client);
+		} finally {
+			client.disconnect();
+		}
+	} catch {
+		return false;
+	}
+}
+
 async function defaultProbeValkey(url) {
 	const { makeRedisClient } = await import("./connection.mjs");
 	const client = makeRedisClient(url, { failFast: true, lazyConnect: true });
@@ -5866,7 +7908,8 @@ export async function podmanChecks(env, seams, { jobImage, jobImageNote = "" })
 		checks.push({
 			ok: false,
 			label: `podman: job image is not in this account's Podman store (${jobImage})`,
-			fix: `pull or load it AS THE WORKER'S ACCOUNT, since rootless Podman keeps one image store per account: ${jobImage === "pi-job:latest" ? PODMAN_JOB_IMAGE_PULL : `podman pull ${jobImage}`} -- jobs run with --pull=never, so the worker never fetches it`,
+			// A name no pull is offered for (issue #523, round 2) is built or loaded, never pulled.
+			fix: `${jobImage === "pi-job:latest" || pullOffered(jobImage) ? "pull or load" : "build or load"} it AS THE WORKER'S ACCOUNT, since rootless Podman keeps one image store per account: ${jobImageFix("podman", jobImage)} -- jobs run with --pull=never, so the worker never fetches it`,
 			...(!localUsed && jobImage === "pi-job:latest"
 				? {
 						fixAction: {
@@ -5920,6 +7963,10 @@ export async function podmanChecks(env, seams, { jobImage, jobImageNote = "" })
 	let proxyRunning = null;
 	// Issue #458: why `--live` must not tear a network down under the proxy here, or null where nothing stops it.
 	let keeperBlocked = null;
+	// Issue #503: the declared model endpoints `--live` probes on this venue, `[]` for none; and whether the rules the
+	// proxy runs include their file (only the shipped proxy's account copy is read; another proxy must include it).
+	let endpoints = [];
+	let endpointRulesInclude = true;
 	if (armed !== false) {
 		// `.State.Status` (issue #453): only `running` carries traffic; Podman reports paused and between-restarts states
 		// with their own words (measured on 4.9.3 and 5.8.1).
@@ -5952,7 +7999,7 @@ export async function podmanChecks(env, seams, { jobImage, jobImageNote = "" })
 		// an image copies its layers (27 to 32 s measured), and `--live` is where this venue already starts containers
 		// built like a job's.
 		if (proxyRunning && seams.live !== true) {
-			checks.push({ ok: false, warn: true, label: "podman: the egress allowlist is read back by `pi-dispatch doctor --live` on this venue, not by this run", fix: "run `pi-dispatch doctor --live`: its egress canary runs two containers built like a podman job's (the job user, --userns=keep-id, the venue's pinned flags) on a job-shaped --internal network under this account's Podman, one that must reach the provider through the proxy and one that must not reach an unlisted host" });
+			checks.push({ ok: false, warn: true, label: "podman: the egress allowlist is read back by `pi-dispatch doctor --live` on this venue, not by this run", fix: "run `pi-dispatch doctor --live`: its egress canary runs three containers built like a podman job's (the job user, --userns=keep-id, the venue's pinned flags) on a job-shaped --internal network under this account's Podman, one that must reach the provider through the proxy, one that must not reach an unlisted host, and one that must not get plain HTTP through to a listed host off port 80" });
 		}
 		// Issue #484: the account-owned copy of the rules the shipped unit mounts, against the installed package's. `service
 		// install` compares it on every run and replaces a differing one only under --force, and `up` installs nothing
@@ -5966,6 +8013,40 @@ export async function podmanChecks(env, seams, { jobImage, jobImageNote = "" })
 				refresh: "`pi-dispatch service install` lists it among what differs and `pi-dispatch service install --force` replaces it and restarts the proxy (squid reads its rules only at start); --force also replaces every other item that list names",
 			});
 			if (stale) checks.push(stale);
+			// Issue #503: endpoints declared while the account copy predates the include, said as docker's venue says it.
+			let rulesInclude = false;
+			try {
+				rulesInclude = rulesIncludeEndpoints(String((seams.readProxyConf ?? ((p) => readFileSync(p, "utf8")))(proxyConfCopyPath(home))));
+			} catch {
+				// No copy yet: `service install` writes the current rules, include and all.
+				rulesInclude = true;
+			}
+			const declared = (seams.includeNeeds ? seams.includeNeeds({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform }).endpointsDeclared : endpointsDeclaredIn({ env, cwd: seams.cwd, fs: { readFileSync, existsSync }, platform: seams.platform ?? process.platform }));
+			if (declared && !rulesInclude) checks.push({ ok: false, warn: true, label: `podman: ${rulesPredateEndpointsLine("podman")}`, fix: "a reload changes nothing here: the rules themselves must include the file, and `service install --force` writes them with the unit that mounts it" });
+			endpointRulesInclude = rulesInclude;
+		}
+		// Issue #503: the declared model endpoints on this venue, as docker's section reads them. The route rows and the
+		// include read here; the three probes per endpoint run with `--live`, beside the canary they share a network with.
+		// None declared, or rules that predate the include (the line above says it all), is nothing more.
+		const { declaredEndpoints = ({ env: e, cwd, platform: p }) => declaredEndpointsIn({ env: e, cwd, fs: { readFileSync, existsSync }, platform: p }), hostAddresses = () => lanIPv4Addresses(networkInterfaces()) } = seams;
+		const declaredList = declaredEndpoints({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform });
+		if (declaredList.length > 0 && endpointRulesInclude) {
+			endpoints = declaredList;
+			// The helper as Podman 5 names it in `podman info` (`rootlessNetworkCmd`), else as this account's running rootless
+			// network shows it (`observeRootlessNetns`, the record or the 4.x argv the worker's widening check reads), else
+			// not known, which the route row says as such.
+			const helper = info?.rootless === true ? (info.rootlessNetworkCmd ?? runningNetnsHelper({ fs: observationFs, euid: ids.euid, runRoot: info.runRoot })) : null;
+			const runtime = info ? { backend: "podman", version: info.version ?? "", ...(typeof info.rootless === "boolean" ? { rootless: info.rootless } : {}), ...(helper ? { helper } : {}) } : null;
+			const addresses = hostAddresses();
+			checks.push(...endpointRouteChecks({ runtime: runtime && addresses ? { ...runtime, hostAddresses: addresses } : runtime, endpoints, prefix: "podman: ", proof: seams.live === true ? "The endpoint probes in this --live run are the proof." : "`pi-dispatch doctor --live` probes it, which is the proof." }));
+			if (proxyRunning) {
+				const inside = await runCmdCapture(spawn, "podman", ["exec", proxy, "cat", ENDPOINTS_INCLUDE_IN_PROXY], { stdoutOnly: true, timeoutMs: CANARY_STEP_TIMEOUT_MS });
+				// The file the proxy actually mounts there, from its own inspect (the Quadlet unit mounts the deployment folder's,
+				// which need not be the folder doctor runs in). Podman gives the source as a plain host path (4.9.3, 5.8.1).
+				const mounts = await runCmdCapture(spawn, "podman", ["inspect", "--format", "{{json .Mounts}}", proxy], { stdoutOnly: true, timeoutMs: CANARY_STEP_TIMEOUT_MS });
+				const mounted = mounts.code === 0 ? readIncludeBindSource(mountsFromJson(mounts.output)) : null;
+				checks.push(endpointsIncludeCheck({ answer: inside, endpoints, bin: "podman", proxy, prefix: "podman: ", mounted, recreate: proxy === DEFAULT_EGRESS_PROXY ? "`systemctl --user restart pi-dispatch-egress-proxy.service` starts a new container on the file (a restart cuts running jobs' tunnels)" : `recreate ${proxy} so it mounts the file anew` }));
+			}
 		}
 		const keeper = await netnsKeeperCheck(spawn, info?.version, { proxy, now: typeof seams.wallClock === "function" ? seams.wallClock : Date.now });
 		keeperBlocked = keeper.keeperBlocked ?? null;
@@ -5974,7 +8055,7 @@ export async function podmanChecks(env, seams, { jobImage, jobImageNote = "" })
 		if (keeperNetwork) checks.push(keeperNetwork);
 	}
 
-	forLive = { run: true, user, relabel, info, imagePresent, egress: { armed, proxy, proxyRunning, keeperBlocked } };
+	forLive = { run: true, user, relabel, info, imagePresent, egress: { armed, proxy, proxyRunning, keeperBlocked, endpoints } };
 	return { checks, observed, relabel, imagesReadable, imageDigest, forLive };
 }
 
@@ -6473,8 +8554,12 @@ async function podmanEgressCanary({ podman, readInfo, run, image, pid, isAlive,
 	if (podman.egress.proxyRunning !== true || podman.imagePresent !== true) return { checks, results: [] };
 	// Announced, as `runLiveProbes` announces its own containers: these start before it, and a cold first keep-id start
 	// can take half a minute each, which is a long silence on an operator's terminal.
-	announce(`starting ${CANARY_PROBE_SLUGS.map((slug) => egressCanaryProbe(slug, pid)).join(" and ")} from ${image} (as the job user ${podman.user}) on the --internal network ${egressCanaryNetwork(pid)}, with ${podman.egress.proxy} attached, to read the egress allowlist back; both are removed when the canary ends`);
-	const canary = await runEgressCanary({ run, bin: "podman", proxy: podman.egress.proxy, image, pid, user: podman.user, gate });
+	const probes = CANARY_PROBE_SLUGS.map((slug) => egressCanaryProbe(slug, pid));
+	// Issue #503: three more per declared model endpoint, said in a second sentence so the canary's own stays as it was.
+	const endpoints = podman.egress.endpoints ?? [];
+	const more = endpoints.length > 0 ? `; then three per declared model endpoint (${endpointsById(endpoints).map((e) => e.id).join(", ")}), named ${EGRESS_ENDPOINT_PROBE_PREFIX}<probe>-<id>-${pid}, removed the same way` : "";
+	announce(`starting ${probes.slice(0, -1).join(", ")} and ${probes.at(-1)} from ${image} (as the job user ${podman.user}) on the --internal network ${egressCanaryNetwork(pid)}, with ${podman.egress.proxy} attached, to read the egress allowlist back; all three are removed when the canary ends${more}`);
+	const canary = await runEgressCanary({ run, bin: "podman", proxy: podman.egress.proxy, image, pid, user: podman.user, gate, endpoints });
 	return { checks: [...checks, ...canary.checks], results: canary.results };
 }