@edgehero/pi-dispatch 2.0.0 → 3.0.0

package/src/start.mjs

@@ -11,6 +11,7 @@ import { makeGitHubAuth } from "./get-token.mjs";
 import { InfraRetry, NETNS_KEEPER_CRASH_LOOP, NETNS_KEEPER_NOT_HOLDING } from "./processor.mjs";
 import { transientError } from "./transient.mjs";
 import { makeGitHubHost } from "./github-host.mjs";
+import { githubFailureFields } from "./octokit-log.mjs";
 import { makeGitLabAuth } from "./gitlab-auth.mjs";
 import { makeGitLabHost } from "./gitlab-host.mjs";
 import { makeForgejoAuth } from "./forgejo-auth.mjs";
@@ -18,14 +19,18 @@ import { makeForgejoHost } from "./forgejo-host.mjs";
 import { makeAzureAuth } from "./azure-auth.mjs";
 import { makeAzureHost } from "./azure-host.mjs";
 import { makeEgressPreflight } from "./egress.mjs";
-import { checkSlotKey, makeFleetLease, makeScopeClaimSweeper, scopeSlotKey } from "./fleet-lease.mjs";
+import { checkSlotKey, endpointSlotKey, hash16, makeClaimSweeper, makeFleetLease, makeScopeClaimSweeper, scopeSlotKey } from "./fleet-lease.mjs";
+import { MAX_SLOTS, loadModelEndpoints, modelEndpointsPath, readOverlayModels } from "./model-endpoints.mjs";
+import { builtinModel, checkModelsKnown } from "./model-catalog.mjs";
 import { capabilityTokens, serializeCaps } from "./capabilities.mjs";
 import { cronFingerprint } from "./fingerprint.mjs";
 import { makeHostRegistry } from "./host-registry.mjs";
 import { makeImagePreflight } from "./image-preflight.mjs";
-import { createWorker, JOB_TIMEOUT_MS } from "./index.mjs";
+import { createWorker, JOB_TIMEOUT_MS, STALLED_FAILED_REASON } from "./index.mjs";
 import { BOOT_REFUSING_JOB_USER_CAUSES, DAEMON_FACTS_TIMEOUT_MS, jobUserRefusal, makeDaemonFactsReader, makeJobUserResolver, relabelsPrivateMounts, resolveImageUser } from "./job-user.mjs";
 import { makeCollectChain } from "./outbox.mjs";
+import { makeCollectPlan } from "./outbox-plan.mjs";
+import { makePortfolioSnapshot } from "./portfolio-snapshot.mjs";
 import { containerPackagePaths, readStageManifest } from "./packages.mjs";
 import { makeCleanup, makeForgePreparers, makePrepareWorkspace } from "./prepare.mjs";
 import { listRunningSandboxes, makeSandboxNetworkSweeper, makeSandboxRuntimeWatch } from "./sandbox.mjs";
@@ -33,10 +38,14 @@ import { makeRetentionSweep } from "./retention-sweep.mjs";
 import { makeSandboxReaper } from "./sandbox-store.mjs";
 import { makeSessionStore } from "./session-store.mjs";
 import { scrubCredentials } from "./redact.mjs";
-import { makeCheckOnceSpent, makeCheckWaitSkew, makeDisarmOnce } from "./triggers-file.mjs";
+import { makeCheckOnceSpent, makeCheckPortfolioFlag, makeCheckWaitSkew, makeDisarmOnce } from "./triggers-file.mjs";
 import { WATCH_DEBOUNCE_MS, changedWhileArming, makeWatchCloser, readBeforeArming } from "./watch-closer.mjs";
 import { loadPauseWindows, pauseUntilMs } from "./pause-windows.mjs";
-import { loadScopedLimits, scopeKeyPrefix } from "./scoped-limits.mjs";
+import { checkProjectRows, danglingProjectRows, dollarRowsWithoutCap, loadScopedLimits, scopeClaimRows } from "./scoped-limits.mjs";
+import { escapeControls, loadProjects, projectOf, projectsFingerprint } from "./projects.mjs";
+import { envelopeDigest, envelopeInsideJobPaths, loadEnvelopeChecked } from "./envelope.mjs";
+import { NO_ENVELOPE_FINGERPRINT, makeAllocationAudit, makeAllocationLogReaper, makeAllocationState } from "./allocation.mjs";
+import { optionalUsdMicros } from "./money.mjs";
 import { makeOnFailure } from "./on-failure.mjs";
 import { makeWaitChecker } from "./wait-check.mjs";
 import { makeWaitState } from "./wait-state.mjs";
@@ -44,17 +53,18 @@ import { hostQueueName, makeQueue } from "./queue.mjs";
 import { endpointShown, makeDockerEndpointResolver, makeLocalBackend, makeReaper, makeStopContainer, quotedShown } from "./backend-local.mjs";
 import { NETNS_KEEPER_MIN_AGE_MS, NETNS_KEEPER_YOUNG_MARGIN_MS, runtimeFromFacts } from "./netns-keeper.mjs";
 import { makeBackendRegistry, reapAll, resolveBackendName } from "./backend-registry.mjs";
-import { DEFAULT_BACKEND, DOCKER_ENDPOINT_LOCAL, PODMAN_ADDS_NO_MOUNTS, PODMAN_BACKEND, PODMAN_BOUNDS_DELEGATED, PODMAN_SERVICE_LOCAL, backendFor, observationRefusalIsTransient, observationRefusals, unobservedFloor } from "./backends.mjs";
+import { DEFAULT_BACKEND, DOCKER_ENDPOINT_LOCAL, PODMAN_ADDS_NO_MOUNTS, PODMAN_BACKEND, PODMAN_BOUNDS_DELEGATED, PODMAN_SERVICE_LOCAL, backendFor, isPerMachineHost, observationRefusalIsTransient, observationRefusals, unobservedFloor } from "./backends.mjs";
 import { PODMAN_BOOT_REFUSING_CAUSES, PODMAN_INFO_TIMEOUT_MS, cachedPodmanInfo, decidePodmanJobUser, makePodmanBackend, makePodmanInfoReader, makePodmanReaper, observePodman, podmanConfRefusal, unavailableFor, podmanConfWidening, podmanJobUserRefusal, resolvePodmanImageUser } from "./backend-podman.mjs";
 import { PODMAN_RESTART_HOLD_EXPIRED, makePodmanServiceReader, onceFs, makeRootfulMemory, observeHost, observeRootfulConf, readRootfulService, rootfulConfRefusal, rootfulConfRetries, rootfulUnreadList, runtimeObservationKey } from "./runtime-observations.mjs";
 
 import { makeRunContainer } from "./run-container.mjs";
 import { resolveProviderCredential } from "./env-allowlist.mjs";
 import { makeSecretsResolver } from "./secrets.mjs";
-import { buildRecord, makeFindPreviousRun, makeLogReaper, makeLogSink, makeRecordWriter, RUNNER_POLICY_REASONS, sanitizeJobId } from "./run-history.mjs";
-import { makeRunMirror } from "./run-mirror.mjs";
-import { effectiveSettings, readOverlay } from "./runtime-settings.mjs";
-import { authoredCron, loadSchedules, servedSchedules } from "./schedules.mjs";
+import { buildRecord, makeFindPreviousRun, makeLogReaper, makeLogSink, makeReadRecord, makeRecordWriter, makeSettledRecord, RUNNER_POLICY_REASONS, sanitizeJobId } from "./run-history.mjs";
+import { makeRunMirror, readMirroredRecord } from "./run-mirror.mjs";
+import { readOverlay, resolveSettings } from "./runtime-settings.mjs";
+import { usdFingerprint } from "./dollar-fingerprint.mjs";
+import { authoredCron, envelopeJobPaths, loadSchedules, servedSchedules } from "./schedules.mjs";
 import { makeStallGuard } from "./scheduler-stall-guard.mjs";
 
 
@@ -164,7 +174,7 @@ export async function settleWithin(promise, ms, fallback) {
  * schedulers. The FSWatcher is unref'd (the debounce it arms is NOT), and the returned closer is what
  * `startWorker` registers so the watch dies with the worker that armed it (issue #295).
  */
-function watchTriggersFile(config, queue, log, ref, registry, tz, fleet, atBoot) {
+function watchTriggersFile(config, queue, log, ref, registry, tz, fleet, atBoot, afterReload = () => {}) {
 	const path = config.triggersFile;
 	const dir = dirname(path) || ".";
 	const file = basename(path);
@@ -180,7 +190,9 @@ function watchTriggersFile(config, queue, log, ref, registry, tz, fleet, atBoot)
 			if (handles.closed) return; // see makeWatchCloser: by construction, not by a delivery rule
 			if (changed && changed !== file) return; // only our file (a null name -> reload to be safe)
 			clearTimeout(handles.timer);
-			handles.timer = setTimeout(() => void reloadSchedules(config, queue, { log: closer.reloadLog, ref, registry, tz, fleet }), WATCH_DEBOUNCE_MS);
+			// Issue #504 part B: a cron folder or a skills dir an edit adds is a new job path, so the envelope's place is
+			// judged again after every triggers reload.
+			handles.timer = setTimeout(() => void reloadSchedules(config, queue, { log: closer.reloadLog, ref, registry, tz, fleet }).then(() => afterReload(closer.reloadLog)), WATCH_DEBOUNCE_MS);
 		});
 		handles.watcher.unref?.();
 		log("triggers_watching", { path });
@@ -192,7 +204,7 @@ function watchTriggersFile(config, queue, log, ref, registry, tz, fleet, atBoot)
 	// changed.
 	if (changedWhileArming(handles, readFile)) {
 		log("triggers_reread_after_arming", { path });
-		void reloadSchedules(config, queue, { log: closer.reloadLog, ref, registry, tz, fleet });
+		void reloadSchedules(config, queue, { log: closer.reloadLog, ref, registry, tz, fleet }).then(() => afterReload(closer.reloadLog));
 	}
 	return closer;
 }
@@ -246,13 +258,74 @@ function watchPauseWindowsFile(config, ref, log, atBoot) {
  * last-good property carries its own test). A bad edit keeps `ref.current` untouched and logs
  * `scoped_limits_reload_invalid` -- the pause-windows posture, INT-SCOPED-LIMITS-FILE-CONTRACT.
  */
-export function reloadScopedLimits(config, ref, log) {
+export function reloadScopedLimits(config, ref, log, deploymentCap = null, pair = null) {
 	try {
-		ref.current = loadScopedLimits(config);
+		const next = loadScopedLimits(config);
+		// Issue #499 part B: the new limits are checked against projects.json (`pair`, null only on a bare test wiring);
+		// a row naming a missing project keeps the last good limits, the boot rule held live.
+		const other = pair ? pairWith(config, next, pair, "limits") : null;
+		ref.current = next;
 		log("scoped_limits_reloaded", { count: ref.current.length });
+		if (deploymentCap) warnDollarRowsWithoutCap(ref.current, deploymentCap(), log);
+		if (other) {
+			pair.projects.current = other;
+			log("projects_reloaded", { count: other.length, with: "scoped-limits" });
+		}
 	} catch (err) {
 		log("scoped_limits_reload_invalid", { reason: err?.message });
+		return;
+	}
+	// Issue #504 part B: the envelope's floors are judged against both files, so a committed edit re-judges it.
+	pair?.afterCommit?.();
+}
+
+/**
+ * The two files a project row joins (issue #499 part B): scoped-limits.json names `project:<id>`, projects.json defines
+ * the id. `{ limits, projects }` are the two live refs, and `deploymentCap` the merged per-job cap thunk the
+ * dollar-rows-without-cap warning reads (null on a bare wiring). A reload of either file is judged as a PAIR (`pairWith`), so the
+ * two live lists never disagree and a correct pair applies whatever order its files were saved in.
+ */
+export function makeProjectPair(limits, projects, deploymentCap = null) {
+	return { limits, projects, deploymentCap };
+}
+
+/**
+ * Judge one side's new list (`next`, already loaded) against the other side, statelessly (issue #499 part B):
+ *   1. against the other file AS IT IS ON DISK: when that loads and the two agree, both are taken together, and the
+ *      other side's list is returned for the caller to commit too (only when it differs from the live one). This is
+ *      what makes a rename (`shop` to `store` in both files) or a project added with its row apply in EITHER save
+ *      order: the second save sees the first file already on disk.
+ *   2. else against the other side's LIVE list: when they agree, this side alone is taken (null returned). This is the
+ *      path when the other file is mid-edit and does not load.
+ *   3. else a `configError` naming the row, its index and both files, so the caller keeps its last good list.
+ */
+function pairWith(config, next, pair, side) {
+	const limitsSide = side === "limits";
+	let disk = null;
+	try {
+		disk = limitsSide ? loadProjects(config) : loadScopedLimits(config);
+	} catch {
+		// The other file does not load right now: its own watcher says so. Judge against its live list alone.
 	}
+	const agree = (limits, projects) => danglingProjectRows(limits, projects).length === 0;
+	if (disk !== null && (limitsSide ? agree(next, disk) : agree(disk, next))) {
+		const live = limitsSide ? pair.projects.current : pair.limits.current;
+		return JSON.stringify(disk) === JSON.stringify(live) ? null : disk;
+	}
+	const liveOther = limitsSide ? pair.projects.current : pair.limits.current;
+	if (limitsSide) checkProjectRows(next, liveOther, config.scopedLimitsFile, config.projectsFile ?? null);
+	else checkProjectRows(liveOther, next, config.scopedLimitsFile, config.projectsFile ?? null);
+	return null;
+}
+
+/**
+ * PR #549's review: a `scoped-limits.json` dollar row on a deployment with no per-job cap (env and overlay merged)
+ * refuses every job it applies to as `config-refused`, unless that job's trigger sets `run.maxCostUsd`. So it is a
+ * WARNING at load and at each reload, never a refusal: the rows by index and kind, never a scope string.
+ */
+export function warnDollarRowsWithoutCap(limits, deploymentMaxCostUsd, log) {
+	const rows = dollarRowsWithoutCap(limits, deploymentMaxCostUsd);
+	if (rows.length > 0) log("scoped_limits_dollar_rows_without_cap", { rows });
 }
 
 /**
@@ -260,7 +333,7 @@ export function reloadScopedLimits(config, ref, log) {
  * for atomic tmp+rename robustness, filtered to the one basename, debounced. Best-effort; the FSWatcher is
  * unref'd and the returned closer stops the watch with the worker (issue #295).
  */
-function watchScopedLimitsFile(config, ref, log, atBoot) {
+function watchScopedLimitsFile(config, ref, log, atBoot, deploymentCap = null, pair = null) {
 	const path = config.scopedLimitsFile;
 	const dir = dirname(path) || ".";
 	const file = basename(path);
@@ -273,7 +346,7 @@ function watchScopedLimitsFile(config, ref, log, atBoot) {
 			if (handles.closed) return; // see makeWatchCloser: by construction, not by a delivery rule
 			if (changed && changed !== file) return;
 			clearTimeout(handles.timer);
-			handles.timer = setTimeout(() => reloadScopedLimits(config, ref, closer.reloadLog), WATCH_DEBOUNCE_MS);
+			handles.timer = setTimeout(() => reloadScopedLimits(config, ref, closer.reloadLog, deploymentCap, pair), WATCH_DEBOUNCE_MS);
 		});
 		handles.watcher.unref?.();
 		log("scoped_limits_watching", { path });
@@ -282,7 +355,188 @@ function watchScopedLimitsFile(config, ref, log, atBoot) {
 	}
 	if (changedWhileArming(handles, readFile)) {
 		log("scoped_limits_reread_after_arming", { path });
-		reloadScopedLimits(config, ref, closer.reloadLog);
+		reloadScopedLimits(config, ref, closer.reloadLog, deploymentCap, pair);
+	}
+	return closer;
+}
+
+/**
+ * The projects reload (issue #499), exported apart from its watcher for `reloadScopedLimits`' reason: last-good is
+ * testable without fs.watch. A bad edit keeps `ref.current` and logs `projects_reload_invalid`; a good one swaps it,
+ * so the next pickup resolves against the new membership. A job already past its pickup keeps the id it was given.
+ * The reason is the loader's message, which never quotes a project's `name` (projects.mjs).
+ */
+export function reloadProjects(config, ref, log, pair = null) {
+	try {
+		const next = loadProjects(config);
+		// Issue #499 part B: an edit that drops (or renames) a project a scoped-limits row still names is kept out, and the
+		// last good projects stay, unless scoped-limits.json on disk already agrees with it (`pairWith`).
+		const other = pair ? pairWith(config, next, pair, "projects") : null;
+		ref.current = next;
+		log("projects_reloaded", { count: ref.current.length });
+		if (other) {
+			pair.limits.current = other;
+			log("scoped_limits_reloaded", { count: other.length, with: "projects" });
+			// Every limits list that goes live is warned on, whichever file's reload committed it.
+			if (pair.deploymentCap) warnDollarRowsWithoutCap(other, pair.deploymentCap(), log);
+		}
+	} catch (err) {
+		// Escaped (PR #569's review): the parser's own refusals already are, and an fs error quoting the path is too.
+		log("projects_reload_invalid", { reason: escapeControls(err?.message) });
+		return;
+	}
+	// Issue #504 part B: as `reloadScopedLimits` does, so the envelope follows a projects edit in either save order.
+	pair?.afterCommit?.();
+}
+
+/**
+ * Watch the projects file (issue #499) as the scoped-limits watcher does: the directory, filtered to the one basename,
+ * debounced, the boot read as the arming baseline. The closer joins `extraClosers`, so the watch stops with the worker
+ * (DES-WATCHERS-CLOSE-WITH-THE-WORKER).
+ */
+function watchProjectsFile(config, ref, log, atBoot, pair = null) {
+	const path = config.projectsFile;
+	const dir = dirname(path) || ".";
+	const file = basename(path);
+	const handles = { watcher: null, timer: null, closed: false };
+	const closer = makeWatchCloser(handles, log);
+	const readFile = () => readFileSync(path, "utf8");
+	readBeforeArming(handles, readFile, atBoot);
+	try {
+		handles.watcher = watch(dir, (_event, changed) => {
+			if (handles.closed) return;
+			if (changed && changed !== file) return;
+			clearTimeout(handles.timer);
+			handles.timer = setTimeout(() => reloadProjects(config, ref, closer.reloadLog, pair), WATCH_DEBOUNCE_MS);
+		});
+		handles.watcher.unref?.();
+		log("projects_watching", { path });
+	} catch (err) {
+		log("projects_watch_unavailable", { reason: err?.message });
+	}
+	if (changedWhileArming(handles, readFile)) {
+		log("projects_reread_after_arming", { path });
+		reloadProjects(config, ref, closer.reloadLog, pair);
+	}
+	return closer;
+}
+
+/**
+ * `envelopeJobPaths` as a thunk that keeps its last good answer (issue #504 part B): a triggers file caught mid-edit
+ * must not turn a containment check into a failure of its own, and the last parse that succeeded is what the running
+ * schedulers were built from. The first call has no last good answer and throws, which at boot refuses.
+ */
+export function makeEnvelopeJobPaths(config, io = {}) {
+	let lastGood = null;
+	return () => {
+		try {
+			lastGood = envelopeJobPaths(config, io);
+		} catch (err) {
+			if (lastGood === null) throw err;
+		}
+		return lastGood;
+	};
+}
+
+/**
+ * The envelope reload (issue #504 part B), exported apart from its watcher for `reloadScopedLimits`' reason. `ref` is
+ * `{ current, digest }`. The file is judged against the LIVE projects and scoped limits (its floors name projects and
+ * sit under project rows) and the job paths of the moment, so a reload is paired with both files: their own reloads
+ * call this again once they commit (`pair.afterCommit`), and an envelope edit that needs a projects edit applies in
+ * either save order. A bad edit, or one that puts the file inside a job path, keeps the last good envelope and logs
+ * `envelope_reload_invalid`; the last good copy can never be one a job wrote, because every reload re-runs the
+ * containment check. A changed digest logs `envelope_reloaded` and calls `onChange` (the re-base, or the mismatch).
+ */
+export function reloadEnvelope(config, ref, log, { projects, limits, maxCostMicros = () => null, jobPaths, onChange = () => {} }) {
+	let next;
+	try {
+		next = loadEnvelopeChecked(config, { projects: projects?.current ?? [], limits: limits?.current ?? [], maxCostMicros: maxCostMicros(), jobPaths: jobPaths() });
+	} catch (err) {
+		log("envelope_reload_invalid", { reason: escapeControls(err?.message) });
+		return;
+	}
+	const digest = next === null ? null : envelopeDigest(next);
+	const changed = digest !== ref.digest;
+	ref.current = next;
+	ref.digest = digest;
+	if (!changed) return;
+	log("envelope_reloaded", { digest });
+	onChange();
+}
+
+/**
+ * Watch the envelope file (issue #504 part B) as the projects watcher does: the directory, filtered to the one
+ * basename, debounced, the boot read as the arming baseline, the closer joining `extraClosers`.
+ */
+function watchEnvelopeFile(config, ref, log, atBoot, ctx) {
+	const path = config.envelopeFile;
+	const dir = dirname(path) || ".";
+	const file = basename(path);
+	const handles = { watcher: null, timer: null, closed: false };
+	const closer = makeWatchCloser(handles, log);
+	const readFile = () => readFileSync(path, "utf8");
+	readBeforeArming(handles, readFile, atBoot);
+	try {
+		handles.watcher = watch(dir, (_event, changed) => {
+			if (handles.closed) return;
+			if (changed && changed !== file) return;
+			clearTimeout(handles.timer);
+			handles.timer = setTimeout(() => reloadEnvelope(config, ref, closer.reloadLog, ctx), WATCH_DEBOUNCE_MS);
+		});
+		handles.watcher.unref?.();
+		log("envelope_watching", { path });
+	} catch (err) {
+		log("envelope_watch_unavailable", { reason: err?.message });
+	}
+	if (changedWhileArming(handles, readFile)) {
+		log("envelope_reread_after_arming", { path });
+		reloadEnvelope(config, ref, closer.reloadLog, ctx);
+	}
+	return closer;
+}
+
+/**
+ * The model-endpoints reload (issue #503), exported apart from its watcher for `reloadScopedLimits`' reason: the
+ * last-good property is testable without fs.watch. A bad edit keeps `ref.current` and logs
+ * `model_endpoints_reload_invalid`; a good one swaps it, so a `slots` edit applies to the next pickup.
+ */
+export function reloadModelEndpoints(config, ref, log) {
+	try {
+		ref.current = loadModelEndpoints(config);
+		log("model_endpoints_reloaded", { count: ref.current.length });
+	} catch (err) {
+		log("model_endpoints_reload_invalid", { reason: err?.message });
+	}
+}
+
+/**
+ * Watch the model-endpoints file (issue #503) as the scoped-limits watcher does. Armed only when the file is named
+ * or exists at boot: the default path is the deployment folder, and a worker started elsewhere must not watch an
+ * arbitrary directory for a file nobody declared. A default file created later is read at the next restart.
+ */
+function watchModelEndpointsFile(config, ref, log, atBoot) {
+	const { path } = modelEndpointsPath(config);
+	const dir = dirname(path) || ".";
+	const file = basename(path);
+	const handles = { watcher: null, timer: null, closed: false };
+	const closer = makeWatchCloser(handles, log);
+	const readFile = () => readFileSync(path, "utf8");
+	readBeforeArming(handles, readFile, atBoot);
+	try {
+		handles.watcher = watch(dir, (_event, changed) => {
+			if (handles.closed) return;
+			if (changed && changed !== file) return;
+			clearTimeout(handles.timer);
+			handles.timer = setTimeout(() => reloadModelEndpoints(config, ref, closer.reloadLog), WATCH_DEBOUNCE_MS);
+		});
+		handles.watcher.unref?.();
+		log("model_endpoints_watching", { path });
+	} catch (err) {
+		log("model_endpoints_watch_unavailable", { reason: err?.message });
+	}
+	if (changedWhileArming(handles, readFile)) {
+		log("model_endpoints_reread_after_arming", { path });
+		reloadModelEndpoints(config, ref, closer.reloadLog);
 	}
 	return closer;
 }
@@ -330,6 +584,8 @@ export async function startWorker(
 		makeLogSink: makeLogSinkFn = makeLogSink,
 		makeRecordWriter: makeRecordWriterFn = makeRecordWriter,
 		makeRunMirror: makeRunMirrorFn = makeRunMirror,
+		// The fleet copy's by-id read, seamed so a wiring test can answer it without a live mirror.
+		readMirroredRecord: readMirroredRecordFn = readMirroredRecord,
 		makeLogReaper: makeLogReaperFn = makeLogReaper,
 		makeSandboxReaper: makeSandboxReaperFn = makeSandboxReaper,
 		makeSandboxNetworkSweeper: makeSandboxNetworkSweeperFn = makeSandboxNetworkSweeper,
@@ -341,6 +597,7 @@ export async function startWorker(
 		makeSecretsResolver: makeSecretsResolverFn = makeSecretsResolver,
 		makeImagePreflight: makeImagePreflightFn = makeImagePreflight,
 		makeScopeClaimSweeper: makeScopeClaimSweeperFn = makeScopeClaimSweeper,
+		makeClaimSweeper: makeClaimSweeperFn = makeClaimSweeper,
 		makeHostRegistry: makeHostRegistryFn = makeHostRegistry,
 		makeEgressPreflight: makeEgressPreflightFn = makeEgressPreflight,
 		// Which docker endpoint this host's CLI resolves (issue #278). A seam because the real one spawns the
@@ -391,6 +648,13 @@ export async function startWorker(
 		// literal address every Valkey client of this worker then connects to. A seam: the real one reads /proc, probes
 		// this host's addresses and resolves the name, none of which belongs in a wiring test.
 		judgeValkey = defaultJudgeValkey,
+		// The scoped-limits watcher, injectable so a test can see what it is armed with (PR #549's review: the cap
+		// thunk the reload warning reads). Production passes nothing and gets the real watcher.
+		watchScopedLimits: watchScopedLimitsFn = watchScopedLimitsFile,
+		// The projects watcher (issue #499), injectable for the same reason: a test sees it armed and closed.
+		watchProjects: watchProjectsFn = watchProjectsFile,
+		// The envelope watcher (issue #504 part B), injectable for the same reason.
+		watchEnvelope: watchEnvelopeFn = watchEnvelopeFile,
 	} = {},
 ) {
 	const config = loadConfigFn(env);
@@ -463,7 +727,7 @@ export async function startWorker(
 	// this race lives in is between these lines and the arming a thousand lines below -- the endpoint probe,
 	// forge auth, the reaper, Valkey -- not the microseconds around the arming itself, which is what a first
 	// attempt measured. `null` where a file is not configured, which reads as "nothing to compare".
-	const atBoot = { triggers: null, pauseWindows: null, scopedLimits: null };
+	const atBoot = { triggers: null, pauseWindows: null, scopedLimits: null, projects: null, modelEndpoints: null, envelope: null };
 	const recording = (into, path) => ({
 		readFileSync: (file, enc) => {
 			const text = readFileSync(file, enc);
@@ -482,6 +746,55 @@ export async function startWorker(
 	// ref for the live-reload watcher, [] when unset (the folder mutex is code and needs no file).
 	const scopedLimits = { current: loadScopedLimits(config, recording("scopedLimits", config.scopedLimitsFile)) };
 
+	// Issue #499: the projects file, same posture (INT-PROJECTS-FILE-CONTRACT): a bad file refuses boot with the operator
+	// present, a mutable ref for the live reload, [] when unset. The pickup gate reads it once per pickup, beside the
+	// limits snapshot, and the id it resolves there is the one the job's record carries.
+	const projects = { current: loadProjects(config, recording("projects", config.projectsFile)) };
+	// Issue #499 part B: a `project:<id>` row whose id is not a project refuses BOOT, naming the row and the id: it would
+	// read as a cap on a group that no job can belong to. The live reloads of either file hold the same rule (`pair`).
+	checkProjectRows(scopedLimits.current, projects.current, config.scopedLimitsFile, config.projectsFile ?? null);
+
+	// Issue #504 part B: the allocation envelope (INT-ENVELOPE-FILE-CONTRACT), same posture: a bad file refuses boot with
+	// the operator present, before any Valkey contact. It is judged against the projects and scoped limits just loaded
+	// (its floors name projects and sit under project rows), needs the merged per-job cost cap (each governed job
+	// reserves it against its share), and must lie outside every host path a job container can see, which is checked
+	// with this load and again with every reload. A mutable ref `{ current, digest }`; null when PI_ENVELOPE_FILE is
+	// unset, and then nothing below governs anything.
+	const envelopeCap = () => {
+		try {
+			const s = resolveSettings(config, readOverlay(config.settingsFile));
+			return optionalUsdMicros(s.invalid ? config.maxCostUsd : s.maxCostUsd, "maxCostUsd");
+		} catch {
+			return null;
+		}
+	};
+	const envelopeJobPathsNow = makeEnvelopeJobPaths(config);
+	const envelope = { current: null, digest: null };
+	if (config.envelopeFile !== null && config.envelopeFile !== undefined) {
+		envelope.current = loadEnvelopeChecked(config, { projects: projects.current, limits: scopedLimits.current, maxCostMicros: envelopeCap(), jobPaths: envelopeJobPathsNow() }, { io: recording("envelope", config.envelopeFile) });
+		envelope.digest = envelope.current === null ? null : envelopeDigest(envelope.current);
+		log("envelope_loaded", { digest: envelope.digest, window: envelope.current?.window ?? null, delegation: envelope.current?.delegation?.enabled === true });
+	}
+	// After a triggers reload (a cron folder or a skills dir is a job path): the envelope's place judged again. The live
+	// copy is kept either way, since every envelope reload re-runs the check and so never adopts a file a job could have
+	// written; this line is what tells the operator that a job can now reach the file.
+	const checkEnvelopePlace = (say = log) => {
+		if (!envelope.current) return;
+		try {
+			const inside = envelopeInsideJobPaths(config.envelopeFile, envelopeJobPathsNow());
+			if (inside) say("envelope_inside_job_path", { kind: inside.kind });
+		} catch (err) {
+			say("envelope_inside_job_path", { reason: escapeControls(err?.message) });
+		}
+	};
+
+	// Issue #503: the declared model endpoints, same posture (INT-MODEL-ENDPOINTS-FILE-CONTRACT): a bad file refuses
+	// boot with the operator present, a mutable ref for the live reload, [] when there is no file. Read per pickup
+	// from the ref, so a `slots` edit applies to the next job.
+	const modelEndpointsAt = modelEndpointsPath(config);
+	const modelEndpoints = { current: loadModelEndpoints(config, recording("modelEndpoints", modelEndpointsAt.path)) };
+	const watchModelEndpoints = modelEndpointsAt.explicit || atBoot.modelEndpoints !== null;
+
 	// Issue #278: WHICH DOCKER DAEMON the job containers' credentials will travel to. Asked of the CLI at boot,
 	// AFTER the free file validations above (a wedged CLI costs up to its bound, and must not delay them) and
 	// BEFORE forge auth, the reaper, Valkey and the worker -- so a refusal here stops a process that built
@@ -643,7 +956,9 @@ export async function startWorker(
 	// `doctor` reports as healthy. The boot posture is unchanged for a DETERMINATE failure, which is what
 	// the local-only case is (no `gh` on PATH is `ENOENT`); a TRANSIENT one now leaves a re-resolver
 	// behind instead of a permanent null.
-	const forges = { github: { auth: null, host: makeHost() } };
+	// Issue #530: the GitHub clients take this worker's logger, so a client's own warning is one more JSON line here and
+	// its plain request lines (`GET /user - 401 ...`) are never printed (`octokitLog`).
+	const forges = { github: { auth: null, host: makeHost({ log }) } };
 	// Per forge kind, what it would take to resolve its auth again: the closure, and the `idOf` its log
 	// line needs. Present only while the last attempt failed transiently -- a determinate failure removes
 	// it, because retrying a wrong credential is how a deployment pays to be told the same thing twice.
@@ -670,7 +985,7 @@ export async function startWorker(
 			// modules throw untagged for a fetch rejection, a transient status and an unparseable body.
 			const transient = err?.piDispatchConfig !== true;
 			if (transient) authRetries.set(kind, { resolve: () => make(cfg), idOf });
-			log(`${kind}_auth_unavailable`, { kind, reason: err?.message, transient });
+			log(`${kind}_auth_unavailable`, { kind, reason: err?.message, ...githubFailureFields(err), transient });
 		}
 	};
 
@@ -711,7 +1026,7 @@ export async function startWorker(
 					authLastError.set(kind, err);
 					if (err?.piDispatchConfig === true) {
 						authRetries.delete(kind);
-						log(`${kind}_auth_unavailable`, { kind, reason: err?.message, transient: false });
+						log(`${kind}_auth_unavailable`, { kind, reason: err?.message, ...githubFailureFields(err), transient: false });
 					} else {
 						authCooldownUntil.set(kind, now() + AUTH_RETRY_COOLDOWN_MS);
 					}
@@ -758,7 +1073,7 @@ export async function startWorker(
 		}
 	};
 
-	await attachAuth("github", makeAuth, config.github);
+	await attachAuth("github", (cfg) => makeAuth(cfg, { log }), config.github);
 	// GitLab joins the same map on the same best-effort terms. It appears only when configured: a forge
 	// with no entry refuses its jobs at mint time with a message naming what is missing, which is a better
 	// answer than an entry that exists and cannot authenticate.
@@ -844,6 +1159,10 @@ export async function startWorker(
 	} catch (err) {
 		log("log_reaper_skipped", { reason: scrubCredentials(err?.message) });
 	}
+	// Issue #504 part B: the allocation audit files (`allocations/YYYY-MM.jsonl`) on the same retention, which the log
+	// reaper above never reaches (it reaps the top-level `.log` and `.json` only). Never throws, so no double wrap.
+	const reapAllocationLogs = makeAllocationLogReaper({ logsDir: config.logsDir, retentionDays: config.logRetentionDays, log });
+	reapAllocationLogs();
 
 	// REQ-RESURRECTABLE-SANDBOX: sweep retained per-job directories past their window, so what `cleanup`
 	// kept for re-opening stays bounded. Third in the row and deliberately its own sweep -- a different
@@ -896,6 +1215,22 @@ export async function startWorker(
 	// ioredis printed a stack per reconnect attempt.
 	onValkeyError(redis, "shared client");
 
+	// Issue #504 part B: the applied split lives in Valkey (`alloc:plan`), shared by every host. Only with an envelope.
+	// The boot reconcile seeds the neutral split when there is none, expires a plan past its life and re-bases on an
+	// envelope this host changed while it was down; a fault is logged and the first pickup tries again, because the
+	// pickup reconciles too and refuses nothing it cannot judge (it throws, and the job is retried).
+	// Built on EVERY host, with an envelope or without: a host with none still asks, at each pickup, whether the fleet is
+	// governed (an applied split exists), and refuses its jobs as envelope-mismatch when it is.
+	const allocationState = makeAllocationState({ redis, host: config.workerName, audit: makeAllocationAudit({ logsDir: config.logsDir }), log });
+	const reconcileAllocation = (why) => {
+		if (!envelope.current) return Promise.resolve();
+		return allocationState
+			.reconcile({ envelope: envelope.current, digest: envelope.digest, now: new Date() })
+			.then((r) => log("allocation_reconciled", { why, mismatch: r.mismatch, digest: envelope.digest, applied: r.state?.envelopeDigest ?? null }))
+			.catch((err) => log("allocation_reconcile_failed", { why, reason: scrubCredentials(err?.message) }));
+	};
+	await reconcileAllocation("boot");
+
 	// This host's own stale scope claims, gated on the reaper having having enumerated: the
 	// reaper is what establishes that this machine holds no `pi-job-*` containers, so a claim naming this
 	// host is a claim for a container that no longer exists. Deleting it is not a second source of truth --
@@ -904,10 +1239,20 @@ export async function startWorker(
 	// mechanism, so a fault costs one TTL of a stale claim and never a boot.
 	try {
 		if (config.workerNameDeclared)
-			await makeScopeClaimSweeperFn({ redis, workerName: config.workerName, limits: scopedLimits.current.map((r) => ({ concurrent: r.concurrent, hash: scopeKeyPrefix(r.scope).slice("budget:s:".length) })), log })({ reaped });
+			await makeScopeClaimSweeperFn({ redis, workerName: config.workerName, limits: scopeClaimRows(scopedLimits.current), log })({ reaped });
 	} catch (err) {
 		log("scope_claims_sweep_skipped", { reason: scrubCredentials(err?.message) });
 	}
+	// Issue #503: this host's stale model endpoint claims, on the same precondition and for the same reason (each is a
+	// claim for a container). Every index up to the parse ceiling, not up to today's `slots`: `slots` can be lowered
+	// live, and a claim on an index above the new value is still this host's to clear. A per-machine endpoint (a host
+	// alias name) takes no fleet claim, so it has none to sweep. The sweep stops at its first fault.
+	try {
+		if (config.workerNameDeclared && modelEndpoints.current.length > 0)
+			await makeClaimSweeperFn({ redis, workerName: config.workerName, keyFor: endpointSlotKey, rows: modelEndpoints.current.filter((e) => !isPerMachineHost(e.host)).map((e) => ({ hash: hash16(e.id), count: MAX_SLOTS })), event: "endpoint_claims", log })({ reaped });
+	} catch (err) {
+		log("endpoint_claims_sweep_skipped", { reason: scrubCredentials(err?.message) });
+	}
 
 	// The persistent runtime queue: the stall guard tears schedulers down through it, AND the outbox
 	// collector enqueues chained children onto it -- the same pi-jobs queue, so one handle serves both.
@@ -974,12 +1319,17 @@ export async function startWorker(
 	// would be bytes nothing reads. That is also what keeps a single-host deployment byte-identical, since
 	// no job then issues a single extra Valkey command.
 	const runMirror = config.workerNameDeclared ? makeRunMirrorFn({ redis, retentionDays: config.logRetentionDays, log }) : null;
-	const recordRun = ({ job, result, error, startedAt, endedAt }) => {
+	const recordRun = ({ job, result, error, startedAt, endedAt, project }) => {
+		// The project (issue #499) was resolved at the pickup gate and rides here as `project` (an id or null), so a live
+		// edit of projects.json mid-run cannot make the record disagree with what the job was counted against. A record
+		// path that ends BEFORE the pickup gate (the wait gate's refusals) passes none, and resolves from the live ref
+		// with the same function.
+		const projectId = project !== undefined ? project : projectOf(job?.data ?? {}, projects.current);
 		// The `host` is stamped HERE rather than inside the processor, which is what keeps every one of its
 		// four `recordRun` call sites byte-unchanged and `buildRecord` a pure function of its arguments.
 		// The default venue rides the same way and for the same reason (#277): it is the value the registry
 		// below is built with, so the record resolves a job's venue exactly as dispatch does.
-		const record = buildRecord({ job, result, error, startedAt, endedAt, host: config.workerName, defaultBackend: config.defaultBackend });
+		const record = buildRecord({ job, result, error, startedAt, endedAt, host: config.workerName, defaultBackend: config.defaultBackend, project: projectId });
 		writeRecord(record);
 		// STRICTLY AFTER the file, and deliberately not awaited. After, because a crash between the two must
 		// leave a record with no fleet row rather than a fleet row with no record -- the mirror is a VIEW,
@@ -997,25 +1347,30 @@ export async function startWorker(
 		// the disarm -- the same chosen direction, met at shutdown instead of a crash.
 		void disarmOnce({ job, endedAt });
 	};
+	// The record read back, for a job the queue lost the lock of after it finished (DES-TERMINAL-COMMENTS-AND-FAILURE-HOOK,
+	// CONST-RETRY-INFRA-ONLY): this host's own file first, then the fleet's copy where a mirror is armed, because the
+	// host that meets the stalled job need not be the one that ran it. A single host has no mirror and needs none.
+	const settledRecord = makeSettledRecord({
+		readRecord: makeReadRecord({ logsDir: config.logsDir }),
+		readMirrored: runMirror ? (jobId) => readMirroredRecordFn(redis, sanitizeJobId(jobId)) : null,
+	});
 
 	// INT-CONFIG-OVERLAY-CONTRACT: the worker reads the runtime-settings overlay at EACH job start, so this
-	// closure -- not a value frozen at boot -- is what the processor calls per job. It resolves the eight
+	// closure -- not a value frozen at boot -- is what the processor calls per job. It resolves the fourteen
 	// effective settings from the overlay over env; an invalid overlay returns `{ invalid }` (logged loudly,
 	// key-name-only per no-pii-in-logs) so the processor RETURNS a settings-overlay-invalid refusal instead
 	// of the run.
 	const settingsFile = config.settingsFile;
 	const getSettings = () => {
-		const res = readOverlay(settingsFile, { log });
+		// `resolveSettings` merges overlay over env and then checks the cross-key dollar rule on the MERGED values
+		// (issue #501), so an overlay window with an env per-job cap is valid. `secretProfiles` rides alongside the
+		// effective keys; that function says why.
+		const res = resolveSettings(config, readOverlay(settingsFile, { log }));
 		if (res.invalid) {
 			log("settings_overlay_invalid", { reason: res.invalid, settingsFile });
 			return { invalid: res.invalid };
 		}
-		// REQ-TRIGGER-SECRETS rides ALONGSIDE the ten tunables rather than inside them. `effectiveSettings`
-		// resolves `overlay > env` over a fixed ten-key literal, and its own tests pin that key set and
-		// assert an empty overlay returns the config verbatim -- so an eleventh key there would break both,
-		// and would also claim a precedence this key deliberately does not have (a name declared in both
-		// sources is refused per delivery, not silently won by either).
-		return { ...effectiveSettings(config, res.overlay), secretProfiles: res.overlay?.secretProfiles ?? {} };
+		return res;
 	};
 
 	// Resolve the Worker constructor's slot count once from the overlay: a present overlay may raise or lower
@@ -1023,6 +1378,13 @@ export async function startWorker(
 	// the per-job path enforce the refusal (getSettings already logged the invalid reason).
 	const bootSettings = getSettings();
 	const bootConcurrency = bootSettings.invalid ? config.concurrency : bootSettings.concurrency;
+	// PR #549's review: the merged per-job cap, for the scoped-limits dollar-row warning at boot and at each reload.
+	// An invalid overlay falls back to the env value, the same fallback as the slot count above.
+	const deploymentMaxCostUsd = () => {
+		const s = getSettings();
+		return s.invalid ? config.maxCostUsd : s.maxCostUsd;
+	};
+	warnDollarRowsWithoutCap(scopedLimits.current, bootSettings.invalid ? config.maxCostUsd : bootSettings.maxCostUsd, log);
 
 	// INT-OUTBOX-CONTRACT chain collector: the host-side reader of a completed local parent's /outbox. It
 	// enqueues chained children onto the CRON queue via enqueueLocalJob -- this host's own when one is
@@ -1033,6 +1395,18 @@ export async function startWorker(
 	// else would enqueue a job only this host can run onto a queue every host drains.
 	const collectChain = makeCollectChain({ queue: cronQueue, config, log });
 
+	// Issue #505. One live-file check, shared by the pickup gate, the snapshot and the plan collector, so the three ask one
+	// file by one rule: the same file and rule as the one-shot checks below (`onceTriggersFile`). `pi-dispatch run
+	// --trigger` reads it there too, so the command that fires a trigger and the check that confirms its flag see one file.
+	const checkPortfolioFlag = makeCheckPortfolioFlag({ triggersPath: onceTriggersFile });
+	const governingNow = () => (envelope.current ? { envelope: envelope.current, digest: envelope.digest } : null);
+	// The plan collector: a completed portfolio job's /outbox/priorities.json, applied under the envelope by the same
+	// allocation state every pickup reconciles. Never throws, like collectChain beside it.
+	const collectPlan = makeCollectPlan({ allocation: allocationState, governing: governingNow, projects: () => projects.current, checkPortfolioFlag, log });
+	// The snapshot a confirmed portfolio job reads as /job/portfolio.json, built at prepare. The run counts are complete
+	// only with the run mirror, which a declared worker name arms (the `runMirror` rule below).
+	const portfolioSnapshot = makePortfolioSnapshot({ checkPortfolioFlag, governing: governingNow, projects: () => projects.current, limits: () => scopedLimits.current, allocation: allocationState, redis, logsDir: config.logsDir, mirror: config.workerNameDeclared === true, log });
+
 	// REQ-GLOBAL-PI-OVERLAY staged packages: read the operator's stage manifest at EACH job start, like
 	// getSettings above and the pause-window ref below.
 	//
@@ -1225,6 +1599,24 @@ export async function startWorker(
 		// here is no opinion at all, and such a host must never be able to disagree with one that has one.
 		fpCron: () => cronFingerprint(authoredCron(config), { tz: hostTz }) ?? "",
 		cronCount: () => schedules.current.length,
+		// Issue #501 part 6: a fingerprint of the dollar caps this host judges the SHARED dollar counters against (the four
+		// settings as a job resolves them, and the scoped-limits dollar rows), so doctor can name two hosts that would
+		// admit different jobs against one counter. A thunk for `fpCron`'s reason: the overlay and the scoped-limits file
+		// change without a restart. Read without a log, so an invalid overlay is not logged on every beat (each job
+		// logs it already). With an invalid overlay it hashes the env values, the slot count's fallback above; such a
+		// host refuses every job (settings-overlay-invalid) until the file is fixed. The env list rides along: it decides
+		// which model rows a job without its own list reserves in.
+		fpUsd: () => {
+			const settings = resolveSettings(config, readOverlay(settingsFile));
+			return usdFingerprint(settings.invalid ? config : settings, scopedLimits.current, config.allowedModels);
+		},
+		// Issue #499 part C: a fingerprint of the LIVE projects (ids and member hashes, never a name), so doctor can name a
+		// host whose projects.json differs. Each host resolves its own jobs' project from its own copy, while the project
+		// rows' counters are shared, so two copies put one repo in two projects. A thunk, so a live edit shows in one beat.
+		fpProjects: () => projectsFingerprint(projects.current),
+		// Issue #504 part B: the digest of this host's live envelope (`envelopeDigest`, 16 hex, never a value), so doctor can
+		// name a host whose envelope differs; such a host refuses governed jobs as `envelope-mismatch`. `none` without one.
+		fpEnvelope: () => envelope.digest ?? NO_ENVELOPE_FINGERPRINT,
 	});
 
 
@@ -1506,6 +1898,9 @@ export async function startWorker(
 	// `operator-cancel`, because the operator initiated it and a push telling them what they just did is
 	// noise with a pager attached.
 	const HOOK_POLICY_REASONS = new Set(["worker-abort", "runner-policy", ...RUNNER_POLICY_REASONS]);
+	// One predicate for the completed listener and the lost-lock path below, so a record replays exactly the page its
+	// result would have sent.
+	const pagesAsPolicy = (result) => Boolean(onFailure) && result?.outcome === "policy" && HOOK_POLICY_REASONS.has(result.reason) && result.budgetReserved !== false;
 	// The infra-terminal sentence (issue #288). FIXED, never err.message: the message classes that reach
 	// a failedReason carry host paths and library words (the #310 record), and for a local job this text
 	// lands verbatim in the service log through the adapter's stdout fallthrough. The worker log already
@@ -1542,6 +1937,7 @@ export async function startWorker(
 		getSettings,
 		redis,
 		recordRun,
+		settledRecord,
 		extraClosers,
 		// REQ-SCOPED-PAUSE-WINDOWS: the processor defers a job whose folder/repo is inside an active window.
 		// Reads the live-reloaded ref, so an operator edit takes effect on the next job without a restart.
@@ -1549,6 +1945,12 @@ export async function startWorker(
 		// Issue #242: the scoped-limits snapshot the pickup gate and the scoped budget read, once per
 		// pickup, from the live-reloaded ref -- same next-job grain as pauseUntil above.
 		scopedLimits: () => scopedLimits.current,
+		// Issue #499: the projects snapshot, read by the pickup gate once, beside the limits snapshot above.
+		projects: () => projects.current,
+		// Issue #504 part B: the live envelope and its digest, and the reconcile the pickup runs before it narrows a job's
+		// dollar ledgers by the applied split. Without an envelope `current()` is null, and `fleetGoverned` asks whether an
+		// applied split exists: if it does, this host's jobs refuse as envelope-mismatch rather than run ungoverned.
+		allocation: { current: () => (envelope.current ? { envelope: envelope.current, digest: envelope.digest } : null), reconcile: allocationState.reconcile, fleetGoverned: allocationState.fleetGoverned },
 		// Issue #230. The `after` ceiling is read per pickup from config rather than frozen into the
 		// processor, so it is one value with one home; the wait state shares the budget's redis client
 		// because it describes the same delayed jobs that client already reasons about.
@@ -1567,6 +1969,14 @@ export async function startWorker(
 		// the operator limited to one. Nothing refreshes this claim, deliberately: a refresher would be a
 		// second thing to get wrong for a window that cannot be reached.
 		scopeLease: hostQueue ? makeFleetLease({ redis, holderPrefix: config.workerName, keyFor: scopeSlotKey, ttlMs: SCOPE_CLAIM_TTL_MS, log }) : null,
+		// Issue #503: the fleet-wide half of a model endpoint's `slots`, armed like the scope lease (declaring a name is
+		// declaring a fleet) and with its TTL for its reason: the claim lives as long as the job's container, which
+		// `JOB_TIMEOUT_MS` bounds. Without a declared name only the in-process bound applies, per host.
+		endpointLease: hostQueue ? makeFleetLease({ redis, holderPrefix: config.workerName, keyFor: endpointSlotKey, ttlMs: SCOPE_CLAIM_TTL_MS, log }) : null,
+		// The endpoint gate's snapshot, read per pickup: the live-reloaded declaration and the overlay models.json, which
+		// the operator edits without a restart too. Read only when an endpoint is declared (the gate's own rule).
+		modelEndpoints: () => modelEndpoints.current,
+		overlayModels: () => readOverlayModels(config.globalPiDir),
 		checkLease: hostQueue
 			? makeFleetLease({
 					redis,
@@ -1584,6 +1994,7 @@ export async function startWorker(
 		maxFaults: () => config.waitMaxFaults,
 		deps: {
 			collectChain,
+			collectPlan,
 			// The one-shot pre-spend check (issue #231): reads the same file the disarm writes, refuses
 			// only on a FOREIGN positive mark (index.mjs binds the real queue jobId so a retry of the
 			// spending delivery is excused). In the compose topology this check is the once-enforcement
@@ -1600,24 +2011,41 @@ export async function startWorker(
 			//
 			// A PROBE: whatever it resolves is dropped on the floor. The credential itself is read where it always
 			// was, inside buildContainerEnv, so no live key is ever in scope in the processor.
-			checkProviderCredential: (job) => {
+			// Issue #503: `modelEndpoints` is the pickup's snapshot, the same one runContainer hands buildContainerEnv.
+			checkProviderCredential: (job, { modelEndpoints = null } = {}) => {
 				try {
-					resolveProviderCredential({ provider: job.provider, hostEnv: env, authFromPi: config.authFromPi, forwardEnv: config.forwardEnv });
+					resolveProviderCredential({ provider: job.provider, hostEnv: env, authFromPi: config.authFromPi, forwardEnv: config.forwardEnv, modelEndpoints });
 					return { ok: true };
 				} catch (error) {
 					// Only OUR determinate refusal. Anything else (a bug here, an fs fault the module does not model)
 					// must not become a policy refusal on the operator's issue: it rethrows into runJob's catch, which
 					// classifies it the way it always did.
+					// Issue #503: a transient overlay read at this pickup is no verdict; the processor retries it as infra.
+					if (error?.piDispatchTransient === true) return { ok: false, unavailable: error.code ?? "unreadable" };
 					if (error?.piDispatchConfig !== true) throw error;
 					return { ok: false, message: error.message };
 				}
 			},
+			// Issue #502. The model-exists gate: pi's builtin catalog, then the overlay models.json, read at most once per
+			// job and only when a model is not builtin, so the operator's edits apply without a restart. The SAME file
+			// the endpoint gate reads, through the same reader, so absent, unreadable and unparseable mean one thing.
+			checkModelsKnown: (refs) => checkModelsKnown(refs, { readOverlay: () => readOverlayModels(config.globalPiDir) }),
+			// Issue #503 part 7: the builtin catalog's model object, for the zero-rated check that lets a job on local
+			// zero-rated models reserve nothing in the dollar windows (processor.mjs, `zeroRatedVerdict`).
+			builtinModel,
+			// Issue #502. The deployment's allowed-model list (PI_ALLOWED_MODELS), null = unrestricted. Env only, and
+			// handed to the processor here rather than through the settings overlay, which a model-callable tool writes.
+			// index.mjs folds it into the effective job (`effectiveJobOf`) under the trigger's own `run.models`.
+			allowedModels: config.allowedModels,
 			// Issue #230. The same file and the same fail-open posture, but its own mtime-cached read: this one
 			// asks whether the AUTHORED entry declares wait conditions the job arrived without, which is how a
 			// service below the version floor turns a wait into a paid run nothing can tell from a correct
 			// one. In the compose topology the worker's read is the live inode while the receiver's is dead
 			// until restart, which is exactly the deployment where the skew happens.
 			checkWaitSkew: makeCheckWaitSkew({ triggersPath: onceTriggersFile }),
+			// Issue #505. Whether the live file still flags a portfolio job's cron trigger, read when such a job is picked
+			// up, from the same file and by the same rule as the two checks above (built once, beside collectPlan).
+			checkPortfolioFlag,
 			// Issue #230. Whether a job the supersede lease names is still in the queue. Without it a holder
 			// that vanished by any route except the clean one leaves a key that refuses every later delivery
 			// for that target until it expires -- and a refused forge delivery is gone, since no webhook
@@ -1694,6 +2122,11 @@ export async function startWorker(
 				jobImage: config.jobImage,
 				// #277: the venue a retained directory records, which the sandbox refuses by when it is not here.
 				defaultBackend: config.defaultBackend,
+				// Issue #504 part B: a local job's folder is resolved at prepare and mounted resolved; one named inside a run
+				// root or a cron folder must still resolve inside it, and none may be the envelope's folder or above it.
+				localPlacement: { jobPaths: envelopeJobPathsNow, envelopeFile: config.envelopeFile ?? null },
+				// Issue #505: /job/portfolio.json for a confirmed portfolio job.
+				portfolioSnapshot,
 				preparers: makeForgePreparers({ gitlabApiUrl: config.gitlab?.apiUrl ?? null, forgejoApiUrl: config.forgejo?.apiUrl ?? null, azureOrgUrl: config.azure?.orgUrl ?? null }),
 				// The cron event.json's previousRunAt (INT-CONTAINER-JOB-INPUTS): read back from the same
 				// per-job run-history sidecars recordRun writes above -- no new store, no new query surface.
@@ -1762,7 +2195,7 @@ export async function startWorker(
 		// comment and the signal for CONST-PI-VERSION-PINNED's silent-no-op mode -- a missing line is
 		// what tells a human a run did nothing. The container's own output already streams via
 		// runContainer's onOutput during the run.
-		// `reason` is a fixed enum (worker-abort | over-budget | unprotected-branch | runner-policy |
+		// `reason` is a fixed enum (worker-abort | over-budget | dollar-cap | allocation-cap | envelope-mismatch | portfolio-no-envelope | portfolio-snapshot-oversize | unprotected-branch | runner-policy |
 		// provider-auth-refused | job-image-missing), never
 		// user content. Included only when present so success lines stay clean; a shutdown-aborted job logs
 		// { outcome: "policy", reason: "worker-abort" }, making a restart-dropped job visible.
@@ -1775,11 +2208,16 @@ export async function startWorker(
 			// and never in the failed listener -- a failed-only mount would miss exactly the paid terminals
 			// the feature exists for. Folded into the existing listener body, never a second w.on: the
 			// start-wiring harness records ONE handler per event, and two would race the log line's pin.
-			if (onFailure && result?.outcome === "policy" && HOOK_POLICY_REASONS.has(result.reason)) {
+			// `budgetReserved !== false` (issue #502): `model-not-allowed` is both a runner stop (paid, pages) and a
+			// pre-spend refusal of a main model outside the job's list (free, comments, pages nobody), and the reason
+			// alone cannot tell them apart. Every paid terminal above carries `budgetReserved: true`.
+			if (pagesAsPolicy(result)) {
 				onFailure({ jobId: job?.id, outcome: "policy", reason: result.reason });
 			}
 		});
-		for (const w of allWorkers) w.on("failed", (job, err) => {
+		// The failed listener's body, for a failure the queue decided. Split out only so the lost-lock check below can
+		// run it after an await; a failure of any other reason runs it synchronously, exactly as before.
+		const onFailed = (job, err) => {
 			log("job_failed", { jobId: job?.id, attempt: job?.attemptsMade, reason: String(err?.message ?? err).slice(0, 120) });
 			// The one reason whose sentence is the fix itself (issue #458): logged WHOLE, beside the cut line above.
 			if (err?.reason === NETNS_KEEPER_NOT_HOLDING || err?.reason === NETNS_KEEPER_CRASH_LOOP) log("job_failed_netns_keeper", { jobId: job?.id, attempt: job?.attemptsMade, reason: String(err?.message ?? "") });
@@ -1794,6 +2232,29 @@ export async function startWorker(
 				void comment({ ...job.data, id: job.id }, (typeof err?.reason === "string" && Object.hasOwn(FAILED_COMMENT_BY_REASON, err.reason) ? FAILED_COMMENT_BY_REASON[err.reason] : null) ?? FAILED_COMMENT);
 				onFailure?.({ jobId: job?.id, outcome: "failed", reason: typeof err?.reason === "string" ? err.reason : "infra" });
 			}
+		};
+		// A job that FINISHED, then lost its lock (DES-TERMINAL-COMMENTS-AND-FAILURE-HOOK). When Valkey is unreachable
+		// for longer than the lock renewal window while a processor finishes, the record is written, BullMQ refuses the
+		// completion ("Missing lock"), and its stall check (`maxStalledCount: 0`) fails the job at the next pickup with
+		// STALLED_FAILED_REASON. Without this check that job posted the failure comment and paged the operator for a run
+		// that ended. So a terminal stall failure first asks the run record: when the record says this attempt finished
+		// without failing, the job's terminal line is `job_lost_lock_after_completion` and nothing is posted. The page
+		// the completed listener would have sent for that record (a paid policy stop) is sent here instead, because
+		// that listener never saw the first finish. No record, an earlier attempt's, a `failed` one, or a lookup fault
+		// keeps the failure path below: the comment and the page.
+		for (const w of allWorkers) w.on("failed", (job, err) => {
+			if (!(job?.finishedOn && err?.message === STALLED_FAILED_REASON)) return onFailed(job, err);
+			void (async () => {
+				// `attemptsMade` is read AFTER BullMQ's moveToFailed added one, so it equals the attempt number the
+				// record carries (`buildRecord`'s `attemptsMade + 1`, written while the job was processing).
+				// A record found and refused is said, with its fixed reason, so an operator reading the failure comment
+				// can see why the record did not suppress it (a clock skew past the tolerance reads `older-than-job`).
+				const onReject = (reason, source) => log("job_lost_lock_record_rejected", { jobId: job.id, reason, source });
+				const record = await settledRecord(job.id, { attempt: job.attemptsMade, since: job.timestamp, onReject });
+				if (!record) return onFailed(job, err);
+				log("job_lost_lock_after_completion", { jobId: job.id, outcome: record.outcome, ...(record.reason ? { reason: record.reason } : {}) });
+				if (pagesAsPolicy(record)) onFailure({ jobId: job.id, outcome: "policy", reason: record.reason });
+			})().catch(() => {}); // `settledRecord` never rejects; this only keeps a throwing log line from going unhandled
 		});
 
 		// CONST-RETRY-INFRA-ONLY money backstop: BullMQ's maxStalledCount does not bound scheduler jobs, so a
@@ -1844,7 +2305,7 @@ export async function startWorker(
 		// Only when a triggers file is configured; best-effort; a bad edit keeps the running schedulers. The
 		// closer each of the three returns joins `extraClosers`, so the watch stops with the worker (issue #295).
 		if (config.triggersFile) {
-			extraClosers.push(watchTriggersFile(config, cronQueue, log, schedules, registry, hostTz, config.workerNameDeclared, atBoot.triggers));
+			extraClosers.push(watchTriggersFile(config, cronQueue, log, schedules, registry, hostTz, config.workerNameDeclared, atBoot.triggers, checkEnvelopePlace));
 		}
 
 		// REQ-SCOPED-PAUSE-WINDOWS live edit: watch the pause-windows file and hot-swap the in-memory windows, so
@@ -1853,9 +2314,29 @@ export async function startWorker(
 			extraClosers.push(watchPauseWindowsFile(config, pauseWindows, log, atBoot.pauseWindows));
 		}
 
+		// Issue #499 part B: the two files a project row joins reload as a pair; the deployment cap rides along so a limits
+		// list either reload commits gets the dollar-rows-without-cap warning.
+		const projectPair = makeProjectPair(scopedLimits, projects, deploymentMaxCostUsd);
+		// Issue #504 part B: the envelope reloads with the pair, since its floors are judged against both files: a committed
+		// limits or projects edit re-judges it from disk, and its own edits are judged against the live pair.
+		const envelopeCtx = { projects, limits: scopedLimits, maxCostMicros: envelopeCap, jobPaths: envelopeJobPathsNow, onChange: () => void reconcileAllocation("reload") };
+		if (config.envelopeFile) {
+			projectPair.afterCommit = () => reloadEnvelope(config, envelope, log, envelopeCtx);
+			extraClosers.push(watchEnvelopeFn(config, envelope, log, atBoot.envelope, envelopeCtx));
+		}
 		// Issue #242 live edit: hot-swap the scoped limits on file change, keeping last-good on a bad edit.
 		if (config.scopedLimitsFile) {
-			extraClosers.push(watchScopedLimitsFile(config, scopedLimits, log, atBoot.scopedLimits));
+			extraClosers.push(watchScopedLimitsFn(config, scopedLimits, log, atBoot.scopedLimits, deploymentMaxCostUsd, projectPair));
+		}
+
+		// Issue #499 live edit: the projects file, keep-last-good on a bad edit.
+		if (config.projectsFile) {
+			extraClosers.push(watchProjectsFn(config, projects, log, atBoot.projects, projectPair));
+		}
+
+		// Issue #503 live edit: the model endpoints, keep-last-good on a bad edit.
+		if (watchModelEndpoints) {
+			extraClosers.push(watchModelEndpointsFile(config, modelEndpoints, log, atBoot.modelEndpoints));
 		}
 
 		// issue #292 / OQ-007: re-run the three retention sweeps on a timer, because the supported deployment
@@ -1873,6 +2354,8 @@ export async function startWorker(
 			const sweep = makeRetentionSweepFn({
 				reapers: [
 					{ name: "log", reap: reapLogs },
+					// Issue #504 part B: where boot runs it, right after the run history it sits beside.
+					{ name: "allocation_log", reap: reapAllocationLogs },
 					{ name: "sandbox", reap: reapSandboxes },
 					{ name: "session", reap: () => sessionStore.reapSessions() },
 				],
@@ -1912,6 +2395,11 @@ export async function startWorker(
 			softHoldPct: config.softHoldPct, // null when the soft-hold band is disabled
 			scopedLimitsFile: config.scopedLimitsFile, // null = no scoped caps/concurrency (the folder mutex holds regardless)
 			scopedLimits: scopedLimits.current.length, // row count -- money config deserves boot visibility; the watcher logs only changes
+			projectsFile: config.projectsFile, // issue #499: null = no projects
+			projects: projects.current.length, // project count, never a name
+			envelopeFile: config.envelopeFile, // issue #504: null = no envelope and no delegation
+			envelopeDigest: envelope.digest, // the envelope's 16-hex digest, the host row's fpEnvelope; null without one
+			modelEndpoints: modelEndpoints.current.length, // issue #503: declared model endpoints, each a slot lease at pickup
 			image: config.jobImage,
 			valkey: config.valkeyUrl,
 			// Issue #464: the literal address every Valkey client of this worker dials, beside the URL as written; null