@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/doctor-bundles.mjs

@@ -0,0 +1,130 @@
+/**
+ * doctor's project secret bundle lines (issue #704, REQ-TRIGGER-SECRETS, DES-PROJECT-SECRET-BUNDLES).
+ *
+ * Its own module, the doctor-openshell.mjs precedent: doctor.mjs is a ten-thousand-line file, and these lines read
+ * three files and (with `--secrets`) spawn resolvers, so a seam per input keeps them testable without a host.
+ *
+ * WHAT IS CHECKED, and why each is a failure rather than a warning:
+ *   - a bundle naming a profile this host does not declare (or declares twice, or declares in the panel outside
+ *     PI_SECRET_RESOLVER_ROOTS): every job of that project refuses pre-spend on this host, deliberately;
+ *   - a bundle naming a project projects.json does not hold: the binding can never apply, and the operator reads it
+ *     as granting an environment. That is the silent no-op this project refuses;
+ *   - bundle profiles declared with no triggers file to read: no job on this host can get a bundle, while the host
+ *     reads as serving them.
+ * Two bundles naming one project is refused by the triggers file's own validator, so it surfaces as that file's
+ * parse failure, which doctor already prints, rather than as a second line here.
+ *
+ * And a WARNING per bundle whose project holds a folder: a local job's /workspace IS the operator's folder, so an
+ * agent that writes a credential to `.env` there writes the whole bundle's into a real repository. The run.secrets
+ * disclosure, raised to a warning because a bundle is a whole environment, not one field.
+ *
+ * `--secrets` (`secrets: true`) resolves each bundle ON THIS HOST and prints its variable NAMES and their count, never
+ * a value. It is opt-in because it spawns every bundle resolver, which reads the manager (and counts against its
+ * rate limit) once per bundle.
+ */
+
+import { FORGE_KINDS } from "./forges.mjs";
+import { mergeSecretProfiles, parseSecretBundleProfiles, servableSecretProfiles } from "./secret-profiles.mjs";
+
+/** Whether a projects.json member is a FOLDER (a local job's scope), not a forge-qualified repository. */
+function isFolderMember(member) {
+	return typeof member === "string" && !FORGE_KINDS.some((kind) => member.startsWith(`${kind}:`));
+}
+
+/** `PI_SECRET_BUNDLES`, never throwing: `{ bundles }` or `{ error }` (the worker refuses to boot on the latter). */
+export function parseSecretBundleProfilesSafe(raw) {
+	try {
+		return { bundles: parseSecretBundleProfiles(raw), error: null };
+	} catch (err) {
+		return { bundles: {}, error: err?.message ?? "unparseable" };
+	}
+}
+
+/**
+ * The checks. Inputs, every one already read by the caller:
+ *   - `bundles`: the triggers file's validated `secretBundles` (`{}` when none);
+ *   - `triggersPresent`: whether the worker has a triggers file to read them from;
+ *   - `projects` / `projectsError`: projects.json as the worker loads it, or its load failure;
+ *   - `envRaw`: `PI_SECRET_BUNDLES` as set; `overlayBundles`: the overlay's `secretBundles`; `roots`: PI_SECRET_RESOLVER_ROOTS;
+ *   - `realExecutablePath`: the resolver's own probe (secrets.mjs `realExecutable`), or null when pi did not load;
+ *   - `resolveBundle`: `(binding) => resolve result`, only with `--secrets`.
+ */
+export async function secretBundleChecks({ bundles = {}, triggersPresent = true, projects = [], projectsError = null, envRaw, overlayBundles = {}, roots = [], realExecutablePath = null, resolveBundle = null } = {}) {
+	const checks = [];
+	const { bundles: envBundles, error } = parseSecretBundleProfilesSafe(envRaw);
+	if (error) {
+		checks.push({ ok: false, label: "PI_SECRET_BUNDLES does not parse", fix: `${error} -- the worker refuses to boot until this is fixed` });
+		return checks;
+	}
+	const ids = Object.keys(bundles);
+	const declaredNames = [...new Set([...Object.keys(envBundles), ...Object.keys(overlayBundles)])].sort();
+	if (ids.length === 0 && declaredNames.length === 0) return checks;
+
+	// The overlay half counts only where the worker would use it: an executable inside the roots (servableSecretProfiles
+	// asks the resolver's own question). Without the probe (pi did not load) an overlay profile counts as written.
+	const overlayPaths = Object.fromEntries(Object.entries(overlayBundles).map(([name, entry]) => [name, entry?.path]));
+	const usableOverlay = realExecutablePath === null ? overlayPaths : servableSecretProfiles({ envProfiles: {}, overlayProfiles: overlayPaths, roots, realExecutablePath }).profiles;
+	const ambiguous = mergeSecretProfiles(envBundles, overlayBundles).ambiguous !== undefined;
+	const ambiguousNames = Object.keys(overlayBundles).filter((name) => Object.hasOwn(envBundles, name));
+
+	if (declaredNames.length > 0) {
+		checks.push({ ok: true, label: `Secret bundle profiles declared: ${declaredNames.map((n) => `${n} (${(Object.hasOwn(envBundles, n) ? envBundles[n] : overlayBundles[n])?.format ?? "?"})`).join(", ")}` });
+		// The rate figure, stated once: what a manager's rate limit counts is job starts.
+		checks.push({ ok: true, label: "A project with a secret bundle costs one resolver call per job start (never one per variable), so a secrets manager's rate limit counts job starts: size it for your busiest hour of jobs across every bundled project" });
+		if (!triggersPresent) {
+			checks.push({ ok: false, label: "secret bundle profiles are declared, but the worker has no triggers file to read secretBundles from", fix: "set PI_TRIGGERS_FILE (or put triggers.json in the worker's folder) on this host -- the worker reads which project holds a bundle from its own copy of that file, so without it no job on this host gets one" });
+		}
+	}
+	if (ambiguous) {
+		checks.push({ ok: false, label: `${ambiguousNames.length} secret bundle profile name(s) are declared in both PI_SECRET_BUNDLES and the settings overlay: ${ambiguousNames.join(", ")}`, fix: "remove each name from one of the two (neither source wins a collision) -- until then every bundled project's jobs refuse as secret-bundle-profile-ambiguous" });
+	}
+
+	const projectIds = new Set((projects ?? []).map((p) => p?.id));
+	for (const id of ids) {
+		const b = bundles[id];
+		const fromEnv = Object.hasOwn(envBundles, b.profile);
+		const fromOverlay = Object.hasOwn(overlayBundles, b.profile);
+		const format = fromEnv ? envBundles[b.profile].format : fromOverlay ? overlayBundles[b.profile]?.format : null;
+		checks.push({ ok: true, label: `secret bundle ${id}: profile ${b.profile}${format ? ` (${format})` : ""}, project ${b.project}${b.forkReviews === true ? ", fork reviews included" : ""}` });
+		if (!fromEnv && !fromOverlay) {
+			checks.push({ ok: false, label: `secret bundle ${id} names profile ${b.profile}, which this host does not declare`, fix: "declare it in PI_SECRET_BUNDLES as name:/absolute/path:format (format dotenv or json), on EVERY host that takes this project's jobs -- until then they refuse pre-spend as secret-bundle-profile-unknown" });
+		} else if (!fromEnv && !Object.hasOwn(usableOverlay, b.profile)) {
+			checks.push({ ok: false, label: `secret bundle ${id} names profile ${b.profile}, declared in the settings overlay but not usable`, fix: roots.length === 0 ? "PI_SECRET_RESOLVER_ROOTS is unset, so the worker uses no overlay-declared resolver: set it, or declare the profile in PI_SECRET_BUNDLES" : "the resolver must be an executable file whose real path sits inside PI_SECRET_RESOLVER_ROOTS" });
+		}
+		if (projectsError !== null) {
+			checks.push({ ok: false, label: `secret bundle ${id} names project ${b.project}, and projects.json does not load`, fix: "fix projects.json (its own line above says why) -- a bundle applies to a project's jobs only once the worker knows the project" });
+		} else if (!projectIds.has(b.project)) {
+			checks.push({ ok: false, label: `secret bundle ${id} names project ${b.project}, which projects.json does not hold`, fix: "add the project to PI_PROJECTS_FILE, or correct the bundle's project -- until then the bundle reaches no job, while the file reads as granting it" });
+		} else {
+			const project = projects.find((p) => p?.id === b.project);
+			const folders = (project?.members ?? []).filter(isFolderMember);
+			if (folders.length > 0) {
+				checks.push({ ok: true, warn: true, label: `secret bundle ${id}'s project ${b.project} holds ${folders.length} folder(s), whose local jobs run IN the operator's own folder with the whole bundle in their environment`, fix: "a value the agent writes to .env, .netrc or .git-credentials there lands in your real repository (and in a retained sandbox), and nothing scans for that: keep those folders out of anything you push, or set run.secretBundle: false on their triggers" });
+			}
+		}
+	}
+
+	if (typeof resolveBundle === "function") {
+		for (const id of ids) {
+			const b = bundles[id];
+			let read;
+			try {
+				read = await resolveBundle({ id, ...b });
+			} catch {
+				read = { unreachable: true, failure: "spawn" };
+			}
+			if (read?.ok === true) {
+				const names = Object.keys(read.vars).sort();
+				checks.push({ ok: true, label: `secret bundle ${id} resolved on this host: ${names.length} variable(s): ${names.join(", ")}` });
+			} else if (read?.reserved !== undefined) {
+				checks.push({ ok: false, label: `secret bundle ${id} carries ${read.reserved}, a name this deployment reserves`, fix: "rename it in the secrets manager -- every job of the project refuses pre-spend as secret-name-reserved until you do" });
+			} else if (read?.profileUnknown !== undefined || read?.ambiguous !== undefined) {
+				// Already its own line above.
+			} else {
+				const what = read?.unreachable ? "could not reach its manager (exit 1, a timeout or a spawn fault: retried at job time)" : `was refused (${read?.failure ?? "unknown"}${read?.name ? `, variable ${read.name}` : ""}${read?.line ? `, line ${read.line}` : ""})`;
+				checks.push({ ok: false, label: `secret bundle ${id}'s resolver ${what}`, fix: "run the profile's resolver by hand with the bundle's ref as its argument -- doctor prints no byte of what it printed" });
+			}
+		}
+	}
+	return checks;
+}

package/src/doctor-model-proposals.mjs

@@ -0,0 +1,109 @@
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ProxyAgent, fetch as proxyFetch } from "undici";
+import { parseTriggersDocument } from "./triggers.mjs";
+import { parseAllowlist, allowlistEntryFor } from "./egress-allowlist.mjs";
+import { parseModelsJson } from "./models-json.mjs";
+import { endpointsForModel, loadModelEndpoints } from "./model-endpoints.mjs";
+import { lifecycleModels, roleProposalChecks } from "./model-proposals.mjs";
+import { getPricedModel } from "./pricing.mjs";
+import { splitModelEntry } from "./model-ref.mjs";
+
+// The default catalog omits retired models, which would make a role's warning vanish on retirement.
+// Match the provider SDK's bracket-array query encoding (internal/utils/query.ts).
+const APIS = Object.freeze({ anthropic: "https://api.anthropic.com/v1/models?limit=1000&lifecycle%5B%5D=active&lifecycle%5B%5D=deprecated&lifecycle%5B%5D=retired", openai: "https://api.openai.com/v1/models" });
+const KEYS = Object.freeze({ anthropic: "ANTHROPIC_API_KEY", openai: "OPENAI_API_KEY" });
+const safeRead = (path) => {
+	const stat = lstatSync(path);
+	if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error("not a bounded regular file");
+	return readFileSync(path, "utf8");
+};
+
+export function parseProposalConfig(text) {
+	const value = JSON.parse(text);
+	if (!value || value.version !== 1 || Object.keys(value).some((key) => !["version", "lifecycleProviders", "proxyUrl", "noticeDays", "replacements", "routes"].includes(key))) throw new Error("invalid proposal configuration");
+	const providers = value.lifecycleProviders ?? [];
+	if (!Array.isArray(providers) || providers.length > 2 || new Set(providers).size !== providers.length || providers.some((p) => !Object.hasOwn(APIS, p))) throw new Error("unsupported lifecycle provider");
+	if (value.noticeDays !== undefined && (!Number.isInteger(value.noticeDays) || value.noticeDays < 1 || value.noticeDays > 365)) throw new Error("invalid notice window");
+	if (providers.length) {
+		const proxy = new URL(value.proxyUrl);
+		if (!["http:", "https:"].includes(proxy.protocol) || proxy.username || proxy.password || proxy.pathname !== "/" || proxy.search || proxy.hash) throw new Error("invalid lifecycle egress proxy");
+	}
+	const ref = (v) => splitModelEntry(v) !== null;
+	if (value.replacements !== undefined && (!value.replacements || typeof value.replacements !== "object" || Array.isArray(value.replacements) || Object.entries(value.replacements).some(([a, b]) => !ref(a) || !ref(b)))) throw new Error("invalid replacements");
+	if (value.routes !== undefined && (!Array.isArray(value.routes) || value.routes.length > 100 || value.routes.some((r) => !r || Object.keys(r).some((k) => !["model", "alternative"].includes(k)) || !ref(r.model) || !ref(r.alternative)))) throw new Error("invalid declared equivalent routes");
+	return { ...value, lifecycleProviders: providers };
+}
+
+/** Every request traverses an operator-declared proxy; no direct fallback and no redirects. */
+export async function fetchLifecycle(provider, { key, proxyUrl, fetch: request, timeoutMs = 5000 }) {
+	if (!Object.hasOwn(APIS, provider)) throw new Error("unsupported lifecycle provider");
+	let dispatcher;
+	if (!request) {
+		dispatcher = new ProxyAgent(proxyUrl);
+		request = proxyFetch;
+	}
+	try {
+		const response = await request(APIS[provider], { dispatcher, redirect: "error", signal: AbortSignal.timeout(timeoutMs), headers: provider === "anthropic" ? { "x-api-key": key, "anthropic-version": "2023-06-01" } : { authorization: `Bearer ${key}` } });
+		if (!response.ok) throw new Error("lifecycle API unavailable");
+		const parts = [];
+		let length = 0;
+		for await (const part of response.body) {
+			length += part.length;
+			if (length > 1024 * 1024) throw new Error("lifecycle response too large");
+			parts.push(part);
+		}
+		const value = JSON.parse(Buffer.concat(parts).toString("utf8"));
+		if (value.has_more === true) throw new Error("lifecycle catalog is incomplete");
+		return lifecycleModels(provider, value);
+	} finally { await dispatcher?.close(); }
+}
+
+export function cheaperRouteChecks(roles, routes, models, endpoints, builtin = getPricedModel) {
+	const active = new Set(Object.values(roles).flatMap((scope) => Object.values(scope).map((v) => typeof v === "string" ? v : v.model)));
+	const lookup = (ref, declaredOnly) => {
+		const slash = ref.indexOf("/"), provider = ref.slice(0, slash), modelId = ref.slice(slash + 1);
+		const own = models.providers?.[provider]?.models?.find((m) => m.id === modelId);
+		if (declaredOnly && (!own || endpointsForModel({ models, provider, modelId, endpoints }).length === 0)) return null;
+		return own?.cost ?? builtin(provider, modelId)?.cost;
+	};
+	const checks = [];
+	for (const route of routes) {
+		if (!active.has(route.model)) continue;
+		const a = lookup(route.model, false), b = lookup(route.alternative, true);
+		const fields = ["input", "output", "cacheRead", "cacheWrite"];
+		if (a && b && !a.tiers && !b.tiers && fields.every((f) => Number.isFinite(a[f]) && a[f] >= 0 && Number.isFinite(b[f]) && b[f] >= 0 && b[f] <= a[f]) && fields.some((f) => b[f] < a[f])) checks.push({ proposal: { kind: "cheaper-route", model: route.model, candidate: route.alternative }, ok: true, label: `Model proposal: ${route.alternative} has lower recorded rates than ${route.model} through a declared endpoint; equivalence is operator-declared, review with a capped canary` });
+	}
+	return checks;
+}
+
+export async function doctorModelProposalChecks(env, { cwd, credentials = {}, now = Date.now, read = safeRead, fetch = fetchLifecycle, endpoints: suppliedEndpoints } = {}) {
+	let config;
+	try { config = parseProposalConfig(read(join(cwd, "model-proposals.json"))); }
+	catch (error) {
+		if (error?.code === "ENOENT") return [];
+		return [{ proposal: { kind: "unavailable" }, ok: false, warn: true, label: "Model proposals: model-proposals.json is unreadable or invalid", fix: "use version 1 with explicit lifecycleProviders, proxyUrl and optional noticeDays, replacements or equivalent routes" }];
+	}
+	const checks = [];
+	let roles;
+	try { roles = parseTriggersDocument(read(env.PI_TRIGGERS_FILE ?? join(cwd, "triggers.json"))).modelRoles ?? {}; }
+	catch { return [{ proposal: { kind: "unavailable" }, ok: false, warn: true, label: "Model proposals: current role map unavailable", fix: "fix triggers.json before evaluating proposals" }]; }
+	const catalogs = {};
+	for (const provider of config.lifecycleProviders) {
+		try {
+			const host = new URL(APIS[provider]).hostname;
+			const allowed = parseAllowlist(read(join(cwd, "egress-allowlist.conf")));
+			if (!allowlistEntryFor(allowed, host) || !credentials[KEYS[provider]]) throw new Error("lifecycle egress or credential unavailable");
+			catalogs[provider] = await fetch(provider, { key: credentials[KEYS[provider]], proxyUrl: config.proxyUrl });
+			checks.push({ proposal: { kind: "catalog-checked", provider }, ok: true, label: `Model proposals: ${provider} lifecycle catalog checked through declared proxy` });
+		} catch { checks.push({ proposal: { kind: "unavailable", provider }, ok: false, warn: true, label: `Model proposals: ${provider} lifecycle catalog unavailable`, fix: "check the opt-in proxy, egress allowlist and API credential; no model was changed" }); }
+	}
+	checks.push(...roleProposalChecks({ roles, catalogs, replacements: config.replacements, now: now(), noticeDays: config.noticeDays }));
+	if (config.routes?.length) try {
+		const parsed = parseModelsJson(read(join(env.PI_GLOBAL_PI_DIR, "models.json")));
+		if (parsed.error) throw new Error("overlay unavailable");
+		const endpoints = suppliedEndpoints ?? loadModelEndpoints({ modelEndpointsFile: env.PI_MODEL_ENDPOINTS_FILE }, { cwd });
+		checks.push(...cheaperRouteChecks(roles, config.routes, parsed.value, endpoints));
+	} catch { checks.push({ proposal: { kind: "unavailable" }, ok: false, warn: true, label: "Model proposals: declared route prices or endpoints unavailable", fix: "check the overlay models.json and declared endpoints; no route was changed" }); }
+	return checks;
+}

package/src/doctor-openshell.mjs

@@ -0,0 +1,238 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DAEMON_FACTS_ARGS, parseDaemonFacts } from "./daemon-facts.mjs";
+import { decideJobUser, JOB_USER_FIX, resolveImageUser } from "./job-user.mjs";
+import { bindProbeArgs, GATEWAY_TOML_WHERE, gatewayTomlFor, judgeBindAnswer, judgeGatewayStatus, judgePtraceScope, OPENSHELL_BREW_INSTALL, OPENSHELL_TESTED_VERSION, PTRACE_SCOPE_PATH, UPSTREAM_BIND_WARNING } from "./openshell-cli.mjs";
+
+/**
+ * `pi-dispatch doctor --openshell` (issue #683): whether this host can run the `openshell` venue, asked before
+ * blessing it in PI_BACKENDS (and run by plain `doctor` once it is, issue #684), so an operator can set the gateway up
+ * and read what the venue meets. Every line is a free read; nothing creates a sandbox (the conformance run,
+ * `.github/scripts/openshell-conformance.mjs`, is the live half).
+ *
+ * The lines, each with what fixes it:
+ *   - the CLI and the gateway are the tested release (`OPENSHELL_TESTED_VERSION`). EXACT, not a floor: OpenShell is
+ *     0.1.x and marks the interfaces this adapter drives experimental, so a newer release is untested until the
+ *     conformance run says otherwise (`OQ-047`);
+ *   - the gateway is connected and on this host (`CONST-VENUE-EGRESS-LAYER`'s third condition, the same judgement the
+ *     per-job check makes);
+ *   - its compute driver is the engine this deployment names, Docker or Podman, the only two v1 admits;
+ *   - no gateway-wide policy is in force;
+ *   - that engine is Docker 28 or later, or Podman 5 or later (measured: Docker Desktop 27.4 refused every create);
+ *   - this host's kernel offers Landlock, on Linux, where the gateway on this host shares it; elsewhere it cannot be
+ *     read here, and Docker Desktop's LinuxKit kernel has none (measured), which is said, never passed;
+ *   - this host's Yama `ptrace_scope` is readable and 1 or more (issue #730), the setting the per-job check refuses
+ *     without, since the job's key holders run readable on this venue;
+ *   - the job image declares `sandboxLayout`, read on that engine, the store the gateway runs images from (copy mode);
+ *   - the job image declares `observableRunner` (issue #730, both modes), without which no connection of a job is made.
+ *
+ * BIND MODE (issue #686 part 3, `openshell-bind` blessed): its engine is Docker (the Podman driver is refused for it), the
+ * gateway's three bind settings are on (one probe create that can only be refused, the adapter's own
+ * `bindProbeArgs`, since no read reveals them; the fix is the gateway.toml to write), and upstream's warning, quoted.
+ * The probe is the one line that asks a create; a gateway that admits binds refuses it on its reserved target at
+ * provisioning and leaves it in phase `Error` (measured), so it is deleted here on every answer.
+ */
+
+/** The labels the adapter's probe carries (backend-openshell.mjs re-exports none of its run path to doctor). */
+const OWNER_LABEL = "pi.dispatch.owner";
+const OWNER = "pi-dispatch";
+const MODE_LABEL = "pi.dispatch.openshell-mode";
+
+/** The settings this check reads, the same two the worker's boot reads (`config.mjs` `openshellFrom`, issue #684). */
+export const OPENSHELL_ENGINE_ENV = "PI_OPENSHELL_ENGINE";
+export const OPENSHELL_GATEWAY_ENV = "PI_OPENSHELL_GATEWAY";
+
+/** The engine floors (issue #683): OpenShell's own support matrix, and Docker 28 measured as a real one. */
+export const ENGINE_FLOORS = Object.freeze({ docker: [28, 0], podman: [5, 0] });
+
+/**
+ * The probe's empty source directory (review round 2 of #714): under the deployment's jobs dir, the tree the engine binds
+ * job dirs from, as the adapter makes it (`bind-probe-*`, which the `job-*` orphan sweep leaves alone). A jobs dir that
+ * does not exist yet (doctor before the first boot) is not created here: the worker's tmp dir stands in, since the probe
+ * is refused on its reserved target whatever the source.
+ */
+function probeSourceIn(jobsDir) {
+	if (typeof jobsDir === "string" && jobsDir !== "") {
+		try {
+			return mkdtempSync(join(jobsDir, "bind-probe-"));
+		} catch {}
+	}
+	return mkdtempSync(join(tmpdir(), "pi-dispatch-bind-probe-"));
+}
+
+/** `{ code, stdout, stderr }`, `code: null` when it could not run or overran. Never throws. */
+export function runQuiet(bin, args, { timeoutMs = 20_000, execFileFn = execFile } = {}) {
+	return new Promise((resolve) => {
+		try {
+			execFileFn(bin, args, { timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+				resolve({ code: err ? (typeof err.code === "number" ? err.code : null) : 0, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
+			});
+		} catch {
+			resolve({ code: null, stdout: "", stderr: "" });
+		}
+	});
+}
+
+const json = (text) => {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+};
+
+/** `[major, minor]` of the first `x.y` in `text`, or null. */
+function versionOf(text) {
+	const m = /(\d+)\.(\d+)/.exec(String(text ?? ""));
+	return m ? [Number(m[1]), Number(m[2])] : null;
+}
+const atLeast = (have, want) => have !== null && (have[0] > want[0] || (have[0] === want[0] && have[1] >= want[1]));
+
+/**
+ * The checks, as doctor's `{ ok, warn?, label, fix? }`. `run` is the seam every spawn goes through; `env` is the
+ * service environment doctor resolved; `platform` and `readLsm` are the Landlock read's, `readPtraceScope` Yama's.
+ */
+export async function openshellChecks(env = {}, { run = runQuiet, platform = process.platform, readLsm = () => readFileSync("/sys/kernel/security/lsm", "utf8"), readPtraceScope = () => readFileSync(PTRACE_SCOPE_PATH, "utf8"), image = env.PI_JOB_IMAGE || "pi-job:latest", modes = { copy: true, bind: false }, ids = { euid: typeof process.geteuid === "function" ? process.geteuid() : null, egid: typeof process.getegid === "function" ? process.getegid() : null }, jobsDir = null, mkdtemp = () => probeSourceIn(jobsDir), rmdir = (dir) => rmSync(dir, { recursive: true, force: true }) } = {}) {
+	const checks = [];
+	const engine = env.PI_OPENSHELL_ENGINE === undefined || env.PI_OPENSHELL_ENGINE === "" ? "docker" : env.PI_OPENSHELL_ENGINE;
+	const gateway = env.PI_OPENSHELL_GATEWAY || null;
+	if (engine !== "docker" && engine !== "podman") {
+		checks.push({ ok: false, label: `openshell: ${OPENSHELL_ENGINE_ENV} names the gateway's engine`, fix: `set ${OPENSHELL_ENGINE_ENV} to docker or podman, the compute drivers v1 admits (it is ${JSON.stringify(engine)})` });
+		return checks;
+	}
+	if (gateway !== null && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/.test(gateway)) {
+		checks.push({ ok: false, label: `openshell: ${OPENSHELL_GATEWAY_ENV} names a registered gateway`, fix: `set ${OPENSHELL_GATEWAY_ENV} to a name \`openshell gateway list\` shows, or unset it for the CLI's active gateway` });
+		return checks;
+	}
+	const os = (args, opts) => run("openshell", [...(gateway ? ["--gateway", gateway] : []), ...args], ...(opts ? [opts] : []));
+
+	const cli = await os(["--version"]);
+	const cliVersion = /openshell (\S+)/.exec(cli.stdout)?.[1] ?? null;
+	if (cli.code !== 0 || cliVersion === null) {
+		checks.push({ ok: false, label: "openshell: the CLI is installed", fix: `install OpenShell ${OPENSHELL_TESTED_VERSION} (https://github.com/NVIDIA/OpenShell/releases/tag/v${OPENSHELL_TESTED_VERSION}), the release this venue was measured on` });
+		return checks;
+	}
+	checks.push(cliVersion === OPENSHELL_TESTED_VERSION ? { ok: true, label: `openshell: CLI ${cliVersion}, the tested release` } : { ok: false, label: `openshell: CLI ${cliVersion} is the tested release (${OPENSHELL_TESTED_VERSION})`, fix: `install OpenShell ${OPENSHELL_TESTED_VERSION}: the venue drives interfaces OpenShell marks experimental, so another release is untested until the conformance run passes on it` });
+
+	const status = judgeGatewayStatus(json((await os(["status", "-o", "json"])).stdout));
+	if (!status.connected) {
+		checks.push({ ok: false, label: "openshell: the gateway answers", fix: "start the gateway (`systemctl --user start openshell-gateway`, or on macOS `brew services start openshell`, which only OpenShell's release formula defines: `" + OPENSHELL_BREW_INSTALL + "`) and register it on loopback: `openshell gateway add https://127.0.0.1:17670 --local`" });
+		return checks;
+	}
+	checks.push(status.local ? { ok: true, label: "openshell: the gateway is on this host (loopback or a unix socket)" } : { ok: false, label: "openshell: the gateway is on this host", fix: "the venue holds the job's credentials in its gateway, so it runs only on one this deployment runs itself (CONST-VENUE-EGRESS-LAYER): register the local gateway on loopback" });
+	checks.push(status.version === OPENSHELL_TESTED_VERSION ? { ok: true, label: `openshell: gateway ${status.version}, the tested release` } : { ok: false, label: `openshell: gateway ${status.version ?? "of unknown version"} is the tested release (${OPENSHELL_TESTED_VERSION})`, fix: `run the gateway of OpenShell ${OPENSHELL_TESTED_VERSION}` });
+
+	const info = json((await os(["gateway", "info", "-o", "json"])).stdout);
+	const drivers = Array.isArray(info?.compute_drivers) ? info.compute_drivers.map((d) => d?.name).filter((n) => typeof n === "string") : null;
+	if (drivers === null) checks.push({ ok: true, warn: true, label: "openshell: the gateway's compute driver could not be read (gateway info answers an admin only)", fix: `make sure the gateway's compute_driver is ${engine}` });
+	else checks.push(drivers.length === 1 && drivers[0] === engine ? { ok: true, label: `openshell: the gateway's compute driver is ${engine}` } : { ok: false, label: `openshell: the gateway's compute driver is ${engine}`, fix: `the gateway runs ${drivers.join(", ") || "no driver"}; set its compute_driver to ${engine} (OPENSHELL_COMPUTE_DRIVER=${engine}), or ${OPENSHELL_ENGINE_ENV} to the one it runs, if that is docker or podman` });
+
+	const global = await os(["policy", "get", "--global", "-o", "json"]);
+	const none = global.code !== 0 && /no global policy revision found/.test(global.stderr.replace(/[│\s]+/g, " "));
+	checks.push(global.code === 0 ? { ok: false, label: "openshell: no gateway-wide policy is in force", fix: "a global policy replaces every sandbox's own, so the per-job policy the worker generates would not be the one in force: `openshell policy delete --global`" } : none ? { ok: true, label: "openshell: no gateway-wide policy is in force" } : { ok: false, label: "openshell: whether a gateway-wide policy is in force could be read", fix: "`openshell policy get --global` failed for another reason than none being set; run it and read the error" });
+
+	if (modes.bind === true) checks.push(...(await bindChecks({ os, run, engine, image, mkdtemp, rmdir, platform, ids })));
+
+	const engineRead = await run(engine, engine === "docker" ? ["version", "--format", "{{.Server.Version}}"] : ["version", "--format", "{{.Version}}"]);
+	const engineVersion = engineRead.code === 0 ? versionOf(engineRead.stdout) : null;
+	const floor = ENGINE_FLOORS[engine];
+	checks.push(atLeast(engineVersion, floor) ? { ok: true, label: `openshell: ${engine} ${engineVersion.join(".")} (${floor[0]} or later)` } : { ok: false, label: `openshell: ${engine} is ${floor[0]} or later`, fix: engineVersion === null ? `${engine} did not answer \`${engine} version\`` : `${engine} ${engineVersion.join(".")} is older than OpenShell supports (measured: Docker Desktop 27.4 refused every sandbox create); upgrade it` });
+
+	if (platform === "linux") {
+		let lsm = null;
+		try {
+			lsm = String(readLsm());
+		} catch {
+			lsm = null;
+		}
+		if (lsm === null) checks.push({ ok: true, warn: true, label: "openshell: Landlock could not be read (/sys/kernel/security/lsm)", fix: "OpenShell needs Landlock ABI 3 (Linux 6.2 or later); a kernel without it fails every create" });
+		else checks.push(lsm.split(",").map((s) => s.trim()).includes("landlock") ? { ok: true, label: "openshell: this kernel offers Landlock" } : { ok: false, label: "openshell: this kernel offers Landlock", fix: "boot a kernel with Landlock in its LSM list (Linux 6.2 or later, `lsm=...,landlock`); the venue confines every sandbox and its job inputs with it" });
+	} else {
+		checks.push({ ok: true, warn: true, label: "openshell: Landlock cannot be read from this host", fix: "the gateway's engine runs in a VM whose kernel must offer Landlock ABI 3; Docker Desktop's LinuxKit kernel offers none (measured), so every create fails there" });
+	}
+	// Issue #730: the same judgement the per-job check makes, so doctor says before a job does.
+	const yama = judgePtraceScope(() => readPtraceScope());
+	const yamaFix = yama.reason === "too-strict"
+		? `this host's kernel.yama.ptrace_scope is ${yama.scope}, which also stops the OpenShell sandbox from observing a job well enough to let it reach the network, so every job here would start and then fail; set it to exactly 1 (\`sysctl -w kernel.yama.ptrace_scope=1\`, and in /etc/sysctl.d to keep it)`
+		: yama.scope === 0
+			? `this host's kernel.yama.ptrace_scope is 0, so a job's tools could read the memory of the processes holding the key that signs its result; set it to 1 (\`sysctl -w kernel.yama.ptrace_scope=1\`, and in /etc/sysctl.d to keep it), or every job here is refused`
+			: `${PTRACE_SCOPE_PATH} cannot be read here (a kernel without Yama, or not Linux), so whether a job's tools could read its key holders' memory is not known, and every job here is refused; run the gateway on a Linux host whose kernel has Yama at exactly 1`;
+	checks.push(yama.ok ? { ok: true, label: `openshell: Yama ptrace_scope is 1 (a tool cannot read its ancestor, the broker can)` } : { ok: false, label: "openshell: Yama ptrace_scope is exactly 1", fix: yamaFix });
+
+	const labels = await run(engine, ["image", "inspect", "--format", '{{index .Config.Labels "dev.pi-dispatch.capabilities"}}', image]);
+	const caps = labels.code === 0 ? labels.stdout.trim().split(",") : null;
+	// Issue #730: both modes. Said only when the image was read; the store line below says when it was not.
+	if (caps !== null) checks.push(caps.includes("observableRunner") ? { ok: true, label: `openshell: the job image (${image}) declares observableRunner` } : { ok: false, label: `openshell: the job image (${image}) declares observableRunner`, fix: "use a job image built after issue #730 (ghcr.io/edgehero/pi-job:latest, or rebuild yours FROM it): it starts the runner from a node the sandbox can observe, without which no job here reaches its model" });
+	// Bind mode alone reads the `mounts` layout, so `sandboxLayout` is copy mode's line only.
+	if (modes.copy !== true) {
+		checks.push(caps === null ? { ok: false, label: `openshell: the job image (${image}) is in ${engine}'s store`, fix: `build or pull ${image} into ${engine}, the store the gateway runs images from` } : { ok: true, label: `openshell: the job image (${image}) is in ${engine}'s store` });
+		return checks;
+	}
+	checks.push(caps === null ? { ok: false, label: `openshell: the job image (${image}) is in ${engine}'s store`, fix: `build or pull ${image} into ${engine}, the store the gateway runs images from` } : caps.includes("sandboxLayout") ? { ok: true, label: `openshell: the job image (${image}) declares sandboxLayout` } : { ok: false, label: `openshell: the job image (${image}) declares sandboxLayout`, fix: "use a job image built after issue #683 (ghcr.io/edgehero/pi-job:latest, or rebuild yours FROM it): its runner finds the job under /sandbox and carries pi-landlock" });
+	return checks;
+}
+
+/**
+ * Bind mode's lines (issue #686 part 3). The settings line asks the adapter's own probe (`bindProbeArgs`) and judges the
+ * answer with the adapter's own reader (`judgeBindAnswer`), so doctor and the per-job gate cannot disagree; its fix is
+ * the gateway.toml to write for this engine. Upstream's warning is a ⚠ on every run, by design: it is true of every host
+ * that runs bind mode, and what holds instead is named in its fix.
+ */
+async function bindChecks({ os, run, engine, image, mkdtemp, rmdir, platform, ids }) {
+	const checks = [];
+	if (engine !== "docker") {
+		checks.push({ ok: false, label: "openshell-bind: the gateway's engine is docker", fix: "bind mode was measured on OpenShell's Docker driver only, and the worker refuses it on Podman (a rootless Podman maps the sandbox's uid away from the worker's); set PI_OPENSHELL_ENGINE=docker, or run the copy venue (openshell)" });
+		return checks;
+	}
+	const toml = gatewayTomlFor(engine);
+	const fixFor = (setting) => `the gateway refuses binds (${setting}); write this into ${GATEWAY_TOML_WHERE}, then restart the gateway:\n${toml}`;
+	const idRead = await run(engine, ["image", "inspect", "--format", "{{.Id}}", image]);
+	const id = idRead.code === 0 ? idRead.stdout.trim() : "";
+	if (!/^sha256:[0-9a-f]{64}$/.test(id)) {
+		checks.push({ ok: true, warn: true, label: "openshell-bind: whether the gateway admits binds could not be asked (the job image is not in the engine's store)", fix: `build or pull ${image} into ${engine}, then run doctor again; the gateway needs, in ${GATEWAY_TOML_WHERE}:\n${toml}` });
+	} else {
+		let source = null;
+		let answer;
+		try {
+			source = mkdtemp();
+			// In the job namespace and owner-labelled, so a probe that was made after all is the reaper's if this delete fails.
+			const name = `pi-job-s${randomBytes(6).toString("hex").slice(0, 11)}`;
+			// 60 s, the adapter's own bound: an admitting gateway answers only after provisioning.
+			const probe = await os(bindProbeArgs({ name, image: id, source, engine, ownerLabel: OWNER_LABEL, owner: OWNER, modeLabel: MODE_LABEL }), { timeoutMs: 60_000 });
+			// Deleted on every answer: an admitting gateway refuses the probe at provisioning and leaves it in phase
+			// `Error` (measured); a settings refusal makes nothing, so this delete is a no-op there.
+			await os(["sandbox", "delete", name]);
+			answer = probe.code === 0 ? { admitted: true } : judgeBindAnswer(`${probe.stderr} ${probe.stdout}`);
+		} catch {
+			answer = {};
+		} finally {
+			if (source !== null) {
+				try {
+					rmdir(source);
+				} catch {}
+			}
+		}
+		if (answer.admitted) checks.push({ ok: true, label: "openshell-bind: the gateway admits bind mounts (allow_driver_config, enable_bind_mounts, resource admission off)" });
+		else if (answer.setting) checks.push({ ok: false, label: "openshell-bind: the gateway admits bind mounts", fix: fixFor(answer.setting) });
+		else checks.push({ ok: true, warn: true, label: "openshell-bind: whether the gateway admits bind mounts could not be read", fix: `the probe create answered in words the worker does not read; the gateway needs, in ${GATEWAY_TOML_WHERE}:\n${toml}` });
+	}
+	// Review round 1 (#714), M2: who a job runs as, by the adapter's rule (`decideOpenshellBindUser`: `local`'s
+	// `decideJobUser` over the engine's `docker info`, then `resolveImageUser` with the image's capabilities).
+	{
+		const desktop = platform === "darwin" || platform === "win32";
+		const info = desktop ? null : await run(engine, [...DAEMON_FACTS_ARGS]);
+		const parsed = info && info.code === 0 ? parseDaemonFacts(info.stdout) : null;
+		const daemon = parsed?.facts ? { answered: true, facts: parsed.facts } : { answered: false, reason: "no-daemon-facts", transient: true };
+		const capsRead = await run(engine, ["image", "inspect", "--format", '{{index .Config.Labels "dev.pi-dispatch.capabilities"}}', image]);
+		const capabilities = capsRead.code === 0 ? capsRead.stdout.trim().split(",") : [];
+		const chosen = resolveImageUser(decideJobUser({ platform, euid: ids.euid, egid: ids.egid, endpoint: { local: true }, daemon }), { capabilities, euid: ids.euid, egid: ids.egid });
+		if (chosen.refused) checks.push({ ok: false, label: "openshell-bind: a uid the job may run as exists", fix: `${JOB_USER_FIX[chosen.cause] ?? "the job user could not be decided"} (the openshell-bind venue binds the job's directories, which the sandbox reads and writes as its uid)` });
+		else if (chosen.unavailable) checks.push({ ok: true, warn: true, label: `openshell-bind: who a job runs as could not be read (\`${engine} info\` did not answer)`, fix: `make \`${engine} info\` answer for this account; the venue decides the job's uid from it, before each job` });
+		else checks.push({ ok: true, label: chosen.user ? `openshell-bind: jobs run as uid:gid ${chosen.user} (the policy's run_as_user) with HOME=/home/pi` : "openshell-bind: jobs run as the image's own user (uid 1001)" });
+	}
+	checks.push({ ok: true, warn: true, label: `openshell-bind: upstream warns: "${UPSTREAM_BIND_WARNING}"`, fix: "on this venue what holds is the worker's own read-only binds (/job, /inbox, the overlay) and the policy entries that list every bind target; /workspace, /session and /outbox are the job's to write, as on local, and a folder job edits the operator's folder in place" });
+	return checks;
+}