@edgehero/pi-dispatch-admin 1.4.0 → 1.5.0

package/README.md

@@ -4,7 +4,7 @@
 
 # pi-dispatch: run the pi coding agent as a self-hosted service
 
-**Let a coding agent work on your repositories while you are not watching, without surprise bills and without giving it the keys to your machine.** [pi](https://github.com/earendil-works/pi) is a superb coding agent, but it has no job queue, no spend limit, and, by its own README, no permission system. pi-dispatch adds exactly those, so you can run pi unattended and safely: on a cron schedule, on your repo's issues and PRs, or straight from the CLI. Every job runs in an isolated container, spend is bounded before a single token is spent, and everything the agent did (and what it cost) is recorded, graphed and priced for you. On a forge you stay in the loop at both ends: a job starts only when someone with write access to the repo asks for one, by a label, an `@pi` comment or a review, and what comes back is a pull request you review and land, because pi-dispatch never merges anything. This is not another agent to weigh against the one you already use; it is the queue, the budget and the box for the pi you already run.
+**Let a coding agent work on your repositories while you are not watching, without surprise bills and without giving it the keys to your machine.** [pi](https://github.com/earendil-works/pi) is a superb coding agent, but it has no job queue, no spend limit, and, by its own README, no permission system. pi-dispatch adds exactly those, so you can run pi unattended and safely: on a cron schedule, on your repo's issues and PRs, or straight from the CLI. Every job runs in an isolated container, spend is bounded before a single token is spent (per deployment and per-repo or per-folder), and everything the agent did (and what it cost) is recorded, graphed and priced for you. On a forge you stay in the loop at both ends: a job starts only when someone with write access to the repo asks for one, by a label, an `@pi` comment or a review, and what comes back is a pull request you review and land, because pi-dispatch never merges anything. This is not another agent to weigh against the one you already use; it is the queue, the budget and the box for the pi you already run.
 
 > This npm package, **`@edgehero/pi-dispatch-admin`**, is the **operator console** (a pi extension). The service itself is `@edgehero/pi-dispatch` (worker + CLI) and `@edgehero/pi-dispatch-receiver` (the webhook edge); the [main repo](https://github.com/edgehero/pi-dispatch) has the container image, docs, and SECURITY.md.
 
@@ -56,7 +56,7 @@ Four forges: GitHub, GitLab, Forgejo (and Gitea), Azure DevOps. **Who may fire a
 One command puts a live TUI over the whole deployment:
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/dispatch-dashboard.png?v=1.0.0" alt="The /dispatch panel: status, spend meters, triggers (including a command trigger shown as its /name), pause windows, runs, and settings" width="820">
+  <img src="https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/dispatch-dashboard.png?v=1.0.0" alt="The /dispatch panel: status, spend meters, triggers (including a command trigger shown as its /name), pause windows, scoped limits, runs, and settings" width="820">
 </p>
 
 - **Status and spend.** Queue and worker state, day/week/month spend meters, a daily token counter, and a run-history table with per-job tokens and cost.
@@ -68,7 +68,8 @@ One command puts a live TUI over the whole deployment:
 
 - **Triggers, editable live.** cron, label, comment, pull_request and issue triggers with colored drill-ins showing what fires each one, what it runs, and its trust model. Added, edited and deleted without a restart. A one-shot (`once: true`) shows armed or spent in its drill-in: a spent entry stays in the list, matches nothing, and re-arms when the operator deletes its `on.disarmed` mark from the file. Triggers that run third-party code or a custom image are badged; opting in or out of either stays an edit to the reviewed `triggers.json`, which neither the console nor a model-callable tool will make for you.
 - **Quiet hours.** Scheduled pause windows per folder or repo: defer runs between certain times, timezone-aware, and resume automatically. Deferred, never dropped, at zero budget cost.
-- **AI-operable, with a human gate.** Model-callable tools let an agent change limits and manage triggers and pause windows, and every **config** write pops an operator confirmation the model cannot answer, refusing outright when no operator is present. Two tools sit outside that gate on purpose: `dispatch_pause` and `dispatch_resume` write durable queue state but are reversible and spend nothing, so they carry no confirm. One more sits outside it and is **not** money-safe: `dispatch_run` enqueues a **paid** run that edits a local folder in place with no undo, bounded instead by six independent limits (the `PI_DISPATCH_RUN_ROOTS` folder allowlist, a committed per-flow `ai-trigger: allow` opt-in read at a pre-agent SHA, a dirty-tree refusal with no force option, no spend knobs on the tool, a per-hour rate limit, and the worker's daily cap). Commands sit outside its reach entirely: `dispatch_run` speaks flows only, and a chained job's request naming a `command` is refused outright, with no opt-in. Read [`SECURITY.md`](https://github.com/edgehero/pi-dispatch/blob/main/SECURITY.md) on that one before you enable it. The bundled `operate-pi-dispatch` skill teaches the agent those gates.
+- **Scoped limits.** Per-repo or per-folder job caps (day, week, month) refused before any spend, plus a per-scope concurrency ceiling enforced by deferral. Local jobs also hold a one-job-per-folder guard that is always on and has no switch (it lives in the worker process, and one worker per docker daemon is the supported shape), because two agents editing one working tree race each other with no gate and no undo.
+- **AI-operable, with a human gate.** Model-callable tools let an agent change limits (global and scoped) and manage triggers and pause windows, and every **config** write pops an operator confirmation the model cannot answer, refusing outright when no operator is present. Two tools sit outside that gate on purpose: `dispatch_pause` and `dispatch_resume` write durable queue state but are reversible and spend nothing, so they carry no confirm. One more sits outside it and is **not** money-safe: `dispatch_run` enqueues a **paid** run that edits a local folder in place with no undo, bounded instead by six independent limits (the `PI_DISPATCH_RUN_ROOTS` folder allowlist, a committed per-flow `ai-trigger: allow` opt-in read at a pre-agent SHA, a dirty-tree refusal with no force option, no spend knobs on the tool, a per-hour rate limit, and the worker's daily cap). Commands sit outside its reach entirely: `dispatch_run` speaks flows only, and a chained job's request naming a `command` is refused outright, with no opt-in. Read [`SECURITY.md`](https://github.com/edgehero/pi-dispatch/blob/main/SECURITY.md) on that one before you enable it. The bundled `operate-pi-dispatch` skill teaches the agent those gates.
 - **Logs stay put.** Raw container output renders only in the overlay viewer, never into model context.
 
 ## Install

package/dist/index.mjs

@@ -8024,10 +8024,100 @@ var init_pause_windows = __esm({
   }
 });
 
-// ../worker/src/subscriptions.mjs
+// ../worker/src/scoped-limits.mjs
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
 function isNonEmptyString3(value) {
   return typeof value === "string" && value.trim() !== "";
 }
+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 = /* @__PURE__ */ new Map();
+  rows.forEach((row, index) => {
+    if (seen.has(row.scope)) {
+      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 (!isNonEmptyString3(row.scope)) throw configError(`${at}: scope must be a non-empty string: ${path}`);
+  const trimmed = row.scope.trim().normalize("NFC");
+  if (trimmed === "*") {
+    throw configError(`${at}: "*" is not supported -- add one row per scope (a per-scope default may adopt "*" later): ${path}`);
+  }
+  if (trimmed.includes("*")) {
+    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];
+    if (value === void 0 || value === null) continue;
+    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;
+}
+function scopeKeyPrefix(scope) {
+  const h = createHash("sha256").update(String(scope)).digest("hex").slice(0, 16);
+  return `budget:s:${h}`;
+}
+var SCOPED_LIMITS_VERSION, LIMIT_FIELDS;
+var init_scoped_limits = __esm({
+  "../worker/src/scoped-limits.mjs"() {
+    init_config2();
+    init_pause_windows();
+    SCOPED_LIMITS_VERSION = 1;
+    LIMIT_FIELDS = ["day", "week", "month", "concurrent"];
+  }
+});
+
+// ../worker/src/subscriptions.mjs
+function isNonEmptyString4(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
 function normalizeGlobs(value, label, at, path) {
   if (!Array.isArray(value) || value.length === 0) {
     throw configError(`${at}: ${label} must be a non-empty array of model globs: ${path}`);
@@ -8073,14 +8163,14 @@ function normalizeSubscription(entry, index, path, seenIds) {
   if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
     throw configError(`${at}: must be an object: ${path}`);
   }
-  if (!isNonEmptyString3(entry.id)) throw configError(`${at}: id must be a non-empty string: ${path}`);
+  if (!isNonEmptyString4(entry.id)) throw configError(`${at}: id must be a non-empty string: ${path}`);
   const id = entry.id.trim();
   if (seenIds.has(id)) {
     throw configError(`${at}: id ${JSON.stringify(id)} is already used by the subscription at index ${seenIds.get(id)}: ${path}`);
   }
   seenIds.set(id, index);
-  if (!isNonEmptyString3(entry.vendor)) throw configError(`${at}: vendor must be a non-empty string: ${path}`);
-  if (!isNonEmptyString3(entry.provider)) throw configError(`${at}: provider must be a non-empty string (the pi-ai provider id this plan covers): ${path}`);
+  if (!isNonEmptyString4(entry.vendor)) throw configError(`${at}: vendor must be a non-empty string: ${path}`);
+  if (!isNonEmptyString4(entry.provider)) throw configError(`${at}: provider must be a non-empty string (the pi-ai provider id this plan covers): ${path}`);
   const models = entry.models === void 0 ? ["*"] : normalizeGlobs(entry.models, "models", at, path);
   const price = entry.price;
   if (price === null || typeof price !== "object" || Array.isArray(price)) {
@@ -8100,7 +8190,7 @@ function normalizeSubscription(entry, index, path, seenIds) {
   let counterfactualModel = null;
   if (entry.counterfactualModel !== void 0 && entry.counterfactualModel !== null) {
     const cm = entry.counterfactualModel;
-    if (typeof cm !== "object" || Array.isArray(cm) || !isNonEmptyString3(cm.provider) || !isNonEmptyString3(cm.id)) {
+    if (typeof cm !== "object" || Array.isArray(cm) || !isNonEmptyString4(cm.provider) || !isNonEmptyString4(cm.id)) {
       throw configError(`${at}: counterfactualModel must be { provider, id } with non-empty strings (a PRICED pi-ai model to re-price covered runs at API rates): ${path}`);
     }
     counterfactualModel = { provider: cm.provider.trim(), id: cm.id.trim() };
@@ -8197,9 +8287,9 @@ var init_connection = __esm({
 });
 
 // ../worker/src/job-id.mjs
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 function localJobId({ folder, flow, task, minute }) {
-  const digest = createHash("sha256").update([folder, flow ?? "", task ?? "", minute].join("\0")).digest("hex");
+  const digest = createHash2("sha256").update([folder, flow ?? "", task ?? "", minute].join("\0")).digest("hex");
   return `local-${digest.slice(0, 16)}`;
 }
 var init_job_id = __esm({
@@ -8276,7 +8366,7 @@ var init_reserved_env = __esm({
 });
 
 // ../worker/src/triggers.mjs
-function isNonEmptyString4(value) {
+function isNonEmptyString5(value) {
   return typeof value === "string" && value.trim() !== "";
 }
 function parseTriggers(text, path) {
@@ -8331,7 +8421,7 @@ function normalizeTrigger(entry, index, path, state) {
 function normalizeCron(on, run, index, path, state) {
   const at = `trigger at index ${index}`;
   const id = on.id;
-  if (!isNonEmptyString4(id)) {
+  if (!isNonEmptyString5(id)) {
     throw configError(`${at}: cron on.id must be a non-empty string: ${path}`);
   }
   if (id.includes(":")) {
@@ -8345,7 +8435,7 @@ function normalizeCron(on, run, index, path, state) {
   }
   state.seenCronIds.add(id);
   const pattern = on.pattern;
-  if (!isNonEmptyString4(pattern)) {
+  if (!isNonEmptyString5(pattern)) {
     throw configError(`cron trigger "${id}": on.pattern must be a non-empty string: ${path}`);
   }
   const fieldCount = pattern.trim().split(/\s+/).length;
@@ -8353,13 +8443,13 @@ function normalizeCron(on, run, index, path, state) {
     throw configError(`cron trigger "${id}": on.pattern must have 5 or 6 space-separated fields, got ${fieldCount}: ${path}`);
   }
   const command = validateCommand(run, `cron trigger "${id}"`, path, { onType: "cron" });
-  if (!isNonEmptyString4(run.folder)) {
+  if (!isNonEmptyString5(run.folder)) {
     throw configError(`cron trigger "${id}": run.folder must be a non-empty string: ${path}`);
   }
-  if (command === void 0 && !isNonEmptyString4(run.flow)) {
+  if (command === void 0 && !isNonEmptyString5(run.flow)) {
     throw configError(`cron trigger "${id}": run.flow must be a non-empty string (or use run.command): ${path}`);
   }
-  if (command === void 0 && !isNonEmptyString4(run.task)) {
+  if (command === void 0 && !isNonEmptyString5(run.task)) {
     throw configError(`cron trigger "${id}": run.task must be a non-empty string: ${path}`);
   }
   if (run.github !== void 0 && typeof run.github !== "boolean") {
@@ -8443,7 +8533,7 @@ function validateCommand(run, at, path, { onType }) {
     throw configError(`${at}: exactly one of run.flow or run.command must be set -- a trigger dispatches either a flow or a registered command, and with both present the file does not say which one runs: ${path}`);
   }
   if (raw === void 0) return void 0;
-  if (!isNonEmptyString4(raw)) {
+  if (!isNonEmptyString5(raw)) {
     throw configError(`${at}: run.command must be a non-empty string -- the registered command name, optionally followed by its arguments: ${path}`);
   }
   if (raw !== raw.trim()) {
@@ -8529,10 +8619,10 @@ function validateDisarmed(on, at, path, { capable = false, onType } = {}) {
       throw configError(`${at}: on.disarmed has an unsupported key ${JSON.stringify(key)} (expected at|jobId): ${path}`);
     }
   }
-  if (!isNonEmptyString4(disarmed.at)) {
+  if (!isNonEmptyString5(disarmed.at)) {
     throw configError(`${at}: on.disarmed.at must be a non-empty string (the time the one-shot fired): ${path}`);
   }
-  if (disarmed.jobId !== void 0 && !isNonEmptyString4(disarmed.jobId)) {
+  if (disarmed.jobId !== void 0 && !isNonEmptyString5(disarmed.jobId)) {
     throw configError(`${at}: on.disarmed.jobId must be a non-empty string when present (the run record it joins to): ${path}`);
   }
   if (on.once !== true) {
@@ -8556,7 +8646,7 @@ function validateRepository(run, onType, at, path) {
   if (!needed) {
     throw configError(`${at}: run.repository is only meaningful on an azure label or comment trigger (a pull request names its own repository): ${path}`);
   }
-  if (!isNonEmptyString4(raw) || raw !== raw.trim() || raw.includes("/")) {
+  if (!isNonEmptyString5(raw) || raw !== raw.trim() || raw.includes("/")) {
     throw configError(`${at}: run.repository must be a non-empty repository NAME within the project, with no slashes and no surrounding whitespace (got ${JSON.stringify(raw)}): ${path}`);
   }
   return raw;
@@ -8596,7 +8686,7 @@ function validateSecrets(run, at, path) {
       throw configError(`${at}: run.secrets key ${JSON.stringify(name)} is a variable the worker sets itself -- the job container would receive the worker's value, not this trigger's, and the trigger would look like it worked: ${path}`);
     }
     const reference = secrets[name];
-    if (!isNonEmptyString4(reference)) {
+    if (!isNonEmptyString5(reference)) {
       throw configError(`${at}: run.secrets.${name} must be a non-empty string reference for your resolver to read (got ${JSON.stringify(reference)}): ${path}`);
     }
     if (reference !== reference.trim()) {
@@ -8614,7 +8704,7 @@ function validateSecrets(run, at, path) {
 function validateSecretsProfile(run, at, path) {
   const profile = run.secretsProfile;
   if (profile === void 0) return void 0;
-  if (!isNonEmptyString4(profile)) {
+  if (!isNonEmptyString5(profile)) {
     throw configError(`${at}: run.secretsProfile must be a non-empty string naming one of the resolver profiles this deployment declares (got ${JSON.stringify(profile)}): ${path}`);
   }
   if (!ID_CHARSET.test(profile)) {
@@ -8632,7 +8722,7 @@ function normalizeLabel(on, run, index, path) {
   validateOnce(on, run, at, path, { onType: "label" });
   validateDisarmed(on, at, path, { onType: "label" });
   const command = validateCommand(run, at, path, { onType: "label" });
-  if (command === void 0 && !isNonEmptyString4(run.flow)) {
+  if (command === void 0 && !isNonEmptyString5(run.flow)) {
     throw configError(`${at}: label trigger run.flow must be a non-empty string (or use run.command): ${path}`);
   }
   validateFlowName(run, at, path);
@@ -8652,14 +8742,14 @@ function normalizeLabel(on, run, index, path) {
 }
 function normalizeComment(on, run, index, path, state) {
   const at = `trigger at index ${index}`;
-  if (!isNonEmptyString4(on.phrase)) {
+  if (!isNonEmptyString5(on.phrase)) {
     throw configError(`${at}: comment trigger on.phrase must be a non-empty string: ${path}`);
   }
   validateNumber(on, at, path, { onType: "comment" });
   validateOnce(on, run, at, path, { onType: "comment" });
   validateDisarmed(on, at, path, { onType: "comment" });
   const command = validateCommand(run, at, path, { onType: "comment" });
-  if (command === void 0 && !isNonEmptyString4(run.flow)) {
+  if (command === void 0 && !isNonEmptyString5(run.flow)) {
     throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string (or use run.command): ${path}`);
   }
   validateFlowName(run, at, path);
@@ -8704,7 +8794,7 @@ function normalizeIssue(on, run, index, path) {
   const once = validateOnce(on, run, at, path, { capable: true, onType: "issue" });
   validateDisarmed(on, at, path, { capable: true, onType: "issue" });
   const command = validateCommand(run, at, path, { onType: "issue" });
-  if (command === void 0 && !isNonEmptyString4(run.flow)) {
+  if (command === void 0 && !isNonEmptyString5(run.flow)) {
     throw configError(`${at}: issue trigger run.flow must be a non-empty string (or use run.command): ${path}`);
   }
   validateFlowName(run, at, path);
@@ -8761,7 +8851,7 @@ function normalizePullRequest(on, run, index, path) {
   const once = validateOnce(on, run, at, path, { capable: isClose, onType: "pull_request" });
   validateDisarmed(on, at, path, { capable: isClose, onType: "pull_request" });
   const command = validateCommand(run, at, path, { onType: "pull_request" });
-  if (command === void 0 && !isNonEmptyString4(run.flow)) {
+  if (command === void 0 && !isNonEmptyString5(run.flow)) {
     throw configError(`${at}: pull_request trigger run.flow must be a non-empty string (or use run.command): ${path}`);
   }
   validateFlowName(run, at, path);
@@ -9031,8 +9121,8 @@ var init_docker_run = __esm({
 
 // ../worker/src/packages.mjs
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname as dirname2, join, resolve } from "node:path";
-function isNonEmptyString5(value) {
+import { basename, dirname as dirname2, join, resolve as resolve2 } from "node:path";
+function isNonEmptyString6(value) {
   return typeof value === "string" && value.trim() !== "";
 }
 function readStageManifest({ globalPiDir, readFile = readFileSync, fileExists = existsSync } = {}) {
@@ -9046,7 +9136,7 @@ function readStageManifest({ globalPiDir, readFile = readFileSync, fileExists =
     for (const entry of parsed.packages) {
       if (entry === null || typeof entry !== "object") return null;
       const { name, version, dir } = entry;
-      if (!isNonEmptyString5(name) || !isNonEmptyString5(version) || !isNonEmptyString5(dir)) return null;
+      if (!isNonEmptyString6(name) || !isNonEmptyString6(version) || !isNonEmptyString6(dir)) return null;
       if (!ENTRY_NAME_RE.test(dir) || dir.length > MAX_DIR_LENGTH) return null;
       packages.push({ name, version, dir, from: entry.from === FROM_HOST ? FROM_HOST : FROM_DECLARED });
     }
@@ -9071,7 +9161,7 @@ function readStagedSkills({ globalPiDir, readFile = readFileSync, fileExists = e
           out.unenumerable.push(pkg.name);
           continue;
         }
-        sources = entries.filter((e) => !e.split(/[\\/]/).includes("..")).map((e) => resolve(root, e));
+        sources = entries.filter((e) => !e.split(/[\\/]/).includes("..")).map((e) => resolve2(root, e));
       } else {
         sources = [join(root, "skills")];
       }
@@ -10368,6 +10458,7 @@ function resolvePaths(env = process.env) {
     // root, and silently wrong (demo triggers) everywhere else.
     triggersPath: env.PI_TRIGGERS_FILE ?? "./triggers.json",
     pauseWindowsPath: env.PI_PAUSE_WINDOWS_FILE ?? "./pause-windows.json",
+    scopedLimitsPath: env.PI_SCOPED_LIMITS_FILE ?? "./scoped-limits.json",
     subscriptionsPath: env.PI_SUBSCRIPTIONS_FILE ?? "./subscriptions.json",
     // The operator's global pi overlay dir (REQ-GLOBAL-PI-OVERLAY), where the staged third-party pi
     // packages live under `packages/`. `|| null` so unset AND empty both read as "no overlay" -- the
@@ -10586,6 +10677,80 @@ function writePauseWindows({ pauseWindowsPath, mutate, fs = nodeFs3 }) {
   fs.renameSync(tmp, pauseWindowsPath);
   return { ok: true };
 }
+function readScopedLimits({ scopedLimitsPath, fs = nodeFs3 }) {
+  let text;
+  try {
+    text = fs.readFileSync(scopedLimitsPath, "utf8");
+  } catch {
+    return { missing: true };
+  }
+  try {
+    return { limits: parseScopedLimits(text, scopedLimitsPath) };
+  } catch (e) {
+    return { invalid: e?.message ?? String(e) };
+  }
+}
+function writeScopedLimits({ scopedLimitsPath, mutate, fs = nodeFs3 }) {
+  let current = [];
+  let existing = null;
+  try {
+    existing = fs.readFileSync(scopedLimitsPath, "utf8");
+  } catch {
+  }
+  if (existing !== null) {
+    try {
+      current = parseScopedLimits(existing, scopedLimitsPath);
+    } catch (e) {
+      return { invalid: e?.message ?? String(e) };
+    }
+  }
+  const next = mutate(current.map((l) => ({ ...l })));
+  const rows = next.map((l) => Object.fromEntries(Object.entries(l).filter(([, v]) => v !== null && v !== void 0)));
+  const text = `${JSON.stringify({ version: SCOPED_LIMITS_VERSION, limits: rows }, null, 2)}
+`;
+  try {
+    parseScopedLimits(text, scopedLimitsPath);
+  } catch (e) {
+    return { invalid: e?.message ?? String(e) };
+  }
+  const tmp = `${scopedLimitsPath}.tmp`;
+  fs.writeFileSync(tmp, text, { mode: 420 });
+  fs.renameSync(tmp, scopedLimitsPath);
+  return { ok: true };
+}
+async function readScopedBudget({ url, limits, redisFn = makeRedisClient, timeoutMs = 2500 } = {}) {
+  if (!Array.isArray(limits) || limits.length === 0) return { rows: [] };
+  let redis;
+  try {
+    parseConnection(url, { failFast: true });
+    redis = redisFn(url);
+    const now = /* @__PURE__ */ new Date();
+    const settled = Promise.all(
+      limits.map(async (l) => {
+        const prefix = scopeKeyPrefix(l.scope);
+        const cell2 = async (key) => Number(await redis.get(key) ?? 0);
+        const row = {};
+        if (l.day !== null && l.day !== void 0) row.day = await cell2(dayKey(now, prefix));
+        if (l.week !== null && l.week !== void 0) row.week = await cell2(weekKey(now, prefix));
+        if (l.month !== null && l.month !== void 0) row.month = await cell2(monthKey(now, prefix));
+        return row;
+      })
+    ).then(
+      (rows) => ({ rows }),
+      (err) => ({ unreachable: err?.message ?? String(err) })
+    );
+    return await withTimeout(settled, timeoutMs, { unreachable: "timed out reaching the queue" });
+  } catch (err) {
+    return { unreachable: err?.message ?? String(err) };
+  } finally {
+    if (redis) {
+      try {
+        redis.disconnect();
+      } catch {
+      }
+    }
+  }
+}
 function readSubscriptions({ subscriptionsPath, fs = nodeFs3 }) {
   if (subscriptionsPath === null || subscriptionsPath === void 0) return { missing: true };
   let text;
@@ -10662,8 +10827,8 @@ async function readBudget({ url, redisFn = makeRedisClient, timeoutMs = 2500 } =
 }
 function withTimeout(promise, ms, fallback) {
   let timer;
-  const timeout = new Promise((resolve2) => {
-    timer = setTimeout(() => resolve2(fallback), ms);
+  const timeout = new Promise((resolve3) => {
+    timer = setTimeout(() => resolve3(fallback), ms);
     if (typeof timer?.unref === "function") timer.unref();
   });
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
@@ -11225,6 +11390,7 @@ var init_read_model = __esm({
     init_run_history();
     init_budget();
     init_pause_windows();
+    init_scoped_limits();
     init_subscriptions();
     init_connection();
     init_queue();
@@ -12751,7 +12917,28 @@ function normBudget(v) {
       cap: Number.isInteger(t.cap) && t.cap > 0 ? t.cap : null,
       state: BUDGET_STATES.includes(t.state) ? t.state : "ok",
       maxTokens: Number.isInteger(t.maxTokens) && t.maxTokens > 0 ? t.maxTokens : null
-    }
+    },
+    // The scoped rows (issue #242): a pre-1.5 payload simply lacks the key and renders nothing.
+    scoped: Array.isArray(v.scoped) ? v.scoped.map(normScopedRow).filter((r) => r !== null) : [],
+    scopedInvalid: typeof v.scopedInvalid === "string" && v.scopedInvalid !== "" ? clip3(v.scopedInvalid, 160) : null
+  };
+}
+function normScopedRow(v) {
+  if (v === null || typeof v !== "object" || typeof v.scope !== "string" || v.scope === "") return null;
+  const win = (w) => {
+    if (w === null || w === void 0 || typeof w !== "object") return null;
+    return {
+      used: Number.isInteger(w.used) && w.used >= 0 ? w.used : null,
+      cap: Number.isInteger(w.cap) && w.cap > 0 ? w.cap : null,
+      state: BUDGET_STATES.includes(w.state) ? w.state : "ok"
+    };
+  };
+  return {
+    scope: clip3(v.scope, 60),
+    day: win(v.day),
+    week: win(v.week),
+    month: win(v.month),
+    concurrent: Number.isInteger(v.concurrent) && v.concurrent > 0 ? v.concurrent : null
   };
 }
 function normSpendMap(v) {
@@ -13123,6 +13310,24 @@ function budgetSectionHtml(nb) {
   if (nb.softHoldPct !== null) {
     rows.push(`<div class="dim small">soft-hold band: ${fmt(nb.softHoldPct)}% of each cap (the amber tick)</div>`);
   }
+  if (nb.scopedInvalid !== null) {
+    rows.push(`<div class="dim small">scoped limits: file invalid (${escapeHtml(nb.scopedInvalid)})</div>`);
+  } else if (nb.scoped.length > 0) {
+    rows.push('<div class="dim small">scoped limits (scoped-limits.json)</div>');
+    for (const s of nb.scoped) {
+      const bits = [];
+      let worst = "ok";
+      for (const key of ["day", "week", "month"]) {
+        const w = s[key];
+        if (w === null || w.cap === null) continue;
+        bits.push(`${key} used ${w.used !== null ? fmt(w.used) : "?"} / cap ${fmt(w.cap)}`);
+        if (w.state !== "ok") worst = w.state;
+      }
+      if (s.concurrent !== null) bits.push(`concurrent \u2264${fmt(s.concurrent)} (config; in-flight not shown)`);
+      rows.push(`<div class="row"><span class="wl">${escapeHtml(s.scope)}</span><span>${escapeHtml(bits.join(" \xB7 "))}</span>${worst !== "ok" ? stateWord(worst) : ""}</div>`);
+    }
+    rows.push('<div class="lever">scoped: dispatch_limit_add/edit/delete \xB7 or press m in the /dispatch panel</div>');
+  }
   rows.push('<div class="lever">adjust: /dispatch set dailyCap|weeklyCap|monthlyCap|dailyTokenCap|softHoldPct &lt;n&gt; \xB7 or press s in the /dispatch panel</div>');
   return `<div id="budget">${rows.join("")}</div>`;
 }
@@ -13528,7 +13733,7 @@ var init_open_browser = __esm({
 // src/deployment-pointer.mjs
 import * as nodeFs4 from "node:fs";
 import { homedir } from "node:os";
-import { join as join3, isAbsolute } from "node:path";
+import { join as join3, isAbsolute as isAbsolute2 } from "node:path";
 function pointerPath(env = process.env) {
   return env.PI_DISPATCH_DEPLOYMENT_FILE || join3(env.PI_CODING_AGENT_DIR || join3(homedir(), ".pi", "agent"), POINTER_BASENAME);
 }
@@ -13542,7 +13747,7 @@ function normalizePointer(raw) {
   if (raw.version > POINTER_VERSION) {
     return { ignored: `version ${raw.version} is newer than the supported version ${POINTER_VERSION}` };
   }
-  if (typeof raw.deploymentDir !== "string" || !isAbsolute(raw.deploymentDir)) {
+  if (typeof raw.deploymentDir !== "string" || !isAbsolute2(raw.deploymentDir)) {
     return { ignored: "deploymentDir must be an absolute path" };
   }
   const rawEnv = raw.env === void 0 ? {} : raw.env;
@@ -13553,7 +13758,7 @@ function normalizePointer(raw) {
   for (const key of POINTER_ENV_ALLOWLIST) {
     const value = rawEnv[key];
     if (typeof value !== "string" || value === "") continue;
-    if (key !== "VALKEY_URL" && !isAbsolute(value)) continue;
+    if (key !== "VALKEY_URL" && !isAbsolute2(value)) continue;
     env[key] = value;
   }
   return { pointer: { version: raw.version, deploymentDir: raw.deploymentDir, env } };
@@ -13624,6 +13829,7 @@ var init_deployment_pointer = __esm({
       "PI_SETTINGS_FILE",
       "PI_TRIGGERS_FILE",
       "PI_PAUSE_WINDOWS_FILE",
+      "PI_SCOPED_LIMITS_FILE",
       "PI_SUBSCRIPTIONS_FILE"
     ]);
     POINTER_BASENAME = "pi-dispatch-deployment.json";
@@ -39168,7 +39374,7 @@ var init_pricing = __esm({
 
 // ../worker/src/sandbox-store.mjs
 import { lstatSync, mkdirSync, readFileSync as readFileSync3, readdirSync as readdirSync2, renameSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute as isAbsolute2, join as join5, relative } from "node:path";
+import { isAbsolute as isAbsolute3, join as join5, relative } from "node:path";
 function readManifest({ sandboxDir, jobId, fs = defaultFs }) {
   if (!sandboxDir || jobId === void 0 || jobId === null) return null;
   const dir = join5(sandboxDir, sanitizeJobId(jobId));
@@ -39241,10 +39447,10 @@ function resolveSandbox({ jobId, sandboxDir, retentionHours, publish = [], fs, f
   return { manifest, name: sandboxContainerName(jobId), publish };
 }
 function launchSandbox({ args, spawnFn = spawn }) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const child = spawnFn("docker", args, { stdio: "inherit" });
-    child.on("error", (err) => resolve2({ code: null, error: err }));
-    child.on("close", (code) => resolve2({ code }));
+    child.on("error", (err) => resolve3({ code: null, error: err }));
+    child.on("close", (code) => resolve3({ code }));
   });
 }
 var exec3, SANDBOX_NAME_PREFIX;
@@ -39299,6 +39505,24 @@ function renderBudget({ budget, settings: settings2 } = {}) {
   if (pct !== null) lines.push(`  soft-hold band: ${pct}%`);
   return lines.join("\n");
 }
+function renderScopedLimits({ limits, scopedBudget } = {}) {
+  if (limits?.invalid) return `Scoped limits: file invalid (${limits.invalid})`;
+  const list = Array.isArray(limits?.limits) ? limits.limits : [];
+  if (list.length === 0) return null;
+  const lines = ["Scoped limits:"];
+  list.forEach((l, i) => {
+    const used = scopedBudget?.rows?.[i] ?? null;
+    const bits = [];
+    for (const key of ["day", "week", "month"]) {
+      if (!Number.isInteger(l[key])) continue;
+      const u = used && Number.isFinite(used[key]) ? used[key] : "-";
+      bits.push(`${key} ${u}/${l[key]}`);
+    }
+    if (Number.isInteger(l.concurrent)) bits.push(`<=${l.concurrent} at once`);
+    lines.push(`  ${l.scope}: ${bits.join(" \xB7 ")}`);
+  });
+  return lines.join("\n");
+}
 function capLabel(cap, reserved, pct) {
   if (!Number.isInteger(cap)) return "unknown (worker env/default)";
   const state = windowState(reserved, cap, pct);
@@ -39666,7 +39890,25 @@ function createDashboardDeps(paths) {
         redis.hgetall(STALL_KEY).catch(() => ({}))
       ]);
       const workers = Array.isArray(workerList) && workerList.length > 0 ? workerList.length : "unknown";
+      const scopedLimits = readScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath });
+      const limitRows = Array.isArray(scopedLimits?.limits) ? scopedLimits.limits : [];
+      const scopedNow = /* @__PURE__ */ new Date();
+      const scopedBudget = {
+        rows: await Promise.all(
+          limitRows.map(async (l) => {
+            const prefix = scopeKeyPrefix(l.scope);
+            const cell2 = (key) => redis.get(key).then((v) => Number(v ?? 0), () => null);
+            const row = {};
+            if (Number.isInteger(l.day)) row.day = await cell2(dayKey(scopedNow, prefix));
+            if (Number.isInteger(l.week)) row.week = await cell2(weekKey(scopedNow, prefix));
+            if (Number.isInteger(l.month)) row.month = await cell2(monthKey(scopedNow, prefix));
+            return row;
+          })
+        )
+      };
       return {
+        scopedLimits,
+        scopedBudget,
         queue: { pausedState, counts, workers },
         budget: { day: Number(dayRaw ?? 0), week: Number(weekRaw ?? 0), month: Number(monthRaw ?? 0), tokensToday: Number(tokenRaw ?? 0) },
         schedulers: mapSchedulers(schedulerList, Date.now()),
@@ -40027,6 +40269,10 @@ function makeDashboard({
         void dispose().finally(() => done({ action: "managePauses" }));
         return;
       }
+      if (data === "m" || data === "M") {
+        void dispose().finally(() => done({ action: "manageLimits" }));
+        return;
+      }
       if (matchesKey(data, "up")) {
         selected = Math.max(0, selected - 1);
         tui?.requestRender?.();
@@ -40130,6 +40376,8 @@ function renderPanel(snapshot, width, state, styler) {
     { title: "RUNS", lines: renderRunList(buildRows(snapshot, runSort), selected, 24) },
     { title: "SETTINGS", lines: toLines(renderSettingsView(snapshot.settings)) }
   ];
+  const scopedText = renderScopedLimits({ limits: snapshot.scopedLimits, scopedBudget: snapshot.scopedBudget });
+  if (scopedText) sections.splice(2, 0, { title: "SCOPED LIMITS", lines: toLines(scopedText) });
   const plain = [title];
   for (const section of sections) plain.push(section.title, ...section.lines);
   plain.push(KEY_HINTS);
@@ -40157,6 +40405,7 @@ function collapseKeys(sections, availableRows, focus, baseRows) {
 function buildListLines(snapshot, selected, inner, styler, runSort = "time", availableRows = null) {
   const trg = triggerLines(snapshot, selected, inner, styler);
   const pw = pauseLines(snapshot.pauseWindows, inner, styler);
+  const sl = limitLines(snapshot.scopedLimits, snapshot.scopedBudget, inner, styler);
   const runRows = buildRows(snapshot, runSort).slice(trg.count);
   const runCount = Array.isArray(snapshot.runs) ? snapshot.runs.length : 0;
   const sections = [
@@ -40164,6 +40413,10 @@ function buildListLines(snapshot, selected, inner, styler, runSort = "time", ava
     { key: "spend", head: ["spend & limits", "jobs & tokens/day \xB7 s set"], body: spendLines(snapshot.budget, snapshot.settings, inner, styler), priority: 4, viewKey: "s" },
     { key: "triggers", head: ["triggers", `${trg.count} standing \xB7 a add \xB7 \u21B5 open`], body: trg.lines, priority: 3, viewKey: "tab" },
     { key: "pauses", head: ["pause windows", `${pw.count} \xB7 w manage`], body: pw.lines, priority: 1, viewKey: "w" },
+    // Priority 0: the section an operator acts on least often from the panel folds FIRST under the
+    // collapse budget. The key hint lives in this divider, not the footer -- the footer's width
+    // arithmetic has no headroom for another hint (its own comment), the s/o/Tab precedent.
+    { key: "limits", head: ["scoped limits", `${sl.count} \xB7 m manage`], body: sl.lines, priority: 0, viewKey: "m" },
     { key: "runs", head: ["runs", `last ${runCount} \xB7 o ${runSort}`], body: runLines(runRows, selected - trg.count, inner, styler) },
     { key: "settings", head: ["settings", "s edit"], body: settingsLines(snapshot.settings, inner, styler), priority: 2, viewKey: "s" }
   ];
@@ -40198,7 +40451,8 @@ function statusHeader(queue, inner, styler) {
   const dot = styler.fg(stateColor, "\u25CF");
   const word = styler.bold(styler.fg(stateColor, running ? "RUNNING" : "PAUSED"));
   const sep2 = styler.fg("dim", " \xB7 ");
-  const vitals = `${c.waiting ?? 0} waiting` + sep2 + `${c.active ?? 0} active` + sep2 + (failed > 0 ? styler.fg("error", `${failed} failed`) : `${failed} failed`) + sep2 + `${queue.workers ?? "?"} workers`;
+  const delayed = Number(c.delayed ?? 0);
+  const vitals = `${c.waiting ?? 0} waiting` + sep2 + `${c.active ?? 0} active` + sep2 + (delayed > 0 ? `${delayed} delayed` + sep2 : "") + (failed > 0 ? styler.fg("error", `${failed} failed`) : `${failed} failed`) + sep2 + `${queue.workers ?? "?"} workers`;
   const clock = (/* @__PURE__ */ new Date()).toISOString().slice(11, 19);
   const left = `${dot} ${word}  ${vitals}`;
   const gap = inner - styler.visibleLen(left) - clock.length;
@@ -40353,6 +40607,39 @@ function pauseRow(w, now, inner, styler) {
   if (until) bits.push(styler.fg("warning", `resumes in ${humanizeMs(until - now) || "<1m"}`));
   return fitLine(bits.join(styler.fg("dim", "  ")), inner, styler);
 }
+function limitLines(scopedLimits, scopedBudget, inner, styler) {
+  const lines = [];
+  if (scopedLimits && scopedLimits.missing) {
+    lines.push(styler.cell("(no scoped limits \xB7 m to manage)", inner, { color: "dim" }));
+    return { count: 0, lines };
+  }
+  if (scopedLimits && scopedLimits.invalid) {
+    lines.push(styler.cell(`(scoped-limits file invalid: ${scopedLimits.invalid})`, inner, { color: "error" }));
+    return { count: 0, lines };
+  }
+  const list = (scopedLimits && scopedLimits.limits) ?? [];
+  if (list.length === 0) {
+    lines.push(styler.cell("(no scoped limits \xB7 m to manage)", inner, { color: "dim" }));
+    return { count: 0, lines };
+  }
+  list.forEach((l, i) => lines.push(limitRow(l, scopedBudget?.rows?.[i] ?? null, inner, styler)));
+  return { count: list.length, lines };
+}
+function limitRow(l, used, inner, styler) {
+  let atCap = false;
+  const windows = [];
+  for (const key of ["day", "week", "month"]) {
+    if (!Number.isInteger(l[key])) continue;
+    const u = used && Number.isFinite(used[key]) ? used[key] : null;
+    const over = u !== null && u >= l[key];
+    if (over) atCap = true;
+    windows.push(styler.fg(over ? "warning" : "text", `${key} ${u ?? "-"}/${l[key]}`));
+  }
+  const dot = atCap ? styler.fg("warning", "\u25CF") : styler.fg("dim", "\u25CB");
+  const bits = [`${dot} ${styler.fg("accent", l.scope ?? "-")}`, ...windows];
+  if (Number.isInteger(l.concurrent)) bits.push(styler.fg("muted", `\u2264${l.concurrent} at once`));
+  return fitLine(bits.join(styler.fg("dim", "  ")), inner, styler);
+}
 function runLines(rows, selected, inner, styler) {
   if (!Array.isArray(rows) || rows.length === 0) return [styler.cell("(no runs)", inner, { color: "dim" })];
   const { top, count } = runsWindow(rows.length, selected);
@@ -40770,6 +41057,7 @@ var init_dashboard = __esm({
     init_scheduler_stall_guard();
     init_pause_windows();
     init_read_model();
+    init_scoped_limits();
     init_render();
     init_keys2();
     init_panel();
@@ -40858,16 +41146,16 @@ async function runAttached(ctx, { title, argv0, args, cwd, env, shell, spawnFn =
 ${title}
 
 `);
-        outcome = await new Promise((resolve2) => {
+        outcome = await new Promise((resolve3) => {
           let child;
           try {
             child = spawnFn(argv0, args, { stdio: "inherit", cwd, env, ...shell ? { shell: true } : {} });
           } catch (err) {
-            resolve2({ code: null, error: err });
+            resolve3({ code: null, error: err });
             return;
           }
-          child.on("error", (err) => resolve2({ code: null, error: err }));
-          child.on("close", (code) => resolve2({ code }));
+          child.on("error", (err) => resolve3({ code: null, error: err }));
+          child.on("close", (code) => resolve3({ code }));
         });
       } catch (err) {
         outcome = { code: null, error: err };
@@ -41086,6 +41374,7 @@ up shows each docker action and asks y/N before it \u2014 nothing is auto-accept
     env: {
       PI_TRIGGERS_FILE: join6(dir, "triggers.json"),
       PI_PAUSE_WINDOWS_FILE: join6(dir, "pause-windows.json"),
+      PI_SCOPED_LIMITS_FILE: join6(dir, "scoped-limits.json"),
       PI_SUBSCRIPTIONS_FILE: join6(dir, "subscriptions.json")
     }
   };
@@ -41318,7 +41607,7 @@ var init_setup_wizard = __esm({
     init_deployment_pointer();
     init_read_model();
     init_index();
-    RUNTIME_VERSION = "1.4.0";
+    RUNTIME_VERSION = "1.5.0";
     RECEIVER_VERSION = "1.3.0";
     RUNTIME_PKG = "@edgehero/pi-dispatch";
     RECEIVER_PKG = "@edgehero/pi-dispatch-receiver";
@@ -41513,15 +41802,15 @@ function registerTools(pi) {
   pi.registerTool({
     name: "dispatch_costs",
     label: "pi-dispatch costs",
-    description: "Read-only. Folds the PII-free run history against the operator's declared subscriptions and pi-ai's rate tables into the costs read-model: window totals, daily buckets, per-flow and per-model rollups, per-plan verdicts, and provenance. window = 7d | 30d | mtd (default mtd); flow filters to one flow's runs.",
-    parameters: typebox_exports.Object({ window: typebox_exports.Optional(typebox_exports.String()), flow: typebox_exports.Optional(typebox_exports.String()) }),
+    description: `Read-only. Folds the PII-free run history against the operator's declared subscriptions and pi-ai's rate tables into the costs read-model: window totals, daily buckets, per-flow and per-model rollups, per-plan verdicts, and provenance. window = 7d | 30d | mtd (default mtd); flow filters to one flow's runs; repo filters to one repo's runs by the by-repo rollup's key (e.g. "acme/web" or "local:site").`,
+    parameters: typebox_exports.Object({ window: typebox_exports.Optional(typebox_exports.String()), flow: typebox_exports.Optional(typebox_exports.String()), repo: typebox_exports.Optional(typebox_exports.String()) }),
     async execute(_toolCallId, params) {
       const window = params.window ?? "mtd";
       if (!COSTS_WINDOWS.includes(window)) {
         throw new Error(`unknown window '${window}' (7d|30d|mtd)`);
       }
       const paths = resolvePaths(process.env);
-      const res = assembleCosts(paths, window, params.flow);
+      const res = assembleCosts(paths, window, params.flow, params.repo);
       if (res.unreachable) throw new Error(`could not read the run history: ${res.unreachable}`);
       return toolText(JSON.stringify({ window, fold: res.fold }));
     }
@@ -41803,6 +42092,113 @@ ${JSON.stringify(before)}
       return toolText(JSON.stringify(result));
     }
   });
+  pi.registerTool({
+    name: "dispatch_limits",
+    label: "pi-dispatch scoped limits",
+    description: "Read-only. Lists the scoped limits (per repo/folder budget caps and concurrency, scoped-limits.json) with their array index and, when the queue is reachable, each scope's used day/week/month run counts. Use the index for dispatch_limit_edit / dispatch_limit_delete. The always-on one-job-per-folder mutex for local jobs is separate: it has no entry here and no switch anywhere.",
+    parameters: typebox_exports.Object({}),
+    async execute() {
+      const paths = resolvePaths(process.env);
+      const p = readScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath });
+      if (!Array.isArray(p?.limits)) return toolText(JSON.stringify(p));
+      const counters = await readScopedBudget({ url: paths.valkeyUrl, limits: p.limits });
+      const rows = p.limits.map((l, index) => ({ index, ...l, used: counters.rows?.[index] ?? null }));
+      return toolText(JSON.stringify(rows));
+    }
+  });
+  pi.registerTool({
+    name: "dispatch_limit_add",
+    label: "pi-dispatch add scoped limit",
+    description: 'Adds a scoped limit and applies it live: jobs whose scope (a repo "owner/name" or a local folder path, ABSOLUTE, matched exactly like pause windows \u2014 no globs) exceed the `day`/`week`/`month` job-count caps are REFUSED before any spend (reason scope-cap, never retried); jobs over `concurrent` are DEFERRED, never dropped, and run when a slot frees. At least one of day/week/month/concurrent is required, each an integer >= 1. The operator MUST approve a confirm dialog showing the entry; refused with no interactive operator.',
+    executionMode: "sequential",
+    parameters: typebox_exports.Object({
+      scope: typebox_exports.String(),
+      day: typebox_exports.Optional(typebox_exports.Integer({ minimum: 1 })),
+      week: typebox_exports.Optional(typebox_exports.Integer({ minimum: 1 })),
+      month: typebox_exports.Optional(typebox_exports.Integer({ minimum: 1 })),
+      concurrent: typebox_exports.Optional(typebox_exports.Integer({ minimum: 1 }))
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const paths = resolvePaths(process.env);
+      const l = buildScopedLimit(params);
+      const result = await confirmedWrite(
+        ctx,
+        { title: "Add scoped limit", message: `Add to scoped-limits.json:
+${JSON.stringify(l)}` },
+        () => {
+          const res = writeScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath, mutate: (list) => [...list, l] });
+          if (res.invalid) throw new Error(`rejected: ${res.invalid}`);
+          return { applied: true, added: l };
+        }
+      );
+      return toolText(JSON.stringify(result));
+    }
+  });
+  pi.registerTool({
+    name: "dispatch_limit_delete",
+    label: "pi-dispatch delete scoped limit",
+    description: "Removes a scoped limit (by array index from dispatch_limits) and applies it live. The operator MUST approve a confirm dialog showing the limit; refused with no interactive operator.",
+    executionMode: "sequential",
+    parameters: typebox_exports.Object({ index: typebox_exports.Integer({ minimum: 0 }) }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const paths = resolvePaths(process.env);
+      const p = readScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath });
+      const list = Array.isArray(p?.limits) ? p.limits : [];
+      const cur = list[params.index];
+      if (!cur) throw new Error(`no scoped limit at index ${params.index} (have ${list.length})`);
+      const result = await confirmedWrite(
+        ctx,
+        { title: `Delete scoped limit #${params.index + 1}`, message: `Remove scoped limit #${params.index + 1}: ${cur.scope} ${limitSummary(cur)}` },
+        () => {
+          const res = writeScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath, mutate: (l) => l.filter((_, i) => i !== params.index) });
+          if (res.invalid) throw new Error(`rejected: ${res.invalid}`);
+          return { applied: true, deletedIndex: params.index };
+        }
+      );
+      return toolText(JSON.stringify(result));
+    }
+  });
+  pi.registerTool({
+    name: "dispatch_limit_edit",
+    label: "pi-dispatch edit scoped limit",
+    description: "Changes fields of an existing scoped limit (by array index from dispatch_limits) and applies it live. Provide only the fields to change (scope/day/week/month/concurrent); the rest keep their current value (to drop one cap from an entry, delete it and re-add without that field). The operator MUST approve a confirm dialog showing the before->after; refused with no interactive operator.",
+    executionMode: "sequential",
+    parameters: typebox_exports.Object({
+      index: typebox_exports.Integer({ minimum: 0 }),
+      scope: typebox_exports.Optional(typebox_exports.String()),
+      day: typebox_exports.Optional(typebox_exports.Integer({ minimum: 1 })),
+      week: typebox_exports.Optional(typebox_exports.Integer({ minimum: 1 })),
+      month: typebox_exports.Optional(typebox_exports.Integer({ minimum: 1 })),
+      concurrent: typebox_exports.Optional(typebox_exports.Integer({ minimum: 1 }))
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const paths = resolvePaths(process.env);
+      const p = readScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath });
+      const list = Array.isArray(p?.limits) ? p.limits : [];
+      const cur = list[params.index];
+      if (!cur) throw new Error(`no scoped limit at index ${params.index} (have ${list.length})`);
+      const before = buildScopedLimit(cur);
+      const merged = buildScopedLimit({
+        scope: params.scope ?? cur.scope,
+        day: params.day ?? cur.day,
+        week: params.week ?? cur.week,
+        month: params.month ?? cur.month,
+        concurrent: params.concurrent ?? cur.concurrent
+      });
+      const result = await confirmedWrite(
+        ctx,
+        { title: `Edit scoped limit #${params.index + 1}`, message: `scoped limit #${params.index + 1}:
+${JSON.stringify(before)}
+\u2192 ${JSON.stringify(merged)}` },
+        () => {
+          const res = writeScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath, mutate: (l) => l.map((w, i) => i === params.index ? merged : w) });
+          if (res.invalid) throw new Error(`rejected: ${res.invalid}`);
+          return { applied: true, index: params.index, limit: merged };
+        }
+      );
+      return toolText(JSON.stringify(result));
+    }
+  });
   pi.registerTool({
     name: "dispatch_trigger_delete",
     label: "pi-dispatch delete trigger",
@@ -41888,6 +42284,22 @@ function buildPauseWindow(f) {
   if (dateTo) w.dateTo = dateTo;
   return w;
 }
+function buildScopedLimit(f) {
+  const l = { scope: String(f.scope ?? "").trim() };
+  for (const k of ["day", "week", "month", "concurrent"]) {
+    const v = optInt(f[k]);
+    if (v !== void 0) l[k] = v;
+  }
+  return l;
+}
+function limitSummary(l) {
+  const bits = [];
+  if (Number.isInteger(l?.day)) bits.push(`day ${l.day}`);
+  if (Number.isInteger(l?.week)) bits.push(`week ${l.week}`);
+  if (Number.isInteger(l?.month)) bits.push(`month ${l.month}`);
+  if (Number.isInteger(l?.concurrent)) bits.push(`\u2264${l.concurrent} at once`);
+  return bits.join(" \xB7 ");
+}
 function asWords(x) {
   if (Array.isArray(x)) return x.map((s) => String(s).trim()).filter(Boolean);
   return splitWords(x);
@@ -41957,7 +42369,11 @@ ${renderBudget({ budget, settings: settings2 })}`);
     case "budget": {
       const budget = await readBudget({ url: paths.valkeyUrl });
       const settings2 = readSettingsView({ settingsFile: paths.settingsFile });
-      send(pi, renderBudget({ budget, settings: settings2 }));
+      const limits = readScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath });
+      const scopedBudget = Array.isArray(limits?.limits) && limits.limits.length > 0 ? await readScopedBudget({ url: paths.valkeyUrl, limits: limits.limits }) : { rows: [] };
+      const scopedText = renderScopedLimits({ limits, scopedBudget });
+      send(pi, `${renderBudget({ budget, settings: settings2 })}${scopedText ? `
+${scopedText}` : ""}`);
       return;
     }
     case "triggers": {
@@ -42038,13 +42454,14 @@ ${renderBudget({ budget, settings: settings2 })}`);
       return;
   }
 }
-function assembleCosts(paths, window, flow) {
+function assembleCosts(paths, window, flow, repo) {
   const nowMs = Date.now();
   const sinceMs = costsSinceMs(window, nowMs);
   const records = scanRunRecords({ logsDir: paths.logsDir, sinceMs, nowMs });
   if (!Array.isArray(records)) return records;
   const subs = readSubscriptions({ subscriptionsPath: paths.subscriptionsPath });
-  const scoped = typeof flow === "string" && flow !== "" ? records.filter((r) => (r?.flow ?? null) === flow) : records;
+  const flowScoped = typeof flow === "string" && flow !== "" ? records.filter((r) => (r?.flow ?? null) === flow) : records;
+  const scoped = typeof repo === "string" && repo !== "" ? flowScoped.filter((r) => repoOfTarget(r?.target) === repo) : flowScoped;
   const triggersView = readTriggers({ triggersPath: paths.triggersPath });
   const triggerJoin = attributeRunsToTriggers({ records: scoped, triggers: Array.isArray(triggersView?.triggers) ? triggersView.triggers : [] });
   const fold = foldCosts({
@@ -42107,13 +42524,27 @@ async function assembleBudgetView(paths) {
   const tokensSpent = unreachable === null ? Number(raw.tokensToday ?? 0) : null;
   const tokenCap = posIntOrNull(overlay.dailyTokenCap);
   const tokenState = tokenCap !== null && tokensSpent !== null ? tokensSpent >= tokenCap ? "over" : pct !== null && tokensSpent > Math.floor(tokenCap * pct / 100) ? "soft-hold" : "ok" : "ok";
+  const limitsView = readScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath });
+  const limits = Array.isArray(limitsView?.limits) ? limitsView.limits : [];
+  const scopedCounters = limits.length > 0 ? await readScopedBudget({ url: paths.valkeyUrl, limits }) : { rows: [] };
+  const scoped = limits.map((l, i) => {
+    const used = scopedCounters?.rows?.[i] ?? null;
+    const win = (cap, key) => {
+      if (cap === null) return null;
+      const u = used && Number.isFinite(used[key]) ? used[key] : null;
+      return { used: u, cap, state: u !== null ? windowState(u, cap, null) : "ok" };
+    };
+    return { scope: l.scope, day: win(l.day, "day"), week: win(l.week, "week"), month: win(l.month, "month"), concurrent: l.concurrent };
+  });
   return {
     unreachable,
     softHoldPct: pct,
     day: slotWindow("day", "dailyCap"),
     week: slotWindow("week", "weeklyCap"),
     month: slotWindow("month", "monthlyCap"),
-    tokens: { spent: tokensSpent, cap: tokenCap, state: tokenState, maxTokens: posIntOrNull(overlay.maxTokens) }
+    tokens: { spent: tokensSpent, cap: tokenCap, state: tokenState, maxTokens: posIntOrNull(overlay.maxTokens) },
+    scoped,
+    scopedInvalid: limitsView?.invalid ? String(limitsView.invalid) : null
   };
 }
 async function assembleInsights(paths, window) {
@@ -42280,7 +42711,7 @@ could not start docker: ${error.message}
   }
 }
 function pauseForMessage() {
-  return new Promise((resolve2) => setTimeout(resolve2, 2500));
+  return new Promise((resolve3) => setTimeout(resolve3, 2500));
 }
 function splitWords(s) {
   return String(s ?? "").split(/\s+/).map((w) => w.trim()).filter(Boolean);
@@ -42306,8 +42737,84 @@ async function handleDashboardAction(result, paths, ctx) {
       return editSettingsViaDialogs(paths, ui, notify);
     case "managePauses":
       return managePausesViaDialogs(paths, ui, notify);
+    case "manageLimits":
+      return manageLimitsViaDialogs(paths, ui, notify);
   }
 }
+async function manageLimitsViaDialogs(paths, ui, notify) {
+  const action = await ui.select("Scoped limits", ["Add a scoped limit", "Edit a scoped limit", "Delete a scoped limit"]);
+  if (!action) return;
+  if (action.startsWith("Add")) return addScopedLimitViaDialogs(paths, ui, notify);
+  if (action.startsWith("Edit")) return editScopedLimitViaDialogs(paths, ui, notify);
+  return deleteScopedLimitViaDialogs(paths, ui, notify);
+}
+async function addScopedLimitViaDialogs(paths, ui, notify) {
+  const scope = await ui.input('scope \u2014 a repo "owner/name" or an ABSOLUTE local folder path (exact match, no globs)', "");
+  if (scope === void 0 || scope.trim() === "") return;
+  const day = await ui.input("day \u2014 max jobs per UTC day for this scope (blank = no day cap)", "");
+  if (day === void 0) return;
+  const week = await ui.input("week \u2014 max jobs per Mon-Sun UTC week (blank = no week cap)", "");
+  if (week === void 0) return;
+  const month = await ui.input("month \u2014 max jobs per calendar month (blank = no month cap)", "");
+  if (month === void 0) return;
+  const concurrent = await ui.input("concurrent \u2014 max jobs in flight for this scope, extras deferred (blank = no limit)", "");
+  if (concurrent === void 0) return;
+  const l = buildScopedLimit({ scope, day, week, month, concurrent });
+  const res = writeScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath, mutate: (list) => [...list, l] });
+  notify?.(res.ok ? `scoped limit added (live) \u2014 ${l.scope} ${limitSummary(l)}` : `add rejected: ${res.invalid}`, res.ok ? "info" : "error");
+}
+async function editScopedLimitViaDialogs(paths, ui, notify) {
+  const p = readScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath });
+  const list = Array.isArray(p?.limits) ? p.limits : [];
+  if (list.length === 0) {
+    notify?.("no scoped limits to edit", "info");
+    return;
+  }
+  const labels = list.map((l, i) => `#${i + 1}  ${l.scope}  ${limitSummary(l)}`);
+  const picked = await ui.select("Edit which scoped limit", labels);
+  if (!picked) return;
+  const index = labels.indexOf(picked);
+  if (index < 0) return;
+  const cur = list[index];
+  const ask = async (label, current) => ui.input(`${label} \u2014 blank keeps "${current}"`, current);
+  const keep = (v, current) => v === void 0 || v.trim() === "" ? current : v;
+  const scope = await ask("scope", cur.scope ?? "");
+  if (scope === void 0) return;
+  const day = await ask("day cap", String(cur.day ?? ""));
+  if (day === void 0) return;
+  const week = await ask("week cap", String(cur.week ?? ""));
+  if (week === void 0) return;
+  const month = await ask("month cap", String(cur.month ?? ""));
+  if (month === void 0) return;
+  const concurrent = await ask("concurrent (max in flight)", String(cur.concurrent ?? ""));
+  if (concurrent === void 0) return;
+  const merged = buildScopedLimit({
+    scope: keep(scope, cur.scope),
+    day: keep(day, cur.day),
+    week: keep(week, cur.week),
+    month: keep(month, cur.month),
+    concurrent: keep(concurrent, cur.concurrent)
+  });
+  const res = writeScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath, mutate: (l) => l.map((w, i) => i === index ? merged : w) });
+  notify?.(res.ok ? `scoped limit #${index + 1} updated (live) \u2014 ${merged.scope} ${limitSummary(merged)}` : `edit rejected: ${res.invalid}`, res.ok ? "info" : "error");
+}
+async function deleteScopedLimitViaDialogs(paths, ui, notify) {
+  const p = readScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath });
+  const list = Array.isArray(p?.limits) ? p.limits : [];
+  if (list.length === 0) {
+    notify?.("no scoped limits to delete", "info");
+    return;
+  }
+  const labels = list.map((l, i) => `#${i + 1}  ${l.scope}  ${limitSummary(l)}`);
+  const picked = await ui.select("Delete which scoped limit", labels);
+  if (!picked) return;
+  const index = labels.indexOf(picked);
+  if (index < 0) return;
+  const ok = await ui.confirm("Delete scoped limit", `Remove ${labels[index]}?`);
+  if (!ok) return;
+  const res = writeScopedLimits({ scopedLimitsPath: paths.scopedLimitsPath, mutate: (l) => l.filter((_, i) => i !== index) });
+  notify?.(res.ok ? `scoped limit #${index + 1} deleted (live)` : `delete rejected: ${res.invalid}`, res.ok ? "info" : "error");
+}
 async function managePausesViaDialogs(paths, ui, notify) {
   const action = await ui.select("Pause windows", ["Add a pause window", "Edit a pause window", "Delete a pause window"]);
   if (!action) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-admin",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Operator console (a pi extension) + skill for pi-dispatch: run the pi coding agent as a self-hosted service. A /dispatch TUI for the queue, spend caps, run history, editable GitHub, GitLab, Forgejo and Azure DevOps triggers (cron/label/comment/PR/MR/work item), and scheduled pause windows — plus AI-operable, human-confirmed controls. Runs against a live pi-dispatch deployment.",
   "keywords": [
     "pi-package",

package/skills/operate-pi-dispatch/SKILL.md

@@ -41,6 +41,12 @@ dialog before it takes effect**:
   (per folder/repo "quiet hours": runs for a scope are deferred between certain times and auto-resume after;
   `dispatch_pauses` lists them with their index). `dispatch_pause_edit` is a partial change — pass the index
   plus only the fields to alter. Deferring never drops a job and costs no budget.
+- `dispatch_limit_add` / `dispatch_limit_edit` / `dispatch_limit_delete` — manage scoped limits (per
+  repo/folder budget caps and concurrency: `day`/`week`/`month` job-count caps refuse a job pre-spend with
+  reason `scope-cap`, never retried; `concurrent` defers the excess, never drops it; `dispatch_limits`
+  lists them with their index and used counts). `dispatch_limit_edit` is a partial change — pass the index
+  plus only the fields to alter. Scopes match exactly (a repo `owner/name` or an ABSOLUTE folder path, no
+  globs).
 
 Use them like this:
 
@@ -235,3 +241,28 @@ If you are asked why a GitLab trigger did not fire, the usual answers in order:
 2. **No label was added by that event.** GitLab has no `labeled` action; the trigger fires on the labels
    an event *added*, so editing an already-labelled issue does nothing. This is deliberate.
 3. **The action word belongs to the other forge.** See above.
+
+## Scoped limits — and the folder mutex you cannot turn off
+
+`scoped-limits.json` holds per-scope bounds beside the deployment-global ones: `day`/`week`/`month` cap
+how many jobs a repo or folder may run per window (refused pre-spend, reason `scope-cap`, never retried,
+the scope's own counter still counts the refusal), and `concurrent` caps how many run at once (the excess
+is deferred to the delayed set and runs when a slot frees — never dropped, no budget spent while waiting).
+Edits apply live: the worker hot-reloads the file and keeps the last good version on a bad edit.
+
+Separate from all of that, **local jobs carry a built-in one-job-per-folder mutex: at most one job per
+folder at a time, always on, with NO configuration, NO tool, and NO panel key.** If an operator asks to
+disable it, say plainly that there is no switch, deliberately: two agents editing one working tree race
+each other with no gate and no undo, and an off switch's only use is re-opening that race. A `concurrent`
+value on a folder scope can never raise the mutex's one-at-a-time (the lower bound always wins).
+
+Three more things to say when asked:
+
+- **A `scope-cap` refusal is final for that window.** The counter is not resettable from any tool; the
+  window rolls over on its own (day/week/month, UTC). Raising the cap via `dispatch_limit_edit` takes
+  effect at the next job.
+- **Deferrals are visible only as the queue's delayed count** (the panel's status line shows it when it
+  is nonzero). That count also includes cron next-occurrences and retry backoff — a nonzero number is
+  normal on any deployment with schedules.
+- **Per-scope in-flight is not displayed anywhere.** The panel and `dispatch_limits` show `concurrent` as
+  configuration only; the live count lives inside the worker process and no reader can see it.