@edgehero/pi-dispatch 1.4.0 → 1.5.0

package/.env.example

@@ -74,6 +74,8 @@ PI_JOB_IMAGE=pi-job:latest          # the DEFAULT job image. Any trigger may nam
                                     # Unset = cron disabled for the worker; the receiver falls back to ./triggers.json in the folder it starts from (what `pi-dispatch init` scaffolds)
                                     # and refuses to start when neither exists (it holds the label/comment/pull_request trigger config)
 # PI_PAUSE_WINDOWS_FILE=            # ABSOLUTE path to pause-windows.json — "quiet hours" per folder/repo (pause runs between certain times/days/dates, auto-resume). Unset = feature off. See docs/pause-windows.md
+# PI_SCOPED_LIMITS_FILE=            # ABSOLUTE path to scoped-limits.json — per repo/folder job-count caps (day/week/month, refused pre-spend as scope-cap) and max concurrent jobs per scope (excess deferred, never dropped).
+                                    # Unset = no scoped caps or concurrency; the one-job-per-folder mutex for local jobs is always on and needs no file. See docs/scoped-limits.md
 # PI_SUBSCRIPTIONS_FILE=            # path to subscriptions.json — operator-declared subscription plan prices (the admin defaults to ./subscriptions.json in its working directory). Read by the ADMIN EXTENSION only, never at job time.
                                     # Subscription-backed providers bill 0 per run (their rate tables are all zeros), so this file is where the real price lives — cost analytics only; it changes no routing, auth, or job behavior
 # PI_SETTINGS_FILE=                 # ABSOLUTE path to the runtime settings overlay (default: OS temp /pi-dispatch/settings.json); edited by the admin extension, read by the worker per job

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
   "keywords": [
@@ -55,6 +55,7 @@
     "./triggers-file": "./src/triggers-file.mjs",
     "./packages": "./src/packages.mjs",
     "./pause-windows": "./src/pause-windows.mjs",
+    "./scoped-limits": "./src/scoped-limits.mjs",
     "./identity": "./src/identity.mjs",
     "./gitlab-identity": "./src/gitlab-identity.mjs",
     "./forgejo-identity": "./src/forgejo-identity.mjs",

package/src/config.mjs

@@ -244,6 +244,7 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		sandboxIdleMinutes: nonNegativeInt(env, "PI_SANDBOX_IDLE_MINUTES", 30), // bash's own TMOUT inside a sandbox; 0 = no idle logout
 		triggersFile: env.PI_TRIGGERS_FILE ?? null, // DES-CRON-VIA-BULLMQ-SCHEDULER: unified triggers file; null = cron disabled for the worker (it selects on.type:"cron")
 		pauseWindowsFile: env.PI_PAUSE_WINDOWS_FILE ?? null, // REQ-SCOPED-PAUSE-WINDOWS: per-folder/repo timed pause; null = no scoped pauses
+		scopedLimitsFile: env.PI_SCOPED_LIMITS_FILE ?? null, // issue #242: per-scope run caps + concurrency (INT-SCOPED-LIMITS-FILE-CONTRACT); null = none. The one-job-per-folder mutex for local jobs is code, not configuration, and holds regardless
 		schedulerStallMax: positiveInt(env, "PI_SCHEDULER_STALL_MAX", 2), // CONST-RETRY-INFRA-ONLY: per-scheduler stall backstop; positiveInt rejects <1 so a 0 threshold fails closed
 		logsDir: env.PI_LOGS_DIR || defaultLogsDir(), // || (not ??) so an empty string falls back to the default
 		settingsFile: env.PI_SETTINGS_FILE || defaultSettingsFile(), // || (not ??) so an empty string falls back; INT-CONFIG-OVERLAY-CONTRACT

package/src/doctor.mjs

@@ -50,6 +50,7 @@ import { dirname, join, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn as nodeSpawn } from "node:child_process";
 import { defaultSandboxDir, globalExtensionsEnabled } from "./config.mjs";
+import { canonicalScope, parseScopedLimits } from "./scoped-limits.mjs";
 import { isForgeKind } from "./forges.mjs";
 import { findLiteralSecret, ADMIN_RE } from "./import-pi.mjs";
 import { agentDirFrom, readHostPi } from "./host-pi.mjs";
@@ -264,7 +265,8 @@ export async function collectChecks(env, seams) {
 	// image checks just below, and `optingOut`/`requiring` colour the staged-packages lines further down.
 	// `optingOut` counts the only value that withholds the staged set; `requiring` counts an explicit
 	// run.packages: true, which arms nothing any more but is still an operator statement of intent.
-	const { requiring, optingOut, resuming, replicating, instructing, commands, secreting, onceArmed, onceSpent, secretProfiles, localSecretFolders, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
+	const { requiring, optingOut, resuming, replicating, instructing, commands, secreting, onceArmed, onceSpent, secretProfiles, localSecretFolders, folders, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
+	const scopedLimitFacts = readScopedLimitFacts(env, fileExists);
 	// FIRST, and fail rather than warn: every check below this line reads counts that a parse failure
 	// zeroed, so a green run here would be reporting on a file nobody could read. The receiver loads this
 	// file unconditionally and refuses to start without it, which is the consequence worth naming.
@@ -1308,6 +1310,58 @@ export async function collectChecks(env, seams) {
 		}
 	}
 
+	// The same trap, scoped-limits edition (issue #242): init scaffolds ./scoped-limits.json, the admin
+	// defaults to it, and the worker reads only PI_SCOPED_LIMITS_FILE. The label's mutex parenthetical is
+	// load-bearing -- the check must not imply local folders run ungated when the file is off.
+	{
+		const scopedLimitsFile = env.PI_SCOPED_LIMITS_FILE;
+		const scaffolded = join(cwd, "scoped-limits.json");
+		if ((typeof scopedLimitsFile !== "string" || scopedLimitsFile.trim() === "") && fileExists(scaffolded)) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `${scaffolded} exists but PI_SCOPED_LIMITS_FILE is unset -- the worker ignores it, so scoped caps and concurrency are OFF (the built-in one-job-per-folder mutex stays on)`,
+				fix: `set PI_SCOPED_LIMITS_FILE=${scaffolded} in .env and restart the worker -- unset means the worker enforces no scoped limits at all, while the admin panel defaults to this same file and reports each limit it writes as applied live; delete the file if this deployment has no scoped limits`,
+			});
+		}
+	}
+
+	// Issue #242: a CONFIGURED scoped-limits file is boot-load fail-loud, so a file that does not load
+	// refuses the next worker start -- doctor says it before the restart does. Never-tier: doctor never
+	// rewrites limits content (DES-CLI-SURFACE).
+	if (scopedLimitFacts.path !== null && scopedLimitFacts.parseError !== null) {
+		checks.push({
+			ok: false,
+			label: `scoped-limits file does not load -- the worker will refuse to start: ${scopedLimitFacts.parseError}`,
+			fix: `fix ${scopedLimitFacts.path} by hand, or through the dispatch_limit_* tools / the panel's m key once it parses again -- doctor never rewrites limits content`,
+		});
+	}
+
+	// The dead-scope advisory (issue #242), honest about what doctor can actually judge. A forge repo
+	// always contains "/" and never begins "/", "./" or "../" or carries a backslash, so a scope in any
+	// of THOSE shapes can only ever be a folder -- and a folder row that matches no trigger's canonical
+	// run.folder guards nothing. Rows that COULD be a repo (an "a/b" shape) stay silent, not caveated:
+	// webhook jobs carry their repo in the delivery, which triggers.json cannot enumerate, so a line on
+	// every legitimate repo cap would be standing noise that teaches skimming (`repositories` is empty
+	// for every valid file today -- run.repository is azure-only, its own fact says so). Guarded on the
+	// TRIGGERS facts being readable too: a zeroed `folders` from an absent or unparseable triggers file
+	// has no honest claim to make (readTriggerFacts' own rule). ok:true -- the replica advisory's tier,
+	// and like it, everything the operator needs lives in the LABEL: an ok:true check never prints its
+	// fix line.
+	if (scopedLimitFacts.parseError === null && scopedLimitFacts.limits.length > 0 && parseError === null && triggersFilePath !== null) {
+		const folderSet = new Set(folders);
+		const folderOnly = (s) => s.startsWith("/") || s.startsWith("./") || s.startsWith("../") || s.includes("\\") || !s.includes("/") || /^[A-Za-z]:/.test(s);
+		const dead = scopedLimitFacts.limits.map((l) => l.scope).filter((s) => folderOnly(s) && !folderSet.has(s));
+		if (dead.length > 0) {
+			checks.push({
+				ok: true,
+				warn: true,
+				label: `${dead.length} scoped limit(s) name a folder no trigger runs in (${dead.join(", ")}) -- the cap guards nothing; scopes match exactly (no globs, folders by resolved ABSOLUTE path), so check the spelling against triggers.json run.folder or delete the entry`,
+				fix: `edit ${scopedLimitFacts.path} by hand or via dispatch_limit_edit/_delete -- repo-shaped scopes are never flagged here, because a webhook job's repo comes from the delivery, which triggers.json cannot enumerate`,
+			});
+		}
+	}
+
 	// REQ-RESURRECTABLE-SANDBOX. A warning, never a failure: retention is a convenience, and the only thing
 	// worth surfacing is that finished runs' directories -- a repository clone plus the run's prompt.md and
 	// event.json, so issue text -- are sitting on disk, and how many. An operator who never opens a sandbox
@@ -1496,8 +1550,30 @@ function parseSecretProfilesSafe(raw) {
 	}
 }
 
+/**
+ * The scoped-limits facts (issue #242): the parsed rows when PI_SCOPED_LIMITS_FILE is set, or the
+ * boot-blocking reason when it will not load. Unset is `none` -- the worker enforces no scoped limits
+ * and doctor has nothing to say (the mutex is code and needs no check). A configured-but-missing file
+ * IS a parseError here: loadScopedLimits refuses boot on it, so doctor must too. Raw fs errors
+ * (EACCES, EISDIR) are reported the same way, deliberately unlike readTriggerFacts' tagged-only
+ * filter: the worker's own boot load is an unguarded readFileSync, so those throws refuse startup
+ * exactly as a parse failure does, and the check's claim is "will the worker start", not "is the
+ * content valid".
+ */
+function readScopedLimitFacts(env, fileExists) {
+	const none = { limits: [], parseError: null, path: null };
+	const path = env.PI_SCOPED_LIMITS_FILE;
+	if (typeof path !== "string" || path.trim() === "") return none;
+	if (!fileExists(path)) return { limits: [], parseError: `scoped-limits file does not exist: ${path}`, path };
+	try {
+		return { limits: parseScopedLimits(readFileSync(path, "utf8"), path), parseError: null, path };
+	} catch (e) {
+		return { limits: [], parseError: e?.message ?? String(e), path };
+	}
+}
+
 function readTriggerFacts(env, fileExists, cwd) {
-	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, onceArmed: 0, onceSpent: 0, secretProfiles: [], localSecretFolders: [], images: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
+	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, onceArmed: 0, onceSpent: 0, secretProfiles: [], localSecretFolders: [], folders: [], images: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
 	try {
 		// Unset falls back to ./triggers.json in cwd, MIRRORING the receiver's own default
 		// (receiver/src/config.mjs) -- the two must read the same file, or doctor preflights a deployment
@@ -1539,6 +1615,10 @@ function readTriggerFacts(env, fileExists, cwd) {
 			// read-write with no clone, so a credential an agent writes into .env lands in the operator's real
 			// repository rather than a temp dir that gets swept. Deduped for skillsDirs' reason.
 			localSecretFolders: [...new Set(triggers.filter((t) => t.run.secrets !== undefined && t.run.kind === "local" && typeof t.run.folder === "string").map((t) => t.run.folder))].sort(),
+			// Issue #242: every local run.folder, CANONICALIZED the way the scoped-limits matcher
+			// canonicalizes a job's folder (one derivation -- canonicalScope, never re-spelled here), so
+			// the unreferenced-scope advisory compares like with like across spelling variants.
+			folders: [...new Set(triggers.filter((t) => t.run.kind === "local" && typeof t.run.folder === "string").map((t) => canonicalScope({ kind: "local", folder: t.run.folder })))].sort(),
 			optingOut: triggers.filter((t) => t.run.packages === false).length,
 			images: [...new Set(triggers.map((t) => t.run.image).filter((i) => typeof i === "string"))].sort(),
 			// REQ-PER-TRIGGER-SKILLS. The distinct host directories the file names, deduped like `images`,
@@ -1569,6 +1649,11 @@ function readTriggerFacts(env, fileExists, cwd) {
 					packages: t.run.packages !== false,
 				}))
 				.filter((f) => typeof f.flow === "string"),
+			// Explicit on the success path too (issue #242): the dead-scope advisory distinguishes
+			// "facts read clean" (path set, no error) from the zeroed `none` -- an implicit undefined
+			// here made that test silently false for every deployment.
+			parseError: null,
+			path,
 		};
 	} catch (e) {
 		// REPORTED, not swallowed. This catch used to justify itself with "a malformed triggers file already

package/src/index.mjs

@@ -2,11 +2,19 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { DelayedError, UnrecoverableError, Worker } from "bullmq";
 import { InfraRetry, runJob } from "./processor.mjs";
+import { budgetCapsFor, canonicalScope, concurrencyFor, makeInFlight } from "./scoped-limits.mjs";
 
 const exec = promisify(execFile);
 
 export const QUEUE = "pi-jobs";
 export const JOB_TIMEOUT_MS = 30 * 60 * 1000; // REQ-JOB-TIMEOUT-30M
+// The scope-busy re-check (issue #242): a held scope has no natural "until" (the holder may run to
+// JOB_TIMEOUT_MS), so a deferred job re-tests on a fixed cadence. 5s keeps the worst case trivial
+// (<=360 wakes across a 30-minute hold, each ~1ms of synchronous predicate briefly occupying a slot)
+// while a same-folder CHAINED job -- enqueued by its parent before the parent's finally releases the
+// folder -- pays exactly one re-check, not fifteen seconds of dead air. No jitter: one worker per
+// docker daemon bounds any herd by its own concurrency, and a contended wake just re-defers.
+export const SCOPE_BUSY_RECHECK_MS = 5_000;
 
 /**
  * Build the BullMQ processor.
@@ -27,7 +35,7 @@ export const JOB_TIMEOUT_MS = 30 * 60 * 1000; // REQ-JOB-TIMEOUT-30M
  * The overlay changes which values the spend caps take, never when they are checked -- reserveBudget still
  * runs inside runJob against the freshly passed caps (CONST-BUDGET-BEFORE-TOKENS).
  */
-export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, applyConcurrency = () => {}, pauseUntil = () => null, deps, recordRun = () => {}, timeoutMs = JOB_TIMEOUT_MS, now = () => Date.now() }) {
+export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, applyConcurrency = () => {}, pauseUntil = () => null, scopedLimits = () => [], inFlight = makeInFlight(), deps, recordRun = () => {}, timeoutMs = JOB_TIMEOUT_MS, now = () => Date.now() }) {
 	return async function processor(job, token, signal) {
 		// Scoped pause windows (REQ-SCOPED-PAUSE-WINDOWS): if this job's folder/repo is inside an active pause
 		// window, DEFER it to the window end via BullMQ's delayed set -- the job keeps its identity/dedup and
@@ -45,19 +53,68 @@ export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, ap
 			throw new DelayedError();
 		}
 
-		const startedAt = new Date().toISOString();
-		const name = `pi-job-${job.id}`;
-		const timer = setTimeout(() => {
-			// BullMQ has no per-job kill timer; this is ours. cancelJob raises the AbortSignal.
-			Promise.resolve(cancelJob(job.id, "job-timeout-30m")).catch(() => {});
-		}, timeoutMs);
+		// Per-scope concurrency and the one-job-per-folder mutex (issue #242,
+		// INT-SCOPED-LIMITS-FILE-CONTRACT). SECOND, after the pause gate (a paused job must not burn
+		// re-check wakes) and STRICTLY above the `try` below, like the pause gate and for the same two
+		// reasons: a DelayedError thrown inside the try would be converted to UnrecoverableError by the
+		// catch, and a moveToDelayed rejection here must escape RAW into BullMQ's normal failed-attempt
+		// handling exactly as the pause gate's does (inside the try it would become a permanent failure
+		// plus a failure record for what was a transient blip). The limits snapshot is read ONCE here and
+		// shared with `scopedCaps` below, so the gate and the money ledger cannot disagree mid-job.
+		// tryAcquire is a synchronous check-and-increment -- no await between read and take, so Node's
+		// single thread makes it atomic at any concurrency -- and the local-folder limit is a structural 1
+		// (concurrencyFor) with no file and no off-switch: the scheduler mints a cron trigger's next
+		// occurrence at pickup and promotes it on time alone, so a slow run overlaps its own successor
+		// (measured: 301ms of live container overlap through this very processor) unless this gate holds.
+		// Infinity-limited scopes still acquire, so release stays uniform for every scoped job.
+		const limits = scopedLimits();
+		const scope = canonicalScope(job.data);
+		let held = false;
+		if (scope) {
+			if (!inFlight.tryAcquire(scope, concurrencyFor(job.data, limits))) {
+				// Optional-chained: makeProcessor gives `deps` no default and bare wirings pass deps: {}.
+				// The scope itself stays out of the log line (no-pii-in-logs -- a local scope is a full
+				// host path); the delayed count and the job id are what an operator needs to see it.
+				deps?.log?.("scope_busy_deferred", { jobId: job.id, kind: job.data?.kind === "local" ? "local" : "forge", delayMs: SCOPE_BUSY_RECHECK_MS });
+				await job.moveToDelayed(nowMs + SCOPE_BUSY_RECHECK_MS, token);
+				throw new DelayedError();
+			}
+			held = true;
+		}
 
-		// Abort (timeout OR shutdown) => stop the container. docker stop sends SIGTERM then SIGKILL
-		// after the grace period; the runner exits and runContainer returns/throws.
-		const onAbort = () => {
-			Promise.resolve(stopContainer(name)).catch(() => {});
-		};
-		signal.addEventListener("abort", onAbort, { once: true });
+		let startedAt;
+		let name;
+		let timer;
+		let onAbort;
+		try {
+			// Nothing between the acquire above and the main `try` below may throw unguarded: the releasing
+			// finally belongs to THAT try, so an unguarded throw here would leak the hold and wedge the
+			// scope until a worker restart. Nothing in this block CAN throw today (setTimeout and
+			// addEventListener on the bullmq-allocated controller are total at processor arity 3); the
+			// guard is structural, not observational.
+			startedAt = new Date().toISOString();
+			name = `pi-job-${job.id}`;
+			timer = setTimeout(() => {
+				// BullMQ has no per-job kill timer; this is ours. cancelJob raises the AbortSignal.
+				Promise.resolve(cancelJob(job.id, "job-timeout-30m")).catch(() => {});
+			}, timeoutMs);
+
+			// Abort (timeout OR shutdown) => stop the container. docker stop sends SIGTERM then SIGKILL
+			// after the grace period; the runner exits and runContainer returns/throws.
+			onAbort = () => {
+				Promise.resolve(stopContainer(name)).catch(() => {});
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+		} catch (error) {
+			// Release and CLEAR the flag: this throw never reaches the main finally below, but a shared
+			// scope must never be releasable twice -- a double release frees another holder's slot.
+			if (held) {
+				inFlight.release(scope);
+				held = false;
+			}
+			clearTimeout(timer);
+			throw error;
+		}
 
 		try {
 			const settings = await getSettings();
@@ -99,6 +156,10 @@ export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, ap
 				// The daily TOKEN cap (issue #25), same overlay > env resolution. Check-AFTER, so it gates the
 				// NEXT job on prior recorded spend; null => the daily token counter is disabled.
 				tokenCap: settings.dailyTokenCap,
+				// This job's scoped budget windows (issue #242), from the SAME limits snapshot the pickup
+				// gate above read -- one read per pickup, so gate and ledger agree for this job's whole
+				// life. Null when no row carries a money window for this scope.
+				scopedCaps: budgetCapsFor(job.data, limits),
 				...deps,
 				runContainer: (ctx) => deps.runContainer({ ...ctx, name, signal }),
 				// REQ-TRIGGER-SECRETS. The resolver runs INSIDE the 30-minute kill timer armed above, so it has
@@ -140,13 +201,16 @@ export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, ap
 			// records it as failed-and-distinct in the queue's failed set without a retry.
 			throw new UnrecoverableError(error.message);
 		} finally {
+			// Release FIRST and never throw (release clamps at zero by construction): a throw here would
+			// mask the job's real error, and a missed release wedges the scope until a worker restart.
+			if (held) inFlight.release(scope);
 			clearTimeout(timer);
 			signal.removeEventListener("abort", onAbort);
 		}
 	};
 }
 
-export function createWorker({ connection, concurrency, getSettings, redis, deps, recordRun, limiter, pauseUntil, extraClosers = [] }) {
+export function createWorker({ connection, concurrency, getSettings, redis, deps, recordRun, limiter, pauseUntil, scopedLimits, inFlight, extraClosers = [] }) {
 	let worker; // referenced by cancelJob/applyConcurrency before assignment; only called later, so the TDZ is fine
 	const processor = makeProcessor({
 		cancelJob: (id, reason) => worker.cancelJob(id, reason),
@@ -159,6 +223,11 @@ export function createWorker({ connection, concurrency, getSettings, redis, deps
 			if (Number.isInteger(n) && worker.concurrency !== n) worker.concurrency = n;
 		},
 		pauseUntil,
+		// Undefined pass-throughs take makeProcessor's own defaults (no limits; a fresh per-processor
+		// in-flight map -- one per worker process, which under DES-CONCURRENCY-3's one-worker-per-daemon
+		// shape means one per daemon).
+		scopedLimits,
+		inFlight,
 		deps,
 		recordRun,
 	});

package/src/init.mjs

@@ -19,6 +19,11 @@ const EMPTY_PACKAGES = `${JSON.stringify({ packages: [] }, null, 2)}\n`;
 // Operator-declared subscription plans (issue #53), read by the admin extension only — never at job
 // time. Versioned because a newer file must fail loud, and that cannot be retrofitted into a v1 reader.
 const EMPTY_SUBSCRIPTIONS = `${JSON.stringify({ version: 1, subscriptions: [] }, null, 2)}\n`;
+// Scoped limits (issue #242): per repo/folder run caps and concurrency. Empty is inert -- and the
+// one-job-per-folder mutex for local jobs is code, not configuration, so it needs no scaffold line.
+// Versioned for the subscriptions reason, sharpened: this is enforcement config, and a silently
+// down-read newer file would be a silently widened spend limit.
+const EMPTY_SCOPED_LIMITS = `${JSON.stringify({ version: 1, limits: [] }, null, 2)}\n`;
 /**
  * The egress allowlist (REQ-EGRESS-ALLOWLIST): the hosts a job container may reach, one bare hostname per
  * line. Scaffolded with the three a job cannot work without, and NOT empty -- unlike every other scaffold
@@ -73,6 +78,7 @@ export function runInit(cwd = process.cwd(), deps = {}) {
 	scaffold(fs, results, join(cwd, "pause-windows.json"), EMPTY_PAUSE_WINDOWS, "empty pause-windows list");
 	scaffold(fs, results, join(cwd, "pi-packages.json"), EMPTY_PACKAGES, "empty pi package list (stage with import-pi --with-packages)");
 	scaffold(fs, results, join(cwd, "subscriptions.json"), EMPTY_SUBSCRIPTIONS, "empty subscription list (declare plan prices for the admin's cost analytics)");
+	scaffold(fs, results, join(cwd, "scoped-limits.json"), EMPTY_SCOPED_LIMITS, "empty scoped-limits list (per repo/folder caps; the folder mutex needs no file)");
 	scaffold(fs, results, join(cwd, "egress-allowlist.conf"), DEFAULT_EGRESS_ALLOWLIST, "egress allowlist (provider + forge + registry; the egress policy is on unless PI_EGRESS=0)");
 
 	for (const [verb, name, note] of results) {

package/src/processor.mjs

@@ -1,6 +1,7 @@
 import { lstatSync } from "node:fs";
 import { checkTokenCap, recordTokenSpend, releaseBudget, reserveBudget } from "./budget.mjs";
 import { configError } from "./config.mjs";
+import { scopeKeyPrefix } from "./scoped-limits.mjs";
 import { DEFAULT_SECRETS_PROFILE, secretsArmed } from "./secrets.mjs";
 import { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "./exit-code.mjs";
 
@@ -37,6 +38,12 @@ export async function runJob(job, deps) {
 		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,
 		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
@@ -124,6 +131,7 @@ export async function runJob(job, deps) {
 	let token = null;
 	let prepared = null;
 	let reserved = false;
+	let scopedReserved = false;
 
 	try {
 		// The one-shot pre-spend check (issue #231), FIRST on the ladder: one file read, cheaper than
@@ -458,11 +466,51 @@ 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
 		}
 
-		// Budget last-but-before-container. A refusal here spends nothing (no container starts). Reserves across
+		// 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
+			}
+		}
+
+		// 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) });
+			}
 			const w = budget.blockedWindow;
 			const win = budget.windows[w];
 			if (budget.reason === "soft-hold") {
@@ -561,8 +609,12 @@ export async function runJob(job, deps) {
 		// 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 (reserved && e instanceof InfraRetry && e.reason === "container-never-started") {
-			await releaseBudget(redis, { caps, now });
+		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) });
 		}
 		throw e;
 	} finally {

package/src/scoped-limits.mjs

@@ -0,0 +1,277 @@
+/**
+ * Scoped limits (issue #242, INT-SCOPED-LIMITS-FILE-CONTRACT): per-scope run caps and per-scope
+ * concurrency, where a scope is what `scopeOf` already answers -- the folder for a local job, the repo
+ * for a forge one. One `scoped-limits.json` of `{ scope, day?, week?, month?, concurrent? }` entries:
+ * the day/week/month caps refuse a job pre-spend (reason `scope-cap`, a policy refusal), `concurrent`
+ * defers the excess through the delayed set (never a refusal -- a busy scope is transient state).
+ *
+ * This module is pure and fs-injectable (mirrors pause-windows.mjs in every respect): `parseScopedLimits`
+ * validates the file TEXT fail-loud, `loadScopedLimits` layers the one fs read on top, and the small
+ * helpers below are what the processor gate and the budget wiring consume. It also owns the in-process
+ * in-flight counter (`makeInFlight`) so the counter is unit-testable without a bullmq import, the same
+ * reason job-id.mjs is queue-free. The wiring that consumes all of this (the gate, the budget calls,
+ * the admin surfaces) lands in this issue's later slices; the module ships first so the contract has
+ * one implementation to bind to -- sentences below describing enforcement describe THOSE slices.
+ *
+ * The file is a SIBLING of pause-windows.json, not part of the settings overlay, deliberately: the
+ * deferral gate runs before the per-job overlay read, so gate-read config must come from a watched
+ * mutable ref, and the overlay's KNOWN_KEYS are flat scalars whose only map-shaped precedent
+ * (secretProfiles) is deliberately model-unreachable -- the opposite of what these limits need.
+ *
+ * `version` is REQUIRED and fail-loud-on-newer (subscriptions.mjs's rule, adopted here because this is a
+ * MONEY file): unknown fields are silently dropped per the operator-file policy, so a v2 cap field an old
+ * worker drops would be a silently WIDENED spend limit. Pause-windows shipping without a version is a
+ * sunk decision, not a precedent to extend to enforcement config.
+ *
+ * Custom: scoped limits validated inline per triggers.mjs/pause-windows.mjs precedent; zod not in deps
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { configError } from "./config.mjs";
+import { scopeOf } from "./pause-windows.mjs";
+
+/** The schema version this build reads and writes. A file declaring a higher one is refused loudly. */
+export const SCOPED_LIMITS_VERSION = 1;
+
+/** The four limit fields a row may carry, in display order. */
+const LIMIT_FIELDS = ["day", "week", "month", "concurrent"];
+
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * The canonical scope string for a job: the RESOLVED folder path for a local job, the repo for a forge
+ * one. `scopeOf` alone is not enough for enforcement: nothing on the trigger path normalizes
+ * `run.folder`, so `/srv/site`, `/srv/site/`, `/srv//site`, `/srv/x/../site` and a padded spelling are
+ * five distinct strings naming ONE directory -- an exact-string mutex keyed on the raw value would run
+ * them concurrently in one working tree, which is the exact race the mutex exists to close.
+ * `path.resolve` (not `normalize`, which keeps trailing slashes and whitespace) collapses them all; a
+ * relative folder resolves against the worker's cwd, the same base `prepareWorkspace`'s existence check
+ * uses; Unicode is NFC-normalized on both the job and the row side (see below). Two residuals,
+ * deliberate: symlinks are NOT resolved (realpath is an fs call on the hot path and can throw), and
+ * neither is filesystem case-insensitivity (on a default macOS/APFS volume `/Srv/Site` and `/srv/site`
+ * are one directory and two scopes) -- the pause matcher lives with both.
+ *
+ * The pause matcher itself keeps the RAW `scopeOf` value: resolving there would silently change which
+ * jobs an operator's existing trailing-slash window matches. The two features share the folder-vs-repo
+ * split (`scopeOf`, defined once) but not the normalization, and this comment is where that difference
+ * is recorded.
+ *
+ * A useful side effect: a resolved local scope is always an absolute path, and a repo string never is,
+ * so a folder named `a/b` and a repo named `a/b` can no longer collide in the counters or the mutex.
+ */
+export function canonicalScope(job) {
+	const scope = scopeOf(job);
+	if (!isNonEmptyString(scope)) return null;
+	// NFC on both kinds: macOS's filesystem hands paths back NFD while an admin dialog types NFC, so
+	// "wéb" can arrive as two byte sequences naming one thing -- without this, an NFD-spelled forge
+	// scope silently escapes an NFC-spelled cap (the local side would at least keep the structural
+	// mutex). ASCII is fixed under NFC, so no existing key changes.
+	return job?.kind === "local" ? resolve(scope.trim().normalize("NFC")) : scope.normalize("NFC");
+}
+
+/**
+ * Parse, validate, and normalize the scoped-limits file TEXT. Returns the normalized `limits` array
+ * (every row rebuilt as an explicit `{ scope, day, week, month, concurrent }` literal, `null` for absent
+ * fields, unknown fields dropped -- the operator-file policy). Throws `configError` (fail-loud) on any
+ * malformed entry. `path` is for error messages only -- this function touches no filesystem.
+ */
+export function parseScopedLimits(text, path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw configError(`scoped-limits file is not valid JSON: ${path} (${error.message})`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw configError(`scoped-limits file must be an object with "version" and "limits": ${path}`);
+	}
+	const version = parsed.version;
+	if (!Number.isInteger(version) || version < 1) {
+		throw configError(`scoped-limits file must have "version": 1 (an integer >= 1): ${path}`);
+	}
+	if (version > SCOPED_LIMITS_VERSION) {
+		throw configError(`scoped-limits file written by a newer pi-dispatch (version ${version}; this build understands ${SCOPED_LIMITS_VERSION}): ${path}`);
+	}
+	if (!Array.isArray(parsed.limits)) {
+		throw configError(`scoped-limits file must have a "limits" array: ${path}`);
+	}
+	const rows = parsed.limits.map((row, index) => normalizeLimit(row, index, path));
+	const seen = new Map();
+	rows.forEach((row, index) => {
+		if (seen.has(row.scope)) {
+			// Two rows for one scope is a precedence question with no right answer; the admin's
+			// edit-in-place never produces one, so a duplicate is always a hand-edit mistake.
+			throw configError(`scoped limit at index ${index}: duplicate scope ${JSON.stringify(row.scope)} (first at index ${seen.get(row.scope)}): ${path}`);
+		}
+		seen.set(row.scope, index);
+	});
+	return rows;
+}
+
+function normalizeLimit(row, index, path) {
+	const at = `scoped limit at index ${index}`;
+	if (row === null || typeof row !== "object" || Array.isArray(row)) {
+		throw configError(`${at}: must be an object: ${path}`);
+	}
+	if (!isNonEmptyString(row.scope)) throw configError(`${at}: scope must be a non-empty string: ${path}`);
+	const trimmed = row.scope.trim().normalize("NFC"); // the same NFC canonicalScope applies job-side
+	if (trimmed === "*") {
+		// "*" as ONE shared counter is redundant with the global caps, so the only useful reading is a
+		// per-scope default -- the OPPOSITE of what "*" means one file over (pause-windows: one rule
+		// matching all scopes). Refused rather than shipped divergent; a later version may adopt the
+		// per-scope-default reading, with an exact row beating "*" (recorded in the contract).
+		throw configError(`${at}: "*" is not supported -- add one row per scope (a per-scope default may adopt "*" later): ${path}`);
+	}
+	if (trimmed.includes("*")) {
+		// No globs, enforced rather than described: an exact matcher makes "acme/*" a row that governs
+		// nothing, and a silently inert money limit is the failure class this repo refuses outright.
+		throw configError(`${at}: scopes match exactly; a scope containing "*" is refused (no globs): ${path}`);
+	}
+	const norm = {
+		// An absolute path is stored resolved so a `/srv/site/` row governs `/srv/site` jobs -- the same
+		// collapse canonicalScope applies on the job side. isAbsolute is PLATFORM-NATIVE on purpose, so a
+		// foreign-platform row (a windows drive path on a POSIX worker) stays verbatim and is inert here;
+		// the doctor's unreferenced-scope advisory names it. Resolving it instead would "work" only by
+		// both sides mangling into the same cwd-prefixed string -- a match by accident, not by contract.
+		scope: isAbsolute(trimmed) ? resolve(trimmed) : trimmed,
+		day: null,
+		week: null,
+		month: null,
+		concurrent: null,
+	};
+	let any = false;
+	for (const field of LIMIT_FIELDS) {
+		const value = row[field];
+		// Absent-or-null (subscriptions.mjs's rule): null is the normalizer's OWN output for an unset
+		// field, so the parser must accept it back or it cannot re-parse what it produced -- the admin's
+		// read-modify-write goes through this parser on both edges.
+		if (value === undefined || value === null) continue;
+		// 0 is refused, not "never run": budget.mjs's caps treat every configured window as >= 1, and
+		// "never run this scope" already has two honest spellings (delete the trigger; a pause window).
+		// isSafeInteger, not isInteger: 1e21 passes isInteger and reads as a limit while being
+		// indistinguishable from unlimited -- a bound that cannot count is not a bound.
+		if (!Number.isSafeInteger(value) || value < 1) {
+			throw configError(`${at}: ${field} must be an integer >= 1: ${path}`);
+		}
+		norm[field] = value;
+		any = true;
+	}
+	if (!any) {
+		throw configError(`${at}: at least one of day, week, month, concurrent is required (a row that limits nothing is a row an operator sets and then trusts): ${path}`);
+	}
+	return norm;
+}
+
+/**
+ * Load and validate the scoped-limits file named by `config.scopedLimitsFile`. Returns `[]` when the file
+ * is unset (no scoped caps or concurrency -- a valid deployment; the folder mutex holds regardless, it is
+ * code, not configuration). `readFileSync`/`existsSync` are injectable for tests.
+ */
+export function loadScopedLimits(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+	const path = config.scopedLimitsFile;
+	if (path === null || path === undefined) return [];
+	if (!existsSync(path)) throw configError(`scoped-limits file does not exist: ${path}`);
+	return parseScopedLimits(readFileSync(path, "utf8"), path);
+}
+
+/**
+ * The exact-match row for a canonical scope, or null. Exact string equality only -- the pause matcher's
+ * semantics minus its "*" (refused above). With duplicates refused there is no precedence ladder.
+ */
+export function limitFor(limits, scope) {
+	if (!Array.isArray(limits) || !isNonEmptyString(scope)) return null;
+	return limits.find((l) => l.scope === scope) ?? null;
+}
+
+/**
+ * The scoped budget windows this job reserves against, or null when nothing applies (no row for the
+ * scope, or the row is concurrency-only). The returned `scope` is CANONICAL so the redis counters are
+ * spelling-stable. Shaped like the global `caps` object so `reserveBudget` consumes it unchanged.
+ */
+export function budgetCapsFor(job, limits) {
+	const scope = canonicalScope(job);
+	const row = limitFor(limits, scope);
+	if (!row || (row.day === null && row.week === null && row.month === null)) return null;
+	return { scope, caps: { day: row.day, week: row.week, month: row.month } };
+}
+
+/**
+ * The effective in-flight ceiling for this job's scope: `min(configured concurrent, structural)`, where
+ * structural is 1 for a local job -- the folder mutex -- and unbounded otherwise. The mutex is
+ * UNCONDITIONAL, in code, with no file configured and no off-switch: two agents in one bind-mounted
+ * working tree is the race `run.replicas` is already refused on local jobs for, and a cron trigger
+ * reaches it with no operator mistake at all (the scheduler mints the next occurrence at pickup and
+ * promotes on time alone, so a slow run overlaps its own successor). A configured `concurrent` above 1
+ * on a folder scope silently clamps to 1 rather than refusing at parse: scope strings are not reliably
+ * typeable as folder-vs-repo (`"a/b"` is a legal relative folder and a legal repo), so a parse-time
+ * classifier would misfire; min() cannot.
+ *
+ * No scope (a malformed payload) means no gate: Infinity, admit -- the job will fail its own validation
+ * downstream, and holding a mutex slot under key `null` helps nobody.
+ */
+export function concurrencyFor(job, limits) {
+	const scope = canonicalScope(job);
+	if (scope === null) return Infinity;
+	const structural = job?.kind === "local" ? 1 : Infinity;
+	const configured = limitFor(limits, scope)?.concurrent ?? Infinity;
+	return Math.min(structural, configured);
+}
+
+/**
+ * The redis key prefix for a scope's budget windows: `budget:s:<16 hex>`. Handed to
+ * `reserveBudget`/`releaseBudget` as `keyPrefix`, so `dayKey`/`weekKey`/`monthKey` compose
+ * `budget:s:<h>:YYYY-MM-DD` / `:w:...` / `:m:...` with zero new key-shape logic. A hash (the localJobId
+ * idiom: sha256, first 16 hex) rather than an escape: a scope legally contains `:` and `/` (folder
+ * paths, gitlab group/subgroup/project), which would collide with budget.mjs's own `w:`/`m:`/`t:`
+ * sub-namespaces, and a bijective escape grammar is a new thing to get wrong with unbounded key lengths.
+ * The one consumer that must map keys BACK to scopes is the admin's counter display, and it knows the
+ * configured scopes -- it recomputes keys through this same export, so unreadability in redis-cli is the
+ * accepted cost.
+ */
+export function scopeKeyPrefix(scope) {
+	const h = createHash("sha256").update(String(scope)).digest("hex").slice(0, 16);
+	return `budget:s:${h}`;
+}
+
+/**
+ * The per-process in-flight counter behind per-scope concurrency and the folder mutex. Process memory is
+ * the CORRECT store, not a compromise: one worker per docker daemon is the shape DES-CONCURRENCY-3
+ * assumes everywhere and `service install` enforces for installed units (`pi-dispatch start` holds no
+ * lock, and two hand-run workers are already unsupported -- the second one's boot reaper kills the
+ * first's live containers); the reaper removes every surviving `pi-job-*` container before the worker
+ * starts draining, so a fresh, empty map is never wrong about a live container except when the reap
+ * itself was skipped (`reaper_skipped`: docker missing/down at boot -- a state where no NEW container
+ * can start either); and a Redis-held counter would survive a crash WRONGLY -- a claim for a container
+ * the reaper just killed, demanding TTL/heartbeat machinery, a second source of truth about "what is
+ * running" (the OQ-008 failure mode).
+ *
+ * `tryAcquire` is a synchronous check-and-increment: no await between the read and the take, so under
+ * Node's single thread no interleaving exists at any concurrency. `release` never throws -- it runs in
+ * the processor's finally, where a throw would mask the job's real error -- and clamps at zero.
+ */
+export function makeInFlight() {
+	const counts = new Map();
+	return {
+		/** True and counted when under `limit`; false WITHOUT counting when at or over it. */
+		tryAcquire(scope, limit) {
+			const current = counts.get(scope) ?? 0;
+			if (current >= limit) return false;
+			counts.set(scope, current + 1);
+			return true;
+		},
+		/** Decrement, deleting at zero; a release without a matching acquire is a no-op, never a throw. */
+		release(scope) {
+			const current = counts.get(scope) ?? 0;
+			if (current <= 1) counts.delete(scope);
+			else counts.set(scope, current - 1);
+		},
+		/** The current in-flight count for a scope (tests and future observability). */
+		count(scope) {
+			return counts.get(scope) ?? 0;
+		},
+	};
+}

package/src/start.mjs

@@ -24,6 +24,7 @@ import { makeSandboxReaper } from "./sandbox-store.mjs";
 import { makeSessionStore } from "./session-store.mjs";
 import { makeCheckOnceSpent, makeDisarmOnce } from "./triggers-file.mjs";
 import { loadPauseWindows, pauseUntilMs } from "./pause-windows.mjs";
+import { loadScopedLimits } from "./scoped-limits.mjs";
 import { makeQueue } from "./queue.mjs";
 import { makeRunContainer } from "./run-container.mjs";
 import { makeSecretsResolver } from "./secrets.mjs";
@@ -103,6 +104,42 @@ function watchPauseWindowsFile(config, ref, log) {
 	}
 }
 
+/**
+ * The scoped-limits reload, EXPORTED apart from its watcher so keep-last-good is unit-testable without
+ * fs.watch (its two watcher siblings above bind theirs inline; this one is money config, so the
+ * 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) {
+	try {
+		ref.current = loadScopedLimits(config);
+		log("scoped_limits_reloaded", { count: ref.current.length });
+	} catch (err) {
+		log("scoped_limits_reload_invalid", { reason: err?.message });
+	}
+}
+
+/**
+ * Watch the scoped-limits file (issue #242) the way the pause-windows watcher above does: the DIRECTORY,
+ * for atomic tmp+rename robustness, filtered to the one basename, debounced. Best-effort + unref'd.
+ */
+function watchScopedLimitsFile(config, ref, log) {
+	const path = config.scopedLimitsFile;
+	const dir = dirname(path) || ".";
+	const file = basename(path);
+	let timer = null;
+	try {
+		watch(dir, (_event, changed) => {
+			if (changed && changed !== file) return;
+			clearTimeout(timer);
+			timer = setTimeout(() => reloadScopedLimits(config, ref, log), 150);
+		}).unref?.();
+		log("scoped_limits_watching", { path });
+	} catch (err) {
+		log("scoped_limits_watch_unavailable", { reason: err?.message });
+	}
+}
+
 export function makeReaper({ log }) {
 	return async function reap() {
 		try {
@@ -188,6 +225,10 @@ export async function startWorker(
 	// pauses. Held in a mutable ref so the live-reload watcher can hot-swap it. [] means no scoped pauses.
 	const pauseWindows = { current: loadPauseWindows(config) };
 
+	// Issue #242: same posture for the scoped-limits file -- fail-loud with the operator present, mutable
+	// ref for the live-reload watcher, [] when unset (the folder mutex is code and needs no file).
+	const scopedLimits = { current: loadScopedLimits(config) };
+
 	// The forge a job belongs to is resolved PER JOB from `job.kind`, not bound once for the process.
 	// Each entry is `{ auth, host }`: `auth` is get-token's `{ mintToken, selfId, source }` (null when that
 	// forge is unconfigured or unreachable), `host` is the three methods github-host.mjs returns. The map
@@ -422,6 +463,9 @@ export async function startWorker(
 		// 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.
 		pauseUntil: (job, now) => pauseUntilMs(pauseWindows.current, job, now),
+		// 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,
 		deps: {
 			collectChain,
 			// The one-shot pre-spend check (issue #231): reads the same file the disarm writes, refuses
@@ -595,6 +639,11 @@ export async function startWorker(
 		watchPauseWindowsFile(config, pauseWindows, log);
 	}
 
+	// Issue #242 live edit: hot-swap the scoped limits on file change, keeping last-good on a bad edit.
+	if (config.scopedLimitsFile) {
+		watchScopedLimitsFile(config, scopedLimits, log);
+	}
+
 	log("worker_started", {
 		queue: "pi-jobs",
 		concurrency: bootConcurrency, // the slot count the Worker is actually constructed with (overlay may raise/lower it)
@@ -602,6 +651,8 @@ export async function startWorker(
 		weeklyCap: config.weeklyCap, // null when the weekly window is disabled
 		monthlyCap: config.monthlyCap, // null when the monthly window is disabled
 		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
 		image: config.jobImage,
 		valkey: config.valkeyUrl,
 		logsDir: config.logsDir,