feat(runner): dispatch a run.command extension command headlessly (#189)

The runner half of issue #189 Gap 2 (the trigger field itself follows as
the producer half). A trigger will be able to name a registered pi
extension command instead of a flow; this PR ships the dispatch protocol
the pinned artifact already supports.

The prompt for a command job is rebuilt from PI_COMMAND as /<command>,
never read from prompt.md: pi's dispatch grammar fires only when the
ENTIRE text starts with a slash, parses the name to the first space and
hands everything after it to the handler verbatim, so there is no such
thing as a command line at the top of a larger prompt, and one
in-container authority means a worker bug cannot make the classification
misread a flow job. prompt.md stays the byte-identical human record.

Before prompting, the runner verifies the name via
session.extensionRunner.getCommand() and refuses an unregistered one as
command-unregistered (exit 2, pre-spend): an unregistered /name is not an
error to pi, it falls through template expansion into a paid model call,
or into a same-named prompt template if one is staged. A handler throw is
SWALLOWED by pi (prompt() resolves cleanly) and surfaces only on the
public extensionRunner.onError channel; the runner subscribes and
classifies it command-error, exit 1 retryable by explicit choice: pi
hands us a message string, transient-vs-deterministic is undecidable, and
the accepted cost (a deterministic extension bug retries until attempts
run out) is recorded on the new DES entry. A clean headless return is
command-completed, exit 0; before that reason existed the same shape was
the retryable no-terminal-message, and the queue re-billed a success. A
handler that drove the model keeps its terminal's ordinary verdict, and
budget aborts keep first position.

The image's capabilities label gains commands, with a verify-image.sh
case asserting the claim against the baked runner source; the worker-side
preflight gate lands with the producer half. A keyless real-session
contract test pins all four dispatch facts against the pinned artifact.

Specs: INT-RUNNER-EXIT-CODE-PROTOCOL AMENDED (three reasons under
existing codes, never a new outcome), INT-CONTAINER-JOB-INPUTS AMENDED
(PI_COMMAND), NEW DES-COMMAND-ENTRY-POINT. UNCHANGED, checked:
INT-TRIGGERS-FILE-CONTRACT, DES-FLOW-RESOLUTION-TWO-ADVISORY-LAYERS,
DES-PER-TRIGGER-JOB-IMAGE, DES-TRIGGER-INSTRUCTION-IN-THE-ENVELOPE.

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

Author: edgehero

image/Dockerfile

@@ -224,7 +224,14 @@ LABEL dev.pi-dispatch.forges="github,gitlab,forgejo"
 # replica job. Both follow one rule -- an image that declares nothing gets no benefit of the doubt about what
 # it contains -- and both leave an UNFLAGGED job reading no label at all. `verify-image.sh` asserts this list
 # against the baked guardrails, so it cannot lie any more than `forges` can.
-LABEL dev.pi-dispatch.capabilities="replicas"
+# `commands` (issue #189) tells the worker this runner understands PI_COMMAND: it dispatches the
+# registered extension command, refuses an unregistered one pre-spend, and classifies a headless
+# command run as command-completed. An older runner handed PI_COMMAND would ignore the variable, read
+# prompt.md, and either feed "/name args" to the model as prose or exit 1 no-terminal-message and be
+# retried as infra -- paid retries of a job that can never classify. The label is how the worker
+# refuses that pairing pre-spend (image-preflight.mjs), which is what makes shipping the runner ahead
+# of the trigger field safe in both directions.
+LABEL dev.pi-dispatch.capabilities="replicas,commands"
 
 USER pi
 WORKDIR /workspace

image/runner/run-job.mjs

@@ -6,7 +6,7 @@ import {
 	ModelRegistry,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { assertPackagePathsExist, assertSessionMountReady, enforceOfflineMode, parseRunnerEnv } from "./src/config.mjs";
+import { assertPackagePathsExist, assertSessionMountReady, commandName, enforceOfflineMode, parseRunnerEnv } from "./src/config.mjs";
 import { buildLoadedResourceLoader, GLOBAL_PI_DIR, JOB_PI_DIR, TRIGGER_SKILLS_DIR, WORKSPACE } from "./src/loader.mjs";
 import {
 	captureTerminal,
@@ -65,7 +65,14 @@ async function main() {
 	// can influence. Idempotent and only ever tightening. INT-SDK-SESSION-OPTIONS.
 	enforceOfflineMode(process.env);
 
-	const prompt = readPrompt(PROMPT_PATH);
+	// A command job's prompt is rebuilt from PI_COMMAND rather than read from disk: one in-container
+	// authority, so a worker bug that wrote a prompt.md disagreeing with the env var cannot make the
+	// classification below (command-completed on a promptless return) misread a flow job. pi's
+	// dispatch grammar demands it anyway -- a command dispatches only when the ENTIRE prompt starts
+	// with "/", and everything after the first space becomes the handler's args, so there is no such
+	// thing as a command line "at the top of" a larger prompt. prompt.md still carries the same bytes
+	// as the human record of what ran (INT-CONTAINER-JOB-INPUTS).
+	const prompt = cfg.command ? `/${cfg.command}` : readPrompt(PROMPT_PATH);
 
 	const agentDir = getAgentDir();
 
@@ -226,6 +233,36 @@ async function main() {
 	// leaving the first call of an extension-provided model unmetered.
 	usageMeter.arm();
 
+	// A command job dispatches BEFORE any spend, so verify the command is actually registered first
+	// (issue #189). pi's fallthrough is the hazard being closed: an unregistered "/name" is not an
+	// error to session.prompt() -- it falls through to prompt-template expansion and then to the
+	// MODEL as literal text, a full paid turn for a config typo, or (with a same-named template
+	// staged) whatever that template does. Extensions have registered by createAgentSession time, so
+	// getCommand() is authoritative here. commandName() is pi's own first-space parse, imported so
+	// the verification reads the string exactly as dispatch will.
+	if (cfg.command) {
+		const name = commandName(cfg.command);
+		if (!session.extensionRunner.getCommand(name)) {
+			throw configError(
+				`run.command names "${name}" but no loaded extension registers it -- stage the package that ships it, or fix the trigger`,
+				"command-unregistered",
+			);
+		}
+		log("command_dispatch", { command: name });
+	}
+
+	// A throwing command handler is SWALLOWED by pi -- emitError, handled=true, prompt() resolves
+	// cleanly -- and the extension runner's error channel is the only place it surfaces at the pin
+	// (never the session event bus). Subscribe before prompt so decideExit can tell a failed command
+	// from a completed one; scoped to command jobs because that is the only path whose success would
+	// otherwise be decided by an event that cannot arrive.
+	let commandFailed = false;
+	const unsubscribeCommandErrors = cfg.command
+		? session.extensionRunner.onError((extensionError) => {
+				if (extensionError?.event === "command") commandFailed = true;
+			})
+		: null;
+
 	// prompt() returns Promise<void>, so this subscription is the ONLY channel through which the
 	// outcome arrives. captureTerminal handles both event shapes (agent_end carries messages[],
 	// turn_end carries message).
@@ -258,6 +295,7 @@ async function main() {
 		// the session it was metering is exactly the kind of thing that becomes one.
 		usageMeter.uninstall();
 		unsubscribeTerminal();
+		unsubscribeCommandErrors?.();
 		// Runs the cleanup callbacks providers register via registerSessionResourceCleanup. Every
 		// official SDK example disposes; skipping it can leak a provider transport and hang the
 		// container until the 30-minute timeout -- a completed job turned into a timeout failure.
@@ -271,6 +309,8 @@ async function main() {
 		// same reason:"token_budget" / exit 2.
 		tokenAborted: usageMeter.ok ? meter.state.breached : tokenBudget.state.aborted,
 		terminal,
+		// Null for every prompt job, so their decision tree is byte-identical to before run.command.
+		command: cfg.command ? { failed: commandFailed } : null,
 	});
 	// `metered: true` on the process-wide snapshot is what tells the daily token counter that this
 	// total includes every in-process session, not just the root's turns.

image/runner/src/config.mjs

@@ -37,6 +37,10 @@ export function parseRunnerEnv(env) {
 		// compare it against the loaded skill names. `null` when the job carries no flow (a bare
 		// run.task cron job), which skips the check entirely.
 		flow: parseFlowName(env, "PI_FLOW"),
+		// INT-CONTAINER-JOB-INPUTS (issue #189): the trigger's run.command -- the registered extension
+		// command this job dispatches instead of a prompt. `null` (the overwhelmingly common state)
+		// means a prompt job, byte-identical to every job before the feature.
+		command: parseCommand(env, "PI_COMMAND"),
 		retry: {
 			maxRetries: parsePositiveInt(env, "PI_RETRY_MAX", 2),
 			baseDelayMs: parsePositiveInt(env, "PI_RETRY_BASE_MS", 2000),
@@ -155,6 +159,47 @@ function parseFlowName(env, name) {
 	return raw;
 }
 
+/**
+ * Parse the command a run.command trigger dispatches (issue #189). Unset or empty is `null` -- a
+ * prompt job, the default. Unlike PI_FLOW this one IS validated, strictly, because the value is not
+ * merely compared: run-job rebuilds the prompt as `/<value>` and hands it to session.prompt(), whose
+ * dispatch grammar at the pin reads the command NAME up to the first space and passes EVERYTHING
+ * after it -- including a newline and whatever follows -- as args. So:
+ *   - a leading "/" is refused: the runner adds the slash, and accepting one here would make
+ *     "//name" -- a prompt, silently, since no command named "/name" can register;
+ *   - surrounding whitespace is refused rather than trimmed: a trailing space changes the args a
+ *     handler receives, and normalizing here would make the container disagree with the reviewed
+ *     file about what runs;
+ *   - control characters are refused outright: a newline would smuggle a second line into what the
+ *     operator reviewed as one command line.
+ * All deterministic misconfigurations: configError, exit 2, never retried.
+ */
+function parseCommand(env, name) {
+	const raw = env[name];
+	if (raw === undefined || raw === "") return null;
+	if (raw.startsWith("/")) {
+		throw configError(`invalid ${name}: ${JSON.stringify(raw)} (no leading "/" -- the runner adds it)`);
+	}
+	if (raw !== raw.trim()) {
+		throw configError(`invalid ${name}: ${JSON.stringify(raw)} (no surrounding whitespace)`);
+	}
+	// Every C0 control plus DEL, written as escapes so the source itself carries no control byte.
+	if (/[\u0000-\u001f\u007f]/.test(raw)) {
+		throw configError(`invalid ${name}: contains a control character (a newline or tab would change what dispatches)`);
+	}
+	return raw;
+}
+
+/**
+ * The command NAME inside a run.command string -- pi's own parse, verbatim (text to the first space,
+ * dist/core/agent-session.js _tryExecuteExtensionCommand). Exported so run-job's pre-prompt
+ * getCommand() verification and the tests read the string the same way pi will.
+ */
+export function commandName(command) {
+	const spaceIndex = command.indexOf(" ");
+	return spaceIndex === -1 ? command : command.slice(0, spaceIndex);
+}
+
 /**
  * Parse the persisted-session path (INT-SESSION-STORE-CONTRACT).
  *

image/runner/src/outcome.mjs

@@ -17,10 +17,13 @@ export const STOP_REASONS = ["stop", "length", "toolUse", "error", "aborted"];
  * retryable. Tagging the error with its exit code is more robust than pattern-matching the
  * message: classifyThrow honours the tag before it ever consults pi's error vocabulary.
  */
-export function configError(message) {
+export function configError(message, reason = "config") {
 	const error = new Error(message);
 	error.piDispatchExit = EXIT_POLICY;
-	error.piDispatchReason = "config";
+	// The optional reason (issue #189) rides the exit log line through classifyThrow, so a distinct
+	// deterministic refusal -- an unregistered run.command -- stays greppable without a new exit code.
+	// The default keeps every pre-existing caller byte-identical.
+	error.piDispatchReason = reason;
 	return error;
 }
 
@@ -82,13 +85,31 @@ export function captureTerminal(previous, event) {
  * and names WHICH cap fired. The turn budget is checked before the token budget only for a stable
  * order; in practice one abort ends the run, so at most one flag is set.
  */
-export function decideExit({ budgetAborted, budgetTurns, tokenAborted, terminal }) {
+export function decideExit({ budgetAborted, budgetTurns, tokenAborted, terminal, command = null }) {
 	if (budgetAborted) {
 		return { code: EXIT_POLICY, reason: "turn_budget", turns: budgetTurns };
 	}
 	if (tokenAborted) {
 		return { code: EXIT_POLICY, reason: "token_budget" };
 	}
+	// A command job (issue #189, run.command): session.prompt("/name args") dispatches a registered
+	// extension command and returns with NO assistant message, so the no-terminal branch below would
+	// classify a clean headless run as infra and pay to retry a success. Three rules, in order:
+	//   - a handler that THREW wins over everything it produced: pi swallows the throw (the runner
+	//     observes it via extensionRunner.onError, the only channel pi offers at the pin) and a
+	//     stop-reason that claimed success would be the swallow reaching the exit code. `command-error`
+	//     is EXIT_INFRA -- retryable, by explicit choice: pi hands us only a message string, so
+	//     transient-vs-deterministic is undecidable, and the accepted cost is that a deterministic
+	//     extension bug retries until the queue's attempts run out (DES-COMMAND-ENTRY-POINT).
+	//   - a handler that drove the model (sendUserMessage/waitForIdle) produced a terminal message,
+	//     and its verdict is real -- a provider 429 inside a handler-driven turn must stay retryable.
+	//   - otherwise the command ran headlessly to completion: exit 0, named `command-completed`.
+	// Budget aborts stay FIRST, above: a handler-driven fanout is bounded by both budgets.
+	if (command) {
+		if (command.failed) return { code: EXIT_INFRA, reason: "command-error" };
+		if (terminal) return classifyStopReason(terminal);
+		return { code: EXIT_COMPLETED, reason: "command-completed" };
+	}
 	return classifyStopReason(terminal);
 }
 

image/runner/test/compose.test.mjs

@@ -119,3 +119,27 @@ test("run-job.mjs verifies the flow against the LOADED skill set, unconditionall
 		"the flow check must sit at the pre-spend moment",
 	);
 });
+
+test("run-job.mjs wires the command path: env-authoritative prompt, pre-spend verification, observed throws", () => {
+	// Same source-guard tactic as the pins above. Five facts, each of which fails silently if unwired:
+	// (1) the prompt is rebuilt from PI_COMMAND, never read from prompt.md, for a command job -- one
+	//     in-container authority, and pi's grammar demands the whole text start with "/";
+	// (2) the command is verified against extensionRunner.getCommand BEFORE session.prompt -- an
+	//     unregistered "/name" is not an error to pi, it falls through toward a paid model call;
+	// (3) the verification failure is the tagged command-unregistered refusal (exit 2, pre-spend);
+	// (4) a swallowed handler throw is observed via extensionRunner.onError before the prompt;
+	// (5) decideExit receives the command outcome, null for every prompt job.
+	const src = readFileSync(new URL("../run-job.mjs", import.meta.url), "utf8");
+	assert.match(src, /cfg\.command \? `\/\$\{cfg\.command\}` : readPrompt\(/, "the prompt must be env-authoritative for command jobs");
+	assert.ok(
+		src.indexOf("extensionRunner.getCommand") < src.indexOf("await session.prompt("),
+		"getCommand verification must run before the prompt is sent",
+	);
+	assert.match(src, /"command-unregistered"/, "the refusal must carry its own greppable reason");
+	assert.ok(
+		src.indexOf("extensionRunner.onError") < src.indexOf("await session.prompt("),
+		"the error-channel subscription must exist before the prompt, or a fast throw is missed",
+	);
+	assert.match(src, /command: cfg\.command \? \{ failed: commandFailed \} : null/, "decideExit must receive the command outcome");
+	assert.match(src, /log\("command_dispatch", \{ command: name \}\)/, "the dispatch line carries the NAME only, never args");
+});

image/runner/test/config.test.mjs

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { assertPackagePathsExist, enforceOfflineMode, parseRunnerEnv } from "../src/config.mjs";
+import { assertPackagePathsExist, commandName, enforceOfflineMode, parseRunnerEnv } from "../src/config.mjs";
 import { EXIT_POLICY } from "../src/outcome.mjs";
 
 const base = { PI_PROVIDER: "anthropic", PI_MODEL: "claude-x", PI_MAX_TURNS: "20" };
@@ -223,3 +223,31 @@ test("PI_FLOW parses to the exact string, with no charset opinion", () => {
 	// yesterday's jobs on an image upgrade. The comparison simply misses, and the miss is the report.
 	assert.equal(parseRunnerEnv({ ...base, PI_FLOW: "Not A Skill Name" }).flow, "Not A Skill Name");
 });
+
+test("PI_COMMAND is optional: unset or empty is null, so a prompt job is byte-identical to today", () => {
+	assert.equal(parseRunnerEnv(base).command, null);
+	assert.equal(parseRunnerEnv({ ...base, PI_COMMAND: "" }).command, null);
+});
+
+test("PI_COMMAND parses a bare name and a name with args, verbatim", () => {
+	assert.equal(parseRunnerEnv({ ...base, PI_COMMAND: "wf" }).command, "wf");
+	assert.equal(parseRunnerEnv({ ...base, PI_COMMAND: "wf run nightly" }).command, "wf run nightly");
+});
+
+test("PI_COMMAND refuses a leading slash, surrounding whitespace, and control characters -- exit 2", () => {
+	// Dispatch grammar at the pin: the runner prepends "/", the name runs to the first space, and
+	// EVERYTHING after -- a newline included -- becomes handler args. Each refusal below is a value
+	// that would silently change what dispatches rather than fail.
+	for (const bad of ["/wf", " wf", "wf ", "wf run\nnightly", "wf\trun", "wf \u001b[1m"]) {
+		assert.throws(
+			() => parseRunnerEnv({ ...base, PI_COMMAND: bad }),
+			(e) => e.piDispatchExit === EXIT_POLICY,
+			`PI_COMMAND=${JSON.stringify(bad)} must refuse pre-spend, not silently reshape the dispatch`,
+		);
+	}
+});
+
+test("commandName reads the string exactly as pi's dispatch will: text to the first space", () => {
+	assert.equal(commandName("wf"), "wf");
+	assert.equal(commandName("wf run nightly"), "wf");
+});