@edgehero/pi-dispatch 0.3.0 → 1.1.0

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

@@ -8,7 +8,10 @@
  * pi's package resolver treats any spec that is not `npm:`/`git:`/a URL as a LOCAL path: it resolves the
  * directory in place -- no install, no network, no writes -- and a `pi` manifest there contributes
  * extensions, skills, prompts and themes. That is precisely what lets a job container load them with
- * network egress denied, which is the whole point of staging at all.
+ * NO JOB-TIME INSTALL, which is the whole point of staging at all. This said "with network egress denied"
+ * until issue #202, and that was the third instance of one claim corrected in the spec and left standing in
+ * its twin: nothing denied egress when it was written, and what staging plus PI_OFFLINE=1 actually buys is
+ * that no install happens, which is true whatever the egress policy is.
  *
  * Versions are EXACT, never a range (CONST-PI-VERSION-PINNED): a floating range turns a silent upstream
  * minor into every queued job becoming a no-op with NO signal -- the queue still reports success, the
@@ -24,8 +27,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 +272,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,15 +190,28 @@ 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
 			// to interpolate, and they are what makes this job's branch differ from its sibling's. This is the
-			// SHARED forge preparer, so the gitlab/forgejo/azure builders receive the two keys and destructure
-			// 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 }),
+			// SHARED forge preparer, and since #187 all four builders READ the two keys rather than destructuring
+			// them away: every forge mints `pi/issue-<n>-r<i>` through the same issueBranch.
+			// `review` rides beside `comment` and IS still destructured away by the gitlab/forgejo/azure builders
+			// -- harmless, and always undefined, because reviews remain github-only. That asymmetry is why both are
+			// spelled out: one of these keys crossed the forge boundary and one did not, and a reader who assumes
+			// they move together will widen the wrong one.
+			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

@@ -41,6 +41,9 @@ export async function runJob(job, deps) {
 		// this job names is on this host (image-preflight.mjs). Default admits everything, so a wiring that
 		// omits it behaves exactly as before -- the container's own failure stays the backstop.
 		imagePreflight = async () => ({ ok: true }),
+		// REQ-EGRESS-ALLOWLIST. Default admits everything, so a wiring that omits it behaves exactly as a
+		// deployment with no egress policy does -- which is also what the real factory returns when unarmed.
+		egressPreflight = async () => ({ ok: true }),
 		// (session, { piVersion }) => { promoted, reason, bytes }. Promotes this job's transcript back into
 		// the store, on a COMPLETED exit only. Never throws. The default is a no-op so a wiring that omits
 		// it behaves exactly as before -- no store, no promotion, no session in the record.
@@ -159,6 +162,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
@@ -167,6 +187,46 @@ export async function runJob(job, deps) {
 			throw new InfraRetry("docker unavailable, image preflight could not run", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
 		}
 
+		// REQ-EGRESS-ALLOWLIST. The egress policy this deployment claims must be able to serve this job
+		// BEFORE the job costs anything. It is one `docker inspect` when the policy is armed and ZERO spawns
+		// when it is not, so a deployment without one pays nothing at all.
+		//
+		// PLACEMENT, and it is the same ladder the image preflight sits at the top of. A missing proxy blocks
+		// EVERY job of EVERY kind on this host -- like a missing image -- and unlike a missing image it blocks
+		// them EXPENSIVELY: the container starts, the provider is unreachable, the runner exits 1, exit 1 is
+		// the retryable class, `attempts: 2`, and `releaseBudget` refunds only `container-never-started` --
+		// this container started. So each such job spends two job-count slots and buys nothing with either,
+		// and a cron-driven deployment empties its daily cap before anyone reads the first failure. That cost
+		// is what makes this a pre-spend gate rather than a doc: measured at three provider attempts,
+		// `Request timed out.`, exit 1, ~40 seconds, zero tokens (docs/egress.md).
+		//
+		// A RETURN, never a throw (CONST-RETRY-INFRA-ONLY): retrying never makes an absent proxy appear.
+		const egress = await egressPreflight(job);
+		if (egress.proxyMissing || egress.proxyStopped) {
+			const proxy = egress.proxyMissing ?? egress.proxyStopped;
+			const state = egress.proxyMissing ? "is not on this host" : "is not running";
+			await comment(job, `Refused: this deployment runs jobs behind an egress policy and its allowlist proxy "${proxy}" ${state}, so the job could not reach the provider and would burn its budget slot proving it. Start it with \`docker compose -f deploy/docker-compose.yml --profile egress up -d\`, or set PI_EGRESS=0 to run without an egress policy. Not run.`);
+			// The proxy's NAME is operator-authored deployment config, never payload -- the same PII class as
+			// the image ref on the refusal above.
+			log(egress.proxyMissing ? "refused_egress_proxy_missing" : "refused_egress_proxy_stopped", { proxy });
+			return {
+				outcome: "policy",
+				reason: egress.proxyMissing ? "egress-proxy-missing" : "egress-proxy-stopped",
+				exitCode: null,
+				turns: null,
+				tokens: null,
+				provider: job.provider ?? null,
+				model: job.model ?? null,
+				budgetReserved: false, // refused before reserveBudget, so no job-count slot was consumed
+			};
+		}
+		if (egress.unavailable) {
+			// The daemon did not answer, so this is indeterminate rather than a refusal -- the same
+			// determinate/indeterminate split the image preflight draws one gate up, and thrown for the same
+			// reason. Pre-reserve, so the refund below is a no-op and still honest if this gate ever moves.
+			throw new InfraRetry("docker unavailable, egress preflight could not run", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
+		}
+
 		// REQ-RESUMABLE-SESSION's one fail-CLOSED case. Everything else in that feature fails OPEN and
 		// NAMES itself -- absent, expired, too-large, unparseable, locked, promote-failed -- because a cold
 		// start is a correct run. This one cannot be: with no `sessionsDir`, resolveSession returns null

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

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { buildDockerRunArgs, CONTAINER_SESSION_FILE } from "./docker-run.mjs";
+import { createJobNetwork, networkNameFor, removeJobNetwork } from "./egress.mjs";
 import { buildContainerEnv } from "./env-allowlist.mjs";
 import { resolveJobImage } from "./image-preflight.mjs";
 import { InfraRetry } from "./processor.mjs";
@@ -40,6 +41,8 @@ export function makeRunContainer({
 	forwardEnv = [],
 	authFromPi = false, // fall back to ~/.pi/agent/auth.json for the provider key when the env has none
 	forgeHosts = {}, // per-forge self-hosted instance URLs, so a forge CLI in the container talks to the right one
+	egress = false, // REQ-EGRESS-ALLOWLIST: put this job on its own --internal network behind the allowlist proxy
+	egressProxy, // the proxy component attached to that network; undefined = egress.mjs's default name
 }) {
 	// async so a synchronous throw (e.g. buildContainerEnv on an unconfigured provider) surfaces as
 	// a rejection, uniformly awaitable by the processor and by tests.
@@ -59,6 +62,8 @@ export function makeRunContainer({
 			forgeKind: job?.kind,
 			forgeHosts,
 			hostEnv,
+			egress, // REQ-EGRESS-ALLOWLIST: emits HTTPS_PROXY/HTTP_PROXY/NO_PROXY/NODE_USE_ENV_PROXY, or nothing
+			egressProxy,
 			allowGlobalExtensions, // REQ-GLOBAL-PI-OVERLAY: false emits the explicit PI_GLOBAL_ALLOW_EXTENSIONS=0 opt-out
 			// REQ-GLOBAL-PI-OVERLAY: the per-job value comes off `job` (like maxTurns), the staged set off
 			// the closure (like allowGlobalExtensions) -- so a trigger can withhold what the operator staged.
@@ -74,9 +79,20 @@ 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
 		});
 
+		// `-net` on this container's own name (egress.mjs). null when no policy is armed, and docker-run's
+		// guard then omits the flag entirely, so the argv is byte-identical to one built before this feature.
+		const network = egress ? networkNameFor(name) : null;
+
 		const args = buildDockerRunArgs({
 			// Same split as packagePaths above: the per-job value off `job`, the deployment value off the closure,
 			// so a trigger can name its own toolchain (INT-TRIGGERS-FILE-CONTRACT). Resolved through the SAME
@@ -92,13 +108,26 @@ export function makeRunContainer({
 			sessionDir: prepared.session?.hostDir,
 			globalPiDir, // undefined/null -> docker-run's guard skips the /opt/pi-global mount
 			name,
+			network, // REQ-EGRESS-ALLOWLIST: null when no policy is armed, and the flag is then absent
 		});
 
+		// REQ-EGRESS-ALLOWLIST. This job's own --internal network, created here rather than at boot because
+		// it holds exactly two endpoints -- this container and the proxy -- and that is what makes job-to-job
+		// traffic structurally impossible rather than merely discouraged. A shared network could not do it:
+		// `enable_icc=false` would block job-to-job AND job-to-proxy, since ICC governs every container pair
+		// on the bridge and the proxy is a container.
+		//
+		// A failure to build it is INFRA, not policy: nothing has been spent, a retry may well succeed, and
+		// `container-never-started` is literally true, so the reservation is given back (processor.mjs).
+		if (network && !(await createJobNetwork(spawnFn, { network, proxy: egressProxy }))) {
+			throw new InfraRetry("container-never-started", { reason: "container-never-started" });
+		}
+
 		// Host-side per-job log sink, teed off `onOutput`. `name` is `pi-job-<jobId>`; the sink
 		// sanitizes internally. No container mount, no env var -- the sink lives on this side only.
 		const sink = openJobLog(name);
 
-		return await new Promise((resolve, reject) => {
+		const run = new Promise((resolve, reject) => {
 			const child = spawnFn("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
 			// A throwing sink.write is swallowed so a misbehaving sink cannot break the tee or hang the run.
 			const tee = (chunk) => {
@@ -134,5 +163,14 @@ export function makeRunContainer({
 				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage } : { code: code ?? 1, aborted: false, turns, tokens, session, usage });
 			});
 		});
+
+		// The network outlives the container by exactly this `finally`. Best-effort and never throwing: the
+		// container has already exited, its code is the job's answer, and a teardown fault must not rewrite
+		// that answer. What a failure leaves behind is a memberless network, which the boot reaper sweeps.
+		try {
+			return await run;
+		} finally {
+			if (network) await removeJobNetwork(spawnFn, { network, proxy: egressProxy });
+		}
 	};
 }

package/src/run-history.mjs

@@ -246,7 +246,7 @@ function rebuildUsage(u) {
  * path embeds the operator's OS account name.
  *
  * `reason` is a fixed enum passthrough (worker-abort | over-budget | unprotected-branch |
- * runner-policy | job-image-missing | ...), never free-form or payload text. `exitCode`, `turns`, and `budgetReserved`
+ * runner-policy | job-image-missing | egress-proxy-missing | ...), never free-form or payload text. `exitCode`, `turns`, and `budgetReserved`
  * default to `null` when the outcome does not carry them, so the record shape is stable whether or not
  * the source reports those fields.
  */

package/src/sandbox-cli.mjs

@@ -1,6 +1,8 @@
+import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import { loadConfig } from "./config.mjs";
 import { sanitizeJobId } from "./run-history.mjs";
+import { createJobNetwork, egressEnv, networkNameFor, removeJobNetwork } from "./egress.mjs";
 import { buildSandboxRunArgs, launchSandbox, listRunningSandboxes, parsePublish, resolveSandbox, sandboxContainerName } from "./sandbox.mjs";
 import { listSandboxes, pinSandbox } from "./sandbox-store.mjs";
 
@@ -22,6 +24,9 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 		isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY),
 		running = listRunningSandboxes,
 		launch = launchSandbox,
+		// The docker spawn used for this session's egress network, seamed like `launch` so the tests never
+		// touch a daemon. Not used when PI_EGRESS=0.
+		spawnNetwork = spawn,
 		now = () => Date.now(),
 	} = deps;
 
@@ -89,6 +94,10 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 		else err(`warning: could not pin ${jobId}: ${pinned.reason}\n`);
 	}
 
+	// REQ-EGRESS-ALLOWLIST: this session's own network, exactly like a job's, named off its own container
+	// so the reaper's `pi-job-` filter never touches it -- a worker restart must not tear the network out
+	// from under a shell an operator is sitting in.
+	const network = config.egress ? networkNameFor(resolved.name) : null;
 	const args = buildSandboxRunArgs({
 		image: resolved.manifest.image,
 		name: resolved.name,
@@ -97,15 +106,27 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 		publish,
 		term: env.TERM,
 		idleSeconds: config.sandboxIdleMinutes * 60,
+		network,
+		egressEnv: egressEnv({ proxy: config.egressProxy, armed: config.egress }),
 	});
 
 	out(`opening ${resolved.name} — image ${resolved.manifest.image}, workspace ${resolved.manifest.workspace}\n`);
 	out("no credentials are set in this container. exit the shell to dispose of it.\n");
 	if (publish.length > 0) out(`published: ${publish.filter((f) => f !== "-p").join(", ")}\n`);
 
-	const { code, error } = await launch({ args });
-	if (error) return fail(err, `could not start docker: ${error.message}`);
-	return code ?? 0;
+	// No pre-spend gate here, deliberately: that is a MONEY gate and a sandbox spends nothing. A missing
+	// proxy fails at `docker run` with docker's own message, in front of an operator at a terminal, which
+	// is the one place a late failure is cheap.
+	if (network && !(await createJobNetwork(spawnNetwork, { network, proxy: config.egressProxy }))) {
+		return fail(err, `could not create the egress network ${network} -- is the proxy running? \`docker compose -f deploy/docker-compose.yml --profile egress up -d\``);
+	}
+	try {
+		const { code, error } = await launch({ args });
+		if (error) return fail(err, `could not start docker: ${error.message}`);
+		return code ?? 0;
+	} finally {
+		if (network) await removeJobNetwork(spawnNetwork, { network, proxy: config.egressProxy });
+	}
 }
 
 /**

package/src/sandbox.mjs

@@ -79,8 +79,10 @@ function inPortRange(n) {
  * @param publish      already-parsed `-p` flags
  * @param term         the host's TERM, so the shell renders
  * @param idleSeconds  bash's own TMOUT; 0 omits it
+ * @param network      this session's own egress network (REQ-EGRESS-ALLOWLIST); null = the default bridge
+ * @param egressEnv    the proxy variables that go with it, or {} when no policy is armed
  */
-export function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], term, idleSeconds = 0 }) {
+export function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], term, idleSeconds = 0, network = null, egressEnv: proxyEnv = {} }) {
 	return buildDockerRunArgs({
 		image,
 		name,
@@ -89,9 +91,20 @@ export function buildSandboxRunArgs({ image, name, workspace, jobDir, publish =
 		// The ONLY two variables, and neither is a credential. TERM so the shell renders; TMOUT so a
 		// forgotten session closes itself. `buildDockerRunArgs` skips undefined, so an unset TERM or a
 		// disabled idle timeout emits nothing rather than an empty string.
+		// A sandbox joins the SAME kind of network a job did, by the same builder, so the boundary cannot
+		// land on job containers and miss this one. Leaving sandboxes on the default bridge was the tempting
+		// alternative and it is the wrong one: it reads as a convenience (install a missing dependency while
+		// debugging) and it is a WIDER reach than the run the sandbox exists to reproduce. A shell that can
+		// go where the run could not is not reproducing the run. Nothing an operator wants is lost, because
+		// the forge and the registry are on the allowlist a job needed anyway.
+		network,
 		env: {
 			TERM: term || undefined,
 			TMOUT: idleSeconds > 0 ? String(idleSeconds) : undefined,
+			// Still NO CREDENTIALS, and that clause is untouched: a proxy URL is not a credential, and
+			// buildContainerEnv is still not reused here. The env is two variables about the terminal and,
+			// when a policy is armed, three about the network.
+			...proxyEnv,
 		},
 		// Ahead of the env and the mounts, and well ahead of the image, which buildDockerRunArgs keeps as
 		// the final positional. `--entrypoint` also clears the image's CMD; this repo's Dockerfile sets

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 } };