@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/host-registry.mjs

@@ -33,9 +33,17 @@
  * `jobs` (issue #599, phase 2) is the one field that carries a list: JSON of the jobs this host runs now, ids and
  * integers only, built and read back by `live-jobs.mjs`, whose header argues each field against this rule. The reader
  * below parses it through that module's allowlist, so a row's `jobs` is an array (or null), never the raw string.
+ *
+ * VALKEY'S CLOCK IS USED ONLY AS A DURATION (issue #737). The reader asks each row's `PTTL` beside its `HGETALL`, and
+ * `ttlMs - PTTL` is how long ago the row's last PEXPIRE landed, counted by the server that holds it. That is a length
+ * of time, never an instant: no field here is ever compared with Valkey's own time of day. Set beside `beatAt` (an
+ * instant on the HOST's clock) and the reader's own `now()`, it gives a third party's estimate of how far the two
+ * machines' clocks disagree (`skewMs`), and it says when a row has no expiry at all (`noExpiry`), which is a row the TTL
+ * will never remove.
  */
 
 import { parseJobsMore, parseLiveJobs } from "./live-jobs.mjs";
+import { WORKER_NAME_RE } from "./worker-name.mjs";
 
 /** The index. A SET cannot expire its members, so the leak is handled by the reader, as `wait:held` does. */
 export const HOST_SET = "host:live";
@@ -54,6 +62,14 @@ export const HOST_BEAT_MS = 15_000;
  */
 export const HOST_TTL_MS = 90_000;
 
+/**
+ * The smallest `skewMs` a reader may call a clock skew (issue #737). TWO BEATS, and the margin is not decoration:
+ * `skewMs` is measured from the row's last PEXPIRE, and a read landing between a beat's HSET (the new `beatAt`) and its
+ * PEXPIRE sees the previous beat's expiry, so the estimate can be off by one beat period, and by a round trip besides.
+ * Below this, a difference is noise a reader must not report.
+ */
+export const HOST_SKEW_CLAIM_MS = 30_000;
+
 /**
  * Build the registry accessor. `redis` is the client the budget and the wait state already share.
  *
@@ -109,7 +125,8 @@ export function makeHostRegistry({ redis, name, now = () => Date.now(), ttlMs =
 		for (const [k, v] of Object.entries(fields)) {
 			let resolved;
 			try {
-				resolved = typeof v === "function" ? v() : v;
+				// A dependent display fact can bind to this row's generation without guessing another clock.
+				resolved = typeof v === "function" ? v(fields) : v;
 			} catch {
 				resolved = ""; // a fact that cannot be computed is absent, never a reason to skip the beat
 			}
@@ -275,8 +292,22 @@ export function makeHostRegistry({ redis, name, now = () => Date.now(), ttlMs =
  * `{ unreachable }` and `[]` are DIFFERENT ANSWERS and must never be collapsed by a caller, even where
  * one treats them alike: "there are no other hosts" and "I could not find out" differ, and a panel that
  * renders the second as the first tells an operator their fleet is gone when Valkey merely blinked.
+ *
+ * Each row also carries three fields read off the key's `PTTL` (issue #737), all null where the client has no `pttl`,
+ * where the PTTL failed or timed out, or where the key went between the two reads (-2):
+ *   - `ttlAgeMs`: how long ago the row's last PEXPIRE landed, `ttlMs - PTTL` (never below 0), on Valkey's clock as a
+ *     duration. `ttlMs` is the TTL the writer sets, `HOST_TTL_MS` for every worker.
+ *   - `skewMs`: `(now() - beatAt) - ttlAgeMs`, the reader's clock minus the host's, as a third party measures it.
+ *     Positive: the host's clock is behind. A round trip and up to one beat period of noise; a reader claims a skew only
+ *     past `HOST_SKEW_CLAIM_MS`. Null without a readable `beatAt`.
+ *   - `noExpiry`: true when the key has no expiry at all (-1), which the TTL will never remove; false when it has one.
+ *     A reader walks `host:live`, and a beat SADDs only after its PEXPIRE, so a reader meets it only under a name an
+ *     EARLIER beat indexed: for a moment when a beat re-creates a row that expired while its name stayed, and for good
+ *     when the process died between that HSET and its PEXPIRE.
+ * The PTTL goes out beside the HGETALL, in the same tick and each under its own bound, so it costs no round trip; a
+ * failed PTTL costs these three fields and never the row.
  */
-export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs = REGISTRY_OP_TIMEOUT_MS, prune = true } = {}) {
+export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs = REGISTRY_OP_TIMEOUT_MS, prune = true, ttlMs = HOST_TTL_MS } = {}) {
 	let names;
 	try {
 		names = await bounded(redis.smembers(HOST_SET), timeoutMs);
@@ -287,9 +318,23 @@ export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs =
 		return { unreachable: err?.message ?? "registry unreadable" };
 	}
 	const hosts = [];
+	const withTtl = typeof redis?.pttl === "function";
 	for (const member of names ?? []) {
+		// A name outside the worker name charset (`WORKER_NAME_RE`: a letter or a digit, then letters, digits, `.`, `_` and
+		// `-`, at most 64 in all) is no host's: anything with the Valkey's URL can SADD one, and a reader that took it would
+		// print it wherever rows are drawn (a 3,000-character member widened the console's page to 43,000 px). The charset
+		// alone, looser than the boot rule, which also refuses a `.json` or `.log` tail on `PI_WORKER_NAME` (`config.mjs`).
+		// Skipped before its row is even read, and never pruned: removing what someone else wrote is not a reader's call,
+		// and the member costs only its place in the set.
+		if (typeof member !== "string" || !WORKER_NAME_RE.test(member)) continue;
 		try {
-			const row = await bounded(redis.hgetall(hostKey(member)), timeoutMs);
+			const key = hostKey(member);
+			// Both issued before either is awaited. The PTTL's own failure (a throw, a rejection, a hang past its bound)
+			// is null here, so only the HGETALL decides whether the row is read at all.
+			const [row, pttl] = await Promise.all([
+				bounded(redis.hgetall(key), timeoutMs),
+				withTtl ? bounded((async () => redis.pttl(key))(), timeoutMs).catch(() => null) : null,
+			]);
 			if (!row || Object.keys(row).length === 0) {
 				// `prune: false` for a reader that promises to write nothing (the capacity report, issue #599): the stale member
 				// is skipped the same, and left for the next pruning reader.
@@ -297,9 +342,13 @@ export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs =
 				continue;
 			}
 			const beatAt = typeof row.beatAt === "string" && row.beatAt.trim() !== "" ? Number(row.beatAt) : NaN;
+			const nowMs = now();
 			// The running jobs through the allowlist (issue #599, phase 2): an array, or null where the row publishes none (a
 			// worker from before the field) or none that parses. A listed entry that does not read is a running job not
 			// counted, so it joins `jobsMore` rather than vanishing.
+			// The row's own `name` stands for the member only when it holds to the same rule, else the row is no host's.
+			const name = row.name || member;
+			if (typeof name !== "string" || !WORKER_NAME_RE.test(name)) continue;
 			const live = parseLiveJobs(row.jobs);
 			const more = parseJobsMore(row.jobsMore);
 			hosts.push({
@@ -309,11 +358,12 @@ export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs =
 				// A row that HAS a `jobs` value that is not a list: how many it runs is unknown, which a reader must say
 				// rather than read as a worker from before the field.
 				jobsUnreadable: live.jobs === null && typeof row.jobs === "string" && row.jobs !== "",
-				name: row.name || member,
+				name,
 				// Derived rather than stored, so the panel can say "stale 2m" about a row that still lives.
 				// A row whose clock is AHEAD of ours reads as 0 rather than negative: the difference is the
-				// skew between two machines, which is its own signal and not this field's to report.
-				staleMs: Number.isFinite(beatAt) ? Math.max(0, now() - beatAt) : null,
+				// skew between two machines, which is its own signal and not this field's to report (`skewMs` is).
+				staleMs: Number.isFinite(beatAt) ? Math.max(0, nowMs - beatAt) : null,
+				...expiryFields(pttl, { ttlMs, beatAt, nowMs }),
 			});
 		} catch {
 			// One unreadable row degrades that row, never the listing.
@@ -322,3 +372,13 @@ export async function readLiveHosts(redis, { now = () => Date.now(), timeoutMs =
 	hosts.sort((a, b) => String(a.name).localeCompare(String(b.name)));
 	return { hosts };
 }
+
+/** `readLiveHosts`'s three PTTL fields (see there). `pttl` is the reply, or null where none was read. */
+function expiryFields(pttl, { ttlMs, beatAt, nowMs }) {
+	if (pttl === -1) return { ttlAgeMs: null, skewMs: null, noExpiry: true };
+	// -2 (the key went between the two reads), a failed read, or a reply that is not a whole number: nothing is known.
+	if (!Number.isSafeInteger(pttl) || pttl < 0) return { ttlAgeMs: null, skewMs: null, noExpiry: null };
+	const ttl = Number.isSafeInteger(ttlMs) && ttlMs > 0 ? ttlMs : HOST_TTL_MS;
+	const ttlAgeMs = Math.max(0, ttl - pttl);
+	return { ttlAgeMs, skewMs: Number.isFinite(beatAt) ? nowMs - beatAt - ttlAgeMs : null, noExpiry: false };
+}

package/src/host-telemetry.mjs

@@ -0,0 +1,92 @@
+/** Host self-description only: no consumer may use these facts to admit or refuse a job (#748). */
+import { BACKEND_NAMES } from "./backends.mjs";
+import { LIVE_JOB_ID_RE, publishedJobId } from "./live-jobs.mjs";
+import { createHash } from "node:crypto";
+import { imageRefProblem } from "./image-ref.mjs";
+import { RUN_KINDS } from "./forges.mjs";
+
+export const SANDBOXES_MAX = 32;
+export const SANDBOX_READ_MS = 60_000;
+export const CPU_RESERVE_WORDS = Object.freeze(["held", "no-parent", "unmanaged", "budget-unknown", "unreadable", "unset", "differs"]);
+const integer = (v) => Number.isSafeInteger(v) && v >= 0;
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const decoded = (raw) => {
+	if (typeof raw !== "string") return raw;
+	if (raw.length > 32 * 1024) return null;
+	try { return JSON.parse(raw); } catch { return null; }
+};
+
+/** Unknown and unreadable are null, never an invented empty inventory. */
+export function parseSandboxes(raw) {
+	const list = decoded(raw);
+	if (!Array.isArray(list) || list.length > SANDBOXES_MAX) return null;
+	// Corruption must not turn a nonempty inventory into a false claim that no workspace remains.
+	if (list.some((r) => !object(r) || typeof r.id !== "string" || !LIVE_JOB_ID_RE.test(r.id) || !BACKEND_NAMES.includes(r.v) || !(r.until === null || integer(r.until)) || typeof r.pin !== "boolean")) return null;
+	if (list.some((r) => (r.prepared !== undefined && typeof r.prepared !== "boolean") || (r.canOpen !== undefined && typeof r.canOpen !== "boolean") || (r.generation !== undefined && !/^[a-f0-9]{64}$/.test(r.generation)))) return null;
+	if (list.some((r) => (r.image !== undefined && imageRefProblem(r.image)) || (r.kind !== undefined && !RUN_KINDS.includes(r.kind)))) return null;
+	return list.map(({ id, v, until, pin, prepared, canOpen, generation, image, kind }) => ({ id, v, until, pin, ...(prepared !== undefined ? { prepared } : {}), ...(canOpen !== undefined ? { canOpen } : {}), ...(generation !== undefined ? { generation } : {}), ...(image !== undefined ? { image } : {}), ...(kind !== undefined ? { kind } : {}) }));
+}
+
+/** An opaque incarnation binds a confirmation to the workspace, without publishing its host path. */
+export function sandboxManifestGeneration(m) {
+	if (typeof m?.jobId !== "string" || typeof m?.image !== "string" || typeof m?.workspace !== "string" || typeof m?.createdAt !== "string") return null;
+	return createHash("sha256").update(JSON.stringify([m.jobId, m.image, m.workspace, m.createdAt, m.backend ?? "local", m.baseSha ?? null, m.prepared?.requestDigest ?? null])).digest("hex");
+}
+
+export function parseBudgetFrom(raw) {
+	const r = decoded(raw);
+	if (!object(r)) return null;
+	const out = {};
+	for (const key of ["memMode", "cpuMode"]) {
+		if (!["auto", "value", "off"].includes(r[key])) return null;
+		out[key] = r[key];
+	}
+	for (const key of ["memTotalMiB", "memReserveMiB", "cpuTotalCenti", "cpuReserveCenti"]) {
+		if (r[key] !== null && !integer(r[key])) return null;
+		out[key] = r[key];
+	}
+	for (const key of ["memFloored", "cpuFloored"]) {
+		if (typeof r[key] !== "boolean") return null;
+		out[key] = r[key];
+	}
+	return out;
+}
+
+export function parseCpuReserve(raw) {
+	const list = decoded(raw);
+	if (!Array.isArray(list)) return null;
+	const seen = new Set();
+	return list.filter((r) => object(r) && BACKEND_NAMES.includes(r.venue) && CPU_RESERVE_WORDS.includes(r.status) && !seen.has(r.venue) && seen.add(r.venue)).map((r) => ({ venue: r.venue, status: r.status, wantCenti: integer(r.wantCenti) ? r.wantCenti : null, quotaCenti: integer(r.quotaCenti) ? r.quotaCenti : null }));
+}
+
+/** Cache filesystem work, not the heartbeat. The caller supplies the store's actual deadline rule. */
+export function makeSandboxTelemetry({ list, deadline, retentionHours, canOpen = null, now = () => Date.now(), log = () => {} }) {
+	let readAt = null;
+	let unreadable = false;
+	let cached = { sandboxes: "", sandboxesMore: "", sandboxRetentionHours: String(retentionHours) };
+	return () => {
+		const at = now();
+		if (readAt !== null && at >= readAt && at - readAt < SANDBOX_READ_MS) return cached;
+		readAt = at;
+		try {
+			const all = list().map((m) => {
+				const id = publishedJobId(m.jobId);
+				const venue = Object.hasOwn(m, "backend") ? m.backend : "local";
+				if (!id || !BACKEND_NAMES.includes(venue)) return null;
+				// Old manifests may lack these facts. Corrupt present facts make the inventory unknown, never invented.
+				if ((m.image !== undefined && imageRefProblem(m.image)) || (m.kind !== undefined && !RUN_KINDS.includes(m.kind))) throw new Error("invalid sandbox image or kind");
+				const d = deadline(m, retentionHours);
+				const generation = sandboxManifestGeneration(m);
+				return { id, v: venue, until: integer(d.until) ? d.until : null, pin: d.source === "pin", ...(m.origin === "prepared" ? { prepared: true } : {}), ...(generation ? { generation } : {}), ...(typeof canOpen === "function" ? { canOpen: canOpen(m) === true } : {}), ...(m.image !== undefined ? { image: m.image } : {}), ...(m.kind !== undefined ? { kind: m.kind } : {}), created: Date.parse(m.createdAt) || 0 };
+			}).filter(Boolean).sort((a, b) => b.created - a.created || a.id.localeCompare(b.id));
+			unreadable = false;
+			cached = { sandboxes: JSON.stringify(all.slice(0, SANDBOXES_MAX).map(({ created, ...r }) => r)), sandboxesMore: String(Math.max(0, all.length - SANDBOXES_MAX)), sandboxRetentionHours: String(retentionHours) };
+		} catch {
+			// A failed read is absent telemetry, never a claim that the host has no retained workspaces.
+			if (!unreadable) log("host_sandboxes_unreadable", { reason: "read-failed" });
+			unreadable = true;
+			cached = { sandboxes: "", sandboxesMore: "", sandboxRetentionHours: String(retentionHours) };
+		}
+		return cached;
+	};
+}

package/src/http-body.mjs

@@ -0,0 +1,78 @@
+/**
+ * The forge-neutral half of a webhook endpoint: read a bounded raw body, recognise a JSON content type,
+ * and write a small JSON response.
+ *
+ * Extracted from verify.mjs when a second forge arrived (issue #42), and extracted rather than copied for
+ * one reason: `readRawBody`'s per-chunk accounting is a memory bound on attacker-controlled input. Two
+ * copies of a security limit drift -- one gets the fix, the other keeps the bug -- and the copy that keeps
+ * it is the one nobody is looking at. Verification itself is NOT here; each forge's gate owns its own,
+ * because that is exactly the part that differs.
+ *
+ * Nothing here reads a header that identifies a forge, and nothing here decides whether a request is
+ * trusted. A caller must still verify before parsing a single field (CONST-HMAC-OVER-RAW-BODY).
+ *
+ * Moved from the receiver to the worker's exports (issue #640) for the same reason it was extracted: the operator
+ * console reads request bodies too, and the console must not import the receiver (its only export is `./start`, and an
+ * admin surface on the receiver is the rejected option `DES-OPERATOR-CONSOLE` keeps). `respond` sets no security
+ * headers; the console wraps every response in its own header set and never calls it directly.
+ */
+
+/** Accept `application/json`, ignoring any parameters and case. */
+export function isJsonContentType(contentType) {
+	return String(contentType ?? "").split(";")[0].trim().toLowerCase() === "application/json";
+}
+
+/**
+ * Collect the request stream into a Buffer, bounded by `limit`. Accumulation is checked on every
+ * chunk so the buffer can never grow past the cap: exceeding it destroys the request and rejects
+ * with `code: "E_PAYLOAD_TOO_LARGE"` rather than reading an unbounded body into memory.
+ */
+export function readRawBody(req, limit) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		let settled = false;
+
+		const cleanup = () => {
+			req.removeListener("data", onData);
+			req.removeListener("end", onEnd);
+			req.removeListener("error", onError);
+		};
+		const onData = (chunk) => {
+			if (settled) return;
+			size += chunk.length;
+			if (size > limit) {
+				settled = true;
+				cleanup();
+				req.destroy();
+				const err = new Error("payload too large");
+				err.code = "E_PAYLOAD_TOO_LARGE";
+				reject(err);
+				return;
+			}
+			chunks.push(chunk);
+		};
+		const onEnd = () => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(Buffer.concat(chunks));
+		};
+		const onError = (err) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(err);
+		};
+
+		req.on("data", onData);
+		req.on("end", onEnd);
+		req.on("error", onError);
+	});
+}
+
+/** Write a small JSON body with an explicit status. `writeHead` sets the status code on the response. */
+export function respond(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json" });
+	res.end(JSON.stringify(body));
+}

package/src/image-preflight.mjs

@@ -16,10 +16,9 @@ import { FORGE_MCP_SERVER_NAME } from "./mcp-config.mjs";
  */
 
 /**
- * The image this job runs in: the job's own `image` when it carries one, otherwise the deployment default
- * (`PI_JOB_IMAGE`). Today nothing sets the per-job field, so every job resolves the default; the seam exists
- * because the preflight and the argv builder must never disagree about which tag they mean, and one function
- * is how that is guaranteed rather than hoped for.
+ * The image this job runs in: the job's own `image` when it carries one (a trigger's `run.image`, the CLI's `--image`),
+ * otherwise the deployment default (`PI_JOB_IMAGE`). The preflight and the argv builder must never disagree about which
+ * tag they mean, and one function is how that is guaranteed rather than hoped for.
  */
 export function resolveJobImage(job, defaultImage) {
 	const image = job?.image ?? defaultImage;
@@ -45,8 +44,9 @@ export function resolveJobImage(job, defaultImage) {
  *   { forgeUnsupported }  -- present, but declares it cannot serve this job's forge => POLICY, refuse
  *   { <gate.result>, declared } -- present, but does not declare a capability this job needs, one key per
  *                            CAPABILITY_GATES row (replicaUnsupported, commandUnsupported,
- *                            excludeToolsUnsupported, modelPolicyUnsupported, costCapUnsupported, mcpUnsupported,
- *                            forgeMcpUnsupported)
+ *                            excludeToolsUnsupported, loadExclusionsUnsupported, modelPolicyUnsupported, costCapUnsupported, mcpUnsupported,
+ *                            forgeMcpUnsupported, awaitInputUnsupported, progressUnsupported, recoverUnsupported,
+ *                            steerUnsupported)
  *                            => POLICY
  *
  * A non-zero `docker image inspect` is AMBIGUOUS -- an absent image and an unreachable daemon both exit 1 --
@@ -60,10 +60,19 @@ export function resolveJobImage(job, defaultImage) {
  * `unavailable` and retry; if it comes up between them we report `missing` on an image that is genuinely
  * absent. Nothing is cached, deliberately -- see the note at the call site in start.mjs.
  */
-export function makeImagePreflight({ image, spawnFn = spawn, bin = "docker" }) {
+export function makeImagePreflight({ image, spawnFn = spawn, bin = "docker", copies = false, brokered = false }) {
+	// Issue #683: `copies` is the venue's, not the job's: a venue that copies the job's files into the box (`binds:
+	// false`, `openshell`) needs the `sandboxLayout` row below on EVERY job, and a binding venue never does. A boolean
+	// and nothing else, so a truthy string from a hand-built bundle cannot arm a gate it did not mean.
+	if (typeof copies !== "boolean") throw new TypeError("makeImagePreflight: `copies` must be a boolean");
+	// Issue #730: `brokered` is the venue's too: a venue whose every connection is mediated by a broker that reads the
+	// caller's memory (both OpenShell venues, copy and bind) needs the `observableRunner` row below on EVERY job. A
+	// boolean, for the same reason.
+	if (typeof brokered !== "boolean") throw new TypeError("makeImagePreflight: `brokered` must be a boolean");
 	// Issue #354: `bin` is the venue's CLI. Both probes go through it, because a `podman image inspect` answered by one
 	// store and an `info` answered by another daemon would tell "absent" from "unavailable" about two different hosts.
-	return async function imagePreflight(job) {
+	return async function imagePreflight(job, { subscriptionAuthRequired = false } = {}) {
+		if (typeof subscriptionAuthRequired !== "boolean") throw new TypeError("imagePreflight: subscriptionAuthRequired must be a boolean");
 		const wanted = resolveJobImage(job, image);
 		// --format keeps docker from serialising the whole image manifest to a pipe we ignore.
 		//
@@ -103,13 +112,16 @@ export function makeImagePreflight({ image, spawnFn = spawn, bin = "docker" }) {
 			// the job actually carries the feature it guards. The gates, their order and why each exists are
 			// the CAPABILITY_GATES table; the first one this job needs and the image lacks refuses.
 			for (const gate of CAPABILITY_GATES) {
-				if (gate.needed(job) && !(capabilities ?? []).includes(gate.token)) {
+				if (gate.needed(job, { copies, brokered, subscriptionAuthRequired }) && !(capabilities ?? []).includes(gate.token)) {
 					return { [gate.result]: wanted, declared: capabilities ?? [] };
 				}
 			}
 			// `capabilities` rides the ok result for issue #341's job-user gate, which needs `anyUid` and runs after
 			// this preflight; an image that declares nothing reads as [].
-			return { ok: true, image: wanted, piVersion, imageDigest, capabilities: capabilities ?? [] };
+			// `fromJob`: a run on an image its job named says nothing of the image this host runs everything else on, which only
+			// this function can tell, since it alone holds both (the record's `imageFromJob`, loaded-record.mjs). A job naming this
+			// host's own default ran on this host's own image, so it is no such run.
+			return { ok: true, image: wanted, piVersion, imageDigest, capabilities: capabilities ?? [], ...(wanted !== image ? { fromJob: true } : {}) };
 		}
 		if ((await runDocker(bin, spawnFn, ["info"])).code === 0) return { missing: wanted };
 		return { unavailable: wanted };
@@ -124,7 +136,8 @@ export function makeImagePreflight({ image, spawnFn = spawn, bin = "docker" }) {
  * row whose `needed(job)` holds and whose `token` the image does not declare, before any spend.
  *
  *   token    the capability the image must declare
- *   needed   whether this job carries the feature (a job that does not pays nothing for the row)
+ *   needed   whether this job carries the feature (a job that does not pays nothing for the row), given the job and
+ *            the venue's `{ copies }` (issue #683: the one row a venue rather than a trigger arms)
  *   result   the key the preflight result names the image under, which the processor branches on
  *   reason   the run record's reason for the refusal
  *   event    the worker log event
@@ -135,8 +148,7 @@ export function makeImagePreflight({ image, spawnFn = spawn, bin = "docker" }) {
  * A new image-gated feature (`costCap`, `modelPolicy`) is a row here, not another branch in two files. Order
  * is the order the branches had, so a job carrying several features is refused for the same one as before.
  */
-export const CAPABILITY_GATES = Object.freeze([
-	// REQ-REPLICA-RUNS: an image built before it bakes a HARD_RULES.md whose rule 3 hard-codes `pi/issue-<n>`
+export const CAPABILITY_GATES = Object.freeze([	// REQ-REPLICA-RUNS: an image built before it bakes a HARD_RULES.md whose rule 3 hard-codes `pi/issue-<n>`
 	// as a SYSTEM rule, which the model treats as authoritative over the user prompt naming `pi/issue-<n>-r2`.
 	// Both replicas would push to one branch: the push race the feature exists to avoid, two runs billed.
 	Object.freeze({
@@ -225,6 +237,107 @@ export const CAPABILITY_GATES = Object.freeze([
 		event: "refused_image_await_input_unsupported",
 		comment: (image, declared) => `Refused: the job image "${image}" does not declare support for stopping to wait for an answer (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore \`run.awaitInput\`. Rebuild the image from a version that has this feature. Not run.`,
 	}),
+	// Issue #644: a runner that predates run.progress reads no PI_REPORT_PROGRESS, so the agent is never offered the
+	// report_progress tool and the trigger's phases never appear, on a run that otherwise reads as fine. Refused for the
+	// awaitInput row's reason: the trigger asked for something this image cannot give.
+	Object.freeze({
+		token: "reportProgress",
+		needed: (job) => job?.progress === true,
+		result: "progressUnsupported",
+		reason: "job-image-progress-unsupported",
+		event: "refused_image_progress_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare support for reporting progress (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore \`run.progress\`. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// Issue #645: a runner that predates run.recover reads no PI_RECOVER and keeps no checkpoint, so a run the worker
+	// loses would fail exactly as an unarmed one does while the trigger promised it would continue. Refused for the
+	// awaitInput row's reason: the trigger asked for something this image cannot give, and saying so costs nothing.
+	Object.freeze({
+		token: "recover",
+		needed: (job) => job?.recover === true,
+		result: "recoverUnsupported",
+		reason: "job-image-recover-unsupported",
+		event: "refused_image_recover_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare support for continuing a lost run from its checkpoint (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore \`run.recover\`. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// Issue #646: a runner that predates run.steer reads no PI_STEER and never looks at /inbox, so every message an
+	// operator sent would be accepted and then never reach the agent. Refused for the recover row's reason: the trigger
+	// asked for something this image cannot give, and saying so costs nothing.
+	Object.freeze({
+		token: "steer",
+		needed: (job) => job?.steer === true,
+		result: "steerUnsupported",
+		reason: "job-image-steer-unsupported",
+		event: "refused_image_steer_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare support for receiving messages while it runs (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore \`run.steer\`. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// Issue #683: on a venue that copies the job's files (`openshell`), a runner that predates PI_JOB_LAYOUT looks for
+	// /job, finds nothing in a sandbox whose files sit under /sandbox, and exits "missing job input" after the sandbox
+	// was made and the budget reserved; and without /opt/pi-dispatch/pi-landlock its /job would be writable by the
+	// agent. Armed by the VENUE, on every job there, never by a trigger, so a binding venue never reads the token.
+	Object.freeze({
+		token: "sandboxLayout",
+		needed: (_job, { copies } = {}) => copies === true,
+		result: "sandboxLayoutUnsupported",
+		reason: "job-image-sandbox-layout-unsupported",
+		event: "refused_image_sandbox_layout_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare support for a venue that copies the job's files into its sandbox (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would not find them, and could not keep the agent from rewriting them. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// Issue #730: on a venue whose connections are mediated by a broker that must read the caller's memory (OpenShell,
+	// both modes), a runner started from the exec-only node cannot be read, so its own provider call and every tool's
+	// connection below it are refused: the job would reserve, start, and fail its first model call. An image that has
+	// the readable copy and the entrypoint that chooses it declares `observableRunner`. Armed by the VENUE, on every job
+	// there, never by a trigger.
+	Object.freeze({
+		token: "observableRunner",
+		needed: (_job, { brokered } = {}) => brokered === true,
+		result: "observableRunnerUnsupported",
+		reason: "job-image-observable-runner-unsupported",
+		event: "refused_image_observable_runner_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare support for a venue whose sandbox must observe the runner to let it reach the network (\`dev.pi-dispatch.capabilities\` ${declared}), so the job could reach neither its model nor anything else. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	Object.freeze({
+		token: "fork",
+		needed: (job) => job?.fork !== undefined || job?.thinkingLevel !== undefined,
+		result: "forkUnsupported",
+		reason: "job-image-fork-unsupported",
+		event: "refused_image_fork_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare managed session forks (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore the selected entry or thinking level. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	Object.freeze({
+		token: "approvalGates",
+		needed: (job) => Array.isArray(job?.gates) && job.gates.length > 0,
+		result: "approvalGatesUnsupported",
+		reason: "job-image-approval-gates-unsupported",
+		event: "refused_image_approval_gates_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare approval gates (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore \`run.gates\`. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+
+	Object.freeze({
+		token: "modelFailover",
+		needed: (job) => job?.fallbackModels !== undefined,
+		result: "modelFailoverUnsupported",
+		reason: "job-image-model-failover-unsupported",
+		event: "refused_image_model_failover_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare model-failover support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner cannot report the authenticated failure and replay evidence this job requires. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	Object.freeze({ token: "modelRoles", needed: (job) => job?.modelRoles !== undefined, result: "modelRolesUnsupported", reason: "job-image-model-roles-unsupported", event: "refused_image_model_roles_unsupported", comment: (image, declared) => `Refused: the job image "${image}" does not declare modelRoles support (\`dev.pi-dispatch.capabilities\` ${declared}), so it cannot resolve reviewed roles before child calls. Rebuild the image from a version that has this feature. Not run.` }),
+	Object.freeze({ token: "watch", needed: (job) => Boolean(job?.watch), result: "watchUnsupported", reason: "job-image-watch-unsupported", event: "refused_image_watch_unsupported", comment: (image, declared) => `Refused: the job image "${image}" does not declare watch isolation (\`dev.pi-dispatch.capabilities\` ${declared}), so it cannot enforce read-only investigations. Rebuild the image from a version that has this feature. Not run.` }),
+	Object.freeze({ token: "questionGrouping", needed: (job) => Boolean(job?.questionGrouping), result: "questionGroupingUnsupported", reason: "job-image-question-grouping-unsupported", event: "refused_image_question_grouping_unsupported", comment: (image, declared) => `Refused: the job image "${image}" does not declare isolated question grouping (\`dev.pi-dispatch.capabilities\` ${declared}), so it cannot run a classifier without loading an agent. Rebuild the image from a version that has this feature. Not run.` }),
+	Object.freeze({ token: "answerDraft", needed: (job) => Boolean(job?.answerDraft), result: "answerDraftUnsupported", reason: "job-image-answer-draft-unsupported", event: "refused_image_answer_draft_unsupported", comment: (image, declared) => `Refused: the job image "${image}" does not declare restricted answer drafts (\`dev.pi-dispatch.capabilities\` ${declared}), so it cannot enforce source-only drafting without posting tools. Rebuild the image from a version that has this feature. Not run.` }),
+	// Only trusted host connection policy arms this gate. Queued input cannot claim or suppress authentication.
+	Object.freeze({ token: "subscriptionAuth", needed: (_job, { subscriptionAuthRequired = false } = {}) => subscriptionAuthRequired === true, result: "subscriptionAuthUnsupported", reason: "job-image-subscription-auth-unsupported", event: "refused_image_subscription_auth_unsupported", comment: (image, declared) => `Refused: the job image "${image}" does not declare subscription authentication (\`dev.pi-dispatch.capabilities\` ${declared}), so it cannot verify the admitted access snapshot, community adapter or final request cost. Rebuild the image from a version that has this feature. Not run.` }),
+	// Issue #800: a runner that predates them reads no PI_EXCLUDE_EXTENSIONS and no PI_EXCLUDE_EXTENSION_TOOLS, so the overlay extension loads, the tool
+	// stays, and the job records a clean exit. A permission quietly not enforced, as the `excludeTools` row says. A package the worker left out of
+	// PI_PACKAGES stays out on any image, but the worker cannot know a name is only that, so either field arms this.
+	// `run.excludeTools` beside a role map arms it too. That runner reads PI_EXCLUDE_TOOLS for its own session, so the `excludeTools` row above passes, and then
+	// starts a role child on pi's CLI with no `--exclude-tools`, so the child keeps what the trigger removed and the job reads clean. `job.modelRoles` is what says
+	// a child can start: `resolveModelRoles` set it at this pickup, a queued one never survives that, and with no map there is no `subagent` tool. An image with no
+	// role machinery at all never reaches this for that reason: the `modelRoles` row stands above and answers first, in its own words. A list of only a server's
+	// names arms it as well, though a child connects no server: the row's words hold of it, the fix is the same rebuild, and this module holds no table of those names.
+	// One sentence for all of these. REJECTED: naming the keys and the role child, which said "would start a role child" of a job with no role map on an image with no role machinery.
+	Object.freeze({ token: "loadExclusions", needed: (job) => job?.excludeExtensions !== undefined || job?.excludeExtensionTools !== undefined || (job?.excludeTools !== undefined && job?.modelRoles !== undefined), result: "loadExclusionsUnsupported", reason: "job-image-load-exclusions-unsupported", event: "refused_image_load_exclusions_unsupported", comment: (image, declared) => `Refused: the job image "${image}" does not declare support for this job's exclusions (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would not honour them. Rebuild the image from a version that has this feature. Not run.` }),
+	// Issue #796: an image too old to report whether a canary's candidate loaded could only ever read "not reported", on a paid run.
+	Object.freeze({ token: "packageCanary", needed: (job) => job?.packageCanary !== undefined, result: "packageCanaryUnsupported", reason: "job-image-package-canary-unsupported", event: "refused_image_package_canary_unsupported", comment: (image, declared) => `Refused: the job image "${image}" does not declare package canaries (\`dev.pi-dispatch.capabilities\` ${declared}), so it could not report whether the candidate loaded. Rebuild the image from a version that has this feature. Not run.` }),
 ]);
 
 /**
@@ -235,6 +348,36 @@ export const CAPABILITY_GATES = Object.freeze([
  */
 export const EXIT_AUTH_CAPABILITY = "exitAuth";
 
+/**
+ * The capability an image declares when its runner mirrors the session file over stderr as records signed with the exit
+ * key, on PI_TRANSCRIPT=stderr (issue #686, image/runner/src/transcript-mirror.mjs). NOT a gate, like `exitAuth`: no job
+ * is refused for lacking it. On a venue that copies the job's files (`openshell`) it is what the live transcript, run
+ * progress and the status comment come from; an image without it runs there without them (`live_transcript_skipped`,
+ * reason `no-capability`). A binding venue never reads it.
+ */
+export const TRANSCRIPT_STDERR_CAPABILITY = "transcriptStderr";
+
+/**
+ * The capability an image declares when its runner reads steer messages as MAC'd frames on stdin, on
+ * PI_EXIT_AUTH=stdin-frames (issue #686, image/runner/src/steer-frames.mjs): the key as frame 1, read before pi loads,
+ * the stream moved off fd 0 so a tool child inherits /dev/null. NOT a gate, like `transcriptStderr`: `steer` stays the
+ * gate a `run.steer` job needs. On a venue that copies the job's files (`openshell`) it is what steering comes over; an
+ * image without it runs there unsteered (`steerSkipped: "venue-copies"`, as before it existed). A binding venue never
+ * reads it: it keeps the read-only `/inbox` mount, which the agent cannot withdraw a message from.
+ */
+export const STEER_STDIN_CAPABILITY = "steerStdin";
+
+/**
+ * The capability an image declares when its runner reads PI_BUNDLE_ENV=1: a project secret bundle's plain variables
+ * from `bundle-env.json` in the job directory into its own environment (issue #704 part 3, image/runner/src/
+ * bundle-env.mjs). A gate on the OpenShell venues only, judged by their bundle gate rather than a CAPABILITY_GATES row
+ * (the need is known only once the bundle is read, which is after those rows run): a job there that would carry plain
+ * bundle variables on an image without it is refused before spend (`openshell-bundle-image-too-old`), since an older
+ * runner would ignore the file and the job would run without them. Every other venue hands the values as env and never
+ * reads it.
+ */
+export const BUNDLE_ENV_FILE_CAPABILITY = "bundleEnvFile";
+
 /**
  * Exported so the test cannot drift from the format string above. `|` because an image id is
  * `sha256:<hex>` and a version is a version, so neither can contain one -- and because a literal control