@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/src/backends.mjs

@@ -61,13 +61,14 @@
  *
  * `OQ-012` already draws this line for images -- "a required OCI label proves INTENT, not conformance" --
  * and the same is true one level out. The value of the table is not that a vendor is verified; it is that a
- * MISMATCH becomes a refusal instead of a silent downgrade. `backend-conformance.mjs` verifies THREE of the
- * thirteen -- exit-code fidelity, the abort flag's independence from the code, and the read-only downgrade a
- * copying runtime takes -- plus the shape of a bundle and the internal consistency of its declaration. EIGHT more
+ * MISMATCH becomes a refusal instead of a silent downgrade. `backend-conformance.mjs` verifies FOUR of the
+ * fourteen -- exit-code fidelity, the abort flag's independence from the code, the read-only downgrade a
+ * copying runtime takes, and (issue #645) that a venue claiming `pausable` carries the verbs, driven through a freeze
+ * only when the adapter supplies a probe -- plus the shape of a bundle and the internal consistency of its declaration. EIGHT more
  * are read back off a live container (issues #278 and #344): for `local` by `doctor --live` (`live-probes.mjs`), for
  * any other runtime through the harness's `readBack` probe, which the adapter supplies. The remaining TWO the harness
  * names with what each would take rather than passing them in silence. So a backend can still declare all of this
- * and do most of it: these words are a contract with three of them checked and eight readable, which is more than
+ * and do most of it: these words are a contract with four of them checked and eight readable, which is more than
  * none and less than proof -- the read-back is of a fixture with the job image, not of every job.
  *
  * THE PROPERTIES ARE NOT A RENDERING OF `ISOLATION_FLAGS`, and must not become one. That array is the
@@ -233,6 +234,17 @@ const PROPERTIES_TABLE = {
 		question: "a local folder can be bind-mounted and edited in place (DES-WORKER-ON-HOST finding 2)",
 		armedBy: null,
 	},
+	pausable: {
+		// Issue #645. OPTIONAL in the sense that matters: nothing a job needs rests on it, so `absent` is an honest word for
+		// a venue that cannot freeze and costs that venue nothing but a live (unfrozen) checkpoint read. Pausing uses the
+		// cgroup freezer (`docker pause`, `podman pause`): every process in the container stops where it stands and
+		// nothing is killed. It exists so the HOST can read a job's bind-mounted workspace as one consistent state while
+		// nothing in the container runs; it grants the container nothing, and no mount, flag or network changes
+		// (CONST-ISOLATION-CONTAINER-PER-JOB is untouched by it). The bundle's `pause(name)` / `unpause(name)` resolve
+		// `{ ok }` and never throw, so a freeze that does not take on one host degrades the read, never the job.
+		question: "a running job can be frozen by the cgroup freezer and thawed again, so the host reads its workspace while nothing in the container runs",
+		armedBy: null,
+	},
 };
 
 /**
@@ -392,6 +404,15 @@ export const PODMAN_ADDS_NO_MOUNTS = "podmanAddsNoMounts";
  */
 export const PODMAN_SERVICE_LOCAL = "podmanServiceLocal";
 
+/**
+ * The observation that the OpenShell gateway this worker's CLI talks to listens on this host (issue #683,
+ * `CONST-VENUE-EGRESS-LAYER`'s third condition): `openshell status -o json` names a server on a loopback address or a
+ * unix socket. Every job's provider key and forge token reach that gateway, so a remote one is where they would travel.
+ * Unlike the docker and podman observations it is not only a floor's business: the openshell venue REFUSES a job on a
+ * gateway it does not observe local, whatever the floor says, because the constitution admits a layer venue only so.
+ */
+export const OPENSHELL_GATEWAY_LOCAL = "openshellGatewayLocal";
+
 /**
  * The podman venue's refusal of an account containers.conf that widens every job (issue #428), and the run record's
  * `reason` for a job it refuses. Here, in the leaf, rather than in backend-podman.mjs beside the check, so the processor
@@ -551,6 +572,7 @@ export const OBSERVATIONS = Object.freeze({
 	[PODMAN_BOUNDS_DELEGATED]: "this worker's rootless Podman runs on cgroup v2 with a systemd user manager running for its account, the pids, memory and cpu controllers delegated to that manager, and Podman putting containers under it, and no containers.conf it reads sets `cgroups`",
 	[PODMAN_ADDS_NO_MOUNTS]: "this worker's rootless Podman adds no mounts of its own to a job container",
 	[PODMAN_SERVICE_LOCAL]: "the podman CLI this worker spawns runs containers on this host, not through a remote service",
+	[OPENSHELL_GATEWAY_LOCAL]: "the OpenShell gateway this worker's openshell CLI talks to listens on a loopback address or a unix socket on this host",
 });
 
 /** What to do about each observation that a floor needed and did not get, keyed like `OBSERVATIONS` and pinned to it. */
@@ -561,6 +583,7 @@ export const OBSERVATION_FIX = Object.freeze({
 	[PODMAN_BOUNDS_DELEGATED]: "Turn on linger for the worker account (`loginctl enable-linger <account>`, which keeps its systemd user manager running with no one logged in) and run the worker as a systemd user service (`pi-dispatch service install`), or give Podman the account's user bus so it uses the systemd cgroup manager; delegate the cpu, memory and pids controllers to that manager on cgroup v2 (a systemd `Delegate=` drop-in for user@.service), remove any `cgroups` key from its containers.conf (written in plain ASCII with no escaped key or multi-line string, which the check refuses rather than guesses at), or lower that entry to `asserted`: `pi-dispatch doctor --live` reads pids.max and memory.max off a real container.",
 	[PODMAN_ADDS_NO_MOUNTS]: "As the worker account, create an empty ~/.config/containers/mounts.conf (or, when it has none, an empty /etc/containers/mounts.conf), remove any `volumes`, `mounts`, `devices` or `hooks_dir` key from every containers.conf it reads (and write those in plain ASCII with no escaped key or multi-line string, which the check refuses rather than guesses at) and any OCI hook, or lower that entry to `asserted`.",
 	[PODMAN_SERVICE_LOCAL]: "Unset CONTAINER_HOST and any containers.conf service destination for the worker account so `podman info` reports serviceIsRemote false, or lower that entry to `asserted`.",
+	[OPENSHELL_GATEWAY_LOCAL]: "Run the OpenShell gateway on this host and register it on loopback (`openshell gateway add https://127.0.0.1:17670 --local`); a remote gateway is refused, not lowered.",
 });
 
 const BACKENDS_TABLE = {
@@ -572,6 +595,14 @@ const BACKENDS_TABLE = {
 		 */
 		describe: "the Docker daemon on this worker's host",
 		remote: false,
+		// Issue #683 (`DES-CONTAINER-BACKEND-REGISTRY`, `CONST-VENUE-EGRESS-LAYER`): the provider key and the forge token sit
+		// in the job's own container, as `-e NAME=VALUE` the agent can read. Not a word on the three-word scale: who holds
+		// the credentials is a closed choice (`CREDENTIAL_CUSTODY`), and `PI_BACKEND_FLOOR` does not compare it.
+		credentialCustody: "container",
+		// Issue #712: what the run-time features this venue serves, in words (`SERVES`). The bundle binds the job's
+		// directories (`binds: true`) and its transcript is a file on the host, so live transcript, progress and `/inbox`
+		// steering work as built; `run.recover` snapshots the host workspace; `pi-dispatch sandbox` has a docker launcher.
+		serves: { liveTranscript: "yes", steering: "yes", recovery: "yes", sandboxShell: "yes" },
 		declares: {
 			// Built by this worker's own argv, in `ISOLATION_FLAGS`, and asserted back member-by-member
 			// against the imported array by two tests. `dockerArgsFromSpec` additionally refuses a
@@ -640,6 +671,11 @@ const BACKENDS_TABLE = {
 			credentialTransit: ENFORCED,
 			// The whole reason `DES-WORKER-ON-HOST` reversed the containerised worker.
 			localFolders: ENFORCED,
+			// `docker pause` on the name (`makePauseVerbs`), the freezer of whichever cgroup version the daemon runs. The
+			// one host this does not hold on is a ROOTLESS Docker on cgroup v1, which cannot freeze; there the CLI's own
+			// non-zero exit comes back as `{ ok: false }` and the read goes unfrozen, rather than the word being lowered
+			// for every rootful host because of it.
+			pausable: ENFORCED,
 		},
 		/**
 		 * WHO is asserting each `asserted` property. Required for every property this backend declares
@@ -682,6 +718,10 @@ const BACKENDS_TABLE = {
 		// The containers run on this host, as this account. A remote service is refused rather than declared remote, so
 		// the venue is never one; `credentialTransit`'s observation is what notices a CLI that tries.
 		remote: false,
+		// `local`'s: the credentials are `-e` values in the job's own container.
+		credentialCustody: "container",
+		// `local`'s, for `local`'s reasons: the bundle binds, the transcript is a host file, and SANDBOX_LAUNCHERS has a podman row.
+		serves: { liveTranscript: "yes", steering: "yes", recovery: "yes", sandboxShell: "yes" },
 		declares: {
 			// The same `ISOLATION_FLAGS` through the same builder (`buildPodmanRunArgs` shares `argsFromSpec`), read back on
 			// a live rootless container: CapEff 0, NoNewPrivs 1, seccomp 2, pids.max 512, memory.max 4 GiB. AND ONLY WHILE
@@ -728,6 +768,12 @@ const BACKENDS_TABLE = {
 			// A bind mount of the operator's folder, as on `local`, never relabelled (on an SELinux host it needs the
 			// `semanage fcontext` doctor names), and writable because the job runs as the account that owns it.
 			localFolders: ENFORCED,
+			// `podman pause` on the name, AND ONLY ON CGROUP V2: rootless Podman cannot freeze on v1 (the freezer needs a
+			// cgroup the user owns, which v1 never delegates). The venue already reads which version from `podman info`
+			// (`isolation`'s observation needs v2 too), so the bundle answers `{ ok: false, reason: "cgroup-v1-rootless" }`
+			// there without spawning (`podmanPausable`), and doctor says so. Not an `observedBy` entry: that machinery
+			// lowers a word to `asserted`, which would name an asserter for a freeze nobody provides.
+			pausable: ENFORCED,
 		},
 		// Nothing asserted: every word above is this worker's own argv or an observation of this host.
 		asserts: {},
@@ -739,6 +785,152 @@ const BACKENDS_TABLE = {
 			credentialTransit: PODMAN_SERVICE_LOCAL,
 		},
 	},
+	openshell: {
+		/**
+		 * An NVIDIA OpenShell sandbox on a gateway this deployment owns (issue #683, `DES-OPENSHELL-VENUE`), driven through
+		 * the real `openshell` CLI with `-o json`, on its Docker or Podman compute driver only. The vendor builds the box:
+		 * an agent container with networking off beside a supervisor container that decides every connection, under
+		 * Landlock and seccomp. So every word this worker cannot build or read back itself is `asserted`, with its asserter
+		 * named, where `local` says `enforced`; `PI_BACKEND_FLOOR` lets an operator refuse that trade at boot. Measured on
+		 * OpenShell 0.1.4, Docker driver, ubuntu-24.04 (Linux 6.17), 2026-10-19.
+		 *
+		 * BLESSABLE SINCE ISSUE #684, which shipped the policy layer `CONST-VENUE-EGRESS-LAYER` asks of a layer venue: the
+		 * per-job network policy generated from the squid venues' own sources, and the per-job credential provider, with
+		 * placeholders in the agent. What the venue does not serve yet (live transcript, progress, steering, recovery) is
+		 * refused or skipped by name until issue #686, which serves the first three here and recovery in bind mode only
+		 * (`openshell-bind`, below).
+		 */
+		describe: "an NVIDIA OpenShell sandbox on this host's gateway, through the openshell CLI",
+		// The gateway is refused unless it is on this host (`OPENSHELL_GATEWAY_LOCAL`), so the venue is never remote.
+		remote: false,
+		// `CONST-VENUE-EGRESS-LAYER`: the venue's own layer holds the credentials, placeholders in the agent (issue #684):
+		// a per-job provider holds the values and the supervisor swaps them in for a request to a host the policy admits.
+		credentialCustody: "layer",
+		// Issue #712: copy mode COPIES the job's files (`binds: false`), so the live transcript comes over the exec's stderr
+		// and steering over its stdin, each only when the job image declares the capability (`transcriptStderr`; for
+		// steering `steerStdin` AND `transcriptStderr`, whose stream carries the acks) and an exit key: `image`. `run.recover` is refused before spend (`openshell-recover-unsupported`)
+		// and refused in the triggers file for a trigger naming this venue (`recoverVenueProblem`). No sandbox launcher.
+		serves: { liveTranscript: "image", steering: "image", recovery: "no", sandboxShell: "no" },
+		declares: {
+			// The agent container and its bounds are the compute driver's (`cap_drop ALL`, `no-new-privileges`, networking
+			// off, a pids limit of 2048, `--cpu` and `--memory`), not an argv this worker builds.
+			isolation: ASSERTED,
+			// The worker creates one sandbox per job and deletes it in a `finally`, and the reaper deletes a crashed one;
+			// that the delete really removes the agent and supervisor containers is the gateway's.
+			ephemeral: ASSERTED,
+			// No mount is the worker's: the job's files are uploaded and downloaded, and what the driver mounts beside them
+			// (its runtime, the supervisor's socket) is the vendor's.
+			mountSet: ASSERTED,
+			// The layer's per-job policy (issue #684), deny-all but for the hosts the allowlist, the model endpoints and the
+			// forge admit. The boot refuses PI_EGRESS=0 with this venue blessed: the layer has no "off" (`config.mjs`).
+			egress: ASSERTED,
+			// Each sandbox's agent has networking off and reaches only its own supervisor, so another job is not on any
+			// network it can see: the driver's construction.
+			jobToJobIsolation: ASSERTED,
+			// The image is resolved by the gateway's driver (`image_pull_policy`, `if_not_present` by default), not by a
+			// `--pull=never` this worker passes.
+			imagePinning: ASSERTED,
+			// `sandbox exec` returns the command's own code and 128+n for a signal (measured: 0, 1, 2, 3, 137, 255, 143
+			// and 137), but through the vendor's relay; a CLI failure also exits 1.
+			exitCodes: ASSERTED,
+			// `sandbox delete` on the name ends the exec (measured: 143), and the abort FLAG is the discriminator as on
+			// every venue; the delete itself is the gateway's.
+			abortable: ASSERTED,
+			// Not a `:ro` bind: the uploaded `/sandbox/job` is read-only because the worker starts the runner through the
+			// image's `pi-landlock`, AFTER the upload (`DES-OPENSHELL-VENUE`, corrected in #683).
+			readOnlyJobInputs: ASSERTED,
+			// OpenShell refuses a root workload, and the worker's policy names the image's uid as `run_as_user`.
+			nonRoot: ASSERTED,
+			// The same resolver and record as `local`, but the values reach a vendor's gateway and supervisor.
+			secretsCustody: ASSERTED,
+			// ENFORCED, AND ONLY WHILE OBSERVED, for `local`'s reason: the values reach the gateway the CLI talks to, and the
+			// worker reads where that is (`openshellGatewayLocal`). A gateway not observed local is refused outright.
+			credentialTransit: ENFORCED,
+			// Copy mode edits a copy, not the operator's folder: a local or cron folder job is refused at load
+			// (`refusesLocalWorkspace`). Bind mode, which can, is its own venue, `openshell-bind` (issue #686 part 3).
+			localFolders: ABSENT,
+			// OpenShell has no pause verb, so live checkpoints are off (`DES-RUN-CHECKPOINT-PAIRED`).
+			pausable: ABSENT,
+		},
+		asserts: {
+			isolation: "OpenShell's compute driver (the agent container it creates with every capability dropped, no new privileges, networking off and a pids limit, under Landlock and seccomp)",
+			ephemeral: "the OpenShell gateway, which removes a sandbox's containers when the worker deletes it",
+			mountSet: "OpenShell's compute driver, which mounts its own runtime and the supervisor's socket and nothing of the job's",
+			egress: "OpenShell's supervisor, which decides every connection by the sandbox's policy",
+			jobToJobIsolation: "OpenShell's compute driver, which gives each sandbox's agent no network beside its own supervisor",
+			imagePinning: "the OpenShell gateway's image pull policy on its compute driver",
+			exitCodes: "OpenShell's exec relay, which returns the command's own code and 128 plus the signal",
+			abortable: "the OpenShell gateway, whose sandbox delete ends the running exec",
+			readOnlyJobInputs: "the job image's /opt/pi-dispatch/pi-landlock (the sandboxLayout capability), which the worker starts the runner through after the upload",
+			nonRoot: "OpenShell, which refuses a root workload, with the image's uid as the policy's run_as_user",
+			secretsCustody: "the OpenShell gateway and supervisor, which hold the job's environment while it runs",
+		},
+		observedBy: {
+			credentialTransit: OPENSHELL_GATEWAY_LOCAL,
+		},
+	},
+	"openshell-bind": {
+		/**
+		 * The OpenShell venue in BIND MODE (issue #686 part 3, `DES-OPENSHELL-VENUE`'s "Bind mode"): the same gateway, the
+		 * same driver, the same per-job network policy and credential provider as `openshell`, but the job's host
+		 * directories are BIND-MOUNTED into the sandbox, as `local` mounts them, through the compute driver's
+		 * `--driver-config-json` mounts. Its own venue rather than a setting of `openshell`, so a floor, a trigger's
+		 * `run.backend` and the run record each name which of the two a job ran in: the words below differ where it
+		 * matters. Opt-in per host: the gateway's gateway.toml must allow driver config and bind mounts and turn resource
+		 * admission off, and upstream warns that a bind "can bypass workspace isolation and filesystem policy".
+		 * Measured on OpenShell 0.1.4, Docker driver, 2026-10-19. Every word not commented is `openshell`'s, for its reason.
+		 */
+		describe: "an NVIDIA OpenShell sandbox on this host's gateway with the job's directories bind-mounted, through the openshell CLI",
+		remote: false,
+		// `CONST-VENUE-EGRESS-LAYER`, UNCHANGED: the provider, the policy and the placeholders are copy mode's exactly.
+		credentialCustody: "layer",
+		// Issue #712: the binds make it `local`'s for the transcript (a host file), `/inbox` steering and recovery (the host
+		// workspace is salvaged and snapshotted at exit); no sandbox launcher, as in copy mode.
+		serves: { liveTranscript: "yes", steering: "yes", recovery: "yes", sandboxShell: "no" },
+		declares: {
+			isolation: ASSERTED,
+			ephemeral: ASSERTED,
+			// The job's mounts ARE the worker's now (the spec's mounts, handed to the driver), but the driver applies them,
+			// beside its own runtime and the supervisor's socket: no argv of the worker's is read back from a daemon.
+			mountSet: ASSERTED,
+			egress: ASSERTED,
+			jobToJobIsolation: ASSERTED,
+			imagePinning: ASSERTED,
+			exitCodes: ASSERTED,
+			abortable: ASSERTED,
+			// A read-only bind (measured: EROFS on a write) and the policy listing `/job` read_only (measured: a write
+			// denied), both applied by the vendor. No pi-landlock here: the bind is the control `local`'s `:ro` is, and the
+			// policy a second one.
+			readOnlyJobInputs: ASSERTED,
+			nonRoot: ASSERTED,
+			secretsCustody: ASSERTED,
+			credentialTransit: ENFORCED,
+			// The operator's folder, bind-mounted read-write as /workspace and edited in place (measured: rw binds write
+			// through, host writes are visible inside live), so a local or cron folder job is admitted. Asserted, not
+			// `local`'s enforced: the driver applies the bind.
+			localFolders: ASSERTED,
+			// Still no pause verb: live checkpoints stay off (`DES-RUN-CHECKPOINT-PAIRED`); an exit snapshot and a salvage
+			// of the host workspace need none.
+			pausable: ABSENT,
+		},
+		asserts: {
+			isolation: "OpenShell's compute driver (the agent container it creates with every capability dropped, no new privileges, networking off and a pids limit, under Landlock and seccomp)",
+			ephemeral: "the OpenShell gateway, which removes a sandbox's containers when the worker deletes it",
+			mountSet: "OpenShell's compute driver, which applies the binds the worker passes in --driver-config-json and mounts its own runtime and the supervisor's socket beside them",
+			egress: "OpenShell's supervisor, which decides every connection by the sandbox's policy",
+			jobToJobIsolation: "OpenShell's compute driver, which gives each sandbox's agent no network beside its own supervisor",
+			imagePinning: "the OpenShell gateway's image pull policy on its compute driver",
+			exitCodes: "OpenShell's exec relay, which returns the command's own code and 128 plus the signal",
+			abortable: "the OpenShell gateway, whose sandbox delete ends the running exec",
+			readOnlyJobInputs: "OpenShell's compute driver, which binds /job read-only, and its supervisor, which applies the policy that lists it read_only",
+			nonRoot: "OpenShell, which refuses a root workload, with the job user's uid as the policy's run_as_user",
+			secretsCustody: "the OpenShell gateway and supervisor, which hold the job's environment while it runs",
+			localFolders: "OpenShell's compute driver, which binds the operator's folder read-write as /workspace",
+		},
+		observedBy: {
+			credentialTransit: OPENSHELL_GATEWAY_LOCAL,
+		},
+	},
 };
 
 /**
@@ -747,6 +939,67 @@ const BACKENDS_TABLE = {
  */
 export const PODMAN_BACKEND = "podman";
 
+/** The OpenShell venue's name (issue #683), for `PODMAN_BACKEND`'s reason. */
+export const OPENSHELL_BACKEND = "openshell";
+/** Its bind mode's (issue #686 part 3): a venue of its own, on the same gateway, settings and CLI. */
+export const OPENSHELL_BIND_BACKEND = "openshell-bind";
+/**
+ * Review round 2 of #714 (CONST-RETRY-INFRA-ONLY): the named result of an `openshell-bind` run whose sandbox could not
+ * be confirmed gone after its exec, where a retry would be wrong: a run that COMPLETED (its work is done and must not be
+ * thrown away as a retry) or a FOLDER job (a second agent must not start on a folder the first sandbox may still be
+ * writing). Determinate, so a policy outcome, never retried; its spend is recorded. Here, in the leaf, so the processor
+ * and the adapter's `OPENSHELL_REFUSALS` share one sentence.
+ */
+export const OPENSHELL_BIND_LINGERING = Object.freeze({
+	reason: "openshell-bind-sandbox-lingering",
+	comment: "Stopped: this job ran in an OpenShell sandbox with its files bound from this machine, and the sandbox could not be confirmed gone after the run, so something in it may still be changing those files. The run's result is not used and it is not run again; what it already changed stays as it is. The operator must check the sandbox on the gateway.",
+});
+
+/** Both OpenShell venues, the copy mode first: what "is any OpenShell venue blessed" asks of a list. */
+export const OPENSHELL_BACKENDS = Object.freeze([OPENSHELL_BACKEND, OPENSHELL_BIND_BACKEND]);
+
+/**
+ * Who holds a venue's credentials (issue #683, `DES-CONTAINER-BACKEND-REGISTRY`): `container` (the job's own container,
+ * where the agent can read them) or `layer` (the venue's own egress layer, placeholders in the agent,
+ * `CONST-VENUE-EGRESS-LAYER`). A closed choice, not a word on the three-word scale, so `PI_BACKEND_FLOOR` never compares
+ * it; an entry that omits it is read as `container`.
+ */
+export const CREDENTIAL_CUSTODY = Object.freeze(["container", "layer"]);
+
+/**
+ * The run-time features a venue serves (issue #712, `DES-CONTAINER-BACKEND-REGISTRY`), each entry's `serves` in words:
+ * `liveTranscript` (the live transcript and the progress it drives), `steering` (`run.steer` messages), `recovery`
+ * (`run.recover`) and `sandboxShell` (`pi-dispatch sandbox <id>`). NOT properties on the three-word scale: they say what a
+ * venue CAN DO for an operator, not what it guarantees, so `PI_BACKEND_FLOOR` never compares them. Derived facts held to
+ * their sources by `worker/test/backends-serves.test.mjs` (the bundle's `binds` and `transcript`, `SANDBOX_LAUNCHERS`, the
+ * copy-mode recovery refusal), so a surface that words them (the console, the panel) reads this table instead of
+ * restating which venue does what.
+ */
+export const SERVES = Object.freeze(["liveTranscript", "steering", "recovery", "sandboxShell"]);
+
+/**
+ * The words a `serves` entry takes. `yes`: the venue carries the feature itself. `no`: it never does (and `run.recover`
+ * naming such a venue is refused). `image`: the venue SKIPS the feature by name (a `liveSkipped` or `steerSkipped`
+ * reason on the record) unless the job image declares the capability that carries it, and an exit key: a copying
+ * venue's stderr transcript (`transcriptStderr`) and its stdin steering (`steerStdin`, which also needs
+ * `transcriptStderr` for the acks). `yes` is about the VENUE only: a feature it serves can still be refused before
+ * spend by what the image lacks on any venue (`job-image-steer-unsupported`, `job-image-recover-unsupported`, a
+ * missing `exitAuth`), as it always was.
+ */
+export const SERVES_WORDS = Object.freeze(["yes", "no", "image"]);
+
+/** A venue's `serves` block, or null for a name this table does not hold. `Object.hasOwn`, so `"toString"` is not a venue. */
+export function servesOf(name) {
+	return typeof name === "string" && Object.hasOwn(BACKENDS, name) ? BACKENDS[name].serves : null;
+}
+
+/**
+ * Venues in the table that `PI_BACKENDS` refuses by name (issue #683): built and tested, and not yet admitted, each with
+ * the sentence that says why. Removing a name here is the whole of blessing it. EMPTY since issue #684 blessed
+ * `openshell`; kept, so the next venue that lands before its gate has the same one-line switch.
+ */
+export const NOT_YET_BLESSABLE = Object.freeze({});
+
 /**
  * FROZEN, deeply. `makeLocalBackend` hands `BACKENDS[name].declares` out on the bundle it returns, so
  * without this a consumer holding a backend could assign one word and silently rewrite what every later
@@ -760,7 +1013,7 @@ export const BACKENDS = Object.freeze(
 		// exists to prevent (#278 found `asserts` had been left mutable).
 		Object.entries(BACKENDS_TABLE).map(([name, entry]) => [
 			name,
-			Object.freeze({ ...entry, declares: Object.freeze({ ...entry.declares }), asserts: Object.freeze({ ...(entry.asserts ?? {}) }), observedBy: Object.freeze({ ...(entry.observedBy ?? {}) }) }),
+			Object.freeze({ ...entry, declares: Object.freeze({ ...entry.declares }), serves: Object.freeze({ ...entry.serves }), asserts: Object.freeze({ ...(entry.asserts ?? {}) }), observedBy: Object.freeze({ ...(entry.observedBy ?? {}) }) }),
 		]),
 	),
 );
@@ -871,6 +1124,9 @@ export function parseBackendList(raw, { known = BACKEND_NAMES } = {}) {
 		if (!known.includes(name)) {
 			throw new Error(`PI_BACKENDS names an unknown backend ${JSON.stringify(name)} (known: ${known.join(", ")})`);
 		}
+		// Issue #683: in the table, refused by name. Only the production table: a test passing its own `known` list
+		// reaches an entry the way the conformance script does, without blessing it.
+		if (known === BACKEND_NAMES && Object.hasOwn(NOT_YET_BLESSABLE, name)) throw new Error(`PI_BACKENDS names ${JSON.stringify(name)}: ${NOT_YET_BLESSABLE[name]}`);
 	}
 	// Deduplicated, order preserved: the first entry is what a deployment means by "the default one", and it is
 	// where a trigger that names no venue is dispatched.
@@ -902,7 +1158,44 @@ export function venuesOf(env) {
 	} catch {
 		blessed = [DEFAULT_BACKEND];
 	}
-	return { localUsed: blessed.includes(DEFAULT_BACKEND), podmanUsed: blessed.includes(PODMAN_BACKEND), podmanDefault: blessed[0] === PODMAN_BACKEND };
+	// `openshellUsed` (issue #683, blessable since #684): the doctor's openshell section runs on it, for either mode (issue
+	// #686 part 3), whose gateway, CLI and settings are one; the two mode flags say which mode's own lines to add.
+	const openshellCopyUsed = blessed.includes(OPENSHELL_BACKEND);
+	const openshellBindUsed = blessed.includes(OPENSHELL_BIND_BACKEND);
+	return { localUsed: blessed.includes(DEFAULT_BACKEND), podmanUsed: blessed.includes(PODMAN_BACKEND), podmanDefault: blessed[0] === PODMAN_BACKEND, openshellUsed: openshellCopyUsed || openshellBindUsed, openshellCopyUsed, openshellBindUsed };
+}
+
+/** The two engines an OpenShell gateway's compute driver may be in v1 (`config.mjs` `openshellFrom` refuses any other). */
+export const OPENSHELL_ENGINES = Object.freeze(["docker", "podman"]);
+
+/**
+ * What setting up the openshell venues needs on this host (issue #707), from the venues `venuesOf` read and the two keys
+ * the worker boots with (`PI_OPENSHELL_ENGINE`, `PI_OPENSHELL_GATEWAY`, read as `openshellFrom` reads them). ONE rule, so
+ * `up`, `service install`, `init`'s next steps and doctor cannot disagree about it:
+ *
+ *   - `engine`: the gateway's compute driver, docker unless the key says podman. It is the image store the gateway runs
+ *     sandboxes from, so the job image must be in it;
+ *   - `imageEngine`: that engine, or null where another blessed venue's own step already puts the image in the SAME
+ *     store (`local` in docker's, `podman` in this account's rootless Podman store), so `up` pulls it once;
+ *   - `valkeyEngine`: the engine Valkey runs on for this deployment, only where neither `local` nor `podman` is blessed
+ *     (each of those already decides where the queue runs, and a second Valkey on the same port would only fail to bind);
+ *   - `gateway`: the registered gateway's name the worker addresses, or null for the CLI's active one;
+ *   - `engineError`: a sentence when the key names an engine v1 does not admit (then both engines above are null).
+ *
+ * The squid egress proxy is NOT part of it, on purpose: the gateway's per-sandbox network policy is the openshell venue's
+ * egress layer (`CONST-VENUE-EGRESS-LAYER`), and a proxy started for it would be one no job of this venue attaches to.
+ * Not blessed: `{ used: false }` with every other field null, so a value left in `.env` changes nothing.
+ */
+export function openshellSetupOf(venues, env = {}) {
+	if (!venues?.openshellUsed) return { used: false, engine: null, gateway: null, imageEngine: null, valkeyEngine: null, engineError: null };
+	const raw = env?.PI_OPENSHELL_ENGINE;
+	const engine = raw === undefined || raw === null || raw === "" ? "docker" : String(raw);
+	const gateway = typeof env?.PI_OPENSHELL_GATEWAY === "string" && env.PI_OPENSHELL_GATEWAY !== "" ? env.PI_OPENSHELL_GATEWAY : null;
+	if (!OPENSHELL_ENGINES.includes(engine)) {
+		return { used: true, engine, gateway, imageEngine: null, valkeyEngine: null, engineError: `PI_OPENSHELL_ENGINE must be docker or podman, the compute drivers the openshell venue admits (got ${JSON.stringify(engine)})` };
+	}
+	const covered = (engine === "docker" && venues.localUsed) || (engine === "podman" && venues.podmanUsed);
+	return { used: true, engine, gateway, imageEngine: covered ? null : engine, valkeyEngine: venues.localUsed || venues.podmanUsed ? null : engine, engineError: null };
 }
 
 /**
@@ -942,6 +1235,87 @@ export function parseBackendFloor(raw) {
 	return floor;
 }
 
+/**
+ * Whether this host's OpenShell gateway is on this host, as a word for the host registry (issue #712): `local`, `remote`,
+ * or `unknown` (not read: the gateway did not answer at boot). A WORD and never the gateway's address, which is operator
+ * topology the registry's content rule keeps out. Closed, so a reader can refuse anything else.
+ */
+export const HOST_GATEWAY_WORDS = Object.freeze(["local", "remote", "unknown"]);
+
+/**
+ * A venue name as a host row may carry one: lowercase-led, lowercase letters, digits and `-`, at most 32 characters.
+ * Exported for the runs filter (issue #712), so a venue a newer worker blesses, which the Venues view lists, is also one
+ * the filter takes. Every name in BACKENDS has this shape (a test holds it).
+ */
+export const HOST_VENUE_NAME_RE = /^[a-z][a-z0-9-]{0,31}$/;
+/** A property name as a host row's floor may carry one: lowercase-led letters and digits, bounded. */
+const HOST_PROPERTY_NAME_RE = /^[a-z][A-Za-z0-9]{0,47}$/;
+
+/**
+ * The registry row's `backends` field (issue #712, `INT-HOST-REGISTRY-CONTRACT`): what venues this host blesses, its
+ * floor, and its OpenShell setup, for the console's and the panel's Venues view. One compact string of names and fixed
+ * words only, so the row keeps its content rule (names, integers, digests):
+ *
+ *   blessed=<venue>[,<venue>...];floor=<property>:<word>[,...];os=<engine>:<gateway word>
+ *
+ * `blessed` is `PI_BACKENDS` as the worker parsed it, in its order, so the FIRST is the default (the parse's own rule,
+ * not a second field that could disagree with it). `floor` is `PI_BACKEND_FLOOR` as `parseBackendFloor` read it, its
+ * property names and words, and is left out when there is none. `os` only while an OpenShell venue is blessed: the
+ * engine (`OPENSHELL_ENGINES`) and whether the gateway is on this host (`HOST_GATEWAY_WORDS`); the modes are the blessed
+ * OpenShell venues themselves (`openshell` copies, `openshell-bind` binds), so they are not written twice.
+ *
+ * NOT JSON, which `jobs` uses: `jobs` is a list of records, and this is three flat lists a reader splits on two
+ * characters, none of which a venue name, a property name or a word can hold. Nothing reads it to decide anything, so
+ * deleting `host:*` still changes nothing: it is what the host says about itself, displayed.
+ */
+export function hostBackendsField({ backends = [], backendFloor = {}, openshellEngine = null, gatewayWord = "unknown" } = {}) {
+	const blessed = (backends ?? []).filter((n) => typeof n === "string" && HOST_VENUE_NAME_RE.test(n));
+	const parts = [`blessed=${blessed.join(",")}`];
+	const floor = Object.entries(backendFloor ?? {}).filter(([p, w]) => HOST_PROPERTY_NAME_RE.test(p) && isDeclaration(w));
+	if (floor.length > 0) parts.push(`floor=${floor.map(([p, w]) => `${p}:${w}`).join(",")}`);
+	if (OPENSHELL_BACKENDS.some((n) => blessed.includes(n))) {
+		const engine = OPENSHELL_ENGINES.includes(openshellEngine) ? openshellEngine : "docker";
+		parts.push(`os=${engine}:${HOST_GATEWAY_WORDS.includes(gatewayWord) ? gatewayWord : "unknown"}`);
+	}
+	return parts.join(";");
+}
+
+/**
+ * A peer's `backends` field read back: `{ blessed, default, floor, openshell }`, or null for a row without the field (a
+ * worker from before it) or one that does not read. PEER-WRITTEN, so every element is re-checked as `parseCaps` does:
+ * a venue name of the right shape is kept even when this build's table does not hold it (a newer worker's venue, which
+ * a reader names rather than hides), a floor entry needs a property-shaped name and one of the three words, and
+ * `openshell` is `{ engine, gateway, modes }` with each value from its closed list (`unknown` otherwise). Unknown keys
+ * are skipped, so a later field does not make an older reader drop the row.
+ */
+export function parseHostBackends(raw) {
+	if (typeof raw !== "string" || raw === "" || raw.length > 1024) return null;
+	const out = { blessed: [], default: null, floor: {}, openshell: null };
+	let sawBlessed = false;
+	for (const part of raw.split(";")) {
+		const at = part.indexOf("=");
+		if (at <= 0) continue;
+		const key = part.slice(0, at);
+		const items = part.slice(at + 1).split(",").filter((s) => s !== "");
+		if (key === "blessed") {
+			sawBlessed = true;
+			out.blessed = [...new Set(items.filter((n) => HOST_VENUE_NAME_RE.test(n)))];
+		} else if (key === "floor") {
+			for (const item of items) {
+				const [property, word, extra] = item.split(":");
+				if (extra === undefined && HOST_PROPERTY_NAME_RE.test(property ?? "") && isDeclaration(word) && !Object.hasOwn(out.floor, property)) out.floor[property] = word;
+			}
+		} else if (key === "os") {
+			const [engine, gateway] = (items[0] ?? "").split(":");
+			out.openshell = { engine: OPENSHELL_ENGINES.includes(engine) ? engine : "unknown", gateway: HOST_GATEWAY_WORDS.includes(gateway) ? gateway : "unknown", modes: [] };
+		}
+	}
+	if (!sawBlessed) return null;
+	out.default = out.blessed[0] ?? null;
+	if (out.openshell) out.openshell.modes = [...(out.blessed.includes(OPENSHELL_BACKEND) ? ["copy"] : []), ...(out.blessed.includes(OPENSHELL_BIND_BACKEND) ? ["bind"] : [])];
+	return out;
+}
+
 /**
  * Which floored properties this deployment is NOT getting because their switch is off, as
  * `[{ property, want, armedBy }]`.
@@ -1044,6 +1418,21 @@ export function backendRefusals({ backends = [], backendFloor = {}, egress = fal
 		);
 	}
 
+	// Issue #684 (the operator's decision): a venue whose own layer holds the credentials (`credentialCustody: layer`)
+	// cannot run with PI_EGRESS=0. Its policy IS the egress control and the provider's placeholders resolve only through
+	// it, so "egress off" has no meaning there: honouring it would mean a policy admitting everything, which hands the
+	// real credential to any host the agent names, and ignoring it would run the job under a control the operator
+	// switched off. Refused at boot, by name, rather than either guess. Every layer venue, not `openshell` by name.
+	if (egress !== true) {
+		const layered = backends.filter((name) => (BACKENDS[name]?.credentialCustody ?? "container") === "layer");
+		if (layered.length > 0) {
+			out.push(
+				`PI_EGRESS=0 cannot run ${layered.join(", ")}: ${layered.length === 1 ? "that venue's" : "those venues'"} own policy layer is the egress control and holds the job's credentials (CONST-VENUE-EGRESS-LAYER), so it has no "egress off". ` +
+					"Arm PI_EGRESS, or remove that backend from PI_BACKENDS.",
+			);
+		}
+	}
+
 	return out;
 }