@edgehero/pi-dispatch-admin 0.8.0 → 1.1.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.
+**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.
 
 > 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.
 
@@ -46,28 +46,28 @@ Every trigger is one `{ on, run }` entry in a single `triggers.json`, read live
 
 Four forges: GitHub, GitLab, Forgejo (and Gitea), Azure DevOps. **Who may fire a trigger is your forge's decision, not this service's**: on GitHub the label *is* the approval, because only collaborators can apply one, while GitLab, Forgejo and Azure resolve the actor's permission through their APIs. Each forge's action vocabulary is validated when the file loads, so a word from the wrong forge is refused instead of silently never matching.
 
-**Flows, and workflows.** `run.flow` names a skill committed to the target repo at `.pi/skills/<flow>/SKILL.md`, read from the **default branch**, so the repo owns the prompt and merging it is the repo's consent. A skill may call other skills, which is already a workflow. For typed multi-stage ones, a pi extension such as `@juicesharp/rpiv-workflow` can be staged into the deployment: pinned to an exact version, installed on your host (never at job time, since jobs run offline), loaded in every container, and declinable per trigger. Anything you already installed with `pi install` is staged automatically, at the version your host has, so there is nothing to declare twice.
+**Flows, and workflows.** `run.flow` names a skill committed to the target repo at `.pi/skills/<flow>/SKILL.md`, read from the **default branch**, so the repo owns the prompt and merging it is the repo's consent. A skill may call other skills, which is already a workflow. For typed multi-stage ones, a pi extension such as `@juicesharp/rpiv-workflow` can be staged into the deployment: pinned to an exact version, installed on your host (never at job time, since jobs run offline), loaded in every container, and declinable per trigger. Anything you already installed with `pi install` is staged automatically, at the version your host has, so there is nothing to declare twice. `run.command` is the second entry point: instead of a flow, a trigger may name a registered command a staged extension provides (`"command": "wf run nightly"`), and the job's whole prompt is that dispatch line, handled by the extension with no model turn in between. It picks which vetted command dispatches, never what code runs, and it is never AI-triggerable: job chaining refuses any request naming one, and `dispatch_run` cannot express one.
 
-**How a workflow gets triggered, in one line:** `label / comment / PR / cron` fires **one job in one container**, that job runs `run.flow`, and the flow drives whatever stages follow. Four consequences worth knowing before you build on it. A trigger names a **flow, never a workflow**, so which stages run is decided inside the job by that skill. A job is **not an interactive session** (the container hands pi one assembled prompt and reads the exit line), so a workflow extension's slash command has nobody to type it: in a job the flow's instructions drive the workflow, or a small extension you also staged calls its API from a lifecycle hook. One trigger is **one job, one budget slot and one turn budget**, so ten stages share the same `PI_MAX_TURNS` and per-job token budget, and exhausting either ends the job as a policy refusal that is never retried. And whether the workflow's own state survives depends on the trigger kind: a cron or CLI job has your folder mounted read-write so state persists between runs, while a forge job gets a fresh clone that is discarded with the container. Full reference: [`docs/workflows.md`](https://github.com/edgehero/pi-dispatch/blob/main/docs/workflows.md).
+**How a workflow gets triggered, in one line:** `label / comment / PR / cron` fires **one job in one container**, that job runs `run.flow` or `run.command`, and the entry point drives whatever stages follow. Four consequences worth knowing before you build on it. A trigger names a **flow or a registered command, never a workflow**, so which stages run is decided by what that entry point does. A job is **not an interactive session** (the container hands pi one assembled prompt and reads the exit line), and that one prompt can be the command itself: `run.command` dispatches a workflow extension's slash command headlessly, while in a flow job the flow's instructions drive the workflow, or a small extension you also staged calls its API from a lifecycle hook. One trigger is **one job, one budget slot and one turn budget**, so ten stages share the same `PI_MAX_TURNS` and per-job token budget, and exhausting either ends the job as a policy refusal that is never retried. And whether the workflow's own state survives depends on the trigger kind: a cron or CLI job has your folder mounted read-write so state persists between runs, while a forge job gets a fresh clone that is discarded with the container. Full reference: [`docs/workflows.md`](https://github.com/edgehero/pi-dispatch/blob/main/docs/workflows.md).
 
 ## The console: `/dispatch`
 
 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=0.11.0" alt="The /dispatch panel: status, spend meters, triggers, 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, 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.
 - **Insights, the one analytics page.** Press `i` on the panel (or type `/dispatch insights`) and a single self contained page opens in your browser: the budget dials (the one lever that actually changes what all of this costs), per-plan verdicts against API rates, daily, cumulative and per-flow spend charts, the four breakdowns (flow, trigger, model, repo), and the whole trigger and flow topology with spend badged onto the triggers that earned it. Every dollar carries its class: a plan-covered run never renders as $0.00, and an estimate is always marked as one. Design your agent loops as triggers and skills, see the loops you actually built, and see what each one costs, all in one place ([`docs/insights.md`](https://github.com/edgehero/pi-dispatch/blob/main/docs/insights.md)).
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/insights-view.png?v=0.11.0" alt="The insights page: KPI tiles, a plan verdict card, the daily spend chart, the four breakdowns with plan-covered buckets drawn as chips instead of dollar bars, and the topology with spend badges" width="820">
+  <img src="https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/insights-view.png?v=1.0.0" alt="The insights page: KPI tiles, a plan verdict card, the daily spend chart, the four breakdowns with plan-covered buckets drawn as chips instead of dollar bars, and the topology with spend badges and tier-resolved flows" width="820">
 </p>
 
 - **Triggers, editable live.** cron, label, comment and pull_request triggers with colored drill-ins showing what fires each one, what it runs, and its trust model. Added, edited and deleted without a restart. 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). 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.
+- **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.
 - **Logs stay put.** Raw container output renders only in the overlay viewer, never into model context.
 
 ## Install
@@ -80,7 +80,7 @@ pi install npm:@edgehero/pi-dispatch-admin   # then, in pi:  /dispatch
 
 Already have a deployment? The panel finds it through the deployment pointer setup writes, or through the same env vars your worker uses (`VALKEY_URL`, `PI_LOGS_DIR`, `PI_SETTINGS_FILE`, `PI_TRIGGERS_FILE`, `PI_PAUSE_WINDOWS_FILE`, `PI_SUBSCRIPTIONS_FILE`). Your env always wins.
 
-`dispatch_run` is inert until you set one more variable yourself: `PI_DISPATCH_RUN_ROOTS` defaults to empty, and an empty allowlist refuses every folder. The deployment pointer deliberately cannot set it (the pointer carries paths, never capability grants), so widening that allowlist is always your own env edit.
+`dispatch_run` is inert until you set one more variable yourself: `PI_DISPATCH_RUN_ROOTS` defaults to empty, and an empty allowlist refuses every folder. The deployment pointer deliberately cannot set it (the pointer carries paths, never capability grants), so widening that allowlist is always your own env edit. No allowlist reaches commands either: a `run.command` fires from the reviewed triggers file only.
 
 ## Get the whole thing
 

package/dist/index.mjs

@@ -7598,6 +7598,12 @@ var init_build = __esm({
   }
 });
 
+// ../worker/src/egress.mjs
+var init_egress = __esm({
+  "../worker/src/egress.mjs"() {
+  }
+});
+
 // ../worker/src/forges.mjs
 function isForgeKind(kind) {
   return typeof kind === "string" && Object.hasOwn(FORGES, kind);
@@ -7698,6 +7704,7 @@ function defaultSettingsFile() {
 var CHAIN_DEPTH_MAX_DEFAULT, CHAIN_MAX_PER_JOB_DEFAULT;
 var init_config2 = __esm({
   "../worker/src/config.mjs"() {
+    init_egress();
     init_forges();
     CHAIN_DEPTH_MAX_DEFAULT = 1;
     CHAIN_MAX_PER_JOB_DEFAULT = 2;
@@ -7927,13 +7934,14 @@ function normalizeCron(on, run, index, path, state) {
   if (fieldCount !== 5 && fieldCount !== 6) {
     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 (!isNonEmptyString2(run.folder)) {
     throw configError(`cron trigger "${id}": run.folder must be a non-empty string: ${path}`);
   }
-  if (!isNonEmptyString2(run.flow)) {
-    throw configError(`cron trigger "${id}": run.flow must be a non-empty string: ${path}`);
+  if (command === void 0 && !isNonEmptyString2(run.flow)) {
+    throw configError(`cron trigger "${id}": run.flow must be a non-empty string (or use run.command): ${path}`);
   }
-  if (!isNonEmptyString2(run.task)) {
+  if (command === void 0 && !isNonEmptyString2(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") {
@@ -7947,7 +7955,7 @@ function normalizeCron(on, run, index, path, state) {
   validateReplicas(run, `cron trigger "${id}"`, path);
   return {
     on: { type: "cron", id, pattern },
-    run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume, ...skillsDir !== void 0 && { skillsDir } }
+    run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir } }
   };
 }
 function validatePackagesFlag(run, at, path) {
@@ -8006,6 +8014,35 @@ function validateInstructions(run, at, path, { cron = false } = {}) {
   }
   return text;
 }
+function validateCommand(run, at, path, { onType }) {
+  const raw = run.command;
+  if (run.flow !== void 0 && raw !== void 0) {
+    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 (!isNonEmptyString2(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()) {
+    throw configError(`${at}: run.command must not have leading or trailing whitespace -- the arguments reach the command handler verbatim, so trimming here would make the reviewed file disagree with what runs (got ${JSON.stringify(raw)}): ${path}`);
+  }
+  if (raw.startsWith("/")) {
+    throw configError(`${at}: run.command must not start with "/" -- the runner prepends the slash when it builds the /name args prompt, so a written one would dispatch "//name" (got ${JSON.stringify(raw)}): ${path}`);
+  }
+  if (/[\u0000-\u001F\u007F]/.test(raw)) {
+    throw configError(`${at}: run.command must not contain control characters -- a newline would smuggle a second line into what the operator reviewed as one command line (got ${JSON.stringify(raw)}): ${path}`);
+  }
+  if (onType === "cron" && run.task !== void 0) {
+    throw configError(`${at}: run.command and run.task cannot be combined -- a command job's prompt IS the /name args line, so there is no task text for the runner to render; put the arguments in run.command: ${path}`);
+  }
+  if (onType !== "cron" && run.instructions !== void 0) {
+    throw configError(`${at}: run.command and run.instructions cannot be combined -- instructions render into the prompt envelope, and a command job's prompt is the exact /name args line with no envelope, so nothing would render them: ${path}`);
+  }
+  if (run.resume === true) {
+    throw configError(`${at}: combining run.command and run.resume is not yet covered -- what a resumed session should do with a re-dispatched command is undesigned, so this is a gap to close, not a limit: ${path}`);
+  }
+  return raw;
+}
 function validatePredicate(on, index, path, requirePositive) {
   const at = `trigger at index ${index}`;
   for (const key of ["any", "all", "none"]) {
@@ -8041,9 +8078,6 @@ function validateReplicas(run, at, path) {
   if (run.kind === "local") {
     throw configError(`${at}: run.replicas is not available on a cron trigger -- a local job's /workspace IS the operator's folder, bind-mounted read-write, so two replicas would edit one working tree with no gate and no undo: ${path}`);
   }
-  if (run.kind !== "github") {
-    throw configError(`${at}: run.replicas is not yet covered for ${run.kind} triggers (github only in this version); every forge mints its branch the same way, so this is a gap to close, not a limit: ${path}`);
-  }
   if (!Number.isInteger(replicas) || replicas < 2 || replicas > REPLICAS_MAX) {
     throw configError(`${at}: run.replicas must be an integer between 2 and ${REPLICAS_MAX} when present -- ${REPLICAS_MAX} is the ceiling because PI_CONCURRENCY defaults to 3, so a further replica would queue instead of racing, and 1 is refused because a one-member replica set is a flag that does nothing (got ${JSON.stringify(replicas)}): ${path}`);
   }
@@ -8055,8 +8089,9 @@ function validateReplicas(run, at, path) {
 function normalizeLabel(on, run, index, path) {
   const at = `trigger at index ${index}`;
   const predicate = validatePredicate(on, index, path, true);
-  if (!isNonEmptyString2(run.flow)) {
-    throw configError(`${at}: label trigger run.flow must be a non-empty string: ${path}`);
+  const command = validateCommand(run, at, path, { onType: "label" });
+  if (command === void 0 && !isNonEmptyString2(run.flow)) {
+    throw configError(`${at}: label trigger run.flow must be a non-empty string (or use run.command): ${path}`);
   }
   const packages = validatePackagesFlag(run, at, path);
   const image = validateImageRef(run, at, path);
@@ -8067,7 +8102,7 @@ function normalizeLabel(on, run, index, path) {
   const replicas = validateReplicas(run, at, path);
   return {
     on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none },
-    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...repository !== void 0 && { repository } }
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...repository !== void 0 && { repository } }
   };
 }
 function normalizeComment(on, run, index, path, state) {
@@ -8075,8 +8110,9 @@ function normalizeComment(on, run, index, path, state) {
   if (!isNonEmptyString2(on.phrase)) {
     throw configError(`${at}: comment trigger on.phrase must be a non-empty string: ${path}`);
   }
-  if (!isNonEmptyString2(run.flow)) {
-    throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string: ${path}`);
+  const command = validateCommand(run, at, path, { onType: "comment" });
+  if (command === void 0 && !isNonEmptyString2(run.flow)) {
+    throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string (or use run.command): ${path}`);
   }
   state.commentCounts[run.kind] = (state.commentCounts[run.kind] ?? 0) + 1;
   if (state.commentCounts[run.kind] > 1) {
@@ -8091,7 +8127,7 @@ function normalizeComment(on, run, index, path, state) {
   const replicas = validateReplicas(run, at, path);
   return {
     on: { type: "comment", phrase: on.phrase },
-    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...repository !== void 0 && { repository } }
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...repository !== void 0 && { repository } }
   };
 }
 function normalizePullRequest(on, run, index, path) {
@@ -8114,8 +8150,9 @@ function normalizePullRequest(on, run, index, path) {
     throw configError(`${at}: an azure pull_request trigger cannot carry a label predicate -- Azure DevOps attaches tags to work items, never to pull requests, so any/all/none could never match: ${path}`);
   }
   const predicate = validatePredicate(on, index, path, requirePositive);
-  if (!isNonEmptyString2(run.flow)) {
-    throw configError(`${at}: pull_request trigger run.flow must be a non-empty string: ${path}`);
+  const command = validateCommand(run, at, path, { onType: "pull_request" });
+  if (command === void 0 && !isNonEmptyString2(run.flow)) {
+    throw configError(`${at}: pull_request trigger run.flow must be a non-empty string (or use run.command): ${path}`);
   }
   const packages = validatePackagesFlag(run, at, path);
   const image = validateImageRef(run, at, path);
@@ -8135,7 +8172,7 @@ function normalizePullRequest(on, run, index, path) {
       all: predicate.all,
       none: predicate.none
     },
-    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions } }
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions } }
   };
 }
 function validateReviewState(on, actions, run, at, path) {
@@ -8516,14 +8553,18 @@ import { Queue } from "bullmq";
 function makeQueue(connection) {
   return new Queue(QUEUE, { connection });
 }
-async function enqueueLocalJob(queue, { folder, flow, task, provider, model, maxTurns, image, skillsDir, chainDepth, parentJobId, jobId, now = /* @__PURE__ */ new Date() }) {
+async function enqueueLocalJob(queue, { folder, flow, task, command, provider, model, maxTurns, image, skillsDir, chainDepth, parentJobId, jobId, now = /* @__PURE__ */ new Date() }) {
   const minute = now.toISOString().slice(0, 16);
-  const id = jobId ?? localJobId({ folder, flow, task, minute });
+  const id = jobId ?? localJobId({ folder, flow: command !== void 0 ? `cmd:${command}` : flow, task, minute });
   const data = {
     kind: "local",
     folder,
     flow,
     task,
+    // The registered pi command this job dispatches instead of a flow (issue #189). Conditional like
+    // `image`, so a flow job's data keeps exactly the keys it has today; the parse-level XOR means a
+    // job carrying it has flow/task undefined, which JSON serialization drops.
+    ...command !== void 0 && { command },
     provider,
     model,
     maxTurns,
@@ -8663,12 +8704,15 @@ function buildDockerRunArgs({
   name,
   memory = "4g",
   cpus = "2",
+  network = null,
   extraFlags = []
 }) {
   if (!image) throw new Error("docker run: image is required");
   if (!name) throw new Error("docker run: container name is required");
   if (!workspace) throw new Error("docker run: workspace mount is required");
-  const args = ["run", `--name=${name}`, ...ISOLATION_FLAGS, `--memory=${memory}`, `--cpus=${cpus}`, ...extraFlags];
+  const args = ["run", `--name=${name}`, ...ISOLATION_FLAGS, `--memory=${memory}`, `--cpus=${cpus}`];
+  if (network) args.push(`--network=${network}`);
+  args.push(...extraFlags);
   for (const [k, v] of Object.entries(env ?? {})) {
     if (v === void 0 || v === null) continue;
     args.push("-e", `${k}=${v}`);
@@ -8714,8 +8758,8 @@ var init_docker_run = __esm({
 });
 
 // ../worker/src/packages.mjs
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname as dirname2, join, resolve } from "node:path";
 function isNonEmptyString5(value) {
   return typeof value === "string" && value.trim() !== "";
 }
@@ -8739,6 +8783,55 @@ function readStageManifest({ globalPiDir, readFile = readFileSync, fileExists =
     return null;
   }
 }
+function readStagedSkills({ globalPiDir, readFile = readFileSync, fileExists = existsSync, readDir = readdirSync } = {}) {
+  const out = { skills: [], unenumerable: [] };
+  const manifest = readStageManifest({ globalPiDir, readFile, fileExists });
+  if (!manifest) return out;
+  for (const pkg of manifest.packages) {
+    const root = join(globalPiDir, PACKAGES_SUBDIR, pkg.dir);
+    let sources;
+    try {
+      const parsed = JSON.parse(readFile(join(root, "package.json"), "utf8"));
+      const pi = parsed !== null && typeof parsed === "object" && parsed.pi !== null && typeof parsed.pi === "object" ? parsed.pi : null;
+      if (pi) {
+        const entries = Array.isArray(pi.skills) ? pi.skills.filter((e) => typeof e === "string") : [];
+        if (entries.some((e) => e.startsWith("!") || e.startsWith("+") || e.startsWith("-") || e.includes("*") || e.includes("?"))) {
+          out.unenumerable.push(pkg.name);
+          continue;
+        }
+        sources = entries.filter((e) => !e.split(/[\\/]/).includes("..")).map((e) => resolve(root, e));
+      } else {
+        sources = [join(root, "skills")];
+      }
+    } catch {
+      continue;
+    }
+    for (const source of sources) {
+      for (const skillFile of walkSkillFiles(source, fileExists, readDir)) {
+        out.skills.push({ name: basename(dirname2(skillFile)), package: pkg.name, dir: pkg.dir });
+      }
+    }
+  }
+  return out;
+}
+function walkSkillFiles(source, fileExists, readDir, depth = 3) {
+  if (basename(source) === "SKILL.md") return fileExists(source) ? [source] : [];
+  const found = [];
+  const own = join(source, "SKILL.md");
+  if (fileExists(own)) found.push(own);
+  if (depth === 0) return found;
+  let children;
+  try {
+    children = readDir(source, { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const child of children) {
+    if (!child.isDirectory?.()) continue;
+    found.push(...walkSkillFiles(join(source, child.name), fileExists, readDir, depth - 1));
+  }
+  return found;
+}
 var PACKAGES_SUBDIR, STAGE_MANIFEST, CONTAINER_PACKAGES_ROOT, FROM_DECLARED, FROM_HOST, MAX_DIR_LENGTH;
 var init_packages = __esm({
   "../worker/src/packages.mjs"() {
@@ -8925,11 +9018,13 @@ function findLoopHints(text) {
   }
   return hints;
 }
-function buildGraphModel({ triggers, schedulers, folderSkills, injectedSkills, foldersTruncated, forgeRepos, cronStats, runJoin, chainEdges, caps, nowMs, triggerCosts } = {}) {
+function buildGraphModel({ triggers, schedulers, folderSkills, injectedSkills, overlaySkills, stagedSkills, foldersTruncated, forgeRepos, cronStats, runJoin, chainEdges, caps, nowMs, triggerCosts } = {}) {
   const triggerList2 = Array.isArray(triggers?.triggers) ? triggers.triggers : [];
   const schedulerList = Array.isArray(schedulers) ? schedulers : [];
   const folders = folderSkills && typeof folderSkills === "object" ? folderSkills : {};
   const injected = injectedSkills && typeof injectedSkills === "object" ? injectedSkills : {};
+  const overlay = overlaySkills && typeof overlaySkills === "object" && Array.isArray(overlaySkills.skills) ? overlaySkills : null;
+  const staged = stagedSkills && typeof stagedSkills === "object" && Array.isArray(stagedSkills.skills) ? stagedSkills : null;
   const statsById = cronStats?.byId && typeof cronStats.byId === "object" ? cronStats.byId : {};
   const statsByIndex = runJoin?.byIndex && typeof runJoin.byIndex === "object" ? runJoin.byIndex : {};
   const observed = Array.isArray(chainEdges?.edges) ? chainEdges.edges : [];
@@ -8955,13 +9050,18 @@ function buildGraphModel({ triggers, schedulers, folderSkills, injectedSkills, f
         // collectGraphInputs' cap flag rides its spread into this input (review finding: this was
         // hardcoded false, so the cap-reached banner could never fire on any surface).
         folders: foldersTruncated === true,
-        skills: Object.values(folders).some((f) => f?.truncated === true),
+        skills: Object.values(folders).some((f) => f?.truncated === true) || overlay?.truncated === true || staged?.truncated === true,
         edges: chainEdges?.truncated === true
       },
       droppedObservedEdges: 0,
       // Injected dirs whose readdir failed (review finding): the OQ-022 badge is the one fact the
       // injected enumeration exists for, and an unreadable dir must not make it silently vanish.
-      injectedUnreachable: Object.entries(injected).filter(([, r]) => typeof r?.unreachable === "string").map(([dir]) => dir).sort()
+      injectedUnreachable: Object.entries(injected).filter(([, r]) => typeof r?.unreachable === "string").map(([dir]) => dir).sort(),
+      // The two tier-honesty counters (issue #188): an overlay whose skills/ failed to read, and the
+      // staged packages whose pattern manifests defeat enumeration. Both feed the softened state
+      // below AND a banner, because a tier the ladder silently skipped would read as "checked".
+      overlayUnreachable: overlay?.unreachable === "unreadable",
+      stagedUnenumerable: (Array.isArray(staged?.unenumerable) ? staged.unenumerable : []).filter((p) => typeof p === "string").sort()
     }
   };
   const folderByPath = /* @__PURE__ */ new Map();
@@ -9034,6 +9134,28 @@ function buildGraphModel({ triggers, schedulers, folderSkills, injectedSkills, f
       }
     }
   }
+  const overlayNodeId = /* @__PURE__ */ new Map();
+  if (overlay) {
+    for (const skill of overlay.skills) {
+      if (typeof skill?.name !== "string" || skill.name === "" || overlayNodeId.has(skill.name)) continue;
+      const id = `overlay:${skill.name}`;
+      overlayNodeId.set(skill.name, id);
+      model.nodes.push({ id, kind: "overlay", name: skill.name });
+    }
+  }
+  const stagedNodeId = /* @__PURE__ */ new Map();
+  if (staged) {
+    const seenStagedIds = /* @__PURE__ */ new Set();
+    for (const skill of staged.skills) {
+      if (typeof skill?.name !== "string" || skill.name === "" || typeof skill?.dir !== "string" || skill.dir === "") continue;
+      const id = `staged:${skill.dir}:${skill.name}`;
+      if (!seenStagedIds.has(id)) {
+        seenStagedIds.add(id);
+        model.nodes.push({ id, kind: "staged", name: skill.name, package: typeof skill.package === "string" && skill.package !== "" ? skill.package : skill.dir });
+      }
+      if (!stagedNodeId.has(skill.name)) stagedNodeId.set(skill.name, id);
+    }
+  }
   const missingNode = (group, name) => {
     const key = `${group.key} ${name}`;
     let node = skillNode.get(key);
@@ -9044,6 +9166,14 @@ function buildGraphModel({ triggers, schedulers, folderSkills, injectedSkills, f
     group.skillIds.push(node.id);
     return node;
   };
+  const notAtHeadNode = (group, name, tiers) => {
+    const node = missingNode(group, name);
+    if (node.kind === "skill-missing") node.kind = "skill-not-at-head";
+    if (node.kind === "skill-not-at-head") {
+      node.tiersUnknown = [.../* @__PURE__ */ new Set([...Array.isArray(node.tiersUnknown) ? node.tiersUnknown : [], ...tiers])].sort();
+    }
+    return node;
+  };
   for (const t of triggerList2) {
     if (!t || typeof t !== "object" || !Number.isInteger(t.index)) continue;
     const id = `trigger:${t.index}`;
@@ -9080,6 +9210,11 @@ function buildGraphModel({ triggers, schedulers, folderSkills, injectedSkills, f
       pattern: isCron ? t.pattern ?? null : null,
       label: triggerMatchLabel(t),
       flow: t.flow ?? null,
+      // A command trigger's dispatched extension command (issue #189), flow's mutually-exclusive
+      // sibling. Carried on the node so the display half (issue #188) has the fact to render; nothing
+      // in THIS module consumes it -- a command names no SKILL.md, so the config-edge machinery below
+      // (guarded on `typeof t.flow === "string"`) correctly draws nothing for it.
+      command: t.command ?? null,
       replicas: t.replicas ?? null,
       folderKey: group?.key ?? null,
       runs: Number.isInteger(stats?.runs) ? stats.runs : 0,
@@ -9110,9 +9245,41 @@ function buildGraphModel({ triggers, schedulers, folderSkills, injectedSkills, f
           existing.isFlow = true;
           model.edges.push({ from: id, to: existing.id, kind: "config" });
         } else {
-          const target = missingNode(group, t.flow);
-          model.edges.push({ from: id, to: target.id, kind: "config" });
-          model.flags.push({ nodeId: id, flag: "no-skill", detail: `.pi/skills/${t.flow}/SKILL.md absent at HEAD` });
+          const probes = [];
+          if (typeof t.skillsDir === "string" && t.skillsDir !== "") {
+            const r = injected[t.skillsDir];
+            if (!r || typeof r.unreachable === "string") probes.push({ tier: TIER_INJECTED, state: "unknown" });
+            else if ((Array.isArray(r.skills) ? r.skills : []).some((s) => s?.name === t.flow)) probes.push({ tier: TIER_INJECTED, state: "hit", nodeId: `injected:${t.skillsDir}:${t.flow}` });
+            else probes.push({ tier: TIER_INJECTED, state: r.truncated === true ? "unknown" : "miss" });
+          }
+          if (overlay === null || typeof overlay.unreachable === "string") probes.push({ tier: TIER_OVERLAY, state: "unknown" });
+          else if (overlayNodeId.has(t.flow)) probes.push({ tier: TIER_OVERLAY, state: "hit", nodeId: overlayNodeId.get(t.flow) });
+          else probes.push({ tier: TIER_OVERLAY, state: overlay.truncated === true ? "unknown" : "miss" });
+          if (t.packages === false) {
+            probes.push({ tier: `${TIER_STAGED} (withheld: run.packages false)`, state: "miss" });
+          } else if (staged === null) probes.push({ tier: TIER_STAGED, state: "unknown" });
+          else if (stagedNodeId.has(t.flow)) probes.push({ tier: TIER_STAGED, state: "hit", nodeId: stagedNodeId.get(t.flow) });
+          else probes.push({ tier: TIER_STAGED, state: staged.unenumerable.length > 0 || staged.truncated === true ? "unknown" : "miss" });
+          let target = null;
+          let blocked = false;
+          for (const probe of probes) {
+            if (probe.state === "hit" && !blocked) {
+              target = probe.nodeId;
+              break;
+            }
+            if (probe.state === "unknown") blocked = true;
+          }
+          if (target !== null) {
+            model.edges.push({ from: id, to: target, kind: "config" });
+          } else if (probes.some((p) => p.state === "unknown")) {
+            const soft = notAtHeadNode(group, t.flow, probes.filter((p) => p.state === "unknown").map((p) => p.tier));
+            model.edges.push({ from: id, to: soft.id, kind: "config" });
+          } else {
+            const target2 = missingNode(group, t.flow);
+            model.edges.push({ from: id, to: target2.id, kind: "config" });
+            const alsoChecked = probes.length > 0 ? `; also checked: ${probes.map((p) => p.tier).join(", ")}` : "";
+            model.flags.push({ nodeId: id, flag: "no-skill", detail: `.pi/skills/${t.flow}/SKILL.md absent at HEAD${alsoChecked}` });
+          }
         }
       } else if (group) {
         const target = missingNode(group, t.flow);
@@ -9215,7 +9382,7 @@ function clipName(name) {
   const s = String(name);
   return s.length > 64 ? `${s.slice(0, 64)}\u2026` : s;
 }
-var FRONTMATTER_BLOCK_RE, META_VALUE_MAX_CHARS, CHAIN_VOCAB_RE, CHAIN_VOCAB_RADIUS, LOOP_HINT_RE, LOOP_HINT_MAX, GRAPH_EDGE_KINDS, GRAPH_FLAGS;
+var FRONTMATTER_BLOCK_RE, META_VALUE_MAX_CHARS, CHAIN_VOCAB_RE, CHAIN_VOCAB_RADIUS, LOOP_HINT_RE, LOOP_HINT_MAX, GRAPH_EDGE_KINDS, GRAPH_FLAGS, GRAPH_NODE_KINDS, TIER_INJECTED, TIER_OVERLAY, TIER_STAGED;
 var init_graph_model = __esm({
   "src/graph-model.mjs"() {
     init_flow_gate();
@@ -9228,7 +9395,7 @@ var init_graph_model = __esm({
     GRAPH_EDGE_KINDS = Object.freeze(["config", "observed", "potential", "cron-rearm"]);
     GRAPH_FLAGS = Object.freeze([
       "no-skill",
-      // config edge target absent at HEAD in an ENUMERATED folder (readFlowGate's precise token)
+      // config edge target absent in EVERY checkable applicable tier (readFlowGate's precise token, now with the full ladder behind it)
       "charset-invalid",
       // run.flow fails SKILL_NAME_RE: can never materialise, a distinct defect from no-skill
       "orphan",
@@ -9242,6 +9409,26 @@ var init_graph_model = __esm({
       "pr-spend-loop-risk"
       // pull_request on opened/synchronize: the OQ-020 cross-actor spend-loop signature
     ]);
+    GRAPH_NODE_KINDS = Object.freeze([
+      "trigger",
+      "skill",
+      // committed at HEAD in an enumerated folder
+      "skill-missing",
+      // absent in every checkable applicable tier: the one red, dangling state
+      "skill-unverified",
+      // the folder itself was never readable (forge/remote): a read that never happened
+      "skill-not-at-head",
+      // absent at HEAD, but some lower tier was not checkable from this session
+      "injected",
+      // run.skillsDir working-tree skill: trigger-reachable, never AI-reachable
+      "overlay",
+      // deployment overlay skills/: trigger-reachable, never AI-reachable
+      "staged"
+      // a staged pi package's skill: trigger-reachable, never AI-reachable
+    ]);
+    TIER_INJECTED = "injected run.skillsDir";
+    TIER_OVERLAY = "overlay skills/";
+    TIER_STAGED = "staged packages";
   }
 });
 
@@ -9889,6 +10076,11 @@ async function enqueueDispatchRun({
   if (typeof flow !== "string" || flow.trim() === "") {
     return { refused: "no flow \u2014 a flow is required to trigger a run" };
   }
+  if (flow.trim().startsWith("/")) {
+    return {
+      refused: `flow '${flow}' names a command, not a flow \u2014 commands are not AI-triggerable; a registered extension command runs only from a reviewed triggers.json entry (run.command)`
+    };
+  }
   const { valkeyUrl, dispatchRunRoots, dispatchRunPerHour } = resolvePaths(env);
   if (aiInvoked && !folderUnderRoots(folder, dispatchRunRoots)) {
     return { refused: "folder not under PI_DISPATCH_RUN_ROOTS" };
@@ -10098,8 +10290,8 @@ async function readBudget({ url, redisFn = makeRedisClient, timeoutMs = 2500 } =
 }
 function withTimeout(promise, ms, fallback) {
   let timer;
-  const timeout = new Promise((resolve) => {
-    timer = setTimeout(() => resolve(fallback), ms);
+  const timeout = new Promise((resolve2) => {
+    timer = setTimeout(() => resolve2(fallback), ms);
     if (typeof timer?.unref === "function") timer.unref();
   });
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
@@ -10193,6 +10385,7 @@ function normalizeTriggerForDisplay(entry) {
   if (on === null || typeof on !== "object") return null;
   const run = entry.run !== null && typeof entry.run === "object" ? entry.run : {};
   const flow = typeof run.flow === "string" ? run.flow : null;
+  const command = typeof run.command === "string" ? run.command : null;
   const packages = run.packages !== false;
   const image = typeof run.image === "string" && run.image.trim() !== "" ? run.image : null;
   const skillsDir = typeof run.skillsDir === "string" && run.skillsDir.trim() !== "" ? run.skillsDir : null;
@@ -10208,6 +10401,7 @@ function normalizeTriggerForDisplay(entry) {
         pattern: typeof on.pattern === "string" ? on.pattern : null,
         folder: typeof run.folder === "string" ? run.folder : null,
         flow,
+        command,
         // Optional per-cron model override (passthrough into job.data); null when the entry resolves the
         // deployment default. Surfaced so the drill-in shows which schedules pin their own model.
         model: typeof run.model === "string" ? run.model : null,
@@ -10218,9 +10412,9 @@ function normalizeTriggerForDisplay(entry) {
         resume
       };
     case "label":
-      return { type: "label", any: normalizeSelector(on.any), all: normalizeSelector(on.all), none: normalizeSelector(on.none), flow, packages, image, skillsDir, instructions, resume, replicas, forge };
+      return { type: "label", any: normalizeSelector(on.any), all: normalizeSelector(on.all), none: normalizeSelector(on.none), flow, command, packages, image, skillsDir, instructions, resume, replicas, forge };
     case "comment":
-      return { type: "comment", phrase: typeof on.phrase === "string" ? on.phrase : null, flow, packages, image, skillsDir, instructions, resume, replicas, forge };
+      return { type: "comment", phrase: typeof on.phrase === "string" ? on.phrase : null, flow, command, packages, image, skillsDir, instructions, resume, replicas, forge };
     case "pull_request":
       return {
         type: "pull_request",
@@ -10229,6 +10423,7 @@ function normalizeTriggerForDisplay(entry) {
         all: normalizeSelector(on.all),
         none: normalizeSelector(on.none),
         flow,
+        command,
         packages,
         image,
         skillsDir,
@@ -10476,8 +10671,69 @@ function readInjectedSkills({ skillsDir, fs = nodeFs2 } = {}) {
   }
   return { skills, truncated, unreachable: null };
 }
-function collectGraphInputs({ triggers, readFolder = readFolderSkills, readInjected = readInjectedSkills } = {}) {
-  const out = { folderSkills: {}, injectedSkills: {}, foldersTruncated: false };
+function readOverlaySkills({ globalPiDir, fs = nodeFs2 } = {}) {
+  if (typeof globalPiDir !== "string" || globalPiDir === "") return { skills: [], truncated: false, unreachable: null };
+  const dir = join2(globalPiDir, "skills");
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (err) {
+    if (err?.code === "ENOENT") return { skills: [], truncated: false, unreachable: null };
+    return { skills: [], truncated: false, unreachable: "unreadable" };
+  }
+  const valid = names.filter((n) => SKILL_NAME_RE.test(n)).sort();
+  const truncated = valid.length > GRAPH_LIMITS.maxSkillsPerFolder;
+  const skills = [];
+  for (const name of valid.slice(0, GRAPH_LIMITS.maxSkillsPerFolder)) {
+    let present = false;
+    try {
+      present = fs.existsSync(join2(dir, name, "SKILL.md"));
+    } catch {
+      present = false;
+    }
+    if (present) skills.push({ name });
+  }
+  return { skills, truncated, unreachable: null };
+}
+function readStagedSkillsList({ globalPiDir, fs = nodeFs2, readStaged = readStagedSkills } = {}) {
+  const empty = { skills: [], unenumerable: [], truncated: false };
+  if (typeof globalPiDir !== "string" || globalPiDir === "") return empty;
+  let result;
+  try {
+    result = readStaged({
+      globalPiDir,
+      readFile: (path) => fs.readFileSync(path, "utf8"),
+      fileExists: (path) => fs.existsSync(path),
+      readDir: (path, opts) => fs.readdirSync(path, opts)
+    });
+  } catch {
+    return empty;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const skills = [];
+  for (const s of Array.isArray(result?.skills) ? result.skills : []) {
+    if (typeof s?.name !== "string" || !SKILL_NAME_RE.test(s.name)) continue;
+    if (typeof s.dir !== "string" || s.dir === "") continue;
+    const key = `${s.dir} ${s.name}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    skills.push({ name: s.name, package: typeof s.package === "string" && s.package !== "" ? s.package : s.dir, dir: s.dir });
+  }
+  return {
+    skills: skills.slice(0, GRAPH_LIMITS.maxStagedSkills),
+    unenumerable: (Array.isArray(result?.unenumerable) ? result.unenumerable : []).filter((p) => typeof p === "string").sort(),
+    truncated: skills.length > GRAPH_LIMITS.maxStagedSkills
+  };
+}
+function collectGraphInputs({
+  triggers,
+  globalPiDir = null,
+  readFolder = readFolderSkills,
+  readInjected = readInjectedSkills,
+  readOverlay: readOverlay2 = readOverlaySkills,
+  readStaged = readStagedSkillsList
+} = {}) {
+  const out = { folderSkills: {}, injectedSkills: {}, overlaySkills: null, stagedSkills: null, foldersTruncated: false };
   if (!Array.isArray(triggers)) return out;
   const folders = [];
   const injectedDirs = [];
@@ -10492,6 +10748,10 @@ function collectGraphInputs({ triggers, readFolder = readFolderSkills, readInjec
   for (const dir of injectedDirs.slice(0, GRAPH_LIMITS.maxFoldersScanned)) {
     out.injectedSkills[dir] = readInjected({ skillsDir: dir });
   }
+  if (typeof globalPiDir === "string" && globalPiDir !== "") {
+    out.overlaySkills = readOverlay2({ globalPiDir });
+    out.stagedSkills = readStaged({ globalPiDir });
+  }
   return out;
 }
 function forgeRepoTargets({ records } = {}) {
@@ -10582,8 +10842,10 @@ var init_read_model = __esm({
       // distinct observed chain edges kept; beyond this the graph says "truncated"
       windowDays: 30,
       // run-record window the graph folds; matches the default PI_LOG_RETENTION_DAYS
-      maxReposListed: 5
+      maxReposListed: 5,
       // repos named per forge group, from record targets; a scope label, not an inventory
+      maxStagedSkills: 64
+      // staged-package skills kept for display; one stage read per graph build
     });
     GRAPH_LS_TREE_MAX_BYTES = 1 << 20;
   }
@@ -10637,7 +10899,11 @@ function normalizeModel(model) {
     // dropped (issue #175): three surfaces of one model must not disagree about what was refused
     // or unreadable. Sorted and clipped like every other array on this page.
     chainRefusals: (m.meta?.chainRefusals && typeof m.meta.chainRefusals === "object" ? Object.entries(m.meta.chainRefusals) : []).flatMap(([scope, count]) => typeof scope === "string" && intOr(count, 0) > 0 ? [{ scope: clip(scope, 80), count: intOr(count, 0) }] : []).sort((a, b) => cmpStr(a.scope, b.scope)),
-    injectedUnreachable: (Array.isArray(m.meta?.injectedUnreachable) ? m.meta.injectedUnreachable : []).filter((d) => typeof d === "string").map((d) => clip(d, 120)).sort().slice(0, 8)
+    injectedUnreachable: (Array.isArray(m.meta?.injectedUnreachable) ? m.meta.injectedUnreachable : []).filter((d) => typeof d === "string").map((d) => clip(d, 120)).sort().slice(0, 8),
+    // The two tier-honesty counters (issue #188), the injectedUnreachable rule applied to the
+    // deployment-wide tiers: a tier the ladder silently skipped would read as "checked".
+    overlayUnreachable: m.meta?.overlayUnreachable === true,
+    stagedUnenumerable: (Array.isArray(m.meta?.stagedUnenumerable) ? m.meta.stagedUnenumerable : []).filter((d) => typeof d === "string").map((d) => clip(d, 80)).sort().slice(0, 8)
   };
   const folders = [];
   for (const f of Array.isArray(m.folders) ? m.folders : []) {
@@ -10671,6 +10937,13 @@ function normalizeModel(model) {
       onType: typeof n.onType === "string" ? n.onType : null,
       pattern: typeof n.pattern === "string" ? n.pattern : null,
       flow: typeof n.flow === "string" ? n.flow : null,
+      // A command trigger's slash command (issue #189's node fact, #188's rendering): the tip is the
+      // detail surface, so the full command rides, clipped like every other string on this page.
+      command: typeof n.command === "string" ? clip(n.command, 80) : null,
+      // The staged tier node's owning package, and the softened state's evidence: which tiers this
+      // session could not check. Both clipped/sorted/capped so a hostile model cannot inflate a tip.
+      package: typeof n.package === "string" ? clip(n.package, 80) : null,
+      tiersUnknown: Array.isArray(n.tiersUnknown) ? [...new Set(n.tiersUnknown.filter((t) => typeof t === "string").map((t) => clip(t, 40)))].sort().slice(0, 4) : [],
       replicas: intOr(n.replicas, null),
       folderKey: typeof n.folderKey === "string" ? n.folderKey : null,
       runs: intOr(n.runs, 0),
@@ -10751,6 +11024,8 @@ function layoutNormalized(norm) {
     placedByOrig.set(n.id, p);
     let g = n.folderKey === null ? null : groupIndexByKey.get(n.folderKey) ?? null;
     if (!g && n.kind === "injected") g = groupIndexByKey.get("~injected") ?? addGroup("~injected", "injected skills (run.skillsDir)", "local", null, null);
+    if (!g && n.kind === "overlay") g = groupIndexByKey.get("~overlay") ?? addGroup("~overlay", "overlay skills (global pi dir)", "local", null, null);
+    if (!g && n.kind === "staged") g = groupIndexByKey.get("~staged") ?? addGroup("~staged", "staged package skills", "local", null, null);
     if (!g) g = groupIndexByKey.get(n.folderKey ?? "~ungrouped") ?? addGroup(n.folderKey ?? "~ungrouped", "ungrouped", "local", null, null);
     g.members.push(p);
     p.groupId = g.id;
@@ -11080,13 +11355,23 @@ function buildTip(n, flags, groupLabel, nowMs) {
   if (n.kind === "trigger") {
     lines.push(`trigger \xB7 ${n.onType ?? "?"} \xB7 ${n.label ?? ""}`.trim());
     if (n.flow !== null) lines.push(`flow: ${n.flow}${n.replicas !== null ? ` \xD7${n.replicas}` : ""}`);
+    else if (n.command !== null) lines.push(`command: /${n.command}${n.replicas !== null ? ` \xD7${n.replicas}` : ""}`);
   } else if (n.kind === "injected") {
     lines.push(`injected skill \xB7 ${n.name ?? "?"}`);
     lines.push("trigger-reachable via run.skillsDir, never AI-reachable");
+  } else if (n.kind === "overlay") {
+    lines.push(`overlay skill \xB7 ${n.name ?? "?"}`);
+    lines.push("deployment overlay skills/, trigger-reachable, never AI-reachable");
+  } else if (n.kind === "staged") {
+    lines.push(`staged skill \xB7 ${n.name ?? "?"}${n.package !== null ? ` \xB7 package ${n.package}` : ""}`);
+    lines.push("staged pi package, trigger-reachable, never AI-reachable");
   } else if (n.kind === "skill-missing") {
     lines.push(`skill \xB7 ${n.name ?? "?"} \xB7 missing at HEAD`);
   } else if (n.kind === "skill-unverified") {
     lines.push(`skill \xB7 ${n.name ?? "?"} \xB7 unverified (repo not readable from this host)`);
+  } else if (n.kind === "skill-not-at-head") {
+    lines.push(`skill \xB7 ${n.name ?? "?"} \xB7 not committed at HEAD`);
+    if (n.tiersUnknown.length > 0) lines.push(`not checkable from this session: ${n.tiersUnknown.join(", ")}`);
   } else {
     lines.push(`skill \xB7 ${n.name ?? "?"}${n.isSub ? " \xB7 sub-skill (never a flow)" : ""}`);
   }
@@ -11133,6 +11418,7 @@ function nodeState(n, flagNames) {
     return { stroke: DANGER, dash: "10,4", faded: false };
   }
   if (n.kind === "skill-unverified") return { stroke: PAGE_DIM, dash: "10,4", faded: false };
+  if (n.kind === "skill-not-at-head") return { stroke: PAGE_AMBER, dash: "10,4", faded: false };
   if (flagNames.has("orphan")) return { stroke: CHIP_STROKE, dash: "8,3", faded: true };
   return { stroke: CHIP_STROKE, dash: null, faded: false };
 }
@@ -11248,7 +11534,8 @@ function legendHtml(norm) {
   row(legendSwatch(`<circle cx="8" cy="6" r="5" fill="${BADGE_ORANGE}"/>`), "unread / injected ai-trigger / PR spend-loop risk");
   row(legendSwatch(`<circle cx="8" cy="6" r="4" fill="none" stroke="${BADGE_GREEN}" stroke-width="2"/>`), "chainable: ai-trigger allow");
   row(legendSwatch(`<rect x="1" y="1" width="14" height="10" rx="2" fill="none" stroke="${CHIP_STROKE}" stroke-dasharray="8,3"/>`), "orphan: no trigger, no ai-trigger, no mention");
-  row(legendSwatch(`<rect x="1" y="1" width="14" height="10" rx="2" fill="none" stroke="${DANGER}" stroke-dasharray="10,4"/>`), "dangling: flow absent or name invalid");
+  row(legendSwatch(`<rect x="1" y="1" width="14" height="10" rx="2" fill="none" stroke="${DANGER}" stroke-dasharray="10,4"/>`), "dangling: absent in every checkable tier or name invalid");
+  row(legendSwatch(`<rect x="1" y="1" width="14" height="10" rx="2" fill="none" stroke="${PAGE_AMBER}" stroke-dasharray="10,4"/>`), "not at HEAD: some skill tiers not checkable from this session");
   row(legendSwatch(`<rect x="1" y="1" width="14" height="10" rx="2" fill="none" stroke="${PAGE_DIM}" stroke-dasharray="10,4"/>`), "unverified: repo not readable from this host");
   rows.push(`<div class="caps">${escapeHtml(capsLineText(norm.caps))}</div>`);
   const honesty = [];
@@ -11260,6 +11547,8 @@ function legendHtml(norm) {
   const refused = norm.meta.chainRefusals.reduce((a, r) => a + r.count, 0);
   if (refused > 0) honesty.push(`${refused} chain requests refused (caps or gate)`);
   if (norm.meta.injectedUnreachable.length > 0) honesty.push(`injected skills dir unreadable: ${norm.meta.injectedUnreachable.join(", ")}`);
+  if (norm.meta.overlayUnreachable) honesty.push("overlay skills dir unreadable (global pi dir)");
+  if (norm.meta.stagedUnenumerable.length > 0) honesty.push(`staged packages not enumerable (manifest patterns): ${norm.meta.stagedUnenumerable.join(", ")}`);
   for (const line of honesty) rows.push(`<div class="honesty">${escapeHtml(line)}</div>`);
   return `<div id="legend">${rows.join("")}</div>`;
 }
@@ -11406,7 +11695,10 @@ var init_graph_html = __esm({
       skill: "\u0192",
       "skill-missing": "!",
       "skill-unverified": "?",
-      injected: "+"
+      "skill-not-at-head": "\u22EF",
+      injected: "+",
+      overlay: "\u25CE",
+      staged: "\u25A3"
     });
     ORANGE_FLAGS = /* @__PURE__ */ new Set(["unread", "injected-ai-trigger", "pr-spend-loop-risk"]);
     DANGLING_FLAGS = /* @__PURE__ */ new Set(["no-skill", "charset-invalid"]);
@@ -38371,7 +38663,7 @@ var init_all = __esm({
 
 // ../worker/src/pricing.mjs
 import { readFileSync as readFileSync2 } from "node:fs";
-import { dirname as dirname2, join as join4 } from "node:path";
+import { dirname as dirname3, join as join4 } from "node:path";
 import { fileURLToPath } from "node:url";
 function listPricedModels() {
   const out = [];
@@ -38400,7 +38692,7 @@ function readTextFromDisk(path) {
 }
 function readPiAiVersion(readText) {
   try {
-    let dir = dirname2(fileURLToPath(import.meta.resolve("@earendil-works/pi-ai")));
+    let dir = dirname3(fileURLToPath(import.meta.resolve("@earendil-works/pi-ai")));
     for (let hops = 0; hops < 8; hops++) {
       try {
         const parsed = JSON.parse(readText(join4(dir, "package.json")));
@@ -38410,7 +38702,7 @@ function readPiAiVersion(readText) {
         }
       } catch {
       }
-      const parent = dirname2(dir);
+      const parent = dirname3(dir);
       if (parent === dir) break;
       dir = parent;
     }
@@ -38455,7 +38747,7 @@ var init_pricing = __esm({
 });
 
 // ../worker/src/sandbox-store.mjs
-import { lstatSync, mkdirSync, readFileSync as readFileSync3, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+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";
 function readManifest({ sandboxDir, jobId, fs = defaultFs }) {
   if (!sandboxDir || jobId === void 0 || jobId === null) return null;
@@ -38472,7 +38764,7 @@ var init_sandbox_store = __esm({
   "../worker/src/sandbox-store.mjs"() {
     init_run_history();
     SANDBOX_MANIFEST = "manifest.json";
-    defaultFs = { lstatSync, mkdirSync, readFileSync: readFileSync3, readdirSync, renameSync, rmSync, writeFileSync };
+    defaultFs = { lstatSync, mkdirSync, readFileSync: readFileSync3, readdirSync: readdirSync2, renameSync, rmSync, writeFileSync };
   }
 });
 
@@ -38483,7 +38775,7 @@ import { promisify as promisify4 } from "node:util";
 function sandboxContainerName(jobId) {
   return `${SANDBOX_NAME_PREFIX}${sanitizeJobId(jobId)}`;
 }
-function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], term, idleSeconds = 0 }) {
+function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], term, idleSeconds = 0, network = null, egressEnv: proxyEnv = {} }) {
   return buildDockerRunArgs({
     image,
     name,
@@ -38492,9 +38784,20 @@ function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], ter
     // The ONLY two variables, and neither is a credential. TERM so the shell renders; TMOUT so a
     // forgotten session closes itself. `buildDockerRunArgs` skips undefined, so an unset TERM or a
     // disabled idle timeout emits nothing rather than an empty string.
+    // A sandbox joins the SAME kind of network a job did, by the same builder, so the boundary cannot
+    // land on job containers and miss this one. Leaving sandboxes on the default bridge was the tempting
+    // alternative and it is the wrong one: it reads as a convenience (install a missing dependency while
+    // debugging) and it is a WIDER reach than the run the sandbox exists to reproduce. A shell that can
+    // go where the run could not is not reproducing the run. Nothing an operator wants is lost, because
+    // the forge and the registry are on the allowlist a job needed anyway.
+    network,
     env: {
       TERM: term || void 0,
-      TMOUT: idleSeconds > 0 ? String(idleSeconds) : void 0
+      TMOUT: idleSeconds > 0 ? String(idleSeconds) : void 0,
+      // Still NO CREDENTIALS, and that clause is untouched: a proxy URL is not a credential, and
+      // buildContainerEnv is still not reused here. The env is two variables about the terminal and,
+      // when a policy is armed, three about the network.
+      ...proxyEnv
     },
     // Ahead of the env and the mounts, and well ahead of the image, which buildDockerRunArgs keeps as
     // the final positional. `--entrypoint` also clears the image's CMD; this repo's Dockerfile sets
@@ -38518,10 +38821,10 @@ function resolveSandbox({ jobId, sandboxDir, retentionHours, publish = [], fs, f
   return { manifest, name: sandboxContainerName(jobId), publish };
 }
 function launchSandbox({ args, spawnFn = spawn }) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const child = spawnFn("docker", args, { stdio: "inherit" });
-    child.on("error", (err) => resolve({ code: null, error: err }));
-    child.on("close", (code) => resolve({ code }));
+    child.on("error", (err) => resolve2({ code: null, error: err }));
+    child.on("close", (code) => resolve2({ code }));
   });
 }
 var exec3, SANDBOX_NAME_PREFIX;
@@ -38606,7 +38909,7 @@ function renderTriggers({ schedulers, triggers } = {}) {
   return out.join("\n");
 }
 function triggerLine(t) {
-  const flow = t?.flow ?? "-";
+  const flow = t?.flow ?? commandSlashLabel(t) ?? "-";
   const forge = t?.forge && t.forge !== "github" ? `  [${t.forge}]` : "";
   const pkgs = t?.packages === true ? "  [packages]" : "";
   const img = t?.image ? `  [image ${t.image}]` : "";
@@ -38630,6 +38933,9 @@ function triggerLine(t) {
       return "(unknown trigger)";
   }
 }
+function commandSlashLabel(t) {
+  return typeof t?.command === "string" && t.command.trim() !== "" ? `/${t.command.trim().split(/\s+/)[0]}` : null;
+}
 function ruleClauses(rule) {
   const clauses = [];
   for (const key of ["any", "all", "none"]) {
@@ -39574,7 +39880,7 @@ function matchColored(t, styler) {
 }
 function targetColored(t, styler) {
   const arrow = styler.fg("dim", "\u2192");
-  const flow = styler.bold(styler.fg("text", t?.flow ?? "-"));
+  const flow = styler.bold(styler.fg("text", t?.flow ?? commandSlashLabel(t) ?? "-"));
   if (t?.type === "cron") {
     const base = t.folder ? String(t.folder).split(/[/\\]/).filter(Boolean).pop() ?? "" : "";
     const folderPart = base ? styler.fg("muted", base) + styler.fg("dim", "/") : "";
@@ -39678,7 +39984,7 @@ function renderTriggerDetail(t, inner, styler, sched = null, staged = null) {
   const kv = (k, v, color = "text") => fitLine(styler.cell(k, 12, { color: "muted" }) + " " + styler.fg(color, v), inner, styler);
   const blank = () => out.push(styler.cell("", inner));
   const section = (label) => out.push(styler.divider(label, null, inner));
-  let header = styler.fg(KIND_COLOR[t.type] ?? "muted", t.type ?? "?") + "  " + styler.bold(styler.fg("text", `\u2192 ${t.flow ?? "-"}`));
+  let header = styler.fg(KIND_COLOR[t.type] ?? "muted", t.type ?? "?") + "  " + styler.bold(styler.fg("text", `\u2192 ${t.flow ?? commandSlashLabel(t) ?? "-"}`));
   if (t.type === "cron" && sched) {
     const healthy = !sched.overdueMs;
     header += "   " + (healthy ? styler.fg("success", "\u2714 healthy") : styler.fg("warning", `\u26A0 overdue ${formatDuration(sched.overdueMs)}`));
@@ -39714,6 +40020,7 @@ function renderTriggerDetail(t, inner, styler, sched = null, staged = null) {
     out.push(kv("target", forgeTargetLabel(t?.forge), "accent"));
     out.push(kv("model", "deployment default", "dim"));
   }
+  if (typeof t.command === "string" && t.command.trim() !== "") out.push(kv("command", `/${t.command.trim()}`, "accent"));
   out.push(kv("image", t.image ?? "deployment default", t.image ? "accent" : "dim"));
   out.push(kv("resume", t.resume === true ? "continues the previous session" : "cold start", t.resume === true ? "warning" : "dim"));
   out.push(kv("replicas", t.replicas > 1 ? `${t.replicas} sandboxes race this flow` : "one run per delivery", t.replicas > 1 ? "warning" : "dim"));
@@ -39942,7 +40249,11 @@ function renderRunDetail(record, inner, styler, allRuns = [], sandbox = null) {
   out.push(kv("chain", chainBits.join(" \xB7 ")));
   if (r.replica > 0) {
     const sibs = (Array.isArray(allRuns) ? allRuns : []).filter(
-      (x) => x?.replica > 0 && x.replica !== r.replica && x.target === r.target && x.flow === r.flow
+      // `kind` is load-bearing since #187, not decoration: `target` is repo + separator + number, and
+      // targetFor renders github and forgejo with the SAME `#`, so a github `o/r#5` and a forgejo `o/r#5`
+      // are one string. While only github could replicate, no two replica runs could collide; now they can,
+      // and naming a stranger's job as your sibling is worse than naming none.
+      (x) => x?.replica > 0 && x.replica !== r.replica && x.kind === r.kind && x.target === r.target && x.flow === r.flow
     );
     const repBits = [`r${r.replica}/${r.replicas ?? "?"}`];
     repBits.push(sibs.length > 0 ? `sibling ${sibs.map((s) => `r${s.replica} ${s.jobId}`).join(", ")}` : "no sibling in this window");
@@ -40096,16 +40407,16 @@ async function runAttached(ctx, { title, argv0, args, cwd, env, shell, spawnFn =
 ${title}
 
 `);
-        outcome = await new Promise((resolve) => {
+        outcome = await new Promise((resolve2) => {
           let child;
           try {
             child = spawnFn(argv0, args, { stdio: "inherit", cwd, env, ...shell ? { shell: true } : {} });
           } catch (err) {
-            resolve({ code: null, error: err });
+            resolve2({ code: null, error: err });
             return;
           }
-          child.on("error", (err) => resolve({ code: null, error: err }));
-          child.on("close", (code) => resolve({ code }));
+          child.on("error", (err) => resolve2({ code: null, error: err }));
+          child.on("close", (code) => resolve2({ code }));
         });
       } catch (err) {
         outcome = { code: null, error: err };
@@ -40556,8 +40867,8 @@ var init_setup_wizard = __esm({
     init_deployment_pointer();
     init_read_model();
     init_index();
-    RUNTIME_VERSION = "0.3.0";
-    RECEIVER_VERSION = "0.2.1";
+    RUNTIME_VERSION = "1.1.0";
+    RECEIVER_VERSION = "1.1.0";
     RUNTIME_PKG = "@edgehero/pi-dispatch";
     RECEIVER_PKG = "@edgehero/pi-dispatch-receiver";
     NUDGE_MARKER_BASENAME = "pi-dispatch-setup.nudged";
@@ -40699,7 +41010,7 @@ function registerTools(pi) {
   pi.registerTool({
     name: "dispatch_run",
     label: "pi-dispatch run",
-    description: "Enqueues a PAID pi-dispatch agent run against a local folder, editing it in place with no undo. Only folders under the operator's PI_DISPATCH_RUN_ROOTS, and only flows whose .pi/skills/<flow>/SKILL.md (at HEAD) sets ai-trigger: allow, can be started. Refuses a dirty git working tree \u2014 no force option. Rate-limited per hour.",
+    description: "Enqueues a PAID pi-dispatch agent run against a local folder, editing it in place with no undo. Only folders under the operator's PI_DISPATCH_RUN_ROOTS, and only flows whose .pi/skills/<flow>/SKILL.md (at HEAD) sets ai-trigger: allow, can be started. Refuses a dirty git working tree \u2014 no force option. Rate-limited per hour. Flows only: a registered extension command (a run.command trigger) is never AI-triggerable and a /name flow is refused.",
     executionMode: "sequential",
     parameters: typebox_exports.Object({ folder: typebox_exports.String(), flow: typebox_exports.String(), task: typebox_exports.String() }),
     async execute(_toolCallId, params) {
@@ -40762,12 +41073,16 @@ function registerTools(pi) {
   pi.registerTool({
     name: "dispatch_trigger_add",
     label: "pi-dispatch add trigger",
-    description: "Adds a trigger to triggers.json and applies it live. The operator MUST approve a confirm dialog showing the entry; with no interactive operator it is refused. `flow` is the .pi/skills/<name> skill the job runs (its SKILL.md is the agent's instructions). `kind` = cron|label|comment|pull_request. cron (local) needs id, pattern, `folder` (absolute host path the job runs in), `flow`, and `task` (the prompt text handed to the agent), and may set optional model/provider/maxTurns for that schedule (omit = deployment default). label needs labels[]+flow; comment needs phrase+flow; pull_request needs action[] (+ optional labels[]) + flow. Webhook triggers take an optional `forge` = github (default) | gitlab, which also decides which action words pull_request accepts: github is labeled|opened|synchronize|reopened|review_submitted, gitlab is open|update|reopen|approved. A github review_submitted trigger may also set reviewState[] (approved|changes_requested|commented) to narrow which verdicts fire; omitted, all three do. For webhook triggers the repo and the task come from the triggering issue/PR event \u2014 set only the match + flow \u2014 and they run under the deployment default model.",
+    description: "Adds a trigger to triggers.json and applies it live. The operator MUST approve a confirm dialog showing the entry; with no interactive operator it is refused. `flow` is the .pi/skills/<name> skill the job runs (its SKILL.md is the agent's instructions). `kind` = cron|label|comment|pull_request. cron (local) needs id, pattern, `folder` (absolute host path the job runs in), `flow`, and `task` (the prompt text handed to the agent), and may set optional model/provider/maxTurns for that schedule (omit = deployment default). label needs labels[]+flow; comment needs phrase+flow; pull_request needs action[] (+ optional labels[]) + flow. Webhook triggers take an optional `forge` = github (default) | gitlab | forgejo | azure, which also decides which action words pull_request accepts: github is labeled|opened|synchronize|reopened|review_submitted, gitlab is open|update|reopen|approved, forgejo is label_updated|opened|synchronized|reopened, azure is created|updated. An azure label or comment trigger must also set `repository` (a work item belongs to a project, not a repository), and an azure pull_request trigger may not carry labels[] at all. A github review_submitted trigger may also set reviewState[] (approved|changes_requested|commented) to narrow which verdicts fire; omitted, all three do. For webhook triggers the repo and the task come from the triggering issue/PR event \u2014 set only the match + flow \u2014 and they run under the deployment default model.",
     executionMode: "sequential",
     parameters: typebox_exports.Object({
       kind: typebox_exports.String(),
       flow: typebox_exports.String(),
       forge: typebox_exports.Optional(typebox_exports.String()),
+      // buildTriggerEntry has always READ `f.repository`, and the schema has always stripped it -- so an
+      // azure label/comment trigger was unauthorable by the model, refused at the write for want of a field
+      // it had no way to send. Surfaced by #187 widening what the description above must say about forges.
+      repository: typebox_exports.Optional(typebox_exports.String()),
       id: typebox_exports.Optional(typebox_exports.String()),
       pattern: typebox_exports.Optional(typebox_exports.String()),
       folder: typebox_exports.Optional(typebox_exports.String()),
@@ -41186,7 +41501,7 @@ async function assembleGraph(paths) {
   return buildGraphModel({
     triggers,
     schedulers: Array.isArray(schedulers) ? schedulers : [],
-    ...collectGraphInputs({ triggers: triggerList2 }),
+    ...collectGraphInputs({ triggers: triggerList2, globalPiDir: paths.globalPiDir }),
     cronStats: cronRunStats({ records: recs, schedulerIds: triggerList2.filter((t) => t.type === "cron" && typeof t.id === "string").map((t) => t.id) }),
     runJoin: joinRunsToTriggers({ records: recs, triggerCount: triggers?.count, triggerTypes: Object.fromEntries(triggerList2.map((t) => [t.index, t.type])) }),
     chainEdges: observedChainEdges({ records: recs }),
@@ -41395,7 +41710,7 @@ could not start docker: ${error.message}
   }
 }
 function pauseForMessage() {
-  return new Promise((resolve) => setTimeout(resolve, 2500));
+  return new Promise((resolve2) => setTimeout(resolve2, 2500));
 }
 function splitWords(s) {
   return String(s ?? "").split(/\s+/).map((w) => w.trim()).filter(Boolean);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-admin",
-  "version": "0.8.0",
+  "version": "1.1.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

@@ -122,14 +122,16 @@ job time; and `pi-dispatch doctor` lists every image their triggers name and fla
 
 ## The forge a trigger listens to — `run.kind`
 
-A webhook trigger names its forge: `"kind": "github"` or `"kind": "gitlab"`. Everything else about the
-trigger is the same — the `on.type`, the `{any, all, none}` label predicate, `flow`, `packages`, `image`.
+A webhook trigger names its forge: `"kind"` is `github`, `gitlab`, `forgejo` or `azure`. Everything else
+about the trigger is the same — the `on.type`, the `{any, all, none}` label predicate, `flow`, `packages`,
+`image`, `replicas`.
 
-Two things are NOT the same, and both refuse at load rather than misbehaving quietly:
+Three things are NOT the same, and all of them refuse at load rather than misbehaving quietly:
 
 - **`pull_request` actions are the forge's own words.** GitHub takes
   `labeled | opened | synchronize | reopened | review_submitted`; GitLab takes
-  `open | update | reopen | approved`. A word
+  `open | update | reopen | approved`; Forgejo takes
+  `label_updated | opened | synchronized | reopened`; Azure takes `created | updated`. A word
   from the wrong forge is refused when the file is written. It would not break anything otherwise — it
   would simply never match an event, and the trigger would look configured while doing nothing.
   `review_submitted` is GitHub's `pull_request_review` event: it fires on **every** submitted review, so
@@ -138,6 +140,29 @@ Two things are NOT the same, and both refuse at load rather than misbehaving qui
   load, because a narrowing that cannot apply reads as one that does.
 - **One `comment` trigger per forge.** Two GitHub comment triggers are refused; one GitHub and one GitLab
   are fine.
+- **Azure names no repository.** A work item belongs to a project, so an azure `label` or `comment` trigger
+  MUST set `run.repository` (the repo within the project to clone) and every other forge's must not. An
+  azure `pull_request` trigger may not carry a label predicate at all: Azure tags work items, never pull
+  requests, so `any`/`all`/`none` could never match and a rule that loads clean and never fires reads as a
+  broken harness.
+
+## Racing two agents on one event — `run.replicas`
+
+`"replicas": 2` on a `label`, `comment` or `pull_request` trigger turns one delivery into **two independent
+paid jobs**: two containers, two branches (`pi/issue-7-r1` and `-r2`), two review requests, one human
+picking. It works on every forge. Absent, nothing changes.
+
+Three things to say when an operator asks about it:
+
+- **It multiplies spend, and the caps are the only ceiling.** Each replica reserves its own budget slot
+  before its own tokens, so a `replicas: 2` trigger firing ten times a day consumes twenty slots of the
+  daily cap, not ten. Nothing is discounted; that is the feature, not an oversight.
+- **You cannot set it from here.** There is no `replicas` parameter on `dispatch_trigger_add` or
+  `_edit`, and no panel key. It is a reviewed edit to `triggers.json`, deliberately: a spend multiplier is
+  plainly a capability a model should not gain. Say so rather than looking for a way around it.
+- **It refuses on cron, and beside `resume`.** A local job's `/workspace` IS the operator's folder, so two
+  replicas would edit one working tree with no gate and no undo. And a resumed run continues one lineage
+  where replicas exist to fork it.
 
 `dispatch_trigger_add` takes an optional `forge` parameter, defaulting to `github`. Unlike `image`, this
 one IS offered to the model — a model that can already add a GitHub trigger can already arm a paid run,