@edgehero/pi-dispatch 0.2.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
   "keywords": [
@@ -44,6 +44,8 @@
     "./config": "./src/config.mjs",
     "./exit-code": "./src/exit-code.mjs",
     "./flow-gate": "./src/flow-gate.mjs",
+    "./materialize": "./src/materialize.mjs",
+    "./open-browser": "./src/open-browser.mjs",
     "./git-dirty": "./src/git-dirty.mjs",
     "./queue": "./src/queue.mjs",
     "./connection": "./src/connection.mjs",

package/src/config.mjs

@@ -15,6 +15,13 @@ export function configError(message) {
 	return error;
 }
 
+// The chain caps' DEFAULTS, exported (issue #54) so the admin's read-model can state them without a
+// second literal to drift and without calling loadConfig, whose GitHub-auth validation throws on
+// problems unrelated to a path read (the documented reason resolvePaths never calls it). The env
+// OVERRIDES stay right here in loadConfig; only the defaults are shared.
+export const CHAIN_DEPTH_MAX_DEFAULT = 1; // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
+export const CHAIN_MAX_PER_JOB_DEFAULT = 2; // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
+
 function boundedInt(env, name, fallback, min, want) {
 	const raw = env[name];
 	if (raw === undefined || raw === "") {
@@ -191,8 +198,8 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// A bound on how large a transcript may be before it stops being resumed. Not disk hygiene: an
 		// oversized transcript is a prefill an operator never sized PI_MAX_TOKENS for.
 		sessionMaxBytes: nonNegativeInt(env, "PI_SESSION_MAX_BYTES", 8 * 1024 * 1024), // 0 = no cap
-		chainDepthMax: nonNegativeInt(env, "PI_CHAIN_DEPTH_MAX", 1), // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
-		chainMaxPerJob: nonNegativeInt(env, "PI_CHAIN_MAX_PER_JOB", 2), // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
+		chainDepthMax: nonNegativeInt(env, "PI_CHAIN_DEPTH_MAX", CHAIN_DEPTH_MAX_DEFAULT), // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
+		chainMaxPerJob: nonNegativeInt(env, "PI_CHAIN_MAX_PER_JOB", CHAIN_MAX_PER_JOB_DEFAULT), // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
 		dispatchRunPerHour: nonNegativeInt(env, "PI_DISPATCH_RUN_PER_HOUR", 3), // DES-ADMIN-VIA-PI-EXTENSION; 0 = disable dispatch_run
 		dispatchRunRoots: delimitedList(env.PI_DISPATCH_RUN_ROOTS), // DES-AI-TRIGGER-FLOW-GATE: default [] fails closed — no folder passes, dispatch_run refuses everything
 		github: { ...loadGitHubAuth(env, fileExists), allowGhResume: env.PI_SESSIONS_ALLOW_GH_SOURCE === "1" },
@@ -262,6 +269,16 @@ export function defaultLogsDir() {
 	return `${process.env.TMPDIR ?? process.env.TEMP ?? "/tmp"}/pi-dispatch/logs`.replace(/\\/g, "/");
 }
 
+export function defaultGraphDir(env = process.env) {
+	// Under the OS temp dir by default, beside logs/ and jobs/ -- the admin's graph HTML artifact
+	// (issue #54) is host-side display output on the defaultLogsDir doctrine, and deliberately NOT
+	// inside logsDir: INT-RUN-HISTORY-FILE-CONTRACT names that directory's filename shape, and a
+	// stray .html beside the sidecars would widen a contract for a file that is not a record.
+	// Overridable with PI_GRAPH_DIR; exported so the admin resolves the same default without
+	// loadConfig, like defaultSandboxDir above.
+	return `${env.TMPDIR ?? env.TEMP ?? "/tmp"}/pi-dispatch/graph`.replace(/\\/g, "/");
+}
+
 export function defaultSettingsFile() {
 	// Under the OS temp dir by default. Holds the runtime-tunable settings overlay shared with the admin
 	// extension (INT-CONFIG-OVERLAY-CONTRACT); a worker-owned path that never enters the container env

package/src/doctor.mjs

@@ -53,8 +53,9 @@ import { defaultSandboxDir, globalExtensionsEnabled } from "./config.mjs";
 import { isForgeKind } from "./forges.mjs";
 import { findLiteralSecret, ADMIN_RE } from "./import-pi.mjs";
 import { agentDirFrom, readHostPi } from "./host-pi.mjs";
-import { PACKAGES_SUBDIR, readStageManifest } from "./packages.mjs";
+import { PACKAGES_SUBDIR, readStagedSkills, readStageManifest } from "./packages.mjs";
 import { copySkillTree } from "./copy-tree.mjs";
+import { SKILL_NAME_RE } from "./flow-gate.mjs";
 import { parseTriggers } from "./triggers.mjs";
 
 const NODE_FLOOR = [22, 19]; // pi's engine floor (22.19.0)
@@ -251,7 +252,7 @@ export async function collectChecks(env, seams) {
 	// image checks just below, and `optingOut`/`requiring` colour the staged-packages lines further down.
 	// `optingOut` counts the only value that withholds the staged set; `requiring` counts an explicit
 	// run.packages: true, which arms nothing any more but is still an operator statement of intent.
-	const { requiring, optingOut, resuming, replicating, instructing, images, skillsDirs, forges, repositories } = readTriggerFacts(env, fileExists, cwd);
+	const { requiring, optingOut, resuming, replicating, instructing, commands, images, skillsDirs, forges, repositories, flows } = readTriggerFacts(env, fileExists, cwd);
 
 	// Only meaningful if docker itself responds; otherwise the image check is noise on top of a down daemon.
 	const imageCode = dockerCode === 0 ? await runCmd(spawn, "docker", ["image", "inspect", jobImage]) : null;
@@ -325,6 +326,91 @@ export async function collectChecks(env, seams) {
 		}
 	}
 
+	// REQ-PER-TRIGGER-SKILLS (issue #189). One line per distinct (flow, folder, skillsDir, packages)
+	// question: does the flow this trigger names resolve in ANY tier this host can see? Probed in the
+	// loader's own precedence order (repo > injected > overlay > staged packages), first hit wins the
+	// line. ⚠ and NEVER ✗ when nothing resolves -- a forge trigger's repo is not on this host and
+	// mid-setup is legal -- and no fixAction (triggers content is the never tier). The runner's
+	// flow_not_loaded line is the exact, in-container half of the same answer
+	// (DES-FLOW-RESOLUTION-TWO-ADVISORY-LAYERS): these probes read dir names, and a frontmatter
+	// `name:` rename is invisible to them, so a ⚠ here can be wrong in only the loud direction.
+	// A deployment with no triggers adds no lines at all, so its output is byte-identical.
+	if (flows.length > 0) {
+		// One stage read for the whole run; each tuple's staged probe is a lookup on its result.
+		const staged = readStagedSkills({ globalPiDir: env.PI_GLOBAL_PI_DIR, readFile: (p) => readFileSync(p, "utf8"), fileExists });
+		const groups = new Map();
+		for (const f of flows) {
+			const key = JSON.stringify([f.flow, f.folder, f.skillsDir, f.packages]);
+			if (!groups.has(key)) groups.set(key, { ...f, labels: [] });
+			groups.get(key).labels.push(f.label);
+		}
+		for (const g of groups.values()) {
+			const at = g.labels.join(", ");
+			// The charset pre-check doubles as the interpolation guard for the git probe below, and it is
+			// a finding of its own: a name the skill charset refuses can never materialise in ANY tier
+			// (materialize and copy-tree enforce the same RE on the way in).
+			if (!SKILL_NAME_RE.test(g.flow)) {
+				checks.push({
+					ok: false,
+					warn: true,
+					label: `Trigger flow ${JSON.stringify(g.flow)} fails the skill name charset (${at})`,
+					fix: "a flow name must match the skill charset (lowercase alphanumerics, - and _, 64 max), or no tier can ever hold it -- fix run.flow",
+				});
+				continue;
+			}
+			let resolved = null;
+			const checked = [];
+			const unknown = [];
+			if (g.folder) {
+				const state = await repoFlowAtHead(spawn, g.folder, g.flow);
+				if (state === "present") resolved = `repo .pi/skills at HEAD of ${g.folder}`;
+				else if (state === "absent") checked.push("repo .pi/skills at HEAD");
+				else unknown.push(`repo (${g.folder} is not readable as a git repo here)`);
+			} else {
+				unknown.push("repo (a forge clone, not on this host)");
+			}
+			if (!resolved && g.skillsDir) {
+				if (fileExists(join(g.skillsDir, g.flow, "SKILL.md"))) resolved = `injected run.skillsDir ${g.skillsDir}`;
+				else checked.push("injected run.skillsDir");
+			}
+			if (!resolved && env.PI_GLOBAL_PI_DIR) {
+				if (fileExists(join(env.PI_GLOBAL_PI_DIR, "skills", g.flow, "SKILL.md"))) resolved = "the overlay skills/";
+				else checked.push("overlay skills/");
+			}
+			if (!resolved) {
+				if (!g.packages) {
+					checked.push("staged packages (withheld: run.packages false)");
+				} else {
+					const hit = staged.skills.find((s) => s.name === g.flow);
+					if (hit) resolved = `staged package ${hit.package}`;
+					else if (staged.unenumerable.length > 0) unknown.push(`staged package(s) ${staged.unenumerable.join(", ")} (manifest patterns, not enumerable here)`);
+					else checked.push("staged packages");
+				}
+			}
+			if (resolved) {
+				checks.push({ ok: true, label: `Trigger flow "${g.flow}" resolves (${at}: ${resolved})` });
+			} else {
+				checks.push({
+					ok: false,
+					warn: true,
+					label: `Trigger flow "${g.flow}" resolves in NO tier visible here (${at})`,
+					fix: `checked: ${checked.join(", ") || "nothing checkable"}${unknown.length > 0 ? `; not checkable here: ${unknown.join(", ")}` : ""} -- commit .pi/skills/${g.flow}/SKILL.md, add the skill to run.skillsDir or the overlay skills/, or stage a package shipping it; a job of this trigger runs without the flow it names (the runner logs flow_not_loaded) and still exits 0`,
+				});
+			}
+		}
+	}
+
+	// run.command triggers (issue #189): ONE advisory line, deliberately WITHOUT the per-tier probes the
+	// flow block above runs. A command is registered by extension CODE at pi startup -- repo .pi/, the
+	// overlay and staged packages all contribute, and none is enumerable host-side without executing the
+	// extension, which doctor must never do. The honest line names where the real check lives instead;
+	// unlike a missing flow, the failure there is LOUD (a refusal, not a clean exit 0), which is why this
+	// is advisory and carries no fixAction (triggers content is the never tier). A deployment with no
+	// command triggers adds no line at all, so its output is byte-identical.
+	if (commands > 0) {
+		checks.push({ ok: true, label: `${commands} command trigger(s): a command is only verifiable in-container -- the runner refuses an unregistered one pre-spend (command-unregistered)` });
+	}
+
 	// Issue #41: every DISTINCT image a trigger names in run.image, minus the deployment default already
 	// checked above. Two silent-failure modes, and both used to be impossible because there was one image.
 	//   1. the image was never built -- a job that refuses pre-spend at 03:00 in a log nobody is reading, and
@@ -1191,8 +1277,37 @@ function aiTriggerNames(dir) {
 	return names;
 }
 
+/**
+ * Does `.pi/skills/<flow>/SKILL.md` exist at HEAD of a local folder? "present" | "absent" | "unknown".
+ *
+ * Deliberately NOT readFlowGate: that module answers WHO may fire a flow (the ai-trigger frontmatter,
+ * at a caller-pinned sha) and its catch collapses ANY git failure into deny -- fail-closed is right
+ * for a gate and exactly wrong here, where deny-because-git-broke would print a confident wrong
+ * answer on an advisory line. Doctor resolving HEAD itself is also fine: the gate's no-ref rule
+ * defends against an agent self-authorizing mid-run, and a host-side preflight has no agent. What IS
+ * the gate's, verbatim, is the ls-tree read, the 100644-blob requirement and the hardening flags --
+ * copied so the two readers cannot disagree about what "a committed skill file" means, and so a
+ * hostile repo config cannot run code during the read (flow-gate.mjs's defaultGit, restated).
+ */
+const GIT_READ_FLAGS = ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "--no-pager"];
+async function repoFlowAtHead(spawn, folder, flow) {
+	if (!SKILL_NAME_RE.test(flow)) return "unknown"; // the caller pre-checks; belt against interpolation
+	const head = await runCmdCapture(spawn, "git", [...GIT_READ_FLAGS, "-C", folder, "rev-parse", "HEAD"]);
+	const sha = head.code === 0 ? head.output.trim() : null;
+	if (!sha || !/^[0-9a-f]{40,64}$/.test(sha)) return "unknown";
+	const tree = await runCmdCapture(spawn, "git", [...GIT_READ_FLAGS, "-C", folder, "ls-tree", "-z", sha, `.pi/skills/${flow}/SKILL.md`]);
+	if (tree.code !== 0) return "unknown";
+	const record = tree.output.split("\0").find((r) => r);
+	if (!record) return "absent"; // valid sha, path absent at that commit
+	const tab = record.indexOf("\t");
+	const [mode, type] = tab === -1 ? [] : record.slice(0, tab).split(/\s+/);
+	// A symlink/gitlink entry is "absent" for this question too: the gate would refuse it, and the
+	// materialiser never copies it, so nothing downstream treats it as a skill file.
+	return mode === "100644" && type === "blob" ? "present" : "absent";
+}
+
 function readTriggerFacts(env, fileExists, cwd) {
-	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, images: [], skillsDirs: [], forges: [], repositories: [] };
+	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, images: [], skillsDirs: [], forges: [], repositories: [], flows: [] };
 	try {
 		// Unset falls back to ./triggers.json in cwd, MIRRORING the receiver's own default
 		// (receiver/src/config.mjs) -- the two must read the same file, or doctor preflights a deployment
@@ -1209,6 +1324,10 @@ function readTriggerFacts(env, fileExists, cwd) {
 			// REQ-REPLICA-RUNS. `> 1` rather than `!== undefined` because the loader already refuses anything
 			// else -- this counts triggers that will actually multiply spend, which is the only reason to say so.
 			replicating: triggers.filter((t) => t.run.replicas > 1).length,
+			// run.command triggers (issue #189), counted for the one advisory line below. The `flows`
+			// tuple list already filters to `typeof f.flow === "string"`, so a command trigger drops out
+			// of the flow-tier probes naturally -- no exclusion needed there.
+			commands: triggers.filter((t) => typeof t.run.command === "string").length,
 			optingOut: triggers.filter((t) => t.run.packages === false).length,
 			images: [...new Set(triggers.map((t) => t.run.image).filter((i) => typeof i === "string"))].sort(),
 			// REQ-PER-TRIGGER-SKILLS. The distinct host directories the file names, deduped like `images`,
@@ -1224,6 +1343,21 @@ function readTriggerFacts(env, fileExists, cwd) {
 			// would report all-green and never mention that the credential it needs was never looked for.
 			forges: [...new Set(triggers.map((t) => t.run.kind).filter(isForgeKind))].sort(),
 			repositories: [...new Set(triggers.filter((t) => t.run.kind === "github" && typeof t.run.repository === "string").map((t) => t.run.repository))].sort(),
+			// REQ-PER-TRIGGER-SKILLS (issue #189). Per-trigger TUPLES, unlike every deduped set above,
+			// because a flow-resolution answer depends on the trigger's own folder/skillsDir/packages --
+			// two triggers naming the same flow with different skillsDirs are two different questions.
+			// The label is how a line names its trigger: cron entries by their id, id-less webhook
+			// entries by raw file position (the admin's trigger:<index> identity).
+			flows: triggers
+				.map((t, index) => ({
+					label: t.on.type === "cron" ? `cron "${t.on.id}"` : `${t.on.type} trigger #${index}`,
+					flow: t.run.flow,
+					kind: t.run.kind,
+					folder: typeof t.run.folder === "string" ? t.run.folder : null,
+					skillsDir: typeof t.run.skillsDir === "string" ? t.run.skillsDir : null,
+					packages: t.run.packages !== false,
+				}))
+				.filter((f) => typeof f.flow === "string"),
 		};
 	} catch {
 		return none;

package/src/env-allowlist.mjs

@@ -110,7 +110,7 @@ function resolveEnvName(provider, cred) {
  * `allowGlobalExtensions` defaults to TRUE here, matching loadConfig's default (REQ-GLOBAL-PI-OVERLAY): a
  * caller that says nothing gets the operator's staged setup, and only an explicit `false` withholds it.
  */
-export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], sessionFile = null, authFromPi = false, agentDir, readFile = readFileSync }) {
+export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], sessionFile = null, flow = null, command = null, authFromPi = false, agentDir, readFile = readFileSync }) {
 	// The provider credential(s), by pi's expected variable name(s) -- from the worker env, or (when
 	// PI_AUTH_FROM_PI is set and the env has none) host-side from pi's auth.json. Throws (config) if
 	// neither source yields one, which the processor turns into a pre-spend refusal.
@@ -146,6 +146,22 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId,
 		// an empty string, for PI_PACKAGES' reason: an empty value is a third state neither side reads the
 		// same way, and the one reading a container must not have to infer which was meant.
 		PI_SESSION_FILE: sessionFile || undefined,
+		// The trigger's run.flow, STRUCTURALLY (issue #189). The flow already reaches the container as
+		// prompt prose ("Use the X skill"), but pi never matches prose against loaded skill names, so a
+		// flow that resolves in no tier runs to a clean exit 0 -- the silent no-op this repo brands the
+		// worst outcome available. This variable is what lets the runner compare the name against what
+		// actually loaded. It rides env and NOT event.json because an execution knob is not a fact about
+		// the delivery (see prepare-github.mjs on replicas). Absent means "no flow to verify" (a bare
+		// run.task cron job), never an empty string, for PI_PACKAGES' reason.
+		PI_FLOW: flow || undefined,
+		// The trigger's run.command, STRUCTURALLY (issue #189) -- PI_FLOW's twin: the runner compares it
+		// against the commands that actually registered and refuses an unregistered one before any spend,
+		// where the prompt's bare `/name` would otherwise read as prose and run to a clean exit 0. It
+		// rides env and NOT event.json for the same reason PI_FLOW does. Absent means "not a command
+		// job", never an empty string, for PI_PACKAGES' reason. PI_FLOW and PI_COMMAND are mutually
+		// exclusive by parse (command XOR flow); that is deliberately NOT re-enforced here -- a second
+		// validator is a second place to disagree with the first.
+		PI_COMMAND: command || undefined,
 		// Kill switch for job-time package installation, UNCONDITIONAL for every job. pi's resolver shells out
 		// to a REAL `npm install` for any npm:/git: source unless offline mode is on, and `~/.pi/agent` IS
 		// writable in the container. We emit only local paths, so nothing should reach that branch -- this

package/src/flow-gate.mjs

@@ -64,7 +64,9 @@ export async function readFlowGate({ folder, flow, sha, git = defaultGit }) {
 // Custom: no YAML parser in worker deps; a single ai-trigger boolean does not justify js-yaml.
 // Strict leading-frontmatter scan: strip a BOM, normalise CRLF, isolate the leading `---`..`---`
 // block, and require an exact `ai-trigger: allow` line (an optional surrounding double quote).
-function aiTriggerAllows(buf) {
+// Exported (issue #54) so the admin's skill enumeration answers "chainable?" with THIS scanner and
+// not a keep-in-sync copy -- the SKILL_NAME_RE lesson one export up, applied to the frontmatter test.
+export function aiTriggerAllows(buf) {
 	const text = buf.toString("utf8").replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
 	const block = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(text);
 	if (!block) return false; // no parseable frontmatter -> deny

package/src/github-app-setup.mjs

@@ -32,13 +32,13 @@
  * Everything side-effecting is injected (fetch, the listener, the browser opener, prompt, fs, clock),
  * defaulting to the real thing — the up.mjs convention — so the whole flow is testable offline.
  */
-import { spawn as nodeSpawn } from "node:child_process";
 import { createSign } from "node:crypto";
 import { chmodSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { updateEnvFile } from "./env-file.mjs";
+import { openBrowser as defaultOpenBrowser } from "./open-browser.mjs";
 import { defaultPrompt } from "./up.mjs";
 
 const API_ROOT = "https://api.github.com";
@@ -503,20 +503,6 @@ async function defaultListen(pageFor) {
 	};
 }
 
-/**
- * Best-effort platform browser opener. ALWAYS paired with the URL printed to the terminal — a
- * headless or SSH'd operator has no opener that works, and the printed URL pasted into any browser
- * (on the right machine, or through the port-forward the wizard suggests) is the real contract; the
- * spawn is only a convenience on top. Failures are swallowed for the same reason.
- */
-function defaultOpenBrowser(url) {
-	const [cmd, args] =
-		process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
-	try {
-		const child = nodeSpawn(cmd, args, { stdio: "ignore", detached: true });
-		child.on("error", () => {});
-		child.unref();
-	} catch {
-		// No opener on this host — the printed URL carries the flow.
-	}
-}
+// The best-effort platform opener moved to its own module (issue #54) so the admin's graph export
+// shares this one reviewed argv table instead of hand-copying it; the print-the-URL-first doctrine
+// lives in its docstring and is unchanged here.

package/src/image-preflight.mjs

@@ -33,6 +33,7 @@ export function resolveJobImage(job, defaultImage) {
  *   { unavailable: image} -- docker itself did not answer              => INFRA, retry
  *   { forgeUnsupported }  -- present, but declares it cannot serve this job's forge => POLICY, refuse
  *   { replicaUnsupported }-- present, but does not declare replica support for a replica job => POLICY
+ *   { commandUnsupported }-- present, but does not declare command support for a command job => POLICY
  *
  * A non-zero `docker image inspect` is AMBIGUOUS -- an absent image and an unreachable daemon both exit 1 --
  * so the failure path disambiguates POSITIVELY with `docker info` rather than by matching docker's stderr.
@@ -87,6 +88,14 @@ export function makeImagePreflight({ image, spawnFn = spawn }) {
 			if (job?.replica !== undefined && !(capabilities ?? []).includes("replicas")) {
 				return { replicaUnsupported: wanted, declared: capabilities ?? [] };
 			}
+			// Same inclusion-list polarity as `replicas` directly above, and the same class of stale-image
+			// failure it guards (issue #189): a runner that predates run.command reads no PI_COMMAND, so
+			// the bare `/name args` prompt reaches the model as PROSE -- no handler runs, the agent
+			// improvises, and the queue records a clean exit 0. Unreachable for a commandless job, so the
+			// existing fleet pays nothing for it.
+			if (job?.command !== undefined && !(capabilities ?? []).includes("commands")) {
+				return { commandUnsupported: wanted, declared: capabilities ?? [] };
+			}
 			return { ok: true, image: wanted, piVersion };
 		}
 		if ((await runDocker(spawnFn, ["info"])).code === 0) return { missing: wanted };

package/src/open-browser.mjs

@@ -0,0 +1,24 @@
+import { spawn as nodeSpawn } from "node:child_process";
+
+/**
+ * Best-effort platform browser opener. ALWAYS paired with the URL printed to the terminal -- a
+ * headless or SSH'd operator has no opener that works, and the printed URL pasted into any browser
+ * (on the right machine, or through the port-forward the caller suggests) is the real contract; the
+ * spawn is only a convenience on top. Failures are swallowed for the same reason.
+ *
+ * One module on purpose (issue #54): the GitHub App wizard and the admin's graph export both open a
+ * browser, and two hand-copies of platform-opener argv is exactly the drift class the repo's mirror
+ * tests exist to prevent. `spawn` and `platform` are injectable so the argv table is testable
+ * without launching anything.
+ */
+export function openBrowser(url, { spawn = nodeSpawn, platform = process.platform } = {}) {
+	const [cmd, args] =
+		platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+	try {
+		const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+		child.on("error", () => {});
+		child.unref();
+	} catch {
+		// No opener on this host -- the printed URL carries the flow.
+	}
+}

package/src/outbox.mjs

@@ -119,6 +119,20 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					continue;
 				}
 
+				// Commands are NEVER AI-reachable (issue #189): a request naming one refuses outright,
+				// with no opt-in to widen. The flow gate below reads a COMMITTED artifact -- the target
+				// repo's SKILL.md frontmatter at the pinned sha, merge-gated and reviewable -- but a
+				// command is an operator-staged pi extension with no committed artifact a gate could
+				// read, so there is nothing to gate ON and fail-closed is the only honest answer. First
+				// in the semantic ladder, before the charset check: which field the request used is
+				// decided before any opinion about its spelling. A completed command job's OWN /outbox
+				// may still chain INTO flows through the unchanged gate below; nothing chains into a
+				// command.
+				if (req.command !== undefined) {
+					refuse("chain-command-refused", i);
+					continue;
+				}
+
 				// Explicit property reads ONLY -- `req` is never spread into job data.
 				const flow = req.flow;
 				const task = req.task;

package/src/packages.mjs

@@ -24,8 +24,8 @@
  *     manifest must degrade to "no staged packages", not crash the worker mid-queue.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { configError } from "./config.mjs";
 // ENTRY_NAME_RE / ADMIN_RE are import-pi's -- imported rather than re-declared so the staged dir charset
 // and the admin block cannot drift between the stager and this validator (doctor.mjs sets the precedent
@@ -269,6 +269,89 @@ export function readStageManifest({ globalPiDir, readFile = readFileSync, fileEx
 	}
 }
 
+/**
+ * Enumerate the skills the staged packages would contribute to a job (issue #189). Returns
+ * `{ skills: [{ name, package, dir }], unenumerable: [packageName...] }`, and NEVER throws --
+ * readStageManifest's policy, because the consumers are advisory (doctor's per-trigger flow lines,
+ * and issue #188's topology) and a half-staged tree must degrade to "nothing visible", not a crash.
+ *
+ * The semantics mirror pi's collectPackageResources at the 0.80.7 pin EXACTLY, because an enumerator
+ * that agrees with pi by hand is how doctor comes to report a tier pi then ignores:
+ *   - a `pi` manifest object means its `skills` entries are the ONLY sources -- a manifest WITHOUT a
+ *     `skills` key contributes NO skills and gets NO convention fallback (readPiManifest short-circuits
+ *     before the dir walk);
+ *   - no `pi` key at all falls through to the convention `skills/` dir (RESOURCE_DIRS);
+ *   - a manifest entry may be a SKILL.md file, a skill dir, or a dir of skill dirs -- pi walks
+ *     recursively, so this walks the same shape (bounded, it is host-advisory);
+ *   - a glob (`*`/`?`) or override (`!`/`+`/`-` prefix) entry makes the whole package UNENUMERABLE
+ *     rather than guessed at: patterns can also DISABLE files, and a wrong ✓ (a skill reported that pi
+ *     filters out) is the direction an advisory line must never err in. Reported, not silently skipped.
+ *
+ * Names are DIR basenames (or the SKILL.md's parent dir), which is pi's fallback naming rule; a
+ * frontmatter `name:` rename is invisible here. That approximation is deliberate and one-directional:
+ * it can only turn a would-be ✓ into a ⚠, and the runner's flow_not_loaded check compares against the
+ * names pi actually loaded (DES-FLOW-RESOLUTION-TWO-ADVISORY-LAYERS).
+ */
+export 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;
+				}
+				// `..`-carrying entries are dropped rather than resolved: the stager never writes one, and
+				// following one would make an advisory reader walk outside the staged tree. A segment
+				// test, not a prefix test, so it holds on Windows separators too (parsePackagePaths' rule).
+				sources = entries.filter((e) => !e.split(/[\\/]/).includes("..")).map((e) => resolve(root, e));
+			} else {
+				sources = [join(root, "skills")];
+			}
+		} catch {
+			continue; // no readable package.json: pi would skip it too
+		}
+		for (const source of sources) {
+			for (const skillFile of walkSkillFiles(source, fileExists, readDir)) {
+				out.skills.push({ name: basename(dirname(skillFile)), package: pkg.name, dir: pkg.dir });
+			}
+		}
+	}
+	return out;
+}
+
+/**
+ * The SKILL.md files under one manifest source, the shapes pi's collectFilesFromPaths accepts: the file
+ * itself, a dir holding SKILL.md, or a tree of skill dirs (walked to a small fixed depth -- pi recurses
+ * unbounded, but a host-advisory reader stops where real layouts stop). Never throws.
+ */
+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; // absent or unreadable: nothing visible here
+	}
+	for (const child of children) {
+		if (!child.isDirectory?.()) continue;
+		found.push(...walkSkillFiles(join(source, child.name), fileExists, readDir, depth - 1));
+	}
+	return found;
+}
+
 /**
  * The CONTAINER paths of the staged packages, in manifest order -- what gets handed to pi as local package
  * specs. Built with template literals and never `path.join`: the worker may run on Windows, where `join`

package/src/prepare-github.mjs

@@ -190,6 +190,15 @@ export async function prepareGithubWorkspace(
 		const session = job.resume === true ? resolveSession(job, { jobDir, resolved, piVersion }) : null;
 
 		// Issue text is DATA: it enters the USER prompt (buildGithubPrompt), never a system prompt.
+		//
+		// A command job (issue #189) skips the per-forge envelope entirely: the prompt is the slash
+		// invocation `/${job.command}` and nothing else -- no data heading, no quoted issue text, and NO
+		// trailing newline, because pi hands everything after the first space to the handler as its
+		// argument string verbatim. CONST-ISSUE-TEXT-IS-DATA is preserved and arguably STRENGTHENED:
+		// payload text reaches a command job only as event.json below, a file the handler chooses to
+		// parse, never interpolated into prompt prose at all. The envelope's never-merge discipline is
+		// not lost either -- that discipline addresses MODEL prose, and a command handler is
+		// operator-staged code, the same trust tier extensions hold generally.
 		writeFile(
 			join(jobDir, "prompt.md"),
 			// `replica`/`replicas` (REQ-REPLICA-RUNS) are host-assigned integers off job.data, so they are safe
@@ -198,7 +207,9 @@ export async function prepareGithubWorkspace(
 			// them away -- harmless, and always undefined while replicas are github-only.
 			// `review` rides beside `comment` and, like `replica`/`replicas`, is destructured away by the
 			// gitlab/forgejo/azure builders -- harmless, and always undefined while reviews are github-only.
-			buildPrompt({ flow: job.flow, target: job.target, comment: job.trigger?.comment, resumed: session?.resume === true, replica: job.replica, replicas: job.replicas, review: job.trigger?.review, instructions: job.instructions }),
+			job.command
+				? `/${job.command}`
+				: buildPrompt({ flow: job.flow, target: job.target, comment: job.trigger?.comment, resumed: session?.resume === true, replica: job.replica, replicas: job.replicas, review: job.trigger?.review, instructions: job.instructions }),
 			{ mode: 0o444 },
 		);
 

package/src/prepare.mjs

@@ -93,10 +93,19 @@ export function makePrepareWorkspace({
 			// flow can discover the trigger context (mirroring the github prompt, which names the same
 			// file); nothing in-container reads it otherwise. The pointer sits AFTER the flow hint and
 			// BEFORE the operator's task, which stays verbatim (CONST-ISSUE-TEXT-IS-DATA).
+			//
+			// A command job (issue #189) bypasses ALL of that: the prompt is the slash invocation itself,
+			// `/name args`, and nothing else -- no pointer line, no task, and critically NO trailing
+			// newline, because pi hands everything after the first space to the handler as its argument
+			// string verbatim, so a newline appended here would land inside the args. The pointer is
+			// prose addressed to a MODEL reading instructions; a command handler is code, and its context
+			// channel is /job/event.json itself, which prepare-local already writes for every local job.
 			const pointer = "Context about this run -- its trigger and schedule -- is in /job/event.json.\n\n";
-			const task = job.flow
-				? `Use the "${job.flow}" skill for this task.\n\n${pointer}${job.task ?? ""}`
-				: `${pointer}${job.task ?? ""}`;
+			const task = job.command
+				? `/${job.command}`
+				: job.flow
+					? `Use the "${job.flow}" skill for this task.\n\n${pointer}${job.task ?? ""}`
+					: `${pointer}${job.task ?? ""}`;
 			const event = localEventContext(job, queueJobId, findPreviousRun);
 			return discardOnPolicy(stampSandbox(await prepareLocal({ folder: job.folder, task, jobDir, event }), sandbox), jobDir);
 		}

package/src/processor.mjs

@@ -159,6 +159,23 @@ export async function runJob(job, deps) {
 			log("refused_image_replicas_unsupported", { image: img.replicaUnsupported, declared: img.declared });
 			return { outcome: "policy", reason: "job-image-replicas-unsupported", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
 		}
+		if (img.commandUnsupported) {
+			// The image is present and does not declare command support (issue #189), so its runner
+			// predates run.command: it reads no PI_COMMAND, and the bare `/name args` prompt reaches the
+			// model as PROSE -- no handler runs, the agent improvises, and the queue records a clean exit
+			// 0. The in-container half of the gate (the runner's own command-unregistered refusal) does
+			// not exist on such an image, which is exactly why the host must refuse first.
+			//
+			// Determinate, so a refusal rather than a retry, and pre-spend, because no version of this
+			// gets better by running. Like the replica branch above, the message names the FIX rather
+			// than the label that noticed it.
+			await comment(
+				job,
+				`Refused: the job image "${img.commandUnsupported}" does not declare command support (\`dev.pi-dispatch.capabilities\` ${img.declared.length > 0 ? `declares: ${img.declared.join(", ")}` : "is absent"}), so its runner would not dispatch \`run.command\`. Rebuild the image from a version that has this feature. Not run.`,
+			);
+			log("refused_image_commands_unsupported", { image: img.commandUnsupported, declared: img.declared });
+			return { outcome: "policy", reason: "job-image-commands-unsupported", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
 		if (img.unavailable) {
 			// docker itself did not answer -- transient infra, NOT a determinate refusal. THROWN so BullMQ
 			// retries (CONST-RETRY-INFRA-ONLY). `container-never-started` is literally true here, and it reuses

package/src/queue.mjs

@@ -16,11 +16,16 @@ export function makeQueue(connection) {
  * removeOnComplete keeps the dedup window ~= the retention. Unlike webhooks, local jobs are not
  * redelivered, so a modest window is enough.
  */
-export async function enqueueLocalJob(queue, { folder, flow, task, provider, model, maxTurns, image, skillsDir, chainDepth, parentJobId, jobId, now = new Date() }) {
+export async function enqueueLocalJob(queue, { folder, flow, task, command, provider, model, maxTurns, image, skillsDir, chainDepth, parentJobId, jobId, now = new Date() }) {
 	const minute = now.toISOString().slice(0, 16); // YYYY-MM-DDTHH:MM -- the dedup window
 	// A caller-supplied jobId (the outbox collector's retry-idempotent chainedJobId) wins; otherwise the
-	// minute-windowed localJobId is the dedup key.
-	const id = jobId ?? localJobId({ folder, flow, task, minute });
+	// minute-windowed localJobId is the dedup key. A command job (issue #189) fills the flow slot with
+	// `cmd:<command>` rather than leaving it empty: a command trigger carries no flow/task, so without it
+	// two DIFFERENT commands on one folder in one minute would hash identically and the second would
+	// vanish silently -- and the `cmd:` prefix keeps a command named X from colliding with a flow named X
+	// (`:` is outside the skill-name charset, so no real flow can spell the prefixed form). A flow job's
+	// key is byte-identical to before the feature.
+	const id = jobId ?? localJobId({ folder, flow: command !== undefined ? `cmd:${command}` : flow, task, minute });
 	// image/chainDepth/parentJobId land on `data` only when present, so a plain non-chained job's data is
 	// byte-identical. `image` is the container image this job runs in (INT-TRIGGERS-FILE-CONTRACT); absent
 	// resolves the deployment default at job start, never a value frozen here.
@@ -29,6 +34,10 @@ export async function enqueueLocalJob(queue, { folder, flow, task, provider, mod
 		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 !== undefined && { command }),
 		provider,
 		model,
 		maxTurns,
@@ -115,7 +124,7 @@ export async function enqueueGitLabJob(queue, fields) {
  * window, replicas never coalesce against each other, and an unflagged job's dedup id is the same string it
  * has always been.
  */
-export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, trigger, provider, model, maxTurns, packages, image, skillsDir, instructions, resume, replica, replicas }) {
+export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, command, trigger, provider, model, maxTurns, packages, image, skillsDir, instructions, resume, replica, replicas }) {
 	const jobId = forgeDeliveryJobId(kind, trigger?.deliveryId, replica);
 	// `packages` (whether to load the operator-staged pi packages) and `image` (which container image to run)
 	// come off the MATCHED trigger (INT-TRIGGERS-FILE-CONTRACT / REQ-GLOBAL-PI-OVERLAY) and land on `data`
@@ -132,6 +141,11 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		...(azure !== undefined && { azure }),
 		target,
 		flow,
+		// The registered pi command this trigger dispatches instead of a flow (issue #189). Conditional
+		// like `packages`/`image` below, so an unflagged trigger's job data is byte-identical -- and at
+		// JOB level, never inside `trigger`, for their reason too: an execution knob is not a fact about
+		// the delivery, and `trigger` is copied verbatim into /job/event.json.
+		...(command !== undefined && { command }),
 		trigger,
 		provider,
 		model,
@@ -156,7 +170,13 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 	};
 	await queue.add(kind, data, {
 		jobId,
-		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${flow}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
+		// A command job (issue #189) fills the semantic key's flow slot with `cmd:<command>`: a command
+		// trigger carries no flow, so the slot would otherwise read `undefined` for every command and one
+		// command's 10-minute window would swallow a different command's delivery on the same target. The
+		// `cmd:` prefix keeps a command named X from coalescing against a flow named X -- `:` is outside
+		// the skill-name charset, so no real flow can spell the prefixed form -- and a flow job's key
+		// stays byte-identical to before the feature.
+		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${command !== undefined ? `cmd:${command}` : flow}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
 		attempts: 2,
 		backoff: { type: "exponential", delay: 60_000 },
 		removeOnComplete: { age: 31 * 24 * 3600 }, // age in seconds -- do not cross units with the ms ttl above

package/src/run-container.mjs

@@ -74,6 +74,13 @@ export function makeRunContainer({
 			// The constant is imported rather than re-typed so the mount below and this variable name one
 			// path -- two literals is how they drift with both suites green.
 			sessionFile: prepared.session ? CONTAINER_SESSION_FILE : undefined,
+			// Issue #189: the flow name, structurally, so the runner can verify it against the loaded
+			// skill set. Off `job` like maxTurns; absent (a bare run.task cron job) emits no variable.
+			flow: typeof job.flow === "string" && job.flow.trim() !== "" ? job.flow : undefined,
+			// Issue #189: the command name, structurally, so the runner can refuse an unregistered one
+			// before any spend (command-unregistered). Same guard shape as `flow` directly above, and
+			// mutually exclusive with it by parse -- a job carries one or the other, never both.
+			command: typeof job.command === "string" && job.command.trim() !== "" ? job.command : undefined,
 			authFromPi, // source the provider key from pi's auth.json when the env has none
 		});
 

package/src/run-history.mjs

@@ -295,6 +295,19 @@ export function buildRecord({ job, result, error, startedAt, endedAt }) {
 		// deliberately not stored, for the reason `session` states one group below.
 		replica: data.replica ?? null,
 		replicas: data.replicas ?? null,
+		// Trigger attribution (INT-RUN-HISTORY-FILE-CONTRACT, issue #54): additive and nullable, explicit
+		// literals beside the replica fields whose admissibility argument they reuse, no spread. Both read
+		// the receiver's harness-computed `matched` from this job's own `job.data.trigger`: `index` is the
+		// raw triggers-array position of the entry that fired (cron entries counted) and `type` that entry's
+		// `on.type` -- an INTEGER and a FIXED ENUM ("label" | "comment" | "pull_request"), nothing
+		// attacker-chosen. The third `matched` key (`label`/`phrase`/`action`) is DELIBERATELY absent:
+		// a label that satisfied an `any` predicate is collaborator-applied payload text, and `type`
+		// already names the route. Cron jobs carry `trigger: { id, pattern }` with no `matched`, so both
+		// stay null there on purpose -- a cron run's attribution is already exact via its
+		// `repeat:<id>:<millis>` jobId (see makeFindPreviousRun), and that join also works retroactively
+		// over the whole retention window, which a new record field cannot.
+		triggerIndex: data.trigger?.matched?.index ?? null,
+		triggerType: data.trigger?.matched?.type ?? null,
 		// Session telemetry (INT-RUN-HISTORY-FILE-CONTRACT): additive, nullable, an explicit literal, no
 		// spread. `{ resumed, reason, bytes }` -- a boolean, a fixed enum and an integer. THE KEY AND THE
 		// BRANCH NAME ARE DELIBERATELY ABSENT: this record's PII-free-by-construction property rests on it

package/src/schedules.mjs

@@ -68,7 +68,13 @@ function normalizeCronSchedule({ on, run }, path, existsSync) {
 	// cron-only field: it is carried into the local `/job/event.json` (INT-CONTAINER-JOB-INPUTS) so a
 	// scheduled job can name its own trigger; the INT-TRIGGERS-FILE-CONTRACT byte-match acceptance is
 	// amended for exactly this field.
-	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), resume: run.resume, trigger: { id: on.id, pattern: on.pattern } };
+	//
+	// `command` (issue #189) is conditional like `skillsDir`, not present-and-undefined like flow/task,
+	// and both spellings serve the same byte-identity: a flow trigger's stored repeatable must not grow a
+	// key. A command trigger carries no flow/task at all (the validator enforces the XOR), so those two
+	// keys hold undefined here and drop at JSON serialization -- the command schedule's data is exactly
+	// kind/folder/command plus the shared fields.
+	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, ...(run.command !== undefined && { command: run.command }), provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), resume: run.resume, trigger: { id: on.id, pattern: on.pattern } };
 	// Retention only; the deterministic repeat:<id>:<millis> jobId supplies dedup, so no jobId here, and
 	// scheduler jobs are not retried (DES-CRON-VIA-BULLMQ-SCHEDULER) so no attempts/backoff.
 	const opts = { removeOnComplete: { age: 24 * 3600 }, removeOnFail: { age: 7 * 24 * 3600 } };

package/src/triggers.mjs

@@ -191,13 +191,20 @@ function normalizeCron(on, run, index, path, state) {
 		throw configError(`cron trigger "${id}": on.pattern must have 5 or 6 space-separated fields, got ${fieldCount}: ${path}`);
 	}
 
+	// FIRST among the run checks (all four normalizers do this), so a command-only entry is never told to
+	// add the flow it deliberately does not have, and a flow+command entry gets the exclusion message
+	// rather than whichever single-field check happens to run first.
+	const command = validateCommand(run, `cron trigger "${id}"`, path, { onType: "cron" });
+
 	if (!isNonEmptyString(run.folder)) {
 		throw configError(`cron trigger "${id}": run.folder must be a non-empty string: ${path}`);
 	}
-	if (!isNonEmptyString(run.flow)) {
-		throw configError(`cron trigger "${id}": run.flow must be a non-empty string: ${path}`);
+	if (command === undefined && !isNonEmptyString(run.flow)) {
+		throw configError(`cron trigger "${id}": run.flow must be a non-empty string (or use run.command): ${path}`);
 	}
-	if (!isNonEmptyString(run.task)) {
+	// Gated on the flow path only: a command job's prompt IS the command line, and validateCommand has
+	// already refused any run.task written beside one.
+	if (command === undefined && !isNonEmptyString(run.task)) {
 		throw configError(`cron trigger "${id}": run.task must be a non-empty string: ${path}`);
 	}
 
@@ -229,7 +236,7 @@ function normalizeCron(on, run, index, path, state) {
 	// freeze today's default into every stored repeatable.
 	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 !== undefined && { 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 !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }) },
 	};
 }
 
@@ -450,6 +457,85 @@ function validateInstructions(run, at, path, { cron = false } = {}) {
 	return text;
 }
 
+/**
+ * `run.command` (issue #189): dispatch a REGISTERED pi extension command headlessly, instead of a flow.
+ * The runner half is already merged: it exports the name via PI_COMMAND, refuses pre-spend when
+ * `getCommand` does not know it, and prompts with the exact `/name args` line and nothing else, so the
+ * arguments reach the command handler precisely as written here. Shared by all four normalizers so both
+ * services refuse the same file identically; the runner re-validates at the paid boundary regardless.
+ *
+ * EXACTLY ONE of run.flow / run.command, and the exclusion is checked BEFORE every normalizer's
+ * flow-required check on purpose: the two mistakes need their own messages. A flow+command entry no
+ * longer says which one runs and must hear that, not whichever single-field complaint fires first; a
+ * command-only entry must never be told to add the flow it deliberately does not have.
+ *
+ * The value rules each refuse something specific:
+ *   - no leading "/": the runner PREPENDS the slash when it builds the prompt, so a written one would
+ *     dispatch "//name" -- a command no registry holds, refused only after review already passed it.
+ *   - surrounding whitespace is REFUSED, never trimmed (validateImageRef's rule): the arguments pass to
+ *     the handler verbatim, so a silent trim is the reviewed file disagreeing with what runs.
+ *   - no control characters. A newline would smuggle a SECOND line into what the operator reviewed as
+ *     one command line, and the whole class is refused rather than the newline alone because every
+ *     member is invisible in review, which is the hazard. The regex is spelled in \u escapes for the
+ *     same reason: a literal ESC in this source would be exactly the unreviewable byte it refuses.
+ *
+ * Cross-field refusals, validateReplicas' posture (a field accepted where it does nothing is one an
+ * operator sets and then trusts):
+ *   - run.task on cron: a command job's prompt IS the `/name args` line, so there is no task text for
+ *     the runner to render -- two prompts written for one job, with only one ever sent.
+ *   - run.instructions on the webhook kinds: instructions land in the prompt ENVELOPE, which a command
+ *     job bypasses entirely, so nothing would render them. (Cron refuses instructions already, with its
+ *     own run.task message, and that refusal stays the one a cron entry gets.)
+ *   - run.resume: true on any kind: what a resumed session should do with a re-dispatched command is
+ *     UNDESIGNED -- "not yet covered", validateResumeFlag's own vocabulary, because it is a gap to
+ *     close and not a limit. Only `true` is refused; `false` is the documented default and refusing it
+ *     would refuse an operator for writing down the behaviour they already have.
+ *
+ * Everything else stays orthogonal on purpose -- replicas, image, packages, skillsDir, repository,
+ * github. Those gate the CONTAINER a job runs in, and a command job runs in the same container a flow
+ * job does.
+ *
+ * A COMMENT command trigger has no default flow, which leaves the receiver's `<phrase> <flow>` comment
+ * override with nothing to override. That token is made inert by the receiver's FILTER, not refused
+ * here: the override lives in adversarial comment text, which this file-shape validator never sees.
+ *
+ * `at` is the caller's message prefix, `onType` selects the cross-field set. Returns the command,
+ * undefined when absent, and the callers spread it conditionally: a flow trigger must not grow the key
+ * at all, so an unflagged file normalizes byte-identically to today's (deepEqual pins depend on it).
+ */
+function validateCommand(run, at, path, { onType }) {
+	const raw = run.command;
+	if (run.flow !== undefined && raw !== undefined) {
+		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 === undefined) return undefined;
+	if (!isNonEmptyString(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}`);
+	}
+	// The class is the RUNNER's (parseCommand, image/runner/src/config.mjs), DEL included: the two
+	// must refuse identically, or a value that loads here refuses in-container with the budget
+	// slot already burned -- the drift INT-TRIGGERS-FILE-CONTRACT promises cannot happen.
+	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 !== undefined) {
+		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 !== undefined) {
+		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;
+}
+
 /**
  * Validate an `{any, all, none}` label predicate. Selectors are validated as arrays of non-empty strings
  * BEFORE the positive-selector count, because `.length` is truthy on a string too -- a string selector
@@ -553,8 +639,10 @@ 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 (!isNonEmptyString(run.flow)) {
-		throw configError(`${at}: label trigger run.flow must be a non-empty string: ${path}`);
+	// First among the run checks, before the flow-required check -- validateCommand says why.
+	const command = validateCommand(run, at, path, { onType: "label" });
+	if (command === undefined && !isNonEmptyString(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);
@@ -565,7 +653,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 !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
 	};
 }
 
@@ -574,8 +662,12 @@ function normalizeComment(on, run, index, path, state) {
 	if (!isNonEmptyString(on.phrase)) {
 		throw configError(`${at}: comment trigger on.phrase must be a non-empty string: ${path}`);
 	}
-	if (!isNonEmptyString(run.flow)) {
-		throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string: ${path}`);
+	// First among the run checks, before the flow-required check -- validateCommand says why. A command
+	// trigger has NO default flow for the `<phrase> <flow>` comment override to replace; making that
+	// token inert is the receiver filter's job, not a shape this validator can see.
+	const command = validateCommand(run, at, path, { onType: "comment" });
+	if (command === undefined && !isNonEmptyString(run.flow)) {
+		throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string (or use run.command): ${path}`);
 	}
 	// At most one comment trigger PER FORGE. The cap exists because the receiver holds one comment rule
 	// per forge and a second would be silently unreachable -- so it is a cap on ambiguity, not on count,
@@ -593,7 +685,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 !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
 	};
 }
 
@@ -634,8 +726,10 @@ 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 (!isNonEmptyString(run.flow)) {
-		throw configError(`${at}: pull_request trigger run.flow must be a non-empty string: ${path}`);
+	// First among the run checks, before the flow-required check -- validateCommand says why.
+	const command = validateCommand(run, at, path, { onType: "pull_request" });
+	if (command === undefined && !isNonEmptyString(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);
@@ -655,7 +749,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 !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }) },
 	};
 }