@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/init.mjs

@@ -10,7 +10,8 @@
 import { existsSync, copyFileSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
-import { parseBackendList, venuesOf } from "./backends.mjs";
+import { openshellSetupOf, parseBackendList, venuesOf } from "./backends.mjs";
+import { OPENSHELL_BREW_INSTALL, OPENSHELL_GATEWAY_UNIT, OPENSHELL_NO_WINDOWS, OPENSHELL_RELEASE_URL, OPENSHELL_TESTED_VERSION } from "./openshell-cli.mjs";
 import { deploymentVenueEnv } from "./deployment-venue.mjs";
 import { setEnvKeyIfEmpty } from "./env-file.mjs";
 import { PACKAGED_EGRESS_PROXY_CONF } from "./egress-conf-copy.mjs";
@@ -167,7 +168,7 @@ export function runInit(cwd = process.cwd(), deps = {}) {
 	const code = results.some(([verb]) => verb === "refused") ? 1 : 0;
 	if (deps.steps === false) return code;
 	if (deps.venues) {
-		out(nextSteps(deps.venues, { platform }));
+		out(nextSteps(deps.venues, { platform, env: deps.venueEnv ?? env }));
 		return code;
 	}
 	// Decided exactly as `up` decides it (issue #453, gate round 1): a next-steps ladder for a venue `up` would refuse to
@@ -184,7 +185,7 @@ export function runInit(cwd = process.cwd(), deps = {}) {
 		out(`\nNext: which venue this deployment runs is unknown, so no steps are shown: ${err.message}. Fix PI_BACKENDS, then run \`pi-dispatch init\` again for them (it keeps every file above).\n`);
 		return code;
 	}
-	out(nextSteps(venuesOf(venue.env), { platform }));
+	out(nextSteps(venuesOf(venue.env), { platform, env: venue.env }));
 	return code;
 }
 
@@ -250,8 +251,14 @@ function lstatOrNull(fs, path) {
  * the job image into this account's own store, the venue key and provider key in `.env` (what `up` and `service
  * install` read), the stack as Quadlet units, doctor, and the worker as a user service.
  */
-export function nextSteps(venues = { localUsed: true, podmanUsed: false }, { platform = "linux" } = {}) {
-	if (venues.podmanUsed && !venues.localUsed) return platform === "linux" ? PODMAN_NEXT_STEPS : PODMAN_OFF_LINUX;
+export function nextSteps(venues = { localUsed: true, podmanUsed: false }, { platform = "linux", env = {} } = {}) {
+	// Issue #707: the openshell venues' ladder, by the rule `up` and `service install` follow (`openshellSetupOf`). Alone,
+	// a ladder of their own; beside `local` or `podman`, that venue's ladder and one line saying what `up` adds for them.
+	const openshell = openshellSetupOf(venues, env);
+	if (openshell.used && platform === "win32") return `\nNext: ${OPENSHELL_NO_WINDOWS}.\n`;
+	if (openshell.used && !venues.localUsed && !venues.podmanUsed) return openshellNextSteps(openshell, platform);
+	const also = openshell.used ? `\nThe openshell venue too: install OpenShell ${OPENSHELL_TESTED_VERSION} (${OPENSHELL_RELEASE_URL}); \`pi-dispatch up\` then checks its gateway,\noffers to start and register it, and puts the job image into ${openshell.engine ?? "its engine"}, the gateway's engine.\n` : "";
+	if (venues.podmanUsed && !venues.localUsed) return platform === "linux" ? `${PODMAN_NEXT_STEPS}${also}` : PODMAN_OFF_LINUX;
 	return `
 Next:
   1. docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest
@@ -263,6 +270,29 @@ Next:
 
 Operator panel (optional): pi install npm:@edgehero/pi-dispatch-admin   then   /dispatch
   (or let the panel do all of the above: /dispatch setup walks these steps with a consent per action)
+${also}`;
+}
+
+/**
+ * The openshell venues alone (issue #707): OpenShell is installed by the operator (`up` never installs it), then `up`
+ * checks its gateway and offers to start and register it, puts the job image into the gateway's engine and runs Valkey
+ * there, and `service install` runs the worker as a unit that pulls the gateway's in (a LaunchAgent on macOS, beside the
+ * release formula's Homebrew service).
+ */
+function openshellNextSteps(openshell, platform) {
+	const pad = (cmd) => cmd.padEnd(52);
+	// The release formula on macOS (review round 1 of #715): homebrew-core's `openshell` defines no Homebrew service.
+	const install = platform === "darwin" ? `\`${OPENSHELL_BREW_INSTALL}\`, the release formula, whose service runs the gateway` : OPENSHELL_RELEASE_URL;
+	const service = platform === "darwin" ? "# the worker as a LaunchAgent; `brew services start openshell` keeps the gateway up" : `# the worker as a user service that pulls in ${OPENSHELL_GATEWAY_UNIT}`;
+	return `
+Next (the openshell venue on ${openshell.engine ?? "its engine"}). First install OpenShell ${OPENSHELL_TESTED_VERSION}, the release the venue was measured
+on (${install}); \`pi-dispatch up\` checks it and installs nothing:
+  1. ${pad("edit .env")}# PI_BACKENDS=openshell (PI_OPENSHELL_ENGINE=podman for Podman), and ANTHROPIC_API_KEY (or your provider's key)
+  2. ${pad("pi-dispatch up")}# the gateway (offers to start and register it), the job image into ${openshell.engine ?? "its engine"}, Valkey there
+  3. ${pad("pi-dispatch doctor")}# verify the gateway, its engine, Landlock, the image and the key
+  4. ${pad("pi-dispatch service install")}${service}
+
+Operator panel (optional): pi install npm:@edgehero/pi-dispatch-admin   then   /dispatch
 `;
 }
 

package/src/job-data-version.mjs

@@ -0,0 +1,75 @@
+/**
+ * The version of a queued job's data (issue #761, `DES-STORE-VERSION-WHEN-NEEDED`). A LEAF apart from the shared rule,
+ * so the receiver can stamp the jobs it stores for later (`fallbackJobOf`) with the same rule the worker's builders use.
+ *
+ * Jobs outlive an upgrade: a forge job is kept `FORGE_JOB_RETENTION_DAYS` (retention.mjs), a recovery may wait up to 7
+ * days, held and parked runs wait as long as their conditions do. A field a newer release adds to job data is DROPPED
+ * by an older worker's builders and IGNORED by its processor, which for a field that narrows a job (a model list, a
+ * cost cap) is a wider job, run and paid for. `trigger-skew` catches that only for the fields it lists, and only for
+ * forge jobs. So a field whose absence an older worker would misread declares the version that introduced it here, the
+ * builders stamp `dataVersion` with the lowest version the data needs, and a worker that meets a version above its own
+ * DEFERS the job (`newer-release`) rather than run it: the job waits, with its reason shown, for a worker that can read
+ * it, and nothing is spent or lost.
+ *
+ * Unversioned on purpose: answer-draft, watch and question-grouping jobs carry only references their runtime resolves at
+ * pickup, and sandbox prepare requests live 30 minutes on their own host's queue.
+ */
+import { neededVersion, valueNeededVersion } from "./store-version.mjs";
+
+/** The highest job data version this build reads. */
+export const JOB_DATA_VERSION = 3;
+
+/**
+ * Each job data field that needs a version above 1, with the version that introduced it.
+ * `packageCanary` (issue #796): an older worker would ignore it and run the trigger's ordinary job in its place, a paid run that tried nothing and reported on nothing.
+ * `excludeExtensions` and `excludeExtensionTools` (issue #800): an older worker would ignore either and run the job with what its trigger takes away, on a clean record.
+ * At 3 and not 2, because a version says what its reader knows and a worker that reads 2 knows `packageCanary` and not these: stamped 2, such a worker
+ * reads the job as its own, runs it with both fields ignored, and rebuilds a stored message without them. A new field takes a version no running worker reads.
+ */
+export const JOB_DATA_FIELD_VERSIONS = Object.freeze({ packageCanary: 2, excludeExtensions: 3, excludeExtensionTools: 3 });
+
+/**
+ * Each EXISTING top-level field whose range a later release widens, as `field -> (value) => version` (the shared rule,
+ * `valueNeededVersion`): a new condition kind in `waitFor`, say, or a new `kind` (a forge this build has no credentials
+ * for, refused `config-refused` at the mint). An older worker meeting the wider value would refuse the job (a comment, a
+ * record, a disarmed one-shot) where a stamp makes it defer. Empty until one does.
+ */
+export const JOB_DATA_VALUE_VERSIONS = Object.freeze({});
+
+/** The field that carries the version. */
+export const JOB_DATA_VERSION_FIELD = "dataVersion";
+
+/** The lowest version `data` needs, from its top-level fields and their values: 1 while nothing in it needs more. */
+export function jobDataVersionFor(data, { table = JOB_DATA_FIELD_VERSIONS, valueTable = JOB_DATA_VALUE_VERSIONS } = {}) {
+	if (data === null || typeof data !== "object") return 1;
+	const { [JOB_DATA_VERSION_FIELD]: _version, ...fields } = data;
+	return Math.max(neededVersion(Object.keys(fields), table), valueNeededVersion(fields, valueTable));
+}
+
+/**
+ * Whether `data` carries a `dataVersion` this build cannot read, as `{ version }`, else null: a version newer than
+ * `supported` (a newer worker's job: `{ version: N }`), or a value that is not a whole number of 1 or more (`null`,
+ * `"1"`, `1.5`, `0`: `{ version: null }`), which no release writes.
+ * A missing `dataVersion` is version 1. The caller defers such a job, malformed included: the hold spends nothing and
+ * an operator can cancel it, while running it would guess at data nothing here wrote. It never reads the rest first.
+ */
+export function jobDataNewer(data, { supported = JOB_DATA_VERSION } = {}) {
+	if (data === null || typeof data !== "object" || !Object.hasOwn(data, JOB_DATA_VERSION_FIELD)) return null;
+	const version = data[JOB_DATA_VERSION_FIELD];
+	if (Number.isSafeInteger(version) && version >= 1 && version <= supported) return null;
+	return { version: Number.isSafeInteger(version) && version >= 1 ? version : null };
+}
+
+/**
+ * `data` with `dataVersion` set to the version it needs: the higher of the version it arrived with (a job a newer
+ * release stored, re-enqueued here) and the one its fields and values need, and no field at all while that is 1. Throws
+ * a RangeError when the data arrived with a version this build cannot read (`jobDataNewer`: newer, or malformed), so a
+ * builder never re-enqueues a newer job under a lower version and erases the evidence its fields were dropped.
+ */
+export function withJobDataVersion(data, { table = JOB_DATA_FIELD_VERSIONS, valueTable = JOB_DATA_VALUE_VERSIONS, supported = JOB_DATA_VERSION } = {}) {
+	if (jobDataNewer(data, { supported })) throw new RangeError(`job data carries a ${JOB_DATA_VERSION_FIELD} this build cannot read (newer than ${supported}, or not a whole number of 1 or more), so it cannot rebuild it`);
+	const declared = data?.[JOB_DATA_VERSION_FIELD];
+	const needed = Math.max(Number.isSafeInteger(declared) ? declared : 1, jobDataVersionFor(data, { table, valueTable }));
+	const { [JOB_DATA_VERSION_FIELD]: _drop, ...rest } = data ?? {};
+	return needed > 1 ? { ...rest, [JOB_DATA_VERSION_FIELD]: needed } : rest;
+}

package/src/job-id.mjs

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { MANUAL_JOB_PREFIX, customJobIdAllowed } from "./bullmq-internals.mjs";
 import { configError } from "./config.mjs";
 import { forgeSpec } from "./forges.mjs";
 
@@ -12,11 +13,13 @@ import { forgeSpec } from "./forges.mjs";
  * Kept free of any bullmq import so the dedup logic is testable everywhere, not only where the
  * queue's dependencies are installed.
  */
-export function localJobId({ folder, flow, task, minute, provider, model, models }) {
+export function localJobId({ folder, flow, task, minute, provider, model, models, fallbackModels }) {
 	// The model fields join the key (issue #544): two runs that differ only in the model are two runs, and with the
 	// key blind to them the second was dropped as a duplicate. Appended only when one is set, so a job that names no
 	// model keeps the id it always had. `models` is JSON so a list cannot collide with a differently split one.
-	const modelFields = provider === undefined && model === undefined && models === undefined ? [] : [provider ?? "", model ?? "", models === undefined ? "" : JSON.stringify(models)];
+	const modelFields = provider === undefined && model === undefined && models === undefined && fallbackModels === undefined ? [] : [provider ?? "", model ?? "", models === undefined ? "" : JSON.stringify(models)];
+	// The ordered fallback policy changes which model may run, so it is part of local identity too.
+	if (fallbackModels !== undefined) modelFields.push(JSON.stringify(fallbackModels));
 	// NUL-delimited so {folder:'a',task:'bc'} and {folder:'ab',task:'c'} cannot collide.
 	const digest = createHash("sha256").update([folder, flow ?? "", task ?? "", minute, ...modelFields].join("\0")).digest("hex");
 	return `local-${digest.slice(0, 16)}`;
@@ -29,15 +32,27 @@ export function localJobId({ folder, flow, task, minute, provider, model, models
  * must not pay twice). A later minute is a new id, so a deliberate re-run is never blocked.
  *
  * The shape is BullMQ's, not a choice: a custom id that holds a `:` is refused unless it splits into exactly three
- * parts (bullmq `Job.addJob`, "Custom Id cannot contain :"), which is how its own `repeat:<id>:<millis>` passes. A cron
- * id can hold no `:` (the triggers loader refuses one), so this always splits into three. An ISO time would add two
- * more. The `manual:` prefix keeps it apart from a scheduled run's `repeat:` id, which is what tells the event writer
- * (`localEventContext`) there is no scheduled instant to report.
+ * parts (`customJobIdAllowed`, BullMQ's own rule), which is how its own `repeat:<id>:<millis>` passes. A cron id can
+ * hold no `:` (the triggers loader refuses one), so this always splits into three; one that does is refused here, by
+ * that rule, before the queue throws it. An ISO time would add two more. The `manual:` prefix keeps it apart from a
+ * scheduled run's `repeat:` id, which is what tells the event writer (`localEventContext`) there is no scheduled
+ * instant to report.
  */
 export function manualTriggerJobId({ triggerId, now }) {
-	if (typeof triggerId !== "string" || triggerId === "" || triggerId.includes(":")) throw new TypeError("a cron trigger id is a non-empty string with no ':'");
-	const millis = Math.floor(now.getTime() / 60_000) * 60_000;
-	return `manual:${triggerId}:${millis}`;
+	const refused = () => new TypeError("a cron trigger id is a non-empty string with no ':'");
+	if (typeof triggerId !== "string" || triggerId === "") throw refused();
+	const id = `${MANUAL_JOB_PREFIX}:${triggerId}:${Math.floor(now.getTime() / 60_000) * 60_000}`;
+	if (!customJobIdAllowed(id)) throw refused();
+	return id;
+}
+
+/**
+ * A canary's jobId (issue #796): the same shape, so every reader that attributes a run to its trigger still does, one millisecond past the minute, so a hand fire in the same minute
+ * cannot swallow it, nor it the fire. They are different jobs running different code.
+ */
+export function manualCanaryJobId({ triggerId, now }) {
+	const base = manualTriggerJobId({ triggerId, now });
+	return base.replace(/\d+$/, (minute) => String(Number(minute) + 1));
 }
 
 /**
@@ -62,9 +77,9 @@ export function chainedJobId({ parentJobId, flow, task }) {
 
 /**
  * The deterministic jobId for a GitHub-triggered job: the `X-GitHub-Delivery` GUID, prefixed.
- * BullMQ's dedup is `EXISTS jobId`, so a redelivered webhook (GitHub retries on timeout) carries
- * the same GUID, resolves to the same id, and the duplicate paid run is rejected --
- * REQ-DEDUP-BY-DELIVERY-GUID.
+ * BullMQ's dedup is `EXISTS jobId`, so a redelivered webhook (GitHub never resends one on its own; a
+ * person redelivers it from the hook's Recent Deliveries or the REST API) carries the same GUID, resolves
+ * to the same id, and the duplicate paid run is rejected -- REQ-DEDUP-BY-DELIVERY-GUID.
  *
  * Kept free of any bullmq import (mirrors localJobId) so the dedup key is derivable everywhere, not
  * only where the queue's dependencies are installed. A missing GUID is a caller bug -- the receiver
@@ -77,9 +92,9 @@ export function deliveryJobId(guid) {
 
 /**
  * The same thing for a GitLab-triggered job: the `webhook-id` (or its older name `Idempotency-Key`),
- * prefixed `gl-`. GitLab keeps that value CONSTANT across its own retries, which is the exact property
- * REQ-DEDUP-BY-DELIVERY-GUID needs, so the guarantee is the same one -- and retention-bounded in the same
- * way.
+ * prefixed `gl-`. GitLab keeps that value CONSTANT when a delivery is resent ("Resend Request" or the API;
+ * GitLab never resends on its own), which is the exact property REQ-DEDUP-BY-DELIVERY-GUID needs, so the
+ * guarantee is the same one -- and retention-bounded in the same way.
  */
 export function gitlabDeliveryJobId(id) {
 	return forgeDeliveryJobId("gitlab", id);

package/src/job-layout.mjs

@@ -0,0 +1,22 @@
+/**
+ * The worker's copy of the container's file layouts (issue #683, INT-CONTAINER-JOB-INPUTS): `mounts` for a venue that
+ * binds the job's directories (`local`, `podman`), `sandbox` for one that copies them under the image's WORKDIR
+ * (`openshell`). The runner reads the same table (image/runner/src/layout.mjs) by the name the worker writes into
+ * PI_JOB_LAYOUT; the two files live on different hosts at run time, so the copy is forced, and
+ * `worker/test/job-layout.test.mjs` holds them identical. CHANGE BOTH, IN THE SAME COMMIT.
+ *
+ * The `mounts` row is exactly container-spec.mjs's mount targets, which predate this file; that test pins them too, so
+ * a binding venue's argv is byte-identical to one built before the table existed.
+ */
+export const LAYOUTS = Object.freeze({
+	mounts: Object.freeze({ job: "/job", workspace: "/workspace", session: "/session", outbox: "/outbox", inbox: "/inbox", global: "/opt/pi-global" }),
+	sandbox: Object.freeze({ job: "/sandbox/job", workspace: "/sandbox/workspace", session: "/sandbox/session", outbox: "/sandbox/outbox", inbox: null, global: "/sandbox/pi-global" }),
+});
+
+export const DEFAULT_LAYOUT = "mounts";
+
+/** The layout `name` names, refusing one the table does not hold: a spec built on a guessed tree reads nothing. */
+export function layoutFor(name = DEFAULT_LAYOUT) {
+	if (typeof name !== "string" || !Object.hasOwn(LAYOUTS, name)) throw new Error(`unknown job layout ${JSON.stringify(name)} (known: ${Object.keys(LAYOUTS).join(", ")})`);
+	return LAYOUTS[name];
+}

package/src/job-size.mjs

@@ -90,6 +90,22 @@ export const DEFAULT_JOB_CPUS = "2";
 /** Where a resolved size came from: the job's project row, the deployment's `PI_JOB_*` settings, or the built-in default. */
 export const JOB_SIZE_SOURCES = Object.freeze(["project", "env", "default"]);
 
+/** pi 1.4.0's QuickJS heap limit per codemode worker, held against its artifact by codemode-workers.pinned.test.mjs. */
+export const CODEMODE_WORKER_HEAP_MIB = 256;
+
+/**
+ * Issue #693: reserve half the job's memory for pi, tools and worker overhead; divide the rest by pi's QuickJS
+ * heap limit. This is a concurrency sizing heuristic, NOT an RSS guarantee: the VM heap excludes worker overhead,
+ * and extensions may create sessions in other processes. The container's memory bound remains the hard limit.
+ * At the 512 MiB floor one worker fits; sizes between whole slots round down rather than borrowing the reserve.
+ */
+export function codemodeWorkersOf(memMiB) {
+	if (!Number.isSafeInteger(memMiB) || memMiB < JOB_MEMORY_FLOOR_MIB || memMiB > JOB_MEMORY_CEILING_MIB) {
+		throw new Error("codemode worker sizing requires a valid job memory in MiB");
+	}
+	return Math.max(1, Math.floor(memMiB / (2 * CODEMODE_WORKER_HEAP_MIB)));
+}
+
 /** The scope prefix of a project row, as `scoped-limits.mjs` spells it (`PROJECT_SCOPE_PREFIX`; a test holds them equal). */
 const PROJECT_ROW_PREFIX = "project:";
 

package/src/live-jobs.mjs

@@ -21,7 +21,10 @@
  *     carried and cannot satisfy it. No quote, backslash, slash or control character can reach the JSON, so the
  *     writer's path-shape check never refuses the field.
  *   - `p` is a project id (`isProjectId`) or null; `runs:rec:*` already carries project ids.
- *   - `m`, `c` and `at` are integers (MiB, hundredths of a CPU, epoch millis), `o` is 1.
+ *   - `m`, `c`, `at` and orphan stop `s` are integers (MiB, hundredths of a CPU, epoch millis), `o` is 1;
+ *     `v` is the orphan runtime from this build's closed venue table.
+ *   - `h` and `ha` are the actual dollar reservation (micro-dollars) and its epoch instant. A zero is known zero;
+ *     absent fields mean an older host or an orphan whose reservation this process cannot know, never zero.
  *
  * ORDER AND SIZE. Oldest first (by `at`, then id), at most `LIVE_JOBS_MAX`: the jobs that have held a slot longest
  * carry the most busy time and are the ones an operator looks for. The rest are counted in `jobsMore`, never dropped
@@ -29,6 +32,7 @@
  */
 
 import { createHash } from "node:crypto";
+import { BACKEND_NAMES } from "./backends.mjs";
 import { isProjectId } from "./project-id.mjs";
 
 /** The most jobs one row lists; the rest are counted (`jobsMore`). */
@@ -38,6 +42,7 @@ export const LIVE_JOB_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
 /** The most a `jobs` value may be before a reader declines to parse it: 32 entries at their longest fit well inside. */
 export const LIVE_JOBS_MAX_BYTES = 16 * 1024;
 
+const nonnegativeInt = (v) => Number.isSafeInteger(v) && v >= 0;
 const positiveInt = (v) => Number.isSafeInteger(v) && v > 0;
 
 /** A job id as it may be published: itself when inside `LIVE_JOB_ID_RE`, else its digest; null for no id. */
@@ -48,11 +53,11 @@ export function publishedJobId(id) {
 }
 
 /**
- * The list a row publishes, before the cap: `[{ id, p, m, c, at, o? }]`, oldest first. `running` is the in-flight
+ * The list a row publishes, before the cap: `[{ id, p, m, c, at, o?, v?, s? }]`, oldest first. `running` is the in-flight
  * map's entries (`{ id, project, memMiB, cpuCenti, at }`), `budgetEntries` the host budget's ledger (`entries()`), of
  * which only orphans are taken. An entry with no id or no instant is left out and counted in `skipped`.
  */
-export function liveJobsOf({ running = [], budgetEntries = [] } = {}) {
+export function liveJobsOf({ running = [], budgetEntries = [], defaultVenue = null } = {}) {
 	const out = [];
 	const seen = new Set();
 	let skipped = 0;
@@ -64,7 +69,8 @@ export function liveJobsOf({ running = [], budgetEntries = [] } = {}) {
 		}
 		if (seen.has(id)) return; // one job, two pickups (or running and orphaned): listed once
 		seen.add(id);
-		out.push({ id, p: isProjectId(e.project) ? e.project : null, ...(positiveInt(e.memMiB) ? { m: e.memMiB } : {}), ...(positiveInt(e.cpuCenti) ? { c: e.cpuCenti } : {}), at: e.at, ...(orphan ? { o: 1 } : {}) });
+		const venue = typeof e.orphan?.venue === "string" ? e.orphan.venue : (e.orphan?.venue && typeof e.orphan.venue === "object" ? (e.orphan.venue.backend ?? defaultVenue) : null);
+		out.push({ id, p: isProjectId(e.project) ? e.project : null, ...(positiveInt(e.memMiB) ? { m: e.memMiB } : {}), ...(positiveInt(e.cpuCenti) ? { c: e.cpuCenti } : {}), at: e.at, ...(nonnegativeInt(e.holdMicros) && positiveInt(e.holdAt) ? { h: e.holdMicros, ha: e.holdAt } : {}), ...(orphan ? { o: 1, ...(BACKEND_NAMES.includes(venue) ? { v: venue } : {}), ...(positiveInt(e.orphan?.since) ? { s: e.orphan.since } : {}) } : {}) });
 	};
 	// Running first, so a job both running and in the ledger as an orphan (it cannot be: the gate defers it) reads as running.
 	for (const e of Array.isArray(running) ? running : []) push(e, false);
@@ -116,11 +122,13 @@ function parseList(list) {
 		const ok = e !== null && typeof e === "object" && !Array.isArray(e);
 		const m = ok ? optionalSize(e.m) : undefined;
 		const c = ok ? optionalSize(e.c) : undefined;
-		if (!ok || typeof e.id !== "string" || !LIVE_JOB_ID_RE.test(e.id) || !(e.p === undefined || e.p === null || isProjectId(e.p)) || m === undefined || c === undefined || !positiveInt(e.at) || !(e.o === undefined || e.o === 1 || typeof e.o === "boolean")) {
+		const venue = ok && (e.v === undefined || e.v === null || BACKEND_NAMES.includes(e.v));
+		const since = ok && (e.s === undefined || e.s === null || positiveInt(e.s));
+		if (!ok || !venue || !since || typeof e.id !== "string" || !LIVE_JOB_ID_RE.test(e.id) || !(e.p === undefined || e.p === null || isProjectId(e.p)) || m === undefined || c === undefined || !positiveInt(e.at) || !(e.o === undefined || e.o === 1 || typeof e.o === "boolean")) {
 			dropped++;
 			continue;
 		}
-		jobs.push({ id: e.id, p: e.p ?? null, m, c, at: e.at, o: e.o === 1 || e.o === true });
+		jobs.push({ id: e.id, p: e.p ?? null, m, c, at: e.at, o: e.o === 1 || e.o === true, ...(nonnegativeInt(e.h) && positiveInt(e.ha) ? { h: e.h, ha: e.ha } : {}), ...(e.v != null ? { v: e.v } : {}), ...(e.s != null ? { s: e.s } : {}) });
 	}
 	return { jobs, dropped };
 }

package/src/live-probes.mjs

@@ -767,8 +767,11 @@ export async function runLiveProbes({
 	// caller's and already knows its binary. `isLocal` is the gate on both endpoint reads: docker's is the observed
 	// endpoint, a podman venue's is `serviceIsRemote === false`, which has no `.local` to read. The gate still decides
 	// on the value it is handed and must answer exactly `true`; anything else runs nothing.
-	buildArgs = buildDockerRunArgs,
-	bin = "docker",
+	// Issue #681: both REQUIRED here, never a docker default. A venue's doctor that forgot to pass them would read back
+	// docker's containers and print the verdict as its own. The four builders keep docker's builder as their default,
+	// since only this entry point reaches them with a venue.
+	buildArgs,
+	bin,
 	isLocal = (observed) => observed?.local === true,
 	// Issue #452, gate round 3: the runtime as this pass already read it (`{ podman, rootless, version } | null`), for the
 	// detach gate, so doctor asks the daemon once per run. Absent, the gate reads it itself.
@@ -782,6 +785,7 @@ export async function runLiveProbes({
 	cgroupParent = CGROUP_PARENT,
 	cpuBudgetCenti = null,
 }) {
+	if (typeof buildArgs !== "function" || typeof bin !== "string" || bin === "") throw new TypeError("runLiveProbes: the venue's buildArgs and bin are required (issue #681)");
 	const notRun = (reason) => ({ ran: false, reason, verdicts: [], notes: [], swept: [] });
 	const notLocal = notRun(`this shell's ${bin} CLI is not observed to point at this host, so bind paths and .Mounts would describe another machine; nothing was run`);
 	if (isLocal(endpoint) !== true) return notLocal;