@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/opener-terminal.mjs

@@ -0,0 +1,128 @@
+/** Terminal launchers start only the approval helper. SSH and the sandbox wait for its empty Enter. */
+import * as nodeFs from "node:fs";
+import { spawn as nodeSpawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { join, delimiter, win32 } from "node:path";
+import { quoteSandboxArg } from "./sandbox-hosts.mjs";
+
+export function findTerminal(env, { fs = nodeFs } = {}) {
+	// env-internal PATH: search only absolute directories for the OS default terminal launcher, never for a sandbox command.
+	for (const bin of ["xdg-terminal-exec", "x-terminal-emulator"]) for (const dir of (env.PATH ?? "/usr/local/bin:/usr/bin:/bin").split(delimiter)) {
+		if (!dir.startsWith("/")) continue;
+		const path = join(dir, bin);
+		try { fs.accessSync(path, fs.constants.X_OK); return { bin: path, args: bin === "x-terminal-emulator" ? ["-e"] : [] }; } catch {}
+	}
+	return null;
+}
+export function windowsArgument(value) {
+	return `"${String(value).replace(/(\\*)"/g, "$1$1\\\"").replace(/(\\+)$/, "$1$1")}"`;
+}
+const psString = (value) => `'${String(value).replaceAll("'", "''")}'`;
+// Redirected dispatcher handles do not create an interactive terminal. The new console owns fresh
+// keyboard/screen buffers instead of inheriting the dispatcher's pipes or NUL input.
+const WINDOWS_CONSOLE_SOURCE = `using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+public static class PiDispatchConsole {
+	[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+	private struct STARTUPINFO {
+		public uint cb;
+		public string lpReserved, lpDesktop, lpTitle;
+		public uint dwX, dwY, dwXSize, dwYSize, dwXCountChars, dwYCountChars, dwFillAttribute, dwFlags;
+		public ushort wShowWindow, cbReserved2;
+		public IntPtr lpReserved2, hStdInput, hStdOutput, hStdError;
+	}
+	[StructLayout(LayoutKind.Sequential)]
+	private struct PROCESS_INFORMATION {
+		public IntPtr hProcess, hThread;
+		public uint dwProcessId, dwThreadId;
+	}
+	[DllImport("kernel32.dll", CharSet = CharSet.Unicode, ExactSpelling = true, SetLastError = true)]
+	[return: MarshalAs(UnmanagedType.Bool)]
+	private static extern bool CreateProcessW(string application, StringBuilder commandLine, IntPtr processAttributes, IntPtr threadAttributes, [MarshalAs(UnmanagedType.Bool)] bool inheritHandles, uint flags, IntPtr environment, string currentDirectory, ref STARTUPINFO startup, out PROCESS_INFORMATION process);
+	[DllImport("kernel32.dll", SetLastError = true)]
+	[return: MarshalAs(UnmanagedType.Bool)]
+	private static extern bool CloseHandle(IntPtr handle);
+	[DllImport("kernel32.dll", SetLastError = true)]
+	[return: MarshalAs(UnmanagedType.Bool)]
+	private static extern bool IsProcessInJob(IntPtr process, IntPtr job, [MarshalAs(UnmanagedType.Bool)] out bool result);
+	[DllImport("kernel32.dll", SetLastError = true)]
+	[return: MarshalAs(UnmanagedType.Bool)]
+	private static extern bool GetExitCodeProcess(IntPtr process, out uint exitCode);
+	[DllImport("kernel32.dll")]
+	private static extern IntPtr GetCurrentProcess();
+	public static string Start(string application, string commandLine) {
+		STARTUPINFO startup = new STARTUPINFO();
+		startup.cb = (uint)Marshal.SizeOf(typeof(STARTUPINFO));
+		startup.dwFlags = 0x00000001;
+		startup.wShowWindow = 1;
+		PROCESS_INFORMATION process;
+		if (!CreateProcessW(application, new StringBuilder(commandLine), IntPtr.Zero, IntPtr.Zero, false, 0x00000010, IntPtr.Zero, null, ref startup, out process)) throw new Win32Exception(Marshal.GetLastWin32Error());
+		try {
+			bool parentJob, childJob;
+			uint exitCode;
+			// The console already started. Optional observations must not turn that success into a refusal.
+			string parentState = IsProcessInJob(GetCurrentProcess(), IntPtr.Zero, out parentJob) ? parentJob.ToString() : "unknown:" + Marshal.GetLastWin32Error();
+			string childState = IsProcessInJob(process.hProcess, IntPtr.Zero, out childJob) ? childJob.ToString() : "unknown:" + Marshal.GetLastWin32Error();
+			string initialExit = GetExitCodeProcess(process.hProcess, out exitCode) ? exitCode.ToString() : "unknown:" + Marshal.GetLastWin32Error();
+			return "pid=" + process.dwProcessId + ";parentJob=" + parentState + ";childJob=" + childState + ";initialExit=" + initialExit;
+		} finally { CloseHandle(process.hThread); CloseHandle(process.hProcess); }
+	}
+}`;
+export function windowsPowerShellEnv(env) {
+	// env-internal PSModulePath: Windows PowerShell must derive its own module directories. A Node child of
+	// PowerShell 7 otherwise inherits incompatible modules ahead of the system's Start-Process implementation.
+	return Object.fromEntries(Object.entries(env).filter(([key]) => key.toLowerCase() !== "psmodulepath"));
+}
+export function terminalLaunch({ platform, nodePath, cliPath, url, directory, env, fs = nodeFs, terminal = findTerminal(env, { fs }) }) {
+	const args = [cliPath, "opener", "prompt", url];
+	if (platform === "linux") {
+		if (!terminal) throw new Error("no default terminal launcher was found; install xdg-terminal-exec or configure x-terminal-emulator, then use Copy until it is installed");
+		return { bin: terminal.bin, args: [...terminal.args, nodePath, ...args] };
+	}
+	if (platform === "darwin") {
+		// Opening a .command file delegates to the account's registered terminal application. The file is private,
+		// contains only a fixed helper invocation and removes itself after that helper ends.
+		fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+		const path = join(directory, `prompt-${randomBytes(12).toString("hex")}.command`);
+		fs.writeFileSync(path, `#!/bin/sh\n${[nodePath, ...args].map(quoteSandboxArg).join(" ")}\nresult=$?\nrm -f -- "$0"\nexit "$result"\n`, { mode: 0o700, flag: "wx" });
+		return { bin: "/usr/bin/open", args: [path] };
+	}
+	if (platform === "win32") {
+		// env-internal SystemRoot: Windows' own system directory, not a variable forwarded to a container.
+		// ShellExecute expands percent templates; CreateProcessW gets the fixed literal argv directly and
+		// explicitly allocates a new console without inheriting the dispatcher's redirected standard handles.
+		const script = `$ErrorActionPreference = 'Stop'; Add-Type -TypeDefinition ${psString(WINDOWS_CONSOLE_SOURCE)}; [PiDispatchConsole]::Start(${psString(nodePath)}, ${psString([nodePath, ...args].map(windowsArgument).join(" "))})`;
+		// EncodedCommand preserves this fixed script through PowerShell 5's command-line parser, including the
+		// nested quotes in Arguments. The URI is still validated data in a quoted literal, never script input.
+		return { bin: win32.join(env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"), args: ["-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")], env: windowsPowerShellEnv(env), waitForExit: true };
+	}
+	throw new Error("this operating system has no supported terminal opener; copy the sandbox command instead");
+}
+export function spawnTerminal(plan, { spawn = nodeSpawn, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
+	return new Promise((resolve, reject) => {
+		// Windows PowerShell can exit successfully without running its command under DETACHED_PROCESS.
+		// Await its finite dispatcher normally. libuv's job has SILENT_BREAKAWAY_OK, so the console that
+		// dispatcher creates is not owned by the URL handler's lifetime (Node 22.19, win/process.c).
+		const child = spawn(plan.bin, plan.args, { detached: !plan.waitForExit, stdio: plan.waitForExit ? ["ignore", "pipe", "pipe"] : "ignore", windowsHide: true, ...(plan.env ? { env: plan.env } : {}) });
+		let timer;
+		let stdout = "", stderr = "";
+		child.stdout?.on("data", (chunk) => { stdout = (stdout + chunk.toString("utf8")).slice(-4096); });
+		child.stderr?.on("data", (chunk) => { stderr = (stderr + chunk.toString("utf8")).slice(-4096); });
+		const failed = (code) => Object.assign(new Error("Windows could not open an interactive console; check Windows PowerShell and use Copy until it is available"), { code, stdout, stderr });
+		child.once("error", (error) => { clearTimer(timer); reject(error); });
+		if (plan.waitForExit) {
+			// This dispatcher exits as soon as CreateProcessW returns. Waiting catches a refused launch without
+			// waiting for the person to press Enter, and the deadline bounds a blocked PowerShell/compiler.
+			timer = setTimer(() => { child.kill(); reject(failed()); }, 30_000);
+			child.once("close", (code) => {
+				clearTimer(timer);
+				// Exit zero alone does not establish that PowerShell executed the fixed dispatcher at all.
+				const receipt = stdout.trim().split(/\r?\n/).at(-1);
+				const created = /^pid=[1-9]\d*;parentJob=(?:True|False|unknown:-?\d+);childJob=(?:True|False|unknown:-?\d+);initialExit=(?:\d+|unknown:-?\d+)$/.test(receipt);
+				if (code === 0 && created) resolve({ stdout, stderr }); else reject(failed(code));
+			});
+		} else child.once("spawn", () => { child.unref(); resolve(); });
+	});
+}

package/src/openshell-cli.mjs

@@ -0,0 +1,155 @@
+/**
+ * The openshell venue's facts that need no run path (issue #683): the tested release and the judgement of the gateway's
+ * `status -o json`, shared by the adapter (worker/src/backend-openshell.mjs) and doctor (doctor-openshell.mjs). A leaf
+ * with no imports, so doctor reads them without loading the run path and pi with it.
+ */
+
+/** The OpenShell release this adapter was measured on: doctor's floor and ceiling (issue #683), one place. */
+export const OPENSHELL_TESTED_VERSION = "0.1.4";
+
+/** Where that release is downloaded, for every line that tells an operator to install it (`up` installs nothing). */
+export const OPENSHELL_RELEASE_URL = `https://github.com/NVIDIA/OpenShell/releases/tag/v${OPENSHELL_TESTED_VERSION}`;
+
+/**
+ * The macOS install that gives `brew services start openshell` something to start (review round 1 of #715): NVIDIA's
+ * release asset `openshell.rb` carries the `service do` block; homebrew-core's `openshell` formula has none.
+ */
+export const OPENSHELL_BREW_INSTALL = `brew install https://github.com/NVIDIA/OpenShell/releases/download/v${OPENSHELL_TESTED_VERSION}/openshell.rb`;
+
+/**
+ * The local gateway as OpenShell 0.1.4 sets it up (issue #707): it listens on loopback at 17670, the deb ships it as the
+ * systemd USER unit `openshell-gateway.service`, and the conformance lane registers it with `openshell gateway add
+ * https://127.0.0.1:17670 --local --name openshell`. `up` offers that registration and `service install` orders the worker
+ * after that unit, so the three are spelled once.
+ */
+export const OPENSHELL_LOCAL_GATEWAY_HOST = "127.0.0.1";
+export const OPENSHELL_LOCAL_GATEWAY_PORT = 17670;
+export const OPENSHELL_LOCAL_GATEWAY_URL = `https://${OPENSHELL_LOCAL_GATEWAY_HOST}:${OPENSHELL_LOCAL_GATEWAY_PORT}`;
+export const OPENSHELL_GATEWAY_UNIT = "openshell-gateway.service";
+export const OPENSHELL_DEFAULT_GATEWAY_NAME = "openshell";
+
+/**
+ * Why the openshell venues are refused on Windows (issue #707): the pinned release's assets (checked 2026-10-19 with
+ * `gh api repos/NVIDIA/OpenShell/releases/tags/v0.1.4`) carry the CLI and the gateway for Linux (deb, rpm, snap, tarballs)
+ * and macOS (aarch64 tarballs, a Homebrew formula) and nothing for Windows, so there is no gateway on this host to set up.
+ */
+export const OPENSHELL_NO_WINDOWS = `OpenShell ${OPENSHELL_TESTED_VERSION}, the release the openshell venue was measured on, ships no Windows build of its CLI or gateway (its release carries Linux and macOS ones only), so the openshell venue cannot run on this host. Run this deployment on Linux or macOS, or remove openshell from PI_BACKENDS`;
+
+/**
+ * The gateway's answer to "where are you" (`openshell status -o json`), judged: `{ connected, local, server, version }`.
+ * `status` exits 0 even when the gateway is down (measured), so the JSON's own `status` decides `connected`. Local means
+ * a loopback host or a unix socket; anything else, or a server this cannot parse, is not local.
+ */
+export function judgeGatewayStatus(doc) {
+	const status = typeof doc?.status === "string" ? doc.status : null;
+	const server = typeof doc?.server === "string" ? doc.server : null;
+	let local = false;
+	if (server !== null) {
+		if (server.startsWith("unix:")) local = true;
+		else {
+			try {
+				const host = new URL(server).hostname.replace(/^\[|\]$/g, "");
+				local = host === "127.0.0.1" || host === "::1" || host === "localhost" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+			} catch {
+				local = false;
+			}
+		}
+	}
+	return { connected: status === "connected" || status === "connected_http", local, server, version: typeof doc?.version === "string" ? doc.version : null };
+}
+
+/**
+ * BIND MODE (issue #686 part 3, the `openshell-bind` venue): what the gateway must be configured with before a sandbox
+ * may carry the worker's binds, and how its refusals read. Here, in the leaf, because the adapter's preflight and doctor
+ * judge the same answer and must not disagree about it.
+ *
+ * Measured on OpenShell 0.1.4, Docker driver, 2026-10-19: a create carrying `--driver-config-json` is refused, in this
+ * ORDER, with the first sentence below on a default gateway, the second with only `allow_driver_config`, the third with
+ * both but resource admission on; each in 50 to 90 ms, creating nothing. `gateway info -o json` does NOT reveal these
+ * settings, so they can only be learned by asking a create (`bindProbeArgs`).
+ */
+export const OPENSHELL_BIND_SETTINGS = Object.freeze(["allow_driver_config", "enable_bind_mounts", "resource_admission"]);
+
+/** Each setting's refusal, as upstream words it (unwrapped first: the CLI breaks its error box across lines). */
+const BIND_REFUSAL_PATTERNS = Object.freeze([
+	["allow_driver_config", /caller driver config is disabled|must enable allow_driver_config/],
+	["enable_bind_mounts", /bind mounts require enable_bind_mounts = true/],
+	["resource_admission", /cannot be attached while resource admission is enabled/],
+]);
+
+/** The one answer that proves the settings are on without anything being created: the probe's reserved target refused. */
+const BIND_PROBE_ADMITTED = /mount target '\/sandbox' is reserved for the OpenShell workspace/;
+
+/**
+ * A create's failure text judged: `{ setting }` for one of the three bind-settings refusals, `{ admitted: true }` for the
+ * probe's reserved-target refusal (the gateway read the binds, so its settings let them through), or `{}` for anything
+ * else. Only fixed patterns are matched; nothing the CLI said is kept.
+ */
+export function judgeBindAnswer(text) {
+	const said = String(text ?? "").replace(/[│\s]+/g, " ");
+	for (const [setting, pattern] of BIND_REFUSAL_PATTERNS) if (pattern.test(said)) return { setting };
+	if (BIND_PROBE_ADMITTED.test(said)) return { admitted: true };
+	return {};
+}
+
+/** The engine's table, the three settings and the TOML header (measured: no `[openshell] version = 2`, no driver table). */
+export function gatewayTomlFor(engine = "docker") {
+	return ["[openshell]", "version = 2", "", `[openshell.drivers.${engine}]`, "allow_driver_config = true", "enable_bind_mounts = true", "", `[openshell.drivers.${engine}.resource_admission]`, "enabled = false", ""].join("\n");
+}
+
+/** Where the gateway reads it, in upstream's words, for a fix text. */
+export const GATEWAY_TOML_WHERE = "the gateway's gateway.toml ($XDG_CONFIG_HOME/openshell/gateway.toml, or the file --config or OPENSHELL_GATEWAY_CONFIG names)";
+
+/** Upstream's own warning (docs/how-it-works/sandboxes/runtimes.mdx at v0.1.4), quoted verbatim wherever bind mode is offered. */
+export const UPSTREAM_BIND_WARNING = "Bind mounts expose gateway-host files to the sandbox and can bypass workspace isolation and filesystem policy.";
+
+/** The `--driver-config-json` document for a list of `{ source, target, readOnly }`, keyed by the driver's name. */
+export function driverConfigFor(engine, mounts) {
+	return JSON.stringify({ [engine]: { mounts: mounts.map((m) => ({ type: "bind", source: m.source, target: m.target, read_only: m.readOnly === true, ...(m.selinuxLabel === "private" ? { selinux_label: "private" } : {}) })) } });
+}
+
+/**
+ * The probe create (`judgeBindAnswer` reads its failure): one read-only bind of an empty directory onto `/sandbox`, a
+ * target OpenShell reserves for the workspace. Measured: a gateway whose settings do not admit binds refuses it with the
+ * setting's own sentence and creates nothing; one whose settings admit them gets past all three checks and fails it at
+ * provisioning ("sandbox entered error phase while provisioning: ContainerCreateFailed: mount target '/sandbox' is
+ * reserved for the OpenShell workspace"), LEAVING the sandbox in phase `Error`. So every caller deletes it on every
+ * answer, and it is owner-labelled and named in the job namespace, so the boot reaper finds one a crash left.
+ */
+export function bindProbeArgs({ name, image, source, engine = "docker", ownerLabel, owner, modeLabel, gateway = null }) {
+	return [...(typeof gateway === "string" && gateway !== "" ? ["--gateway", gateway] : []), "sandbox", "create", "--detach", "--name", name, "--from", image, "--label", `${ownerLabel}=${owner}`, "--label", `${modeLabel}=bind`, "--driver-config-json", driverConfigFor(engine, [{ source, target: "/sandbox", readOnly: true }]), "--no-auto-providers", "-o", "json"];
+}
+
+/**
+ * Issue #730: the Yama setting that keeps a job's tools from the memory of their ancestors, the job's key holders,
+ * which run readable on this venue (image/Dockerfile, `observableRunner`). OpenShell's workload seccomp denies
+ * process_vm_readv, ptrace and pidfd_getfd on every host; opening and reading /proc/<pid>/mem is not a syscall it
+ * filters, and Yama's ptrace_scope EXACTLY 1 is what refuses that to a descendant while still letting the broker read
+ * the workload (measured on the lane: EACCES to a tool at scope 1). At 0, the kernel default where nothing sets it, a
+ * same-uid tool reads a dumpable ancestor's memory (issue #545 measured exactly that on Fedora and Docker Desktop). At
+ * 2 or 3 the kernel admits a PTRACE_MODE_ATTACH read only from a process with CAP_SYS_PTRACE in the target's user namespace, which the
+ * broker is NOT, so its own process_vm_readv of the workload fails and every job would reserve and then fail its first
+ * connection: refused with a distinct reason, never run. Nothing in the sandbox can lower the sysctl (a host-wide
+ * setting; the sandbox holds no capability), so the host value is the sandbox's.
+ */
+export const PTRACE_SCOPE_PATH = "/proc/sys/kernel/yama/ptrace_scope";
+
+/**
+ * `{ ok: true, scope: 1 }` only when Yama is present and EXACTLY 1; otherwise `{ ok: false, reason, scope }`:
+ * `unprotected` (scope 0, or a read that failed/garbled/absent: refused, since the key would be exposed or nothing is
+ * known) or `too-strict` (scope 2 or 3: the broker cannot read the workload, so every job would reserve then fail).
+ * Strict: the file's text must be one decimal integer.
+ */
+export function judgePtraceScope(read) {
+	let text;
+	try {
+		text = String(read());
+	} catch {
+		return { ok: false, reason: "unprotected", scope: null };
+	}
+	const trimmed = text.trim();
+	if (!/^[0-9]{1,3}$/.test(trimmed)) return { ok: false, reason: "unprotected", scope: null };
+	const scope = Number(trimmed);
+	if (scope === 1) return { ok: true, scope };
+	return { ok: false, reason: scope >= 2 ? "too-strict" : "unprotected", scope };
+}

package/src/openshell-policy.mjs

@@ -0,0 +1,163 @@
+/**
+ * The `openshell` venue's network policy, generated per job (issue #684, `CONST-VENUE-EGRESS-LAYER`'s second condition,
+ * `INT-EGRESS-POLICY-CONTRACT`'s "A venue's own egress layer"). The SAME sources the squid venues read, translated into
+ * OpenShell's `network_policies`, so the two venues admit the same hosts:
+ *
+ *   - `egress-allowlist.conf` (`parseAllowlist`): a name admits that host on 443; a leading `.x.y` admits `x.y` and every
+ *     name under it, which OpenShell spells as the name plus a `*.x.y` wildcard. squid opens an allowlisted name on 443
+ *     only (every request is a CONNECT, `deploy/egress-proxy.conf`), so 443 only here too.
+ *   - `model-endpoints.json`: exactly each endpoint's host and port. A model server on the gateway host is reached by
+ *     OpenShell's trusted aliases (`host.openshell.internal`, `host.docker.internal`, `host.containers.internal`,
+ *     measured); a loopback name is never authorizable there, as `to_host_local` refuses it on squid.
+ *   - GitHub's web host, when the allowlist admits it, carries the git transport and nothing else writable: reads,
+ *     `git-upload-pack` and LFS batch requests for any repository, and `git-receive-pack` for the job's OWN repository
+ *     only, so a push to any other repository is refused by the layer, which squid, matching names, never could. ONLY
+ *     GitHub: there the API lives on its own host (api.github.com), so narrowing github.com costs the CLIs nothing. On
+ *     GitLab, Forgejo and Azure the API shares the git host (and a self-hosted one may sit under a URL path), so the
+ *     same narrowing would refuse every merge request and comment the job makes; their host keeps `access: full`, as
+ *     squid gives it, and the push rule is GitHub's alone, said so in `INT-EGRESS-POLICY-CONTRACT`.
+ *
+ * Every endpoint says `enforcement: enforce`: OpenShell's default is `audit`, which reports a violation and lets it
+ * through. Every endpoint says `protocol: rest`, so the layer reads each request (and can swap a credential placeholder
+ * into it, issue #684 part 2); a WebSocket or another protocol on 443 that squid tunnelled blindly is refused here,
+ * named in `INT-EGRESS-POLICY-CONTRACT`.
+ *
+ * THE BINARIES ARE NOT A CONTROL HERE, and saying so is the point. A rule's `binaries` match the connecting process or
+ * ANY of its ancestors (OpenShell's own documentation), and every process of a job descends from
+ * the runner's node (`/opt/pi-dispatch/runner-observable` on this venue since issue #730, `runner-node` before), which
+ * must reach the provider. So each rule names the image's declared network
+ * binaries (`dev.pi-dispatch.net-binaries`), the runner first, and that admits every tool the agent starts: the host
+ * list is the boundary, exactly as it is on squid. The runner's node is put first whatever an image's label says,
+ * since without it no provider call matches (an operator-built image's label may predate it).
+ *
+ * Pure: text in, a policy object out, and a refusal for what cannot be translated. Never reads a file.
+ */
+import { createHash } from "node:crypto";
+import { allowlistEntryFor } from "./egress-allowlist.mjs";
+
+/** The binary the runner and pi run as, which every job process descends from: always the first binary of every rule. */
+export const RUNNER_NODE = "/opt/pi-dispatch/runner-node";
+/**
+ * Issue #730: the readable copy the job's key holders start from on the OpenShell venues (image/Dockerfile), so the
+ * binary every provider call there leaves through. Listed beside RUNNER_NODE on every rule for the same reason that one
+ * is: an image that predates the label still gets its runner named, and this venue refuses before spend an image that
+ * lacks the copy (`observableRunner`).
+ */
+export const RUNNER_OBSERVABLE = "/opt/pi-dispatch/runner-observable";
+
+/** A refusal this module returns instead of guessing: `{ refused, entry? }`. */
+const refusal = (refused, extra = {}) => ({ refused, ...extra });
+
+/** The DNS labels of a name. */
+const labels = (name) => String(name).split(".").filter((l) => l !== "");
+
+/** A hostname the policy may name: lowercase letters, digits, hyphens and dots, 253 at most. */
+const HOST_RE = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+
+/**
+ * The hosts one allowlist entry admits, as OpenShell names them, or a refusal. A leading-dot entry needs a wildcard of
+ * at least three labels in OpenShell (`*.x.y`), so `.x.y` is fine and `.y` (a top-level domain) is refused by name: it
+ * would admit a whole TLD on squid, and widening it here is not this file's to guess.
+ */
+export function hostsOfEntry(entry) {
+	const e = String(entry).toLowerCase();
+	if (e.startsWith(".")) {
+		const base = e.slice(1);
+		// A line squid reads as a name that matches nothing (a trailing dot, a port, an address) admits nothing here
+		// either: skipped, never a refusal of every job, and named in the log by the caller.
+		if (!HOST_RE.test(base)) return { hosts: [], skipped: e };
+		if (labels(base).length < 2) return refusal("wildcard-too-wide", { entry: e });
+		return { hosts: [base, `*.${base}`] };
+	}
+	if (!HOST_RE.test(e)) return { hosts: [], skipped: e };
+	return { hosts: [e] };
+}
+
+/** The web host a job's forge serves git from, or null: GitHub's own, else the instance URL the deployment names. */
+export function forgeGitHost(kind) {
+	return kind === "github" ? "github.com" : null;
+}
+
+/**
+ * The git-transport rules for the forge's web host: reads anywhere, a fetch from any repository, a push to `repo` only.
+ * `repo` is the job's `owner/name` (GitHub, Forgejo) or its GitLab project path; a path segment outside the name rules
+ * is refused rather than put into a glob, since a `*` or `**` in it would widen the push rule.
+ */
+export function forgeGitRules(repo) {
+	// GitHub's own name rules: letters, digits, `_`, `.` and `-` (so `acme/.github` and `acme/_infra` are names), never
+	// a segment of `.` or `..`, never a glob character, which would widen the push rule.
+	if (typeof repo !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || repo.split("/").some((seg) => seg === "." || seg === "..")) return refusal("repo-not-a-path");
+	const own = repo.replace(/\.git$/, "");
+	return {
+		rules: [
+			{ allow: { method: "GET", path: "**" } },
+			{ allow: { method: "HEAD", path: "**" } },
+			{ allow: { method: "OPTIONS", path: "**" } },
+			{ allow: { method: "POST", path: "/**/git-upload-pack" } },
+			// Git LFS asks what to fetch with a POST; the objects themselves come from GitHub's media hosts.
+			{ allow: { method: "POST", path: "/**/info/lfs/objects/batch" } },
+			{ allow: { method: "POST", path: `/${own}.git/git-receive-pack` } },
+			{ allow: { method: "POST", path: `/${own}/git-receive-pack` } },
+		],
+	};
+}
+
+/**
+ * The rule key for a host and port: readable, and stable, with a short hash of the exact host so two hosts that
+ * spell alike once sanitised (`a-b.com` and `a.b.com`, `*.x.y` and `any.x.y`) never overwrite each other's rule.
+ */
+function ruleKey(prefix, host, port) {
+	const tag = createHash("sha256").update(`${host}:${port}`).digest("hex").slice(0, 8);
+	return `${prefix}_${host.replace(/\*/g, "any").replace(/[^a-z0-9]+/g, "_").slice(0, 80)}_${port}_${tag}`;
+}
+
+/**
+ * `networkPolicyFor({ allowlist, endpoints, kind, repo, binaries, onSkipped })` -> `{ network_policies }` or
+ * `{ refused, entry? }`.
+ *
+ *   allowlist  the parsed `egress-allowlist.conf` entries (`parseAllowlist`)
+ *   endpoints  the job's `model-endpoints.json` entries (`{ host, port }`)
+ *   kind, repo the job's forge and repository, for GitHub's push rule
+ *   binaries   the image's `dev.pi-dispatch.net-binaries` paths, after the runner's node, which is always first
+ *   onSkipped  told of every allowlist line and label entry left out, for the log
+ */
+export function networkPolicyFor({ allowlist = [], endpoints = [], kind = null, repo = null, binaries = [], onSkipped = () => {} } = {}) {
+	// The runner's node first, then the image's declared paths that are absolute and glob-free; an entry that is not is
+	// skipped and named (a glob would widen the rule), never a refusal of every job for a label typo.
+	const declared = (Array.isArray(binaries) ? binaries : []).map((b) => String(b).trim()).filter((b) => b !== "");
+	for (const b of declared) if (!b.startsWith("/") || /[*?[\]{}]/.test(b)) onSkipped({ binary: b });
+	const bins = [...new Set([RUNNER_NODE, RUNNER_OBSERVABLE, ...declared.filter((b) => b.startsWith("/") && !/[*?[\]{}]/.test(b))])].map((path) => ({ path }));
+	const policies = {};
+	const add = (key, endpoint) => {
+		policies[key] = { name: key, endpoints: [{ ...endpoint, enforcement: "enforce" }], binaries: bins };
+	};
+
+	// The forge's web host, when the allowlist admits it: the git transport with the push rule, never `access: full`.
+	const gitHost = kind ? forgeGitHost(kind) : null;
+	let gitRules = null;
+	if (gitHost !== null && allowlistEntryFor(allowlist, gitHost) !== null) {
+		const r = forgeGitRules(repo);
+		if (r.refused) return r;
+		gitRules = r.rules;
+		add(ruleKey("forge", gitHost, 443), { host: gitHost, port: 443, protocol: "rest", rules: gitRules });
+	}
+
+	for (const entry of allowlist) {
+		const r = hostsOfEntry(entry);
+		if (r.refused) return r;
+		if (r.skipped) onSkipped({ entry: r.skipped });
+		for (const host of r.hosts) {
+			if (host === gitHost) continue; // its own rule above, narrower than `full`
+			add(ruleKey("allow", host, 443), { host, port: 443, protocol: "rest", access: "full" });
+		}
+	}
+
+	for (const ep of endpoints ?? []) {
+		const host = String(ep?.host ?? "").toLowerCase();
+		const port = Number(ep?.port);
+		if (!HOST_RE.test(host) || !Number.isSafeInteger(port) || port < 1 || port > 65535) return refusal("endpoint-not-a-host-port", { entry: `${ep?.host}:${ep?.port}` });
+		if (host === "localhost" || labels(host).length === 0) return refusal("endpoint-loopback", { entry: host });
+		add(ruleKey("endpoint", host, port), { host, port, protocol: "rest", access: "full" });
+	}
+	return { network_policies: policies };
+}

package/src/outbox.mjs

@@ -50,6 +50,8 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 			// Belt-and-suspenders: a github parent has no /outbox mount at all (the request channel does not
 			// exist for it), but guard here too so a stray dir cannot chain off an untrusted issue author.
 			if (job?.data?.kind !== "local") return { enqueued: 0, refused: 0 };
+			// A collector signature is not a human's permission to start a write-capable child.
+			if (job.data.watch) { refuse("watch-human-required", 0); return { enqueued, refused }; }
 
 			const outboxDir = join(prepared.jobDir, "outbox");
 			let names;
@@ -186,6 +188,7 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					provider: job.data?.provider,
 					model: job.data?.model,
 					models: job.data?.models,
+					fallbackModels: job.data?.fallbackModels,
 					// Issue #501's per-job dollar cap, by the same narrowing rule: a child that dropped it would run
 					// uncapped. Passed through whenever the parent's data carries it; absent stays absent.
 					maxCostUsd: job.data?.maxCostUsd,
@@ -211,6 +214,17 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					// Less the names of the parent's MCP tools: the child connects no server (`mcp` below), its runner knows
 					// none of them, and they would refuse it at start while removing nothing.
 					excludeTools: withoutMcpExclusions(job.data?.excludeTools),
+					// Issue #800, both by #291's inverted direction: dropped, a child loads what its parent's trigger took away and
+					// keeps the tool. Whole, unlike the line above. A child connects no server, but it does load extensions, so a
+					// name here still removes something, and an unmatched one widens nothing: the runner stops only a job with no
+					// parent (`PI_EXCLUDE_TOOLS_STRICT`, run-container.mjs).
+					excludeExtensions: job.data?.excludeExtensions,
+					excludeExtensionTools: job.data?.excludeExtensionTools,
+					// `"packages": false`, by the same inverted direction, and the line those two left a hole beside: with only them, a trigger
+					// that withheld every staged package chained a child holding all of them, while one that named a package kept it out. `image`'s
+					// toolchain argument does not stand against it: a child's flow is its repository's, which is what the gate above reads, so a child
+					// without the packages is a child with what its parent had. Off `job.data`, so the request file cannot set it.
+					packages: job.data?.packages,
 					// `secrets`/`secretsProfile` are deliberately ABSENT, and the two lines above are exactly why
 					// this comment exists: their reasoning reads as though it should apply here too, and it must
 					// not. An image and a skills directory are toolchain; a resolved credential is a capability.

package/src/output-cap.mjs

@@ -22,6 +22,7 @@ export const COMPLETIONS_CATALOG_HOSTS = Object.freeze([
 	"api.fireworks.ai",
 	"api.groq.com",
 	"api.individual.githubcopilot.com",
+	"api.kimi.com",
 	"api.moonshot.ai",
 	"api.moonshot.cn",
 	"api.together.ai",

package/src/package-canary-record.mjs

@@ -0,0 +1,26 @@
+/**
+ * The canary's two facts on a run record (issue #796). Its own small module because `run-history.mjs` is imported almost everywhere, and must not bring npm or the stager with it.
+ */
+import { EXACT_VERSION_RE, isPackageName } from "./package-names.mjs";
+
+export const CANARY_LOADS = Object.freeze(["loaded", "failed"]);
+export const CANARY_RECORD_LOADS = Object.freeze(["loaded", "failed", "not-reported"]);
+
+/**
+ * `{ name, version }`, rebuilt, or `null`. The one reader of the job field and of the record's copy of it, and the one validator of
+ * a package's name and exact version wherever else they are read back (`loaded-record.mjs`, `host-loads.mjs`).
+ */
+export function parsePackageCanary(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const { name, version } = raw;
+	if (!isPackageName(name)) return null;
+	if (typeof version !== "string" || version.length > 128 || !EXACT_VERSION_RE.test(version)) return null;
+	return { name, version };
+}
+
+/** The run record's field: the job's candidate, and what the runner said of it. A missing report is its own word, which every reader draws as failed. */
+export function recordedPackageCanary(field, load) {
+	const canary = parsePackageCanary(field);
+	if (!canary) return null;
+	return { ...canary, load: CANARY_LOADS.includes(load) ? load : "not-reported" };
+}