@edgehero/pi-dispatch 1.3.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/deploy/docker-compose.yml

@@ -49,7 +49,11 @@ services:
       PI_TRIGGERS_FILE: /config/triggers.json
     # The repo-root triggers.json (`pi-dispatch init` scaffolds it -- run that first: mounting a path
     # that does not exist makes Docker create it as a DIRECTORY and the boot fails confusingly).
-    # Read-only: the receiver live-reloads this file on change; it never writes it.
+    # Read-only: the receiver live-reloads this file on change; it never writes it. One consequence of
+    # a single-FILE bind mount (issue #231): every write to this file is an atomic tmp+rename that
+    # SWAPS THE INODE, and the mount stays pinned to the old one -- so the worker's one-shot disarm is
+    # invisible in here until the container restarts, and the worker's own pre-spend check is what
+    # keeps a spent one-shot from running again in the meantime. A restart picks up the current file.
     volumes:
       - ../triggers.json:/config/triggers.json:ro
     # Loopback only, like Valkey's port above: the operator's reverse proxy or tunnel (TLS, public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.3.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": [
@@ -52,8 +52,10 @@
     "./job-id": "./src/job-id.mjs",
     "./forges": "./src/forges.mjs",
     "./triggers": "./src/triggers.mjs",
+    "./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, 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.
@@ -1242,6 +1244,31 @@ export async function collectChecks(env, seams) {
 		});
 	}
 
+	// One-shot close triggers (issue #231, DES-ONE-SHOT-DISARM-IN-THE-FILE). Advisory only -- doctor
+	// never touches triggers -- and counted from the RAW file (readTriggerFacts says why). Two lines
+	// with different lives: the armed line names the count and, when PI_TRIGGERS_FILE is unset, warns
+	// that the disarm resolves ./triggers.json against the WORKER SERVICE's working directory -- a
+	// service unit whose WorkingDirectory differs from the receiver's would disarm a file nobody
+	// matches against, the split-file hazard no mechanism can detect. The spent line states the
+	// deliberate degradation: a spent entry counts toward NO parsed fact above (forges, flows,
+	// webhook-secret), mirroring what the receiver serves at its next boot.
+	if (onceArmed > 0) {
+		checks.push({
+			ok: true,
+			warn: env.PI_TRIGGERS_FILE === undefined,
+			label: `${onceArmed} one-shot trigger(s) armed (on.once) -- the worker disarms the entry in ${env.PI_TRIGGERS_FILE === undefined ? "./triggers.json resolved against the worker service's working directory; set PI_TRIGGERS_FILE so worker and receiver name the same file from anywhere" : "PI_TRIGGERS_FILE"} after the run record exists`,
+			fix: "set PI_TRIGGERS_FILE to an absolute path in both services' environments",
+		});
+	}
+	if (onceSpent > 0) {
+		checks.push({
+			ok: true,
+			warn: false,
+			label: `${onceSpent} one-shot trigger(s) already spent (on.disarmed) -- spent entries match nothing and count toward no credential or flow check; delete on.disarmed to re-arm, or delete the entry once its history no longer matters`,
+			fix: "",
+		});
+	}
+
 	// REQ-SCOPED-PAUSE-WINDOWS, the panel-writes-what-the-worker-ignores trap (issue #99). Three defaults
 	// that are individually defensible and together silent:
 	//
@@ -1283,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
@@ -1471,16 +1550,48 @@ 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, 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
 		// the receiver will not boot. An absent file still means "no triggers at all", exactly as before.
 		const path = env.PI_TRIGGERS_FILE ?? join(cwd, "triggers.json");
 		if (!fileExists(path)) return none;
-		const triggers = parseTriggers(readFileSync(path, "utf8"), path);
+		const text = readFileSync(path, "utf8");
+		const triggers = parseTriggers(text, path);
+		// The one-shot facts are counted from the RAW entries, not the parsed records, because the
+		// validator collapses a disarmed entry to a sentinel that carries neither `once` nor
+		// `disarmed` -- exactly so nothing can match it -- which also erases it from every parsed
+		// count above. Doctor is the surface that must still SEE the spent entry: "why did nothing
+		// fire" is answered by a spent row, and only the raw file still holds it. Safe unguarded:
+		// parseTriggers just accepted this same text, so JSON.parse cannot throw here.
+		const rawEntries = JSON.parse(text)?.triggers ?? [];
 		return {
+			onceArmed: rawEntries.filter((t) => t?.on?.once === true && t.on.disarmed === undefined).length,
+			onceSpent: rawEntries.filter((t) => t?.on?.disarmed !== undefined).length,
 			requiring: triggers.filter((t) => t.run.packages === true).length,
 			resuming: triggers.filter((t) => t.run.resume === true).length,
 			// REQ-PER-TRIGGER-INSTRUCTION. Counted beside `resuming` for the same reason: it is a per-trigger
@@ -1504,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`,
@@ -1534,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/get-token.mjs

@@ -104,10 +104,15 @@ export async function makeGitHubAuth(cfg, deps = {}) {
 				);
 			}
 			const repositoryNames = [repoNameOf(repo)]; // scope to the ONE repo; owner stripped
+			// An optional PERMISSIONS narrowing (issue #231): the receiver's closer-permission lookup asks
+			// for `{ metadata: "read" }`, so the token it holds for that one question cannot write anything
+			// even if leaked. Job mints never pass this and keep the installation's full grant -- narrowing
+			// is the caller's statement of intent, not a default this mint could guess.
+			const permissions = job?.permissions;
 			let minted;
 			try {
 				const appAuth = createAppAuth(auth);
-				minted = await appAuth({ type: "installation", repositoryNames });
+				minted = await appAuth({ type: "installation", repositoryNames, ...(permissions && { permissions }) });
 			} catch (error) {
 				throw classifyAppMintError(error);
 			}

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
@@ -125,6 +186,11 @@ export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, ap
 				// `queueJobId`, mirroring the collectChain injection above. Omitted when unwired so a bare
 				// processor keeps runJob's plain (job, token) call.
 				...(deps.prepareWorkspace ? { prepareWorkspace: (j, t) => deps.prepareWorkspace(j, t, { queueJobId: job.id }) } : {}),
+				// The one-shot pre-spend check (issue #231) needs the REAL BullMQ job's `.id` to excuse this
+				// delivery's own earlier attempt -- runJob's effectiveJob has no `.id`, prepareWorkspace's
+				// own injection above states why, and this one mirrors it. Omitted when unwired so a bare
+				// processor keeps runJob's admit-everything default.
+				...(deps.checkOnceSpent ? { checkOnceSpent: (j) => deps.checkOnceSpent(j, { queueJobId: job.id }) } : {}),
 			});
 			recordRun({ job, result, startedAt, endedAt: new Date().toISOString() });
 			return result;
@@ -135,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),
@@ -154,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,11 +38,22 @@ 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
 		// omits it behaves exactly as before -- the container's own failure stays the backstop.
 		imagePreflight = async () => ({ ok: true }),
+		// (job) => { ok } | { refused, at, jobId }. The one-shot pre-spend check (issue #231,
+		// DES-ONE-SHOT-DISARM-IN-THE-FILE). Default admits everything -- an unwired processor behaves
+		// exactly as before, and the gate below only calls it for a job whose matched rule was a
+		// one-shot, so the default is never a probe running on every delivery.
+		checkOnceSpent = async () => ({ ok: true }),
 		// 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 }),
@@ -119,8 +131,30 @@ 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
+		// the docker inspect below, free, determinate, credential-less. Only a FOREIGN positive
+		// disarmed mark refuses -- the check excuses this queue job's own id, so a retry of the
+		// delivery that spent the trigger still runs (attempts:2 stays attempts:2) -- and anything
+		// unreadable or changed means "run": fail-open, because the disarm writer owns the loud
+		// refusals, and a broken read must never wedge every once job. In the compose topology the
+		// receiver reads a dead inode until restart, so this check is the once-enforcement layer
+		// there, not optional hardening.
+		if (job.trigger?.matched?.once === true) {
+			const spent = await checkOnceSpent(job);
+			if (spent.refused) {
+				// Commented like every sibling policy refusal: explainability is this refusal's whole
+				// purpose, and only a DISTINCT re-close reaches it past the GUID dedup, so the noise
+				// bound is the operator's own reopen-close rate. `at`/`jobId` are harness-written
+				// provenance, never payload text.
+				await comment(job, `Refused: this one-shot trigger was already spent${spent.at ? ` at ${spent.at}` : ""}${spent.jobId ? ` by job ${spent.jobId}` : ""}. The close that armed it has already produced a run; delete on.disarmed from the trigger entry to re-arm it. Not run.`);
+				log("refused_once_already_spent", { triggerIndex: job.trigger?.matched?.index ?? null });
+				return { outcome: "policy", reason: "once-already-spent", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+		}
+
 		// The job image must exist on THIS host before anything else happens. Free, determinate and
 		// credential-less, so it precedes the mint, the clone and the reservation: a host that cannot run the
 		// image refuses without minting a credential it will not use, cloning a repo it will not read, or
@@ -432,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") {
@@ -535,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/queue.mjs

@@ -1,6 +1,11 @@
 import { Queue } from "bullmq";
 import { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId } from "./job-id.mjs";
 import { targetSeparator } from "./forges.mjs";
+import { PR_CLOSE_ACTIONS } from "./triggers.mjs";
+
+// The close words in every forge's spelling, derived from the one table (never re-typed here): a
+// matched PR action in this set marks a close job for the semantic-key discriminant below.
+const PR_CLOSE_WORDS = new Set(Object.values(PR_CLOSE_ACTIONS));
 
 export const QUEUE = "pi-jobs";
 export { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId };
@@ -180,6 +185,21 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		...(replica !== undefined && { replica }),
 		...(replicas !== undefined && { replicas }),
 	};
+	// A close-triggered job (issue #231) leads the semantic key's flow slot with `closed:`. Without it,
+	// a label/comment/PR job on the same target and flow inside the 10-minute window silently swallows
+	// the close job -- and because a swallowed close job writes no run record, the once trigger it was
+	// meant to spend never disarms: a permanently dead one-shot with nothing in the panel to say why.
+	// The discriminant is DERIVED from the matched rule (`issue` type, or a PR close action word) rather
+	// than carried as a job field: an execution detail of dedup is not a fact about the delivery, and
+	// `data`/`event.json` stay byte-identical. `:` is outside the skill-name charset -- enforced at load
+	// since #231 -- so no real flow can spell either prefixed form, and `closed:cmd:<name>` composes for
+	// close-dispatched commands (outermost discriminant first, then the entry-point prefix).
+	const matched = trigger?.matched;
+	// `type === "issue"` reads as "close" only while the issue vocabulary is close-only (it is; the
+	// tables say "one word each so far"). If that type ever grows a non-close action, this test must
+	// narrow to the matched action word, like the PR half already does.
+	const isCloseJob = matched?.type === "issue" || (matched?.type === "pull_request" && PR_CLOSE_WORDS.has(matched?.action));
+	const flowSlot = `${isCloseJob ? "closed:" : ""}${command !== undefined ? `cmd:${command}` : flow}`;
 	await queue.add(kind, data, {
 		jobId,
 		// A command job (issue #189) fills the semantic key's flow slot with `cmd:<command>`: a command
@@ -188,7 +208,7 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// `cmd:` prefix keeps a command named X from coalescing against a flow named X -- `:` is outside
 		// the skill-name charset, so no real flow can spell the prefixed form -- and a flow job's key
 		// stays byte-identical to before the feature.
-		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${command !== undefined ? `cmd:${command}` : flow}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
+		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${flowSlot}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
 		attempts: 2,
 		backoff: { type: "exponential", delay: 60_000 },
 		removeOnComplete: { age: 31 * 24 * 3600 }, // age in seconds -- do not cross units with the ms ttl above