@edgehero/pi-dispatch 2.1.0 → 3.0.0

package/src/processor.mjs

@@ -1,13 +1,25 @@
 import { DAEMON_APPLIES_BOUNDS, DEFAULT_BACKEND, DOCKER_ENDPOINT_LOCAL, DOCKER_NEVER_STARTED_EXITS, PODMAN_ADDS_NO_MOUNTS, PODMAN_BACKEND, PODMAN_BOUNDS_DELEGATED, PODMAN_CONF_WIDENS_JOB, PODMAN_SERVICE_LOCAL, RUNTIME_ADDS_NO_MOUNTS } from "./backends.mjs";
 import { resolveBackendName } from "./backend-registry.mjs";
 import { lstatSync } from "node:fs";
-import { checkTokenCap, recordTokenSpend, releaseBudget, reserveBudget } from "./budget.mjs";
+import { checkTokenCap, recordTokenSpend, releaseLedgers, reserveLedgers } from "./budget.mjs";
 import { configError } from "./config.mjs";
-import { scopeKeyPrefix } from "./scoped-limits.mjs";
+import { unqualifiedScope } from "./pause-windows.mjs";
+import { PROJECT_CAP_REASON } from "./scoped-limits.mjs";
 import { DEFAULT_SECRETS_PROFILE, secretsArmed } from "./secrets.mjs";
+import { RESERVED_ENV_NAMES } from "./triggers.mjs";
 import { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "./exit-code.mjs";
-import { RUNNER_POLICY_REASONS } from "./run-history.mjs";
+import { COST_CAP_WHYS, RUNNER_POLICY_REASONS } from "./run-history.mjs";
 import { DEFAULT_EGRESS_PROXY } from "./egress.mjs";
+import { CAPABILITY_GATES, EXIT_AUTH_CAPABILITY } from "./image-preflight.mjs";
+import { modelListProblem, modelOnList, splitModelEntry } from "./model-ref.mjs";
+import { ALLOCATION_CAP_REASON, ENVELOPE_MISMATCH_REASON } from "./allocation.mjs";
+
+/** The refusal of a local job whose resolved folder belongs to another project than the one decided at pickup (issue #504 part B). */
+export const LOCAL_FOLDER_PROJECT_CHANGED = "local-folder-project-changed";
+// Issue #505: a portfolio cron job refused before it spends, because this host could not apply the plan it would write.
+export const PORTFOLIO_NO_ENVELOPE = "portfolio-no-envelope";
+import { DOLLAR_CAP_REASON, DOLLAR_KEY_PREFIX, dollarLedgers, dollarSettlement, dollarsRecord, holdPart, meteredMicros, modelDollarSettlement, releaseDollars, reserveDollars, settleDollars } from "./dollar-budget.mjs";
+import { zeroRatedVerdict } from "./model-endpoints.mjs";
 
 /**
  * The forge comment's reason for each observation a floor refusal missed (issues #278 and #345), keyed like
@@ -88,8 +100,22 @@ export const TERMINAL_COMMENTS = {
 	// Issue #437. Names the cause but never the provider's own message, which may echo a key fragment. "Or
 	// access" because a 403 is as often a key that works but may not use this model or route as a bad key.
 	"provider-auth-refused": "Stopped: the AI provider refused this worker's credentials or access (an authentication or permission error). The operator needs to check the provider key and what it is allowed to use. Not retried.",
+	// Issues #501, #502. The two stops name the policy, never the amount or the model: both are operator
+	// configuration, and the comment's reader may be an issue author who can act on neither.
+	"cost-cap": "Stopped: the next AI call could have taken this run past its cost limit, so it was not made. Partial work may exist. Not retried.",
+	"model-not-allowed": "Stopped: the run tried to call an AI model this trigger does not allow, or to change an AI request in a way it does not allow, so the call was not made. Partial work may exist. Not retried.",
+	"cost-cap-unenforceable": "Stopped: this run has a cost limit, and the job image could not enforce it before each AI call, so nothing was sent to the AI provider. The operator needs to update the job image. Not retried.",
+	"model-policy-unenforceable": "Stopped: this run is limited to certain AI models, and the job image could not enforce that before each AI call, so nothing was sent to the AI provider. The operator needs to update the job image. Not retried.",
 };
 
+// Issue #502: the `model-unknown` refusal's comment. Names no model: the reader may be an issue author.
+export const MODEL_UNKNOWN_COMMENT = "Refused: this job names an AI model that this deployment does not know (it is in neither pi's model catalog nor the overlay models.json), so no container was started and nothing was spent. Ask the operator to check the trigger's model settings. Not run.";
+
+// The `model-unknown` refusal whose `why` is `overlay-*` (PR #558, the end-of-round check of #501 and #502): the deployment's overlay
+// models.json is the problem, not the job's model, so the generic text above would send the author to the wrong
+// place. Fixed text naming no path and no model; the operator finds which file and why in the worker log.
+export const OVERLAY_REFUSED_COMMENT = "Refused before starting: the deployment's model settings file (models.json in the overlay) cannot be used for this job, so no container was started and nothing was spent. The operator needs to fix that file. Not run.";
+
 // Issue #341: the forge comments for a `job-user-unmappable` refusal, keyed by cause. Shorter than the operator
 // texts in job-user.mjs on purpose: a comment's reader may be an issue author, who can act on none of it.
 const JOB_USER_COMMENTS = Object.freeze({
@@ -126,18 +152,54 @@ function egressProxyFix(venue, proxy = DEFAULT_EGRESS_PROXY) {
 	return "Start it with `pi-dispatch up` from the deployment folder";
 }
 
+/**
+ * Did the runtime never hand control to the runner (issue #227)? ONE answer for the two places that ask it (issue
+ * #501): the exit-code switch, which refunds such an exit as `container-never-started`, and the dollar settlement,
+ * which must not settle a container that never ran (the refund in the catch gives its reservation back instead).
+ * Two answers could drift: a never-started exit settled at the floor AND refunded would give back twice, and one
+ * neither settled nor refunded would leave its hold standing.
+ *
+ * A detached container (issue #345) DID start, and an aborted one is classified by its flag first, so neither is
+ * never-started whatever its code. The runner's own three codes are never the venue's never-started set's to claim.
+ */
+export function isNeverStartedExit({ code, aborted, detached }, neverStartedCodes) {
+	if (detached === true || aborted) return false;
+	if (code === EXIT_COMPLETED || code === EXIT_POLICY || code === EXIT_INFRA) return false;
+	return (neverStartedCodes ?? []).includes(code);
+}
+
+/** The key prefixes of a job's model dollar ledgers (`modelDollarRows`), to tell a model window's keys in a hold apart. */
+function modelPrefixesOf(modelDollars) {
+	return new Set((modelDollars ?? []).map((m) => m.keyPrefix));
+}
+
+/**
+ * The models a job may call (issue #501, #503 part 7), as `{ provider, id }` refs: its main model, and every entry of
+ * its effective allowed-model list when it has one. A list entry that does not split is kept as `null`, which the
+ * zero-rated check reads as "not zero-rated" (fail closed).
+ */
+function callableModelRefs(job) {
+	const refs = [{ provider: job.provider, id: job.model }];
+	for (const entry of Array.isArray(job.models) ? job.models : []) {
+		const ref = splitModelEntry(entry);
+		refs.push(ref === null ? null : { provider: ref.provider, id: ref.model });
+	}
+	return refs;
+}
+
 export async function runJob(job, deps) {
 	const {
 		redis,
 		caps, // { day, week, month }; week/month null when that window is disabled (REQ-SPEND-CAPS-MULTI-WINDOW)
 		softHoldPct, // int 1-99 or null; the soft-hold band applied to every active window
 		tokenCap = null, // int or null; the daily TOKEN cap (issue #25). Check-AFTER, so it gates the NEXT job on prior spend
-		// { scope, caps: { day, week, month } } | null -- this job's scoped budget windows (issue #242,
-		// INT-SCOPED-LIMITS-FILE-CONTRACT), resolved by the wiring from the same watched-limits snapshot the
-		// pickup gate read. Null when the file is unset or the scope's row is concurrency-only; the default
-		// keeps an unwired processor byte-identical. The folder MUTEX does not live here -- it is the pickup
-		// gate's, pre-everything; this is only the money half.
-		scopedCaps = null,
+		// [{ scope, keyPrefix, caps: { day, week, month }, reason }] -- this job's scoped job-count ledgers in reserve order
+		// (issues #242 and #499 part B, INT-SCOPED-LIMITS-FILE-CONTRACT): its repo or folder row's, then its project row's,
+		// from ONE builder (`scopedLedgers`) over the same watched-limits snapshot and pickup project the gate read. The
+		// global ledger is appended here, last. Empty when no row carries a job-count window; the default keeps an
+		// unwired processor byte-identical. The folder MUTEX and the `concurrent` slots do not live here -- they are the
+		// pickup gate's, pre-everything; this is only the money half.
+		scopedLedgers = [],
 		recordSpend = recordTokenSpend, // injected so the post-container INCRBY is testable/stubbable
 		// (job) => { ok } | { missing: <ref> } | { unavailable: <ref> }. The pre-spend check that the image
 		// this job names is on this host (image-preflight.mjs). Default admits everything, so a wiring that
@@ -151,13 +213,21 @@ export async function runJob(job, deps) {
 		// Issue #230. Admit-everything by default, like checkOnceSpent above and for its reason: an
 		// unwired seam must not refuse, and the wiring is what turns the check on.
 		checkWaitSkew = async () => ({ ok: true }),
-		// () => { ok } | { message }. Issue #310. Resolves this deployment's provider credential the way
+		// () => { ok } | { message } | { unavailable } (issue #503: a transient overlay read, retried). Issue #310. Resolves this deployment's provider credential the way
 		// buildContainerEnv will, and answers whether it exists AT ALL, so an unconfigured provider refuses
 		// here rather than inside runContainer with the budget already reserved. Admit-everything by default,
 		// like the two above and for their reason. A PROBE, deliberately: it discards whatever it resolves and
 		// the real read happens where it always did, because threading a live credential through the processor
 		// would put it in scope for every log line and record between here and the container.
 		checkProviderCredential = () => ({ ok: true }),
+		// (refs) => { ok } | { unknown: { provider, id }, why } | { unavailable: code } (issue #502). Is each of this
+		// job's models, its main one and every listed one, a model pi knows (model-catalog.mjs `checkModelsKnown`,
+		// the builtin catalog plus the overlay models.json)? Admit-everything by default, like the credential probe
+		// above and for its reason: an unwired seam must not refuse, and the wiring is what turns the check on.
+		checkModelsKnown = () => ({ ok: true }),
+		// Issue #503: the pickup's endpoint snapshot `{ endpoints, models, set }` (index.mjs), read once per pickup. Null on
+		// a wiring with no endpoint seam, which leaves the credential gate and the container env exactly as before.
+		modelEndpoints = null,
 		// REQ-EGRESS-ALLOWLIST. Default admits everything, so a wiring that omits it behaves exactly as a
 		// deployment with no egress policy does -- which is also what the real factory returns when unarmed.
 		egressPreflight = async () => ({ ok: true }),
@@ -230,7 +300,7 @@ export async function runJob(job, deps) {
 		mintToken,
 		isDefaultBranchProtected, // (job, token) => boolean; same reason -- the forge is the job's, not the process's
 		prepareWorkspace, // (job, token) => { workspaceDir, jobDir }  (clone+materialise+prompt)
-		// runContainer({ job, token, prepared, secrets, name, signal, user, home }) => { code, aborted, abortReason, turns, tokens, session, usage, context, exitReason }.
+		// runContainer({ job, token, prepared, secrets, name, signal, user, home, modelEndpoints? }) => { code, aborted, abortReason, turns, tokens, session, usage, context, exitReason }.
 		// `exitReason` (issue #437) is parseExitReason's closed-set label, read only inside the exit-2 branch.
 		// `user`/`home` are the job-user gate's answer (issue #341), null for the image's own USER.
 		// `secrets` is the resolved map from the gate above: values, already fetched, host-side. It MUST honour
@@ -247,6 +317,49 @@ export async function runJob(job, deps) {
 		// or a github job with no /outbox -- chains nothing. It NEVER throws (outbox.mjs), so its counts are
 		// additive telemetry that can never flip the parent's completed outcome (CONST-RETRY-INFRA-ONLY).
 		collectChain = async () => ({ enqueued: 0, refused: 0 }),
+		// The plan collector (issue #505, outbox-plan.mjs): a completed portfolio job's `/outbox/priorities.json`, handed to
+		// applyPlan. Called on the completed branch only, after collectChain, with the pickup's `portfolio` decision. It
+		// NEVER throws, so a refused plan is a recorded outcome of a completed job and never a retry. The default collects
+		// nothing (null: no plan), so a wiring that omits it records `plan: null`.
+		collectPlan = async () => null,
+		// Issue #501: the deployment's dollar windows `{ day, week, month }` in micro-dollars (each null when unset), or
+		// null when no window is set. Null is the default and the off switch: nothing is reserved or settled and no
+		// `budget:usd:*` key is written, so a deployment with no dollar setting is byte-identical.
+		dollarCaps = null,
+		// Issues #501 part 5 and #502 part 6 (scoped-limits.json version 2): this job's repo or folder dollar windows,
+		// `{ scope, keyPrefix, caps }` from `dollarCapsFor`, or null; and the model dollar windows it reserves in,
+		// `[{ ref, keyPrefix, caps }]` from `modelDollarRows` over its effective list (every model row when it has
+		// none). Both default to nothing, so an unwired processor reserves exactly what it did before.
+		scopedDollars = null,
+		// Issue #499 part B: this job's project row's dollar windows, `{ scope, keyPrefix, caps }` from
+		// `projectDollarCapsFor` with the project resolved at pickup, or null. Reserved after the repo or folder row's.
+		projectDollars = null,
+		modelDollars = [],
+		// Issue #504 part B (DES-DELEGATED-ALLOCATION-INSIDE-ENVELOPE): under an envelope, `governedDollars` narrows the
+		// ledgers above by the applied split, and these three ride beside them. `otherDollars` is `_other`'s ledger
+		// (`{ scope, keyPrefix, caps, capSource }`), for a job in no envelope project; `dollarCapSource` says, per window,
+		// whether the deployment cap came from the operator or the envelope total (`scopedDollars` and `projectDollars`
+		// carry their own `capSource`). `envelopeMismatch` is the pickup's verdict that this host's envelope is not the
+		// applied split's (true), or that it has none while one is applied ("no-envelope"). All default to nothing, so a deployment with no envelope is byte-identical.
+		otherDollars = null,
+		dollarCapSource = null,
+		envelopeMismatch = false,
+		// Issue #505: whether the LIVE triggers file still flags this job's cron trigger `run.portfolio: true`, as
+		// `(job) => boolean`, and this host's envelope `delegation` block (`{ enabled, writers }`), null with no envelope.
+		// The flag on the job data is what the trigger said when the job was queued; the file is what the operator says
+		// now, so removing the flag takes effect for a job already queued. The default answers "not flagged": an unwired
+		// processor treats every job as an ordinary one, which is what a job with no confirmed flag is.
+		checkPortfolioFlag = async () => false,
+		envelopeDelegation = null,
+		// Issue #504 part B: the project decided at pickup on the folder as named, and a function giving the project of a
+		// folder from the same projects snapshot. A local job whose RESOLVED folder belongs to another project is refused
+		// after prepare, before any reserve. Absent on a bare wiring, which checks nothing.
+		pickupProject = null,
+		folderProject = null,
+		// Issue #503 part 7: the builtin catalog's model object for (provider, id), or null (model-catalog.mjs
+		// `builtinModel`). Read only by the zero-rated check; the default knows no builtin model, so an unwired
+		// processor judges overlay models alone and reserves for every other.
+		builtinModel = () => null,
 		now = new Date(),
 	} = deps;
 
@@ -261,10 +374,29 @@ export async function runJob(job, deps) {
 	const wantsForgeToken = isForgeBacked || job.github === true;
 	let token = null;
 	let prepared = null;
-	let reserved = false;
-	let scopedReserved = false;
+	// The job-count reservations still standing, in reserve order (issue #499 part B): what `reserveLedgers` took and
+	// no refund has given back yet. EVERY refund below is `releaseLedgers` over this one list, last first, so no path
+	// can give back one ledger and forget another, and none can give one back twice: a released ledger leaves the list.
+	const held = [];
+	// The global ledger's own entry, so `budgetReserved` can ask the list. ONE rule on every path (a count refusal, a
+	// dollar-cap, config-refused, an InfraRetry): `budgetReserved` says whether the GLOBAL slot is still held after any
+	// refund, global-only as INT-RUN-HISTORY-FILE-CONTRACT has it. A scoped or project slot a failed refund left behind
+	// is in the `budget_release_failed` log line, not in this field.
+	let globalLedger = null;
+	const globalHeld = () => globalLedger !== null && held.includes(globalLedger);
+	// Give back every held job-count slot, NEVER throwing: a refund that did not land must not replace the caller's
+	// classification with a Redis message. Logged with `at`; returns whether the list is empty afterwards.
+	const refundLedgers = async (at) => {
+		try {
+			await releaseLedgers(redis, held, { now });
+			return true;
+		} catch (releaseError) {
+			log("budget_release_failed", { at, code: releaseError?.code ?? null });
+			return false;
+		}
+	};
 	// Set once `runContainer` has RESOLVED, which is the only moment a container is known to have run. The
-	// config classifier in the catch refunds both ledgers, and its whole justification is that nothing was
+	// config classifier in the catch refunds every job-count ledger, and its whole justification is that nothing was
 	// spent; without a fact to test, that is a claim about where config throws happen to live today rather
 	// than a property of the code. A config-tagged throw raised after a paid run would otherwise refund a slot
 	// the container really spent AND tell the operator publicly that nothing was.
@@ -275,6 +407,11 @@ export async function runJob(job, deps) {
 	// A spawn fault that fails between is an InfraRetry carrying `container-never-started`, refunded by the
 	// arm below, which has a discriminator of its own.
 	let containerRan = false;
+	// Issue #501. `dollarHold` is the dollar reservation still standing (reserveDollars' hold), null when none was
+	// taken or once it has been settled or given back, so no path can settle or refund it twice. `dollars` is what
+	// the record says about it (INT-RUN-HISTORY-FILE-CONTRACT), null until the reservation step ran.
+	let dollarHold = null;
+	let dollars = null;
 
 	try {
 		// The one-shot pre-spend check (issue #231), FIRST on the ladder: one file read, cheaper than
@@ -306,6 +443,18 @@ export async function runJob(job, deps) {
 		// standing between a stale receiver and a paid job that ran when the operator wrote "wait".
 		{
 			const skew = await checkWaitSkew(job);
+			// Issue #502: an authored NARROWING field the job arrived without (`AUTHORED_NARROWING_FIELDS`, triggers-file.mjs),
+			// today `run.models` and `run.maxCostUsd`. The same two causes as a dropped wait, and the same refusal shape; without it the job would
+			// run on the deployment's list, or on none, while every record reads like a correct run. The FIELD is named,
+			// never its value: the comment's reader may be an issue author.
+			if (skew.skewed && typeof skew.field === "string") {
+				// Three causes, the likeliest first (PR #536's review, round 3, made the check strict): the trigger gained the
+				// field after this job was queued, a service is below the version that carries it, or one still reads an
+				// older copy of the triggers file. The first is fixed by re-running the job, so the comment says so.
+				await comment(job, `Refused: this trigger sets \`run.${skew.field}\`, but the job reached the worker without it, so it would have run without that limit. Either the trigger changed after this job was queued (re-run it), or a service in this deployment is stale: below the version that carries the field, or still reading an older copy of the triggers file and in need of a restart. Not run.`);
+				log("refused_trigger_skew", { triggerIndex: job.trigger?.matched?.index ?? null, field: skew.field, causes: "trigger-changed-after-queue-or-stale-service" });
+				return { outcome: "policy", reason: "trigger-skew", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false };
+			}
 			if (skew.skewed) {
 				// Named for the operator, not the payload: how many conditions were authored, never what
 				// they say. The fix is a version, so the comment says which one.
@@ -487,57 +636,16 @@ export async function runJob(job, deps) {
 			log("refused_image_forge_unsupported", { image: img.forgeUnsupported, kind: img.kind, declared: img.declared });
 			return { outcome: "policy", reason: "job-image-forge-unsupported", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
 		}
-		if (img.replicaUnsupported) {
-			// The image is present and does not declare replica support (REQ-REPLICA-RUNS), so its baked
-			// HARD_RULES.md predates the amendment and still hard-codes `pi/issue-<n>` as a SYSTEM rule --
-			// which the model treats as authoritative over the user prompt naming `pi/issue-<n>-r2`. Both
-			// replicas would push to one branch: not an error, just the push race the feature exists to
-			// avoid, with two runs billed and one pull request to show for it.
-			//
-			// Determinate, so a refusal rather than a retry, and pre-spend, because no version of this gets
-			// better by running. Like the forge branch above, the message names the FIX rather than the label
-			// that noticed it -- an operator reading "rebuild the image" is already where they need to be.
-			await comment(
-				job,
-				`Refused: the job image "${img.replicaUnsupported}" does not declare replica support (\`dev.pi-dispatch.capabilities\` ${img.declared.length > 0 ? `declares: ${img.declared.join(", ")}` : "is absent"}), so its baked guardrails would name the wrong branch. Rebuild the image from a version that has this feature. Not run.`,
-			);
-			log("refused_image_replicas_unsupported", { image: img.replicaUnsupported, declared: img.declared });
-			return { outcome: "policy", reason: "job-image-replicas-unsupported", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
-		}
-		if (img.commandUnsupported) {
-			// The image is present and does not declare command support (issue #189), so its runner
-			// predates run.command: it reads no PI_COMMAND, and the bare `/name args` prompt reaches the
-			// model as PROSE -- no handler runs, the agent improvises, and the queue records a clean exit
-			// 0. The in-container half of the gate (the runner's own command-unregistered refusal) does
-			// not exist on such an image, which is exactly why the host must refuse first.
-			//
-			// Determinate, so a refusal rather than a retry, and pre-spend, because no version of this
-			// gets better by running. Like the replica branch above, the message names the FIX rather
-			// than the label that noticed it.
-			await comment(
-				job,
-				`Refused: the job image "${img.commandUnsupported}" does not declare command support (\`dev.pi-dispatch.capabilities\` ${img.declared.length > 0 ? `declares: ${img.declared.join(", ")}` : "is absent"}), so its runner would not dispatch \`run.command\`. Rebuild the image from a version that has this feature. Not run.`,
-			);
-			log("refused_image_commands_unsupported", { image: img.commandUnsupported, declared: img.declared });
-			return { outcome: "policy", reason: "job-image-commands-unsupported", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
-		}
-		if (img.excludeToolsUnsupported) {
-			// The image is present and does not declare exclude-tools support (issue #291), so its runner
-			// predates run.excludeTools: it reads no PI_EXCLUDE_TOOLS, and the job would run with every
-			// tool the trigger says to remove -- a "read-only" trigger with a working editor and shell,
-			// recording a clean exit. That is a PERMISSION quietly not enforced, the silent fail-open this
-			// repo brands the worst outcome available, which is exactly why the host refuses before spend
-			// rather than letting the container fail open.
-			//
-			// Determinate, so a refusal rather than a retry, and pre-spend, because no version of this
-			// gets better by running. Like the command branch above, the message names the FIX rather
-			// than the label that noticed it.
-			await comment(
-				job,
-				`Refused: the job image "${img.excludeToolsUnsupported}" does not declare exclude-tools support (\`dev.pi-dispatch.capabilities\` ${img.declared.length > 0 ? `declares: ${img.declared.join(", ")}` : "is absent"}), so its runner would ignore \`run.excludeTools\` and run this trigger with every tool it says to remove. Rebuild the image from a version that has this feature. Not run.`,
-			);
-			log("refused_image_exclude_tools_unsupported", { image: img.excludeToolsUnsupported, declared: img.declared });
-			return { outcome: "policy", reason: "job-image-exclude-tools-unsupported", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		// The image capability gates (one table, CAPABILITY_GATES in image-preflight.mjs): the image is present and
+		// does not declare a feature this job carries, so its runner would silently ignore it. Determinate, so a
+		// refusal rather than a retry, and pre-spend, because no version of this gets better by running. Like the
+		// forge branch above, each row's comment names the FIX rather than the label that noticed it.
+		const gate = CAPABILITY_GATES.find((row) => img[row.result]);
+		if (gate) {
+			const image = img[gate.result];
+			await comment(job, gate.comment(image, img.declared.length > 0 ? `declares: ${img.declared.join(", ")}` : "is absent"));
+			log(gate.event, { image, declared: img.declared });
+			return { outcome: "policy", reason: gate.reason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
 		}
 		if (img.unavailable) {
 			// docker itself did not answer -- transient infra, NOT a determinate refusal. THROWN so BullMQ
@@ -568,6 +676,65 @@ export async function runJob(job, deps) {
 			throw new InfraRetry("the job user could not be decided", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
 		}
 
+		// Issue #502, two free gates on the job's models, BEFORE the credential gate so a typo in a model or provider
+		// id is named as itself rather than as a missing key, and so before the egress probe, the secret resolvers,
+		// the mint, the clone, the token-cap read and both reserves (CONST-BUDGET-BEFORE-TOKENS). Both read the
+		// EFFECTIVE job (index.mjs `effectiveJobOf`): the main model after the `job.data > overlay > env` fill, and
+		// the list as `job.data.models ?? PI_ALLOWED_MODELS`. Checking `job.data` alone would wave through a model
+		// the overlay or the env supplied, which is the common case: most forge triggers name none.
+		//
+		// The model ids are operator configuration, so the log names them; the forge comment does not, for the
+		// terminal comments' reason: its reader may be an issue author, who can act on neither.
+		{
+			// A list that is PRESENT but not a valid list (a string, `{}`, `0`, `false`, `""`, a bad entry) refuses here
+			// rather than reading as "no list": the loader and the env parser both refuse such a value, so it is a
+			// hand-built or foreign job, and treating it as absent would let it run unrestricted (or hide the
+			// deployment's own list behind it). Same refusal as an unknown model, with its own `why`.
+			if (job.models !== undefined && job.models !== null && modelListProblem(job.models) !== null) {
+				await comment(job, MODEL_UNKNOWN_COMMENT);
+				log("refused_model_unknown", { provider: job.provider ?? null, model: job.model ?? null, why: "list-malformed" });
+				return { outcome: "policy", reason: "model-unknown", why: "list-malformed", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+			const refs = [{ provider: job.provider, id: job.model, main: true }];
+			for (const entry of Array.isArray(job.models) ? job.models : []) {
+				const ref = splitModelEntry(entry);
+				refs.push({ provider: ref.provider, id: ref.model });
+			}
+			const known = await checkModelsKnown(refs);
+			if (known?.unavailable) {
+				// The overlay models.json could not be READ just now (an errno, never file text). Retried, never
+				// refused, the credential gate's rule for the same file below.
+				log("model_catalog_unavailable", { provider: job.provider ?? null, model: job.model ?? null, reason: known.unavailable });
+				throw new InfraRetry("whether this job's models exist could not be decided", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
+			}
+			if (known?.unknown) {
+				// An `overlay-*` why is the deployment's file, not the job's model: its own comment.
+				const why = typeof known.why === "string" ? known.why : null;
+				await comment(job, why?.startsWith("overlay-") ? OVERLAY_REFUSED_COMMENT : MODEL_UNKNOWN_COMMENT);
+				// `why` is a fixed token: `overlay-unparseable` tells the operator the file is the problem, not the id.
+				log("refused_model_unknown", { provider: known.unknown.provider ?? null, model: known.unknown.id ?? null, why: known.why ?? null });
+				return { outcome: "policy", reason: "model-unknown", why, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+			// The main model must be on the job's list. The loader refuses this when one trigger names all three, so
+			// what reaches here is a model or provider the overlay or the env supplied: a `PI_ALLOWED_MODELS` that
+			// does not list `PI_MODEL`, or a `dispatch_set model` that moved the default off a trigger's list. Both
+			// halves are compared, exact (`modelOnList`), the runner guard's rule.
+			if (Array.isArray(job.models) && !modelOnList(job.models, job.provider, job.model)) {
+				await comment(job, "Refused: the AI model this job would run on is not on the list of models it is allowed to use, so no container was started and nothing was spent. Ask the operator to check the trigger's model settings. Not run.");
+				log("refused_model_not_allowed", { provider: job.provider ?? null, model: job.model ?? null });
+				return { outcome: "policy", reason: "model-not-allowed", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+			// A listed model whose declared fallbacks are not all listed (model-catalog.mjs `declaredFallbacks`): on
+			// anthropic-messages pi sends them with every call, so the runner's guard would refuse every call to it after
+			// the container started; on any other api the worker is stricter than the runner, by decision. Refused here, free. The log names the listed model, the operator's own configuration; the
+			// comment names none.
+			if (known?.fallbackUnlisted) {
+				await comment(job, "Refused: a model this job is allowed to use declares fallback models that are not on the job's list, so no container was started and nothing was spent. Ask the operator to list those models too, or remove that model. Not run.");
+				log("refused_model_not_allowed", { provider: known.fallbackUnlisted.provider ?? null, model: known.fallbackUnlisted.id ?? null, why: "fallback-unlisted" });
+				return { outcome: "policy", reason: "model-not-allowed", why: "fallback-unlisted", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+		}
+
 		// Is there a credential to run this job with at all? FREE, determinate and I/O-light: a pure function
 		// of the job's provider, the worker env, and (only when the env has no key) one small readFileSync of
 		// pi's auth.json. So it goes here, with the other free gates, which is further than issue #310 asked
@@ -590,7 +757,61 @@ export async function runJob(job, deps) {
 		// The refusal names no path. `credentialFromPiAuth`'s messages carry auth.json's location, `comment`
 		// posts publicly on the issue, and the reason an operator needs is the same either way: their
 		// deployment has no usable provider credential and `doctor` will say exactly which variable.
-		const credential = await checkProviderCredential(job);
+		// `modelEndpoints` is the pickup's snapshot (issue #503), handed to the gate and to runContainer alike, so a
+		// keyless provider passes here and gets its PI_DISPATCH_KEYLESS there from ONE read of the declaration. runContainer
+		// is handed it only when an endpoint is declared, so with none its context is byte-identical to before.
+		// THE ENVELOPE GATE (issue #504 part B, DES-DELEGATED-ALLOCATION-INSIDE-ENVELOPE): this host's envelope digest is not
+		// the applied split's, so the split this job would be judged against was computed for another envelope. FREE and
+		// determinate (the pickup read decided it), so it sits with the free gates, before the mint, the clone, the
+		// token-cap read and every reserve (CONST-BUDGET-BEFORE-TOKENS), and it RETURNS: a retry meets the same envelope
+		// until the operator makes the hosts agree (CONST-RETRY-INFRA-ONLY). Refusing is loud and money-safe; judging one
+		// split against two envelopes is neither.
+		// `envelopeMismatch` is true (this host's envelope is another one) or "no-envelope" (it has none while the fleet has
+		// an applied split): one reason, two texts, since the fix differs.
+		if (envelopeMismatch === true || envelopeMismatch === "no-envelope") {
+			const absent = envelopeMismatch === "no-envelope";
+			await comment(
+				job,
+				absent
+					? "Refused: this worker has no budget envelope while the other workers share an applied budget split, so no container was started and nothing was spent. Ask the operator to install the envelope on this worker, or to turn delegated allocation off for every worker (`pi-dispatch doctor` says how). Not run."
+					: "Refused: this worker's budget envelope differs from the one the current budget split was made for, so no container was started and nothing was spent. Ask the operator to run `pi-dispatch doctor`. Not run.",
+			);
+			log("refused_envelope_mismatch", absent ? { envelope: "none" } : {});
+			return { outcome: "policy", reason: ENVELOPE_MISMATCH_REASON, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+
+		// THE PORTFOLIO GATE (issue #505, `portfolio-no-envelope`). A portfolio job exists to write a priorities plan, and a
+		// plan applies only on a host whose envelope has delegation on with `portfolio-job` among its writers. Without
+		// that the plan is refused after the job has paid to write it, so the job is refused here instead: FREE (the
+		// envelope was read at boot or reload, the triggers file is one local read), before the mint, the clone, the
+		// token-cap read and every reserve (CONST-BUDGET-BEFORE-TOKENS), and RETURNED, since a retry meets the same
+		// envelope (CONST-RETRY-INFRA-ONLY). After the envelope gate, which names the host-wide fault first.
+		//
+		// The live flag comes FIRST. The job data says what the trigger said when it was queued; the live file says what
+		// the operator says now. A job whose trigger no longer flags it (or whose file cannot be read) is an ordinary
+		// cron job: it runs unflagged and passes this gate, rather than being refused for a flag nobody holds any more.
+		// Only a job with a cron `trigger` and no chain fields is asked about at all: a manual run and a chained child can
+		// never be a portfolio job, whatever their data says.
+		const portfolio = job.portfolio === true && job.trigger !== undefined && job.parentJobId === undefined && job.chainDepth === undefined && (await Promise.resolve().then(() => checkPortfolioFlag(job)).catch(() => false)) === true;
+		if (portfolio) {
+			const delegation = envelopeDelegation;
+			const why = delegation === null || delegation === undefined ? "no-envelope" : delegation.enabled !== true ? "delegation-off" : !Array.isArray(delegation.writers) || !delegation.writers.includes("portfolio-job") ? "writer-not-allowed" : null;
+			if (why !== null) {
+				// No comment: a portfolio job is always local, and a local job has no issue to comment on. `why` is a
+				// fixed token, so the log says which of the three the operator has to change.
+				log("refused_portfolio_no_envelope", { why });
+				return { outcome: "policy", reason: PORTFOLIO_NO_ENVELOPE, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+		}
+
+		const credential = await checkProviderCredential(job, { modelEndpoints });
+		if (credential.unavailable) {
+			// Issue #503: the overlay models.json could not be read at this pickup for a transient reason, so the gate has no
+			// verdict for a provider that may be keyless. Retried, never refused: a refusal is permanent and public, and the
+			// next attempt may read the file. The code is a fixed errno token, never file text.
+			log("provider_credential_unavailable", { provider: job.provider ?? null, reason: credential.unavailable });
+			throw new InfraRetry("the provider credential could not be decided", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
+		}
 		if (!credential.ok) {
 			// The PROVIDER is named and the message is not. The provider is operator-authored config, already
 			// on the record and the mirror, and named freely by the sibling refusals (`backend-unblessed` names
@@ -732,7 +953,16 @@ export async function runJob(job, deps) {
 		//
 		// Guarded by `secretsArmed` at the CALL SITE, not inside the resolver: an unflagged job must not reach
 		// it under ANY wiring, and a guard that lives in the default is a guard an injected resolver skips.
-		const resolved = secretsArmed(job) ? await resolveSecrets(job) : { ok: true, secrets: {} };
+		//
+		// The load-time reserved names are asked again HERE, of the job itself, for the same reason (issue
+		// #511). parseTriggers refuses them when the file loads, but a job does not always come from a file
+		// this worker loaded: one queued before an upgrade widened the set, a cron job-scheduler template
+		// stored in Valkey (schedules.mjs keeps `run.secrets` in it), or a receiver older than the worker all
+		// carry `secrets` the current set would refuse, and buildContainerEnv would write every one of them.
+		// The same set the loader uses, imported, so the two cannot drift, and checked before the resolver so
+		// no wiring of it can skip the check.
+		const loadReserved = secretsArmed(job) ? Object.keys(job.secrets ?? {}).find((name) => RESERVED_ENV_NAMES.has(name)) : undefined;
+		const resolved = loadReserved !== undefined ? { reserved: loadReserved, atLoad: true } : secretsArmed(job) ? await resolveSecrets(job) : { ok: true, secrets: {} };
 		if (resolved.profileUnknown) {
 			await comment(job, "Refused: this trigger set `run.secrets`, and the resolver profile it names is not usable on this worker host. No profile of that name is declared, or its resolver is absent or not executable. The job would have started with those variables unset, and an agent that gets a 401 writes a plausible report and exits 0. Run `pi-dispatch doctor` on the worker to see which profiles it has. Not run.");
 			// The operator's own profile LABEL, and never a path, a reference, or a byte the resolver printed.
@@ -771,7 +1001,14 @@ export async function runJob(job, deps) {
 			//     (apiKeyVariable skips both), so a trigger binding one lands beside the operator's key and
 			//     outranks it in pi's own precedence.
 			// The old message asserted the first for both, which is exactly backwards for the second.
-			await comment(job, `Refused: this trigger's \`run.secrets\` binds \`${resolved.reserved}\`, which is a variable this deployment already uses for the job's own credentials. Whichever of the two values reached the container, one of them would be silently ignored. Rename it in the triggers file. Not run.`);
+			// A name the triggers file itself would refuse at load (issue #511) reaches here only from a job
+			// queued before that refusal, a stored cron scheduler template, or an older receiver, so it says that.
+			await comment(
+				job,
+				resolved.atLoad
+					? `Refused: this job's \`run.secrets\` binds \`${resolved.reserved}\`, a name the triggers file refuses at load because this deployment writes it or pi reads it to configure a provider or itself. The job was queued before that refusal applied, by a stored cron schedule, or by an older receiver. Rename it in the triggers file. Not run.`
+					: `Refused: this trigger's \`run.secrets\` binds \`${resolved.reserved}\`, which is a variable this deployment already uses for the job's own credentials. Whichever of the two values reached the container, one of them would be silently ignored. Rename it in the triggers file. Not run.`,
+			);
 			// The variable NAME only. It is the operator's own choice of name, not payload, and naming it is what
 			// makes the refusal actionable -- but the REFERENCE behind it never appears.
 			log("refused_secret_name_reserved", { kind: job.kind ?? null, name: resolved.reserved });
@@ -797,7 +1034,7 @@ export async function runJob(job, deps) {
 			// than by matching its stderr, which image-preflight.mjs forbids for good reason. Folding this into
 			// the refusal above would permanently burn a delivery over a twenty-second vault blip, and a webhook
 			// does not redeliver itself. Nothing has spent: `budgetReserved` computes false in the catch below
-			// because `reserved` is still false here.
+			// because no ledger is held yet.
 			log("secret_resolver_unreachable", { kind: job.kind ?? null, name: resolved.unreachable, failure: resolved.failure ?? null, code: resolved.code ?? null, stderrBytes: resolved.stderrBytes ?? 0 });
 			throw new InfraRetry(`secret resolver could not answer for ${resolved.unreachable}`, { reason: "secret-resolver-unreachable", provider: job.provider ?? null, model: job.model ?? null });
 		}
@@ -828,16 +1065,35 @@ export async function runJob(job, deps) {
 		}
 
 		// `podmanStore` (issue #429) only where the venue's job user carried one: the podman store the container ran in.
-		prepared = await prepareWorkspace(job, token, { piVersion, jobUser: { user: jobUser?.user ?? null, home: jobUser?.home ?? null }, ...(typeof jobUser?.store === "string" ? { podmanStore: jobUser.store } : {}) }); // resolves SHA, clones, materialises .pi/, writes prompt
+		// `portfolio` (issue #505) only for a job the gate above confirmed: prepare then writes /job/portfolio.json, after
+		// asking the live file once more. Absent otherwise, so every other job's prepare call is unchanged.
+		prepared = await prepareWorkspace(job, token, { piVersion, jobUser: { user: jobUser?.user ?? null, home: jobUser?.home ?? null }, ...(typeof jobUser?.store === "string" ? { podmanStore: jobUser.store } : {}), ...(portfolio ? { portfolio: true } : {}) }); // resolves SHA, clones, materialises .pi/, writes prompt
 
 		// A determinate prepare refusal -- sha-gone (the default branch advanced past the resolved tip),
 		// or a `pi-*` materialiser cap breach (the repo's .pi/ is too large to place in /job, issue #60)
 		// -- is POLICY: return before reserveBudget so it burns no cap slot and is never retried.
 		// Mirrors the branch-protection policy return above. Spread-plus-attribution: the prepare
 		// result keeps its own reason and fields, and the host-effective provider/model land beside
-		// them exactly as on every other terminal result.
+		// them exactly as on every other terminal result. `budgetReserved: false` like every pre-reserve refusal (issue
+		// #507): nothing was reserved and no container started, so the record says so and the cost fold counts the run as
+		// an exact $0 rather than a floor (REQ-COST-ANALYTICS (d)). After the spread, so no preparer can say otherwise.
 		if (prepared?.outcome === "policy") {
-			return { ...prepared, provider: job.provider ?? null, model: job.model ?? null };
+			return { ...prepared, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false };
+		}
+
+		// THE RESOLVED FOLDER'S PROJECT (issue #504 part B). The pickup decided the project, and so the share a job reserves
+		// against, from the folder AS NAMED; the container mounts the folder prepare RESOLVED. A link or a case variant
+		// inside a run root that leads into ANOTHER project's member would bill that work to the named project's share.
+		// Refused here, after prepare and before the token-cap read and every reserve: free, determinate, never retried. A
+		// resolved folder in no project is not refused, because the named spelling is the operator's own membership
+		// (a symlinked member is listed by the path the triggers use, docs/projects.md).
+		if (job.kind === "local" && typeof folderProject === "function" && typeof prepared?.workspace === "string") {
+			const resolvedProject = folderProject(prepared.workspace);
+			if (resolvedProject !== null && resolvedProject !== pickupProject) {
+				await comment(job, "Refused: this job's folder now leads into another project's folder, so no container was started and nothing was spent. Not run.");
+				log("refused_local_folder_project_changed", { pickup: pickupProject, resolved: resolvedProject });
+				return { outcome: "policy", reason: LOCAL_FOLDER_PROJECT_CHANGED, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
 		}
 
 		// Daily TOKEN cap (issue #25): the deliberate check-AFTER control. Token cost is only known
@@ -857,75 +1113,169 @@ export async function runJob(job, deps) {
 			return { outcome: "policy", reason: "daily-token-cap", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
 		}
 
-		// Per-scope budget windows (issue #242, INT-SCOPED-LIMITS-FILE-CONTRACT): the NARROWER ledger
-		// reserves FIRST, so a noisy scope's refusals never consume a global slot -- the global INCR below
-		// runs only for jobs the scope admitted. Same atomic INCR, same refused-still-counts invariant,
-		// through budget.mjs's keyPrefix seam (dayKey/weekKey/monthKey under budget:s:<hash16>). softHoldPct
-		// is deliberately GLOBAL-ONLY: the band is one operator brake on overall spend, not a per-row knob;
-		// scoped windows are hard caps (DES-SCOPED-LIMITS-AND-FOLDER-MUTEX).
-		if (scopedCaps) {
-			// A redis fault BETWEEN this reserve and the global one below strands the scoped INCR with no
-			// run and no refund -- the pre-existing mid-reserve posture, shared with the global ledger's
-			// own partial-INCR seam; the compensating release below covers REFUSALS, not faults.
-			const scoped = await reserveBudget(redis, { caps: scopedCaps.caps, now, keyPrefix: scopeKeyPrefix(scopedCaps.scope) });
-			scopedReserved = true;
-			if (!scoped.allowed) {
-				const w = scoped.blockedWindow;
-				const win = scoped.windows[w];
-				// A local job's scope is a full host path and its "comment" is not dropped -- the wiring's
-				// local adapter LOGS the text (start.mjs forgeFor fallthrough) -- so the path must never
-				// enter the message; "this folder" is enough beside the jobId the adapter logs. A forge
-				// scope IS the repo the comment posts on, safe to name.
-				const scopeLabel = job.kind === "local" ? "this folder" : scopedCaps.scope;
-				await comment(job, `Over the ${w} run cap for ${scopeLabel} (${win.cap}). Not run.`);
-				// The scope rides the log as its 16-hex key, NEVER the raw string: a folder-scoped cap would
-				// put a full host path in the worker log against no-pii-in-logs (the record keeps only
-				// basename(folder) for the same reason). The admin recomputes the key from the configured
-				// scope to join it back.
-				log("over_scope_budget", { scopeKey: scopeKeyPrefix(scopedCaps.scope), window: w, reserved: win.reserved, cap: win.cap, kind: job.kind === "local" ? "local" : "forge" });
-				// budgetReserved false: the GLOBAL slot was never touched (scoped reserves first). The scoped
-				// counter did INCR and keeps it -- its own refused-reservation-still-counts, per ledger.
-				return { outcome: "policy", reason: "scope-cap", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		// The JOB-COUNT ledgers (issues #242 and #499 part B, INT-SCOPED-LIMITS-FILE-CONTRACT), narrowest first: the repo
+		// or folder row, the project row, then the global windows, reserved in that order by ONE helper. A narrow
+		// ledger's refusal never consumes a slot in a wider one -- the global INCR runs only for jobs every scoped ledger
+		// admitted, and a project's only for jobs their repo admitted. Same atomic INCR, same refused-still-counts
+		// invariant per ledger, through budget.mjs's keyPrefix seam (budget:s:<hash16> of the row scope). softHoldPct is
+		// deliberately GLOBAL-ONLY: the band is one operator brake on overall spend, not a per-row knob; scoped windows
+		// are hard caps (DES-SCOPED-LIMITS-AND-FOLDER-MUTEX).
+		//
+		// A redis fault mid-walk gives back every LEDGER that landed whole (`held` is exact) and rethrows. Inside the
+		// ledger that faulted, the windows INCRed before the fault stay counted (a week INCR that faults leaves that
+		// ledger's day counted, an EXPIRE that faults leaves its key without a TTL): `reserveBudget` does not say which of
+		// its windows landed, so giving them back could DECR a window that never rose. That is the pre-existing
+		// mid-reserve posture of one ledger, unchanged.
+		globalLedger = { scope: null, keyPrefix: null, caps, softHoldPct, reason: null };
+		let counted;
+		try {
+			counted = await reserveLedgers(redis, [...(scopedLedgers ?? []), globalLedger], held, { now });
+		} catch (error) {
+			// Valkey failed mid-walk. No container can have started, and `held` lists exactly the reservations that
+			// landed, so they go back (last first, never throwing) before the error escapes; otherwise a repo and a
+			// project slot would stay counted for a job that never ran.
+			await refundLedgers("reserve-fault");
+			throw error;
+		}
+		if (!counted.allowed) {
+			// Every ledger BEFORE the refusing one gives its slot back, last first: a ledger that did not issue the
+			// refusal gives back. Without this, an exhausted global window drains every arriving scope's and project's own
+			// counters with zero runs to show for it, and a full project drains its members' repo windows. The refusing
+			// ledger keeps its own slot (refused-still-counts, per ledger).
+			await refundLedgers(counted.refusedBy.reason ?? counted.result.reason);
+			const result = counted.result;
+			const w = result.blockedWindow;
+			const win = result.windows[w];
+			if (counted.refusedBy === globalLedger) {
+				if (result.reason === "soft-hold") {
+					await comment(job, `Soft-hold: ${w} spend ${win.reserved}/${win.cap} is inside the ${softHoldPct}% hold band. New starts paused; not run.`);
+					log("soft_hold", { window: w, reserved: win.reserved, cap: win.cap, pct: softHoldPct });
+				} else {
+					await comment(job, `Over the ${w} budget cap (${win.cap}). Not run.`);
+					log("over_budget", { window: w, reserved: win.reserved, cap: win.cap });
+				}
+				// budgetReserved true: the global slot is reserved and kept (a refused reservation still counts). Both
+				// over-budget and soft-hold are POLICY, RETURNED (not retried) -- the agent never ran.
+				return { outcome: "policy", reason: result.reason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: true }; // return => not retried
 			}
+			const isProject = counted.refusedBy.reason === PROJECT_CAP_REASON;
+			// A local job's scope is a full host path and its "comment" is not dropped -- the wiring's local adapter LOGS
+			// the text (start.mjs forgeFor fallthrough) -- so the path must never enter the message; "this folder" is enough
+			// beside the jobId the adapter logs. A forge scope IS the repo the comment posts on, safe to name, and named
+			// without a forge prefix (issue #498). A project is "this project": the comment's reader may be an issue
+			// author, and which repos an operator groups is the operator's business, not theirs.
+			const scopeLabel = isProject ? "this project" : job.kind === "local" ? "this folder" : unqualifiedScope(counted.refusedBy.scope);
+			await comment(job, `Over the ${w} run cap for ${scopeLabel} (${win.cap}). Not run.`);
+			// The scope rides the log as its 16-hex key, NEVER the raw string: a folder-scoped cap would put a full host
+			// path in the worker log against no-pii-in-logs. The admin recomputes the key from the configured scope. A
+			// project refusal adds `ledger: "project"`; a repo or folder one keeps the line it always had.
+			log("over_scope_budget", { scopeKey: counted.refusedBy.keyPrefix, ...(isProject ? { ledger: "project" } : {}), window: w, reserved: win.reserved, cap: win.cap, kind: job.kind === "local" ? "local" : "forge" });
+			// budgetReserved false: the GLOBAL slot was never touched (every scoped ledger reserves first).
+			return { outcome: "policy", reason: counted.refusedBy.reason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
 		}
 
-		// GLOBAL budget last-but-before-container. A refusal here spends nothing (no container starts). Reserves across
-		// every active window (day + optional week/month) and the soft-hold band in one atomic pass.
-		const budget = await reserveBudget(redis, { caps, softHoldPct, now });
-		reserved = true;
-		if (!budget.allowed) {
-			// The scoped reserve above committed before this global refusal -- give that slot back. Without
-			// this, an exhausted global window drains every arriving scope's own day/week/month counters
-			// with zero runs to show for it (a storm against a spent global daily cap would empty a repo's
-			// week by noon). The scoped ledger's refused-still-counts covers the SCOPE's own refusal above,
-			// never a refusal it did not issue.
-			if (scopedReserved && scopedCaps) {
-				await releaseBudget(redis, { caps: scopedCaps.caps, now, keyPrefix: scopeKeyPrefix(scopedCaps.scope) });
-				// CLEARED, so the ledger's state and the flag agree. Nothing between here and the return can
-				// throw today (`comment` is non-throwing by construction and `log` is a write), but the catch
-				// below now releases on a whole CLASS of error rather than one reason, and a second release
-				// against this same key would take it to -1: `releaseBudget` is a floorless DECR. The invariant
-				// belongs where the release is, not in the guard of every future reader.
-				scopedReserved = false;
-			}
-			const w = budget.blockedWindow;
-			const win = budget.windows[w];
-			if (budget.reason === "soft-hold") {
-				await comment(job, `Soft-hold: ${w} spend ${win.reserved}/${win.cap} is inside the ${softHoldPct}% hold band. New starts paused; not run.`);
-				log("soft_hold", { window: w, reserved: win.reserved, cap: win.cap, pct: softHoldPct });
+		// DOLLAR windows (issue #501, part 3), after EVERY job-count reserve and before the container: the last gate
+		// before the spend line (CONST-BUDGET-BEFORE-TOKENS). Every free gate and every job-count ledger come first, so
+		// a refusal anywhere above never touches a dollar counter. The amount is the job's per-job cost cap, which the
+		// runner enforces before every call, so it bounds what the run can spend; the worker needs no prices.
+		let containerJob = job;
+		// Every dollar ledger this job reserves in: the deployment's windows, its repo or folder row's, and each model
+		// row it may reach (scoped-limits.json version 2). ONE reservation over all of them, so a refusal in any window
+		// gives back every key, the deployment's included.
+		const ledgers = dollarLedgers(dollarCaps, { scope: scopedDollars, project: projectDollars, other: otherDollars, models: modelDollars });
+		const modelPrefixes = new Map((modelDollars ?? []).map((m) => [m.keyPrefix, m.ref]));
+		// The ledgers that settle to the JOB's cost (the deployment's, the repo or folder row's, the project row's), named
+		// rather than derived as "not a model", so a ledger kind added later settles nowhere until it is put on a list.
+		// `_other`'s ledger (issue #504 part B) settles to the job's cost too: its counter is what the unassigned work spent.
+		const jobCostPrefixes = new Set([DOLLAR_KEY_PREFIX, scopedDollars?.keyPrefix, projectDollars?.keyPrefix, otherDollars?.keyPrefix].filter((p) => typeof p === "string"));
+		if (ledgers.length > 0) {
+			// A window needs a per-job cap (the settings invariant, `checkDollarInvariant`; for a scoped or model row, the
+			// same rule), so a job with none here is a defect, a hand-built queue entry, or a dollar row in
+			// scoped-limits.json on a deployment with no `maxCostUsd`: refused as configuration, before anything is
+			// reserved, and the config arm below refunds every job-count slot.
+			if (job.maxCostMicros === null || job.maxCostMicros === undefined) throw configError("a dollar window is set but this job has no per-job cost cap to reserve");
+			// Issue #503 part 7: a job that CANNOT spend reserves nothing. Every model it may call is served by a declared
+			// endpoint and zero-rated, so its container runs under a per-job cap of 0, which the runner's cost guard holds
+			// before every call: a call whose bound is above 0 is refused, so the job's spend is 0 by construction, not
+			// by trust in the cost table. The capability gate above already required `costCap` of this job's image (the
+			// job carried a non-null cap), so an image that would ignore the 0 never gets here. A cap that is ALREADY 0
+			// (a malformed queued value reads as 0, `effectiveCostCapMicros`) has nothing to reserve either.
+			const refs = callableModelRefs(job);
+			const zero = job.maxCostMicros === 0 ? { zeroRated: true } : zeroRatedVerdict({ models: modelEndpoints?.models ?? null, endpoints: modelEndpoints?.endpoints ?? [], refs, builtinModel });
+			if (zero.zeroRated) {
+				containerJob = { ...job, maxCostMicros: 0 };
+				dollars = dollarsRecord({ reservedMicros: 0, settledMicros: 0, basis: "unreserved" });
+				log("dollar_unreserved", { models: refs.length });
 			} else {
-				await comment(job, `Over the ${w} budget cap (${win.cap}). Not run.`);
-				log("over_budget", { window: w, reserved: win.reserved, cap: win.cap });
+				let reservation;
+				try {
+					reservation = await reserveDollars(redis, { ledgers, amountMicros: job.maxCostMicros, now, log });
+				} catch (error) {
+					// Valkey did not answer. reserveDollars tried to give back what it had added, key by key (a key it could
+					// not is logged, dollar_giveback_error), so nothing is held by this job; the job-count
+					// slots are refunded by the never-started arm below, and the job is retried: nothing started.
+					log("dollar_reserve_error", { code: typeof error?.code === "string" ? error.code : "error" });
+					throw new InfraRetry("the dollar windows could not be reserved", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
+				}
+				if (!reservation.allowed) {
+					// Refused, and every dollar key it touched given back, best effort per key (the departure from the job-count
+					// rule, see dollar-budget.mjs; a key that could not be is logged and the record says floor). Every held
+					// job-count slot goes back too, last first: a ledger that did not issue the refusal gives back, the rule
+					// the count ledgers follow among themselves above.
+					// WHOSE NUMBER bound (issue #504 part B): `allocation-cap` when the refusing window's cap came from the applied split
+					// or the envelope total (`capSource`), `dollar-cap` when it was the operator's own (a tie is the operator's). One
+					// ledger and one window refused, and the reservation names both.
+					const capSourceOf = (prefix) => (prefix === DOLLAR_KEY_PREFIX ? dollarCapSource : [scopedDollars, projectDollars, otherDollars].find((l) => l?.keyPrefix === prefix)?.capSource);
+					const byAllocation = capSourceOf(reservation.ledger)?.[reservation.window] === "allocation";
+					const refusalReason = byAllocation ? ALLOCATION_CAP_REASON : DOLLAR_CAP_REASON;
+					const refunded = await refundLedgers(refusalReason);
+					// The window is named and the amounts are not: the comment's reader may be an issue author, and the
+					// amounts are the operator's, which the log carries. Which ledger refused is named too: the deployment,
+					// the repo (a forge scope IS the repo the comment posts on), "this folder" (a local scope is a host path,
+					// kept out of the comment and the log), or the model (operator configuration, never payload). The log
+					// names a scoped or model ledger by its key prefix, a hash, never the scope string.
+					const period = { day: "today's", week: "this week's", month: "this month's" }[reservation.window] ?? "a";
+					// Two different states, told apart (PR #549's review): a window whose cap is BELOW one job's cap refuses every
+					// such job until the operator changes a setting, which "no room left" would hide behind a wait that never ends.
+					const capBelowJob = reservation.capMicros < job.maxCostMicros;
+					// A project window (issue #499 part B) is "this project", for the job-count refusal's reason.
+					const refusedBy = reservation.ledger === DOLLAR_KEY_PREFIX ? "deployment" : modelPrefixes.has(reservation.ledger) ? "model" : reservation.ledger === projectDollars?.keyPrefix ? "project" : reservation.ledger === otherDollars?.keyPrefix ? "other" : "scope";
+					const whose = refusedBy === "deployment" ? "this deployment" : refusedBy === "model" ? `the model ${modelPrefixes.get(reservation.ledger)}` : refusedBy === "project" ? "this project" : refusedBy === "other" ? "the work outside the budget split's projects" : job.kind === "local" ? "this folder" : unqualifiedScope(scopedDollars.scope);
+					// The allocation's own words (issue #504 part B): the number that bound is the split inside the operator's envelope,
+					// which moves with the next priorities plan or an envelope edit, so this text never tells its reader to raise a budget.
+					const adjective = { day: "daily", week: "weekly", month: "monthly" }[reservation.window] ?? "";
+					const allocationText = capBelowJob
+						? `Refused: the ${adjective} share of the budget split for ${whose} is smaller than this run's cost limit, so no container was started and nothing was spent. The split changes with the next priorities plan or an envelope change. Not run.`
+						: `Refused: ${period} share of the budget split for ${whose} has no room left for this run's cost limit, so no container was started and nothing was spent. Not run.`;
+					await comment(
+						job,
+						byAllocation
+							? allocationText
+							: capBelowJob
+							? `Refused: the ${{ day: "daily", week: "weekly", month: "monthly" }[reservation.window] ?? ""} dollar budget for ${whose} is smaller than this run's cost limit, so no run with this limit can start until the operator raises the budget or lowers the limit. No container was started and nothing was spent. Not run.`
+							: `Refused: ${period} dollar budget for ${whose} has no room left for this run's cost limit, so no container was started and nothing was spent. Not run.`,
+					);
+					log("over_dollar_budget", { ledger: refusedBy, ...(refusedBy === "deployment" ? {} : { key: reservation.ledger }), ...(refusedBy === "model" ? { model: modelPrefixes.get(reservation.ledger) } : {}), window: reservation.window, reservedMicros: reservation.reservedMicros, capMicros: reservation.capMicros, amountMicros: job.maxCostMicros, ...(capBelowJob ? { capBelowJob: true } : {}), ...(byAllocation ? { source: "allocation" } : {}), refunded });
+					const stranded = reservation.stranded > 0;
+					const modelBasis = modelPrefixes.size === 0 ? null : stranded ? "floor" : "refunded";
+					return { outcome: "policy", reason: refusalReason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: globalHeld(), dollars: stranded ? dollarsRecord({ reservedMicros: job.maxCostMicros, settledMicros: job.maxCostMicros, basis: "floor", modelBasis }) : dollarsRecord({ reservedMicros: job.maxCostMicros, settledMicros: 0, basis: "refunded", modelBasis }) }; // return => not retried
+				}
+				dollarHold = reservation.hold;
+				dollars = dollarsRecord({ reservedMicros: job.maxCostMicros, settledMicros: job.maxCostMicros, basis: "floor", modelBasis: modelPrefixes.size > 0 ? "floor" : null });
 			}
-			// budgetReserved true: the slot is reserved above and kept (a refused reservation still counts). Both
-			// over-budget and soft-hold are POLICY, RETURNED (not retried) -- the agent never ran.
-			return { outcome: "policy", reason: budget.reason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: true }; // return => not retried
 		}
 
 		// The user the gate above decided is the user that runs: one answer, never two call sites that agree.
-		const { code, aborted, abortReason, turns, tokens, session, usage, context, detached, exitReason } = await runContainer({ job, token, prepared, secrets, user: jobUser?.user ?? null, home: jobUser?.home ?? null, relabel: jobUser?.relabel === true });
+		// Issue #545: an image that declares `exitAuth` is handed a per-job key on stdin and signs its exit line with it, and
+		// then only a signed line is read (run-container.mjs, run-history.mjs `authenticExitLines`). An image that does not
+		// declare it is read as before, under the #542 trust rule below alone.
+		const exitAuth = (img.capabilities ?? []).includes(EXIT_AUTH_CAPABILITY);
+		const { code, aborted, abortReason, turns, tokens, session, usage, context, detached, exitReason, exitWhy = null, exitLineCode = null, exitAuth: exitAuthResult = null } = await runContainer({ job: containerJob, token, prepared, secrets, user: jobUser?.user ?? null, home: jobUser?.home ?? null, relabel: jobUser?.relabel === true, ...(modelEndpoints?.endpoints?.length > 0 ? { modelEndpoints } : {}), ...(exitAuth ? { exitAuth: true } : {}) });
 		containerRan = true;
-		log("container_exit", { exitCode: code, aborted, ...(detached === true ? { detached: true } : {}) });
+		// `exitAuth: "unverified"` is a run whose image signs its exit line and no signed line was found: the runner died
+		// before writing one, or a line was forged or taken off the pipe. Its tokens read as unknown and its dollars settle
+		// at the floor, the same as a container that wrote no exit line at all.
+		log("container_exit", { exitCode: code, aborted, ...(detached === true ? { detached: true } : {}), ...(exitAuthResult !== null ? { exitAuth: exitAuthResult } : {}) });
 
 		// Record token spend post-run (the check-AFTER half of the lagging token cap). The container ran,
 		// so it spent real tokens on EVERY path that reaches here -- abort, completed, policy, AND the infra
@@ -938,12 +1288,53 @@ export async function runJob(job, deps) {
 			await recordSpend(redis, tokensSpent, { now }).catch((err) => log("token_spend_error", { reason: err?.message }));
 		}
 
+		// SETTLE the dollar reservation (issue #501, part 4), ONCE, here, for every exit where the container ran:
+		// completed, runner policy, a worker abort or cancel, exit 1, an unknown exit, and a detached container. A
+		// never-started exit is not settled: the catch refunds it whole, and `isNeverStartedExit` is the one answer both
+		// ask. Before any classification below, so every return and every throw carries the same `dollars`.
+		const neverStarted = isNeverStartedExit({ code, aborted, detached }, neverStartedExits(job));
+		if (dollarHold !== null && !neverStarted) {
+			// The exit line is trusted only when the container exited ON ITS OWN (the worker did not abort, cancel, time
+			// out or detach it, so the runner had the chance to write its genuine last line) AND that line's own `code` is
+			// the container's real exit code (PR #542's review, round 3: a job's tool can forge a $0 line before a stop).
+			const trusted = !aborted && detached !== true && Number.isSafeInteger(exitLineCode) && exitLineCode === code;
+			const reservedMicros = dollarHold.amountMicros;
+			const { settledMicros, basis } = dollarSettlement({ tokens, usage: usage ?? null, reservedMicros, trusted });
+			// The deployment, the repo or folder and the project windows settle to the job's cost; each model window to its
+			// own row of the usage ledger (`modelDollarSettlement`), never to the job's total.
+			const jobPart = holdPart(dollarHold, (prefix) => jobCostPrefixes.has(prefix));
+			const { applied, of } = await settleDollars(redis, jobPart, settledMicros, { log });
+			let modelBasis = null;
+			for (const part of dollarHold.ledgers ?? []) {
+				const ref = modelPrefixes.get(part.keyPrefix);
+				if (ref === undefined) continue;
+				const m = modelDollarSettlement({ ref, basis, tokens, usage: usage ?? null, reservedMicros, trusted });
+				const done = await settleDollars(redis, { amountMicros: reservedMicros, keys: part.keys }, m.settledMicros, { log });
+				// The deployment rule below, per model window: a fault that adjusted none of its keys left the reservation.
+				const mBasis = done.applied === 0 && done.of > 0 && m.settledMicros !== reservedMicros ? "floor" : m.basis;
+				modelBasis = modelBasis === "floor" || mBasis === "floor" ? "floor" : "metered";
+				// The model is operator configuration (a scoped-limits row), and the key a hash; no value but the amounts.
+				log("dollar_model_settled", { model: ref, key: part.keyPrefix, settledMicros: m.settledMicros, basis: mBasis });
+			}
+			// A fault that adjusted no key leaves the whole reservation in every window, which is a floor whatever the
+			// basis would have been, and the record says so. A partial one is logged (dollar_settle_error) and recorded
+			// as computed: the keys that were adjusted hold the settled amount.
+			dollars = applied === 0 && of > 0 && settledMicros !== reservedMicros ? dollarsRecord({ reservedMicros, settledMicros: reservedMicros, basis: "floor", modelBasis }) : dollarsRecord({ reservedMicros, settledMicros, basis, modelBasis });
+			dollarHold = null;
+			log("dollar_settled", { reservedMicros: dollars.reservedMicros, settledMicros: dollars.settledMicros, basis: dollars.basis, ...(modelBasis !== null ? { modelBasis } : {}) });
+		} else if (dollars?.basis === "unreserved") {
+			// Nothing was held, so nothing is written. A metered cost above 0 here would mean the runner's cap of 0 let a
+			// priced call through, which it cannot by construction; it is logged so it cannot pass unseen.
+			const spent = meteredMicros(tokens?.cost);
+			if (spent !== null && spent > 0) log("dollar_unreserved_spent", { meteredMicros: spent });
+		}
+
 		// Issue #345: `docker run` exited with a never-started code, but THIS attempt's container was found by its cidfile,
 		// still there, and was stopped and removed (run-container.mjs, measured on Podman with its API service killed
 		// mid-job). It DID start, so this is never refunded as never-started: it keeps its slot and retries as infrastructure,
 		// BEFORE the exit-code switch, where the same code would read as a free never-started exit.
 		if (detached === true) {
-			throw new InfraRetry(`the container outlived its docker run, exit ${code}`, { reason: "container-detached", exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session) });
+			throw new InfraRetry(`the container outlived its docker run, exit ${code}`, { reason: "container-detached", exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars });
 		}
 
 		// A WORKER-initiated stop (30-min timeout via cancelJob, graceful-shutdown docker stop, or an
@@ -961,7 +1352,7 @@ export async function runJob(job, deps) {
 			// Awaited bare like every determinate refusal above: the adapter never throws by contract, and
 			// the one swallowed comment in this file (the catch's) justifies itself by its position.
 			await comment(job, TERMINAL_COMMENTS[reason]);
-			return { outcome: "policy", reason, exitCode: code, turns, tokens, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true };
+			return { outcome: "policy", reason, exitCode: code, turns, tokens, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true, ...(dollars ? { dollars } : {}) };
 		}
 
 		switch (code) {
@@ -972,6 +1363,10 @@ export async function runJob(job, deps) {
 				// over-budget, infra): an InfraRetry job is retried, so chaining there would double-enqueue.
 				// collectChain never throws; chainEnqueued/chainRefused are additive telemetry only.
 				const chain = await collectChain({ job, prepared });
+				// Issue #505: the plan, after the chain and on this branch only, for the reason the chain is here: a policy or
+				// infra exit collects nothing, and a retried job must not apply what its failed attempt wrote. `portfolio` is
+				// the pickup's decision; the collector asks the live file again, and both must agree. Never throws.
+				const plan = await collectPlan({ job, prepared, portfolio });
 				// COMPLETED-ONLY PROMOTION, and the exclusivity is the point rather than an optimisation.
 				// A policy or infra exit leaves the canonical transcript byte-identical to what it was
 				// before this run, so a retry starts from exactly what the first attempt did -- promote on
@@ -995,6 +1390,10 @@ export async function runJob(job, deps) {
 					budgetReserved: true,
 					chainEnqueued: chain.enqueued,
 					chainRefused: chain.refused,
+					...(dollars ? { dollars } : {}),
+					// Only when the collector returned a plan (a file, or a confirmed portfolio job with none, `plan-absent`): the
+					// record's `plan` is null otherwise, and every other result is unchanged.
+					...(plan ? { plan } : {}),
 				};
 			}
 			case EXIT_POLICY: {
@@ -1017,7 +1416,11 @@ export async function runJob(job, deps) {
 				// Every other reason the runner gives still reads as runner-policy.
 				const reason = RUNNER_POLICY_REASONS.has(exitReason) && code === 2 ? exitReason : "runner-policy";
 				await comment(job, TERMINAL_COMMENTS[reason]);
-				return { outcome: "policy", reason, exitCode: code, turns, tokens, usage: usage ?? null, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true };
+				// Issue #507: which rule of the cost guard refused (`unboundable`, `external`, `over-cap`), as the record's
+				// `why`. parseExitWhy keeps only a member of the closed COST_CAP_WHYS off a `cost-cap` line that said code 2,
+				// and it rides only beside a `cost-cap` reason, so a forged line can at worst name the wrong rule of three.
+				const why = reason === "cost-cap" && COST_CAP_WHYS.includes(exitWhy) ? { why: exitWhy } : {};
+				return { outcome: "policy", reason, exitCode: code, turns, tokens, usage: usage ?? null, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), budgetReserved: true, ...(dollars ? { dollars } : {}), ...why };
 			}
 			case EXIT_INFRA:
 				// NO comment on any infra throw, here or in the catch: an InfraRetry may be retried and
@@ -1025,7 +1428,7 @@ export async function runJob(job, deps) {
 				// the whole infra class lives at the terminal seam -- start.mjs's failed listener, guarded on
 				// BullMQ's own finishedOn -- which also catches the stall-kill and wait-gate paths this
 				// function never sees (issue #288).
-				throw new InfraRetry(`infra failure, container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session) });
+				throw new InfraRetry(`infra failure, container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars });
 			default:
 				// THE RUNTIME NEVER HANDED CONTROL TO THE RUNNER, in whatever integers this venue spells that
 				// (issue #227). For docker it is 125 (`docker run` itself failed), 126 (the entrypoint exists
@@ -1039,10 +1442,11 @@ export async function runJob(job, deps) {
 				// silently wrong for any venue where 125 is a real runner exit, and the assumption was
 				// invisible while there was one runtime. An adapter declares its own set, or declares none
 				// and normalises to this outcome itself.
-				if ((neverStartedExits(job) ?? []).includes(code)) {
+				if (neverStarted) {
+					// No `dollars` here: the hold is still standing, and the catch refunds it whole with the job-count slots.
 					throw new InfraRetry(`the runtime could not start the container, exit ${code}`, { reason: "container-never-started", exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session) });
 				}
-				throw new InfraRetry(`unknown container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session) });
+				throw new InfraRetry(`unknown container exit ${code}`, { exitCode: code, turns, tokens, usage, provider: job.provider ?? null, model: job.model ?? null, session: mergeSession(prepared, session), dollars });
 		}
 	} catch (e) {
 		// A CONFIG-tagged throw is a determinate policy refusal wearing an exception, and issue #310 is the
@@ -1059,35 +1463,50 @@ export async function runJob(job, deps) {
 		// this project exists to make legible.
 		//
 		// Refunding is right BECAUSE no container started: identical to `container-never-started`, and the
-		// same both-or-neither pair, under the same `reserved`/`scopedReserved` guards so it still cannot
-		// double-release. The gate above catches the provider case for free, before the mint and the clone;
+		// same all-or-none refund of every held job-count ledger, through the same `releaseLedgers` list, so it still
+		// cannot double-release. The gate above catches the provider case for free, before the mint and the clone;
 		// this is the backstop for every other config throw that can still land here (an unknown forge kind in
 		// `buildContainerEnv`, a prepare-time refusal), which would otherwise keep the same slot silently.
 		// `!containerRan` is the discriminator, and it is what makes the refund and the sentence below TRUE
 		// rather than merely true today. Every config-tagged throw site in the worker is pre-container, so this
 		// changes nothing now; the day one is added after a paid run, that run keeps its slot and falls through
 		// to the untagged path instead of being refunded and publicly declared free.
+		// Issue #501: a dollar hold still standing here was neither settled nor refunded. Two kinds of throw give it back
+		// whole, because no container ran: never-started (the arm below) and config-refused (the next arm). Any other
+		// throw may have followed a container that ran (runContainer itself throwing, a defect), so the hold STAYS, the
+		// floor, which errs toward overcounting, and `dollar_hold_unsettled` says so. Released FIRST and never throwing
+		// (releaseDollars), so a Valkey fault cannot replace either arm's classification.
+		if (dollarHold !== null) {
+			const hold = dollarHold;
+			dollarHold = null;
+			if ((e?.piDispatchConfig === true && !containerRan) || isNeverStartedRetry(e)) {
+				const { applied, of } = await releaseDollars(redis, hold, { log });
+				const heldModel = (hold.ledgers ?? []).some((l) => modelPrefixesOf(modelDollars).has(l.keyPrefix));
+				dollars = dollarsRecord({ reservedMicros: hold.amountMicros, settledMicros: applied === of ? 0 : hold.amountMicros, basis: applied === of ? "refunded" : "floor", modelBasis: heldModel ? (applied === of ? "refunded" : "floor") : null });
+			} else {
+				log("dollar_hold_unsettled", { reservedMicros: hold.amountMicros, error: e instanceof InfraRetry ? "infra-retry" : (e?.name ?? "error") });
+				const heldModel = (hold.ledgers ?? []).some((l) => modelPrefixesOf(modelDollars).has(l.keyPrefix));
+				dollars = dollarsRecord({ reservedMicros: hold.amountMicros, settledMicros: hold.amountMicros, basis: "floor", modelBasis: heldModel ? "floor" : null });
+			}
+		}
+		// The record reads `dollars` off the error on every throw path (buildRecord), so a retried or failed attempt says
+		// what its windows were charged.
+		if (dollars !== null && e !== null && typeof e === "object") {
+			try {
+				e.dollars = dollars;
+			} catch {
+				// a frozen error keeps its own fields; the log lines above are the record of the hold
+			}
+		}
+
 		if (e?.piDispatchConfig === true && !containerRan) {
-			// GUARDED, and the flags are the record of what actually happened. `releaseBudget` is a loop of
+			// GUARDED, and the `held` list is the record of what actually happened. `releaseLedgers` is a loop of
 			// DECRs over the active windows and can reject part-way (a read-only replica, a dropped
 			// connection), which would otherwise replace this determinate refusal with a Redis message: the
 			// operator would be told their queue is broken when their deployment is misconfigured, and the
 			// escaping error is untagged so it is not retried either. A refund that did not land must not be
 			// reported as one, so `budgetReserved` follows the ledger and not the intent.
-			let refunded = true;
-			try {
-				if (reserved) {
-					await releaseBudget(redis, { caps, now });
-					reserved = false;
-				}
-				if (scopedReserved && scopedCaps) {
-					await releaseBudget(redis, { caps: scopedCaps.caps, now, keyPrefix: scopeKeyPrefix(scopedCaps.scope) });
-					scopedReserved = false;
-				}
-			} catch (releaseError) {
-				refunded = false;
-				log("budget_release_failed", { at: "config-refused", code: releaseError?.code ?? null });
-			}
+			const refunded = await refundLedgers("config-refused");
 			// A FIXED sentence, and NO message in the log either. Two different reasons, both load-bearing:
 			// `credentialFromPiAuth` puts `auth.json`'s location in its refusals and `prepare-local` puts the
 			// operator's folder in its own, which `buildRecord` reduces to a basename precisely because a host
@@ -1103,26 +1522,24 @@ export async function runJob(job, deps) {
 			// shipped adapter never throws; this makes that a property of the arm rather than of the wiring.
 			await comment(job, "Refused: this deployment is misconfigured, so the job could not be started. Ask the operator to run `pi-dispatch doctor`. Not run.").catch(() => {});
 			log("refused_config", { kind: job.kind ?? null, refunded });
-			// budgetReserved reflects the LEDGER: false when the refund landed, true when it did not and the
-			// slot is still out there.
-			return { outcome: "policy", reason: "config-refused", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: !refunded }; // return => not retried
+			// budgetReserved reflects the LEDGER: whether the GLOBAL slot is still held after the refund (`globalHeld`).
+			return { outcome: "policy", reason: "config-refused", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: globalHeld(), ...(dollars ? { dollars } : {}) }; // return => not retried
 		}
 
 		// A spawn fault (docker daemon down / binary missing) reserved a slot but never started a
 		// container, so nothing was spent -- give the slot back before the retry. Every other throw
 		// here (exit-1 infra, unknown exit) means the container ran and legitimately spent its slot,
-		// so `reason` gates the release to the never-started case only. Guarded on `reserved` and run
-		// once per invocation; a BullMQ retry reserves afresh, so this cannot double-release.
-		// budgetReserved reflects whether a slot stays spent: false when never-started refunds below,
-		// true for a real container that ran and spent (exit-1 infra / unknown exit).
-		if (e instanceof InfraRetry) e.budgetReserved = reserved && e.reason !== "container-never-started";
-		if (e instanceof InfraRetry && e.reason === "container-never-started") {
-			// Both-or-neither (issue #242): a never-started container can only follow BOTH reserves (the
-			// scoped one precedes the global one, and the container follows both), so they refund
-			// together -- and a scoped refusal returned above without ever touching the global ledger.
-			if (reserved) await releaseBudget(redis, { caps, now });
-			if (scopedReserved && scopedCaps) await releaseBudget(redis, { caps: scopedCaps.caps, now, keyPrefix: scopeKeyPrefix(scopedCaps.scope) });
+		// so `reason` gates the release to the never-started case only. It releases only what `held` still
+		// lists and run once per invocation; a BullMQ retry reserves afresh, so this cannot double-release.
+		if (isNeverStartedRetry(e)) {
+			// All-or-none (issues #242 and #499 part B): a never-started container follows EVERY job-count reserve, so
+			// every held ledger refunds together, last first, through the one helper -- and a scoped or project refusal
+			// returned above with the ledgers before it already given back.
+			await refundLedgers("container-never-started");
 		}
+		// After the refund, so it says what the ledger holds: false when never-started gave the global slot back, true
+		// for a real container that ran and spent (exit-1 infra / unknown exit) or a refund that did not land.
+		if (e instanceof InfraRetry) e.budgetReserved = globalHeld();
 		throw e;
 	} finally {
 		if (prepared) await cleanup(prepared).catch(() => {});
@@ -1198,8 +1615,17 @@ const SECRET_FAILURES = {
 	nul: "printed a value containing a NUL byte, which cannot survive the container's argv",
 };
 
+/**
+ * Is this throw the "the runner never ran" retry (issue #227), whichever path raised it: a never-started exit
+ * (`isNeverStartedExit`), a spawn fault, or a pre-start gate? The catch's refunds (the job-count slots and, issue
+ * #501, the dollar hold) key off this one test.
+ */
+function isNeverStartedRetry(e) {
+	return e instanceof InfraRetry && e.reason === "container-never-started";
+}
+
 export class InfraRetry extends Error {
-	constructor(message, { cause, reason, exitCode, turns, tokens, session, usage, provider, model, budgetReserved } = {}) {
+	constructor(message, { cause, reason, exitCode, turns, tokens, session, usage, provider, model, budgetReserved, dollars } = {}) {
 		super(message, cause ? { cause } : undefined);
 		this.name = "InfraRetry";
 		this.piDispatchRetry = true;
@@ -1218,6 +1644,9 @@ export class InfraRetry extends Error {
 		this.provider = provider ?? null;
 		this.model = model ?? null;
 		this.budgetReserved = budgetReserved ?? null;
+		// Issue #501: the dollar reservation's outcome (`dollarsRecord`), or null when no dollar window applied. Set by
+		// the processor on a throw after the reservation, so a retried attempt's record says what its window was charged.
+		this.dollars = dollars ?? null;
 	}
 }