feat(triggers): run.command dispatches a registered extension command (#189)

The producer half of issue #189 Gap 2 (the runner protocol merged as
#192): a trigger may now name a registered pi extension command instead of
a flow, on all four trigger kinds.

Parse (shared validator, both services fail identically): exactly one of
run.flow or run.command, refused before every flow check so a command-only
entry never sees the wrong error; the value is validated exactly as the
runner validates PI_COMMAND (non-empty, no leading slash, no surrounding
whitespace, no control characters DEL included) so a file that loads never
refuses in-container; run.task, run.instructions and run.resume are
refused beside command, each naming both fields; everything else stays
orthogonal; an unflagged trigger normalizes byte-identically.

Prompt: a command job's prompt is exactly /name args, local and forge
alike, no envelope, no pointer, no trailing newline; the delivery rides
/job/event.json as the handler's data channel. CONST-ISSUE-TEXT-IS-DATA is
preserved and arguably strengthened: payload text reaches a command job
only as a file the handler chooses to parse, never as prompt prose.

Never AI-reachable, stricter than flows and BUILT rather than fallen out
(the OQ-022 inversion, now recorded there): chain requests carrying a
command key refuse outright as chain-command-refused before the charset
check, with no opt-in, and dispatch_run refuses a slash-leading flow with
a readable message on both invocation paths while remaining structurally
incapable of naming a command. Commands may chain OUT through their own
outbox; nothing chains INTO a command.

Receiver: knownFlows collects only flow-carrying rules; all four forge
gates (github, gitlab, forgejo, azure) dispatch command rules with the
comment phrase-plus-flow override channel INERT on them, so a collaborator
can neither retarget nor veto a command by appending words. Worker: cron
and forge job data carry command; both dedup keys use a cmd: prefix so a
command and a flow of one name cannot collide; image-preflight refuses a
command job on an image not declaring the commands capability, pre-spend,
as job-image-commands-unsupported; doctor counts command triggers and says
where they are verifiable. Admin: display and TUI show /name; the graph
carries command for issue #188; writeTriggers inherits the exclusion.

Specs: INT-TRIGGERS-FILE-CONTRACT AMENDED (the command clause on the
run.image no-model-callable-path template), INT-OUTBOX-CONTRACT AMENDED,
DES-COMMAND-ENTRY-POINT AMENDED (producer half), DES-AI-TRIGGER-FLOW-GATE
AMENDED, DES-JOB-OUTBOX-CHAINING AMENDED,
DES-TRIGGER-INSTRUCTION-IN-THE-ENVELOPE AMENDED (the byte-for-byte
objection answered: command prompts are NEW prompts), OQ-022 AMENDED,
REQ-AI-TRIGGERED-RUNS, REQ-CRON-SCHEDULED-JOBS and REQ-TRIGGER-AUTHOR-GATE
AMENDED. UNCHANGED, checked: DES-TRIGGERS-UNIFIED-FILE,
REQ-DEPLOYMENT-BOOTSTRAP, OQ-008, OQ-019 (its (b) stays open), OQ-009.
docs/workflows.md doctrine rewritten (run.flow and run.command are the two
entry points; the nobody-to-type-it premise refuted at the pin), both
READMEs and docs/job-image.md updated, triggers.example.json gains a cron
command entry.

Signed-off-by: Rob Boerman <robboerman@live.nl>

Author: edgehero

README.md

@@ -126,8 +126,8 @@ receiver (forges), and editable from the panel:
 ### The four trigger types: what fires each one, and what it runs
 
 pi-dispatch is the trigger layer. Every entry is one `{ on, run }` pair: **`on` is what fires it**, and
-**`run` is the skill it runs** (`flow` names a `.pi/skills/<flow>` in the target repo: see
-[Flows](#flows-the-custom-prompt-a-trigger-runs) for what that file is, and
+**`run` is what it runs**, either a flow or a registered command (`flow` names a `.pi/skills/<flow>` in
+the target repo: see [Flows](#flows-the-custom-prompt-a-trigger-runs) for what that file is, and
 [Multi-stage workflows](#multi-stage-workflows-and-third-party-pi-extensions) for chaining skills or
 staging a workflow extension).
 
@@ -138,16 +138,23 @@ staging a workflow extension).
 | `comment` | a comment containing your phrase | `phrase`, for example `@pi` | the phrase, and **one comment trigger per forge** | the comment body plus the issue title and body |
 | `pull_request` | a PR or MR event, including a submitted GitHub review | `action`, a non-empty array in your forge's own words | `action`, plus the same label predicate; where the forge has a label action and you name it, a positive selector becomes **required**; on a GitHub review, also `reviewState` | the PR title and body, plus the review body when a review fired it |
 
-Every type also needs `run.kind` (`local` for cron, else the forge) and `run.flow`. Cron additionally
+One variation changes that last column for every type: a trigger that names `run.command` instead of
+`run.flow` gives the agent exactly `/command args` as its whole prompt, and the issue, comment or PR text
+waits in `/job/event.json` for the command's handler to read (see
+[Multi-stage workflows](#multi-stage-workflows-and-third-party-pi-extensions)).
+
+Every type also needs `run.kind` (`local` for cron, else the forge) and exactly one of `run.flow` or
+`run.command` (naming both, or neither, refuses to load in both services). Cron additionally
 needs `folder` (a host path the worker checks exists when it loads the file; make it absolute, since a
-relative path resolves against the worker's own directory) and `task`. Azure `label` and `comment`
-triggers need `run.repository`, because a work item belongs to a project and names no repository.
+relative path resolves against the worker's own directory) and, with `flow`, a `task`. Azure `label` and
+`comment` triggers need `run.repository`, because a work item belongs to a project and names no repository.
 
 Two matching behaviours worth knowing before you arm a paid trigger:
 
 - **A comment can choose the flow.** `<phrase> <flow>` in the comment body overrides the trigger's
   `run.flow` whenever that word matches another trigger's flow in the same file, so `run.flow` is a
-  default rather than a fixed pairing.
+  default rather than a fixed pairing. On a rule that names `run.command` this channel is inert: trailing
+  words never retarget or suppress the command, and reach the job only as data in `/job/event.json`.
 - **Label triggers match differently per forge.** GitHub and Forgejo match the issue's **whole current
   label set**, so reopening an already-labelled issue, or adding an unrelated label to one, fires
   again. GitLab and Azure match only the labels **that event added**, which is exactly why they do not
@@ -193,6 +200,13 @@ permission check, dedup, quiet hours, the image preflight, branch protection, an
 Each is a deliberate file-only edit (no panel key, no AI tool, because each one changes what code runs
 or what it costs):
 
+- `"command"` replaces `flow` (exactly one of the two, on any trigger type): the job dispatches a
+  registered pi extension command headlessly, its whole prompt being `/command args`. Arguments are fixed
+  in the reviewed file; the event text reaches the handler only as `/job/event.json`, which it reads
+  itself. A command is never AI-triggerable: job chaining refuses any request naming one, and
+  `dispatch_run` cannot express one ([`docs/workflows.md`](docs/workflows.md)). The job image must declare
+  the `commands` capability (the shipped image does); a command job on an image that does not is refused
+  before it costs anything.
 - `"image"` names the container image for that trigger's jobs; absent means `PI_JOB_IMAGE`. The image
   decides what is in the box, never what the box can do: the isolation flags are the worker's, always
   ([`docs/job-image.md`](docs/job-image.md)).
@@ -282,17 +296,19 @@ in every job container**, pinned to an exact version and present offline.
 runs inside the one job the trigger produced:
 
 ```text
-label / comment / PR / cron  ->  one job, one container  ->  run.flow (a skill)  ->  the skills it calls,
-                                                                                     or a workflow extension
+label / comment / PR / cron  ->  one job, one container  ->  run.flow | run.command  ->  the skills it calls,
+                                                                                         or a workflow extension
 ```
 
 Four basics follow from that shape:
 
-- **`run.flow` is the only entry point.** A trigger names a flow, never a workflow. Which stages run, and
-  in what order, is decided inside the job by that skill.
+- **`run.flow` and `run.command` are the two entry points.** A trigger names a flow or a registered
+  command, never a workflow. In a flow job, which stages run is decided inside the job by that skill; in a
+  command job, the named command dispatches directly, with its arguments fixed in the reviewed file.
 - **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 (`/wf`, in the example below) has nobody to type it. In a
-  job a workflow starts because the flow's instructions drive it, or because you also staged a small
+  line. That one prompt can be a slash command: `"command": "wf"` on a trigger dispatches a workflow
+  extension's `/wf` (in the example below) exactly as a typed one would, with no model turn in between. In
+  a flow job a workflow starts because the flow's instructions drive it, or because you also staged a small
   extension that calls the workflow API from a lifecycle hook.
 - **One trigger is one job, one budget slot, one turn budget.** Ten stages share the same `PI_MAX_TURNS`
   and the same per-job token budget; exhausting either aborts the job as a policy refusal that is never

admin/README.md

@@ -46,9 +46,9 @@ 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`
 
@@ -67,7 +67,7 @@ One command puts a live TUI over the whole deployment:
 
 - **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
 

admin/src/graph-model.mjs

@@ -342,6 +342,11 @@ export function buildGraphModel({ triggers, schedulers, folderSkills, injectedSk
       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,

admin/src/index.ts

@@ -371,7 +371,8 @@ function registerTools(pi: ExtensionAPI): void {
       "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 — no force option. " +
-      "Rate-limited per hour.",
+      "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: Type.Object({ folder: Type.String(), flow: Type.String(), task: Type.String() }),
     async execute(_toolCallId, params) {