@edgehero/pi-dispatch 1.10.3 → 2.1.0

package/deploy/worker-env-wrapper.sh

@@ -24,9 +24,9 @@
 # profile happens to export. Nothing here contains a credential -- the secrets live in `.env`, which is
 # gitignored and read at runtime.
 #
-# TRAP: inside pi, `ANTHROPIC_OAUTH_TOKEN` silently takes precedence over `ANTHROPIC_API_KEY`. Set exactly
-# one in `.env`; this wrapper only ADDS the `.env` vars on top of the current environment, it does not
-# clear a stray pre-existing one, so a leaked host `ANTHROPIC_OAUTH_TOKEN` would still win.
+# TRAP: inside pi, `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_OAUTH_TOKEN` silently take precedence over
+# `ANTHROPIC_API_KEY`. Set exactly one in `.env`; this wrapper only ADDS the `.env` vars on top of the
+# current environment, it does not clear a stray pre-existing one, so a leaked host token would still win.
 #
 # One worker per host (DES-CONCURRENCY-3): parallelism is PI_CONCURRENCY inside the single process, not
 # multiple daemons. Requires the AOF-enabled Valkey from deploy/docker-compose.yml.
@@ -46,39 +46,57 @@ fi
 # own CLI, not just from the daemon: `pi-dispatch service stop` on macOS is `launchctl kill SIGTERM` at
 # this pid.
 #
-# The other window is two instructions wide, and is closed by the re-send after `child=$!` below. The
-# handler is a FUNCTION rather than a trap string because it is installed twice -- here, and again after
-# the sourcing -- and one behaviour spelled out in two places is one behaviour that can drift.
-signaled=0
-child=
-wrapper_on_stop() {
-	signaled=1
-	# `child` is empty until the fork below has been assigned, and `kill -TERM ""` kills nothing and
-	# fails silently, so a stop arriving before then has no pid to reach. It is not lost: the re-send
-	# after `child=$!` re-delivers it, and the launch gate refuses to start at all if nothing was
-	# started yet.
-	[ -n "$child" ] && kill -TERM "$child" 2>/dev/null
-	# Never leave a nonzero status behind. `rc=$?` is read immediately after the `wait` this interrupts,
-	# and the double wait at the bottom keys on rc >= 128.
-	return 0
+# The other window is two instructions wide, and is closed by the re-send after `child=$!` below.
+#
+# NOTHING THIS WRAPPER READS IS LEFT WHERE ./.env CAN ASSIGN IT (issue #470). ./.env is sourced into this
+# shell, so any line in it can set any variable this script uses: `env_setup=/x.sh` named a script the
+# wrapper then ran, `signaled=1` made it exit 0 without starting the worker, and `child=<pid>` pointed the
+# stop at another process. So the rule is: every variable below is assigned AFTER the load; the one value
+# it needs from before the load (PI_ENV_SETUP, as the unit set it) travels across the load in the
+# positional parameters, which no assignment line can reach; and a stop DURING the preparation is handled
+# by `wrapper_stopped_early`, which reads no variable at all and simply does not start the worker.
+wrapper_stopped_early() {
+	# A stop that arrived while the environment was being prepared is honoured by NOT STARTING. Launching
+	# would hand the service manager a worker it has already asked to go away: it would reserve a budget
+	# slot and take a job, and then need a drain nobody is waiting for. Exit 0 because 0 is the only code
+	# launchd's KeepAlive/SuccessfulExit=false leaves stopped -- the same reason the exit-2 conversion at the
+	# bottom exists. Not 2, because nothing was refused; not 1, because nothing failed; the manager's own
+	# instruction was carried out, and this says so rather than exiting mute. The shell runs a trap only
+	# after the command in progress returns, so a setup script's network call is not cut off mid-write.
+	echo "worker-env-wrapper: stopped before the worker started -- a stop signal arrived while the environment was being prepared, so the command was never launched; exiting 0 (nothing to restart)" >&2
+	exit 0
 }
-trap wrapper_on_stop TERM INT
+trap wrapper_stopped_early TERM INT
 
 # The env-setup seam (issue #209): `pi-dispatch service render|install --env-setup <path>` puts an
 # operator-typed path here -- the plist's EnvironmentVariables dict on macOS, nssm's AppEnvironmentExtra
 # on Windows -- so a secrets manager can fill this process's environment without anyone hand-editing a
 # rendered unit. Captured BEFORE ./.env is sourced, on purpose: the path is UNIT configuration, and a
-# `.env` line must never be able to name a script this wrapper then runs.
-env_setup="${PI_ENV_SETUP:-}"
+# `.env` line must never be able to name a script this wrapper then runs. It is held as "$1" across the
+# load (a `PI_ENV_SETUP=` or `env_setup=` line there reaches neither), and the command is "$2" onwards
+# until the `shift` below.
+set -- "${PI_ENV_SETUP:-}" "$@"
 
 if [ -f ./.env ]; then
 	set -a; . ./.env; set +a
-elif [ -z "$env_setup" ]; then
+elif [ -z "$1" ]; then
 	echo "worker-env-wrapper: .env not found in $PWD -- this wrapper must be started in the deployment folder (the unit's WorkingDirectory / nssm AppDirectory); it no longer guesses a location from its own path" >&2
 	exit 1
 else
 	# Only a configured seam earns this: the environment demonstrably comes from somewhere else.
-	echo "worker-env-wrapper: no .env in $PWD -- the environment comes from $env_setup (PI_ENV_SETUP)" >&2
+	echo "worker-env-wrapper: no .env in $PWD -- the environment comes from $1 (PI_ENV_SETUP)" >&2
+fi
+
+# AFTER THE LOAD, every variable this wrapper reads is assigned, so no assignment line of ./.env
+# reaches one. The worker sees the unit's PI_ENV_SETUP too, never one the file set (the setup script,
+# which is unit configuration, may still set its own).
+env_setup=$1
+shift
+if [ -n "$env_setup" ]; then
+	PI_ENV_SETUP=$env_setup
+	export PI_ENV_SETUP
+else
+	unset PI_ENV_SETUP
 fi
 
 # AFTER ./.env, deliberately. The manager is the newer source of truth, so a stale key left in the file
@@ -102,23 +120,31 @@ if [ -n "$env_setup" ]; then
 	set +a
 fi
 
-# RE-ASSERTED after the sourcing, and this is not belt-and-braces. A sourced script runs in THIS shell,
-# so a `trap ... TERM` inside one REPLACES the handler above and the drain silently disappears -- a
-# manager's cleanup helper does exactly that. One line restores it. What it cannot undo is a script that
-# IGNORES TERM (`trap '' TERM`): a signal discarded while it was ignored is already gone, and the child
-# forked below would inherit SIG_IGN and be unable to trap TERM at all. That is why docs/secrets.md now
-# tells operators not to touch signals in a setup script.
+# THE FORWARDING HANDLER, installed after the sourcing, and the placement is not belt-and-braces. A
+# sourced script runs in THIS shell, so a `trap ... TERM` inside one REPLACES whatever handler is up and
+# the drain would silently disappear -- a manager's cleanup helper does exactly that. Installing it here
+# restores it. Its two variables are assigned here too, after the load, for the reason given at the
+# top. What it cannot undo is a script that IGNORES TERM (`trap '' TERM`): a signal discarded while it
+# was ignored is already gone, and the child forked below would inherit SIG_IGN and be unable to trap
+# TERM at all. That is why docs/secrets.md now tells operators not to touch signals in a setup script.
+signaled=0
+child=
+wrapper_on_stop() {
+	signaled=1
+	# `child` is empty until the fork below has been assigned, and `kill -TERM ""` kills nothing and
+	# fails silently, so a stop arriving before then has no pid to reach. It is not lost: the re-send
+	# after `child=$!` re-delivers it, and the launch gate refuses to start at all if nothing was
+	# started yet.
+	[ -n "$child" ] && kill -TERM "$child" 2>/dev/null
+	# Never leave a nonzero status behind. `rc=$?` is read immediately after the `wait` this interrupts,
+	# and the double wait at the bottom keys on rc >= 128.
+	return 0
+}
 trap wrapper_on_stop TERM INT
 
-# A stop that arrived while the environment was being prepared is honoured by NOT STARTING. Launching now
-# would hand the service manager a worker it has already asked to go away: it would reserve a budget slot
-# and take a job, and then need a drain nobody is waiting for. Exit 0 because 0 is the only code launchd's
-# KeepAlive/SuccessfulExit=false leaves stopped -- the same reason the exit-2 conversion at the bottom
-# exists. Not 2, because nothing was refused; not 1, because nothing failed; the manager's own instruction
-# was carried out, and this says so rather than exiting mute.
+# A stop between the line above and the fork: the same answer as one during the preparation.
 if [ "$signaled" -eq 1 ]; then
-	echo "worker-env-wrapper: stopped before the worker started -- a stop signal arrived while the environment was being prepared, so the command was never launched; exiting 0 (nothing to restart)" >&2
-	exit 0
+	wrapper_stopped_early
 fi
 
 # `exec` is deliberately GONE here (it used to hand this shell's pid straight to node): intercepting

package/deploy/worker.service

@@ -13,20 +13,28 @@
 # WorkingDirectory / EnvironmentFile / User / node path below are PLACEHOLDERS: set them to wherever
 # you cloned the repo and whoever owns it.
 #
-# PI_LOGS_DIR (run-history records; default OS-temp /pi-dispatch/logs) is created and written by the
-# worker at boot, so it must be writable by User= (pi) -- do NOT pre-create it as root, or the non-root
-# worker hits EACCES at boot. Set via `.env` (EnvironmentFile), no unit change needed; the default path
-# avoids colliding with the daemon's own logs/worker.out.log.
+# PI_LOGS_DIR (run-history records) and PI_SETTINGS_FILE (the runtime-tunable settings overlay) both
+# default to ~/.pi-dispatch, which is DURABLE across a reboot. Both are created and written by the
+# worker at boot, so they must be writable by User= (pi) -- do NOT pre-create them as root, or the
+# non-root worker hits EACCES at boot.
 #
-# PI_SETTINGS_FILE is the runtime-tunable settings overlay (default under OS temp, which may be wiped on
-# reboot) -- point it at a durable path in production. Set via `.env` (EnvironmentFile), no unit change
-# needed; it is worker-owned and never belongs in the container env allowlist.
+# SET BOTH EXPLICITLY HERE, and this is the one setting on this page you should not skip. The default
+# is per USER, and User= below is very likely not the account you run `/dispatch` from: leave them
+# unset and the worker writes ~pi/.pi-dispatch while your panel reads ~you/.pi-dispatch, so the run
+# list shows nothing and every cap you set from the panel lands in a file this worker never opens.
+# `pi-dispatch up` writes both into `.env` for you, as the ACCOUNT DEFAULT resolved by whoever ran it.
+# If your own shell sets either to a relative path or one inside the deployment folder, `up` refuses to
+# persist it and says so, because the retention sweep below is why. If the service runs as
+# another account than the one that ran `up`, check that account can write there. Set via `.env`
+# (EnvironmentFile), no unit change needed; both are worker-owned and never belong in the container
+# env allowlist. Do not point PI_LOGS_DIR at the daemon's own logs/ directory: the retention sweep
+# deletes every .log and .json past its window and would eat worker.out.log.
 
 [Unit]
 Description=pi-dispatch worker (drains the job queue on the host; launches job containers via docker)
 After=network-online.target docker.service
 Wants=network-online.target
-# Valkey must be reachable (docker compose -f deploy/docker-compose.yml up -d), but it is a separate
+# Valkey must be reachable (on this host, `pi-dispatch up` in the deployment folder starts it), but it is a separate
 # unit/container -- not ordered here since it may be remote.
 # Crash-loop bound: at most StartLimitBurst restarts within StartLimitIntervalSec, then systemd stops
 # trying. A restart loop against a paid provider is a bill, not just log noise. Pairs with
@@ -36,6 +44,8 @@ StartLimitBurst=5
 
 [Service]
 Type=simple
+# On native Linux a job container runs as this account's uid (issue #341), so a local-folder trigger's folder
+# must be writable by it, and the account must not be root.
 User=pi
 WorkingDirectory=/opt/pi-dispatch
 EnvironmentFile=/opt/pi-dispatch/.env

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.10.3",
+  "version": "2.1.0",
   "type": "module",
-  "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
+  "description": "The pi-dispatch worker and CLI: runs the pi coding agent as a self-hosted service, one locked down Docker or Podman container per job, with spend caps checked before anything is spent, plus init, up, doctor and service install.",
   "keywords": [
     "pi",
     "pi-coding-agent",
@@ -19,7 +19,8 @@
     "bullmq",
     "cron",
     "docker",
-    "cli"
+    "cli",
+    "podman"
   ],
   "license": "MIT",
   "author": "Rob Boerman",
@@ -43,6 +44,11 @@
     ".": "./src/index.mjs",
     "./config": "./src/config.mjs",
     "./exit-code": "./src/exit-code.mjs",
+    "./entry": "./src/entry.mjs",
+    "./git-hardening": "./src/git-hardening.mjs",
+    "./env-file": "./src/env-file.mjs",
+    "./service-env": "./src/service-env.mjs",
+    "./podman-stack": "./src/podman-stack.mjs",
     "./flow-gate": "./src/flow-gate.mjs",
     "./materialize": "./src/materialize.mjs",
     "./open-browser": "./src/open-browser.mjs",
@@ -50,6 +56,7 @@
     "./queue": "./src/queue.mjs",
     "./capabilities": "./src/capabilities.mjs",
     "./connection": "./src/connection.mjs",
+    "./valkey-auth": "./src/valkey-auth.mjs",
     "./job-id": "./src/job-id.mjs",
     "./forges": "./src/forges.mjs",
     "./backend-local": "./src/backend-local.mjs",
@@ -57,6 +64,7 @@
 		"./backend-registry": "./src/backend-registry.mjs",
 		"./container-spec": "./src/container-spec.mjs",
 		"./backend-conformance": "./src/backend-conformance.mjs",
+		"./live-probes": "./src/live-probes.mjs",
 		"./triggers": "./src/triggers.mjs",
     "./triggers-file": "./src/triggers-file.mjs",
     "./packages": "./src/packages.mjs",
@@ -64,6 +72,7 @@
     "./scoped-limits": "./src/scoped-limits.mjs",
     "./wait-for": "./src/wait-for.mjs",
     "./wait-state": "./src/wait-state.mjs",
+    "./cancel-state": "./src/cancel-state.mjs",
     "./host-registry": "./src/host-registry.mjs",
     "./identity": "./src/identity.mjs",
     "./gitlab-identity": "./src/gitlab-identity.mjs",
@@ -78,7 +87,8 @@
     "./subscriptions": "./src/subscriptions.mjs",
     "./budget": "./src/budget.mjs",
     "./pricing": "./src/pricing.mjs",
-    "./scheduler-stall-guard": "./src/scheduler-stall-guard.mjs"
+    "./scheduler-stall-guard": "./src/scheduler-stall-guard.mjs",
+    "./watch-closer": "./src/watch-closer.mjs"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -88,7 +98,7 @@
     "start": "node src/cli.mjs worker"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "0.80.7",
+    "@earendil-works/pi-ai": "0.99.1",
     "@octokit/auth-app": "8.2.0",
     "@octokit/rest": "22.0.1",
     "bullmq": "5.80.4",

package/src/azure-host.mjs

@@ -24,6 +24,7 @@
 import { configError } from "./config.mjs";
 import { InfraRetry } from "./processor.mjs";
 import { fetchFailureReason } from "./gitlab-identity.mjs";
+import { isDeterminateFetchFailure } from "./transient.mjs";
 
 const API_VERSION = "7.1";
 
@@ -42,6 +43,15 @@ export function makeAzureHost({ orgUrl, fetchFn = fetch } = {}) {
 		try {
 			res = await fetchFn(url, { headers: { Authorization: authHeader(token), accept: "application/json" }, redirect: "error" });
 		} catch (err) {
+			// The one condition where the identity modules and this one now agree, because the issue's
+			// acceptance asks for exactly that (#316): a TLS trust failure, a protocol mismatch and a URL
+			// that always redirects are the operator's, and retrying them twice before failing tells
+			// nobody anything. Everything else here stays unconditionally retryable, which is right for a
+			// per-job call behind the queue: a wrong retry costs one more attempt, a wrong refusal costs
+			// the delivery and posts publicly that the deployment is misconfigured.
+			if (isDeterminateFetchFailure(err)) {
+				throw configError(`azure-host: GET ${path} failed (${fetchFailureReason(err)})`);
+			}
 			throw new InfraRetry(`azure-host: GET ${path} failed (${fetchFailureReason(err)})`);
 		}
 		if (!res.ok) {
@@ -157,6 +167,15 @@ export function makeAzureHost({ orgUrl, fetchFn = fetch } = {}) {
 				redirect: "error",
 			});
 		} catch (err) {
+			// The one condition where the identity modules and this one now agree, because the issue's
+			// acceptance asks for exactly that (#316): a TLS trust failure, a protocol mismatch and a URL
+			// that always redirects are the operator's, and retrying them twice before failing tells
+			// nobody anything. Everything else here stays unconditionally retryable, which is right for a
+			// per-job call behind the queue: a wrong retry costs one more attempt, a wrong refusal costs
+			// the delivery and posts publicly that the deployment is misconfigured.
+			if (isDeterminateFetchFailure(err)) {
+				throw configError(`azure-host: POST ${path} failed (${fetchFailureReason(err)})`);
+			}
 			throw new InfraRetry(`azure-host: POST ${path} failed (${fetchFailureReason(err)})`);
 		}
 		if (!res.ok) {

package/src/azure-identity.mjs

@@ -15,6 +15,7 @@
  */
 
 import { configError } from "./config.mjs";
+import { isDeterminateFetchFailure, isJsonContentType, isTransientStatus, responseHeaderReader, transientError } from "./transient.mjs";
 import { fetchFailureReason } from "./gitlab-identity.mjs";
 
 /**
@@ -33,17 +34,32 @@ export async function resolveAzureSelfId({ orgUrl, token, fetchFn = fetch }) {
 	try {
 		res = await fetchFn(url, { headers: { Authorization: auth, accept: "application/json" }, redirect: "error" });
 	} catch (err) {
-		throw configError(`could not resolve the azure bot identity from ${url}: ${fetchFailureReason(err)}`);
+		// Transient, EXCEPT for the trust and redirect faults below. azure-host.mjs retries every
+		// rejection unconditionally; that is right for a job and wrong for a boot, which is the whole
+		// distinction issue #316 turns on.
+		if (isDeterminateFetchFailure(err)) throw configError(`could not resolve the azure bot identity from ${url}: ${fetchFailureReason(err)}`);
+		throw transientError(`could not resolve the azure bot identity from ${url}: ${fetchFailureReason(err)}`, err);
 	}
 	if (!res.ok) {
 		// The status only. An Azure error body can echo the request, and the request carried the token.
+		if (isTransientStatus(res.status, responseHeaderReader(res))) {
+			throw transientError(`could not resolve the azure bot identity: connectionData returned ${res.status}`);
+		}
 		throw configError(`could not resolve the azure bot identity: connectionData returned ${res.status}`);
 	}
 	let body;
 	try {
 		body = await res.json();
 	} catch (err) {
-		throw configError(`could not resolve the azure bot identity: unparseable JSON from connectionData (${err?.message ?? "unknown"})`);
+		// A body that will not parse is ambiguous in the expensive direction, so the CONTENT TYPE
+		// decides it. A truncated JSON body is transient. An HTML page is not: it is a Cloudflare
+		// Access or OIDC portal answering instead of the forge, and no amount of restarting gets past
+		// one (issue #316).
+		const contentType = responseHeaderReader(res);
+		if (contentType("content-type") !== undefined && !isJsonContentType(contentType)) {
+			throw configError(`could not resolve the azure bot identity: connectionData answered ${String(contentType("content-type"))} instead of JSON. Azure answers an expired or invalid PAT with 203 and a sign-in page, which is what this usually is`);
+		}
+		throw transientError(`could not resolve the azure bot identity: unparseable JSON from connectionData (${err?.message ?? "unknown"})`, err);
 	}
 
 	const user = body?.authenticatedUser ?? {};

package/src/backend-conformance.mjs

@@ -14,7 +14,9 @@
  *
  * WHAT IT CAN AND CANNOT DO, stated at its true size. It verifies the SHAPE of a bundle, the INTERNAL
  * CONSISTENCY of its declaration, and the behaviour of whatever the caller's PROBES produce. It cannot
- * start a real container, reach a real daemon, or prove a kernel enforced anything.
+ * start a real container, reach a real daemon, or prove a kernel enforced anything itself: the eight properties a
+ * container read can reach arrive through a `readBack` probe (READ_BACK_BY_A_LIVE_PROBE), which for `local` is
+ * `doctor --live`.
  *
  * THE PROBES ARE THE ADAPTER'S OWN CODE, and that is a real limit rather than a detail. How you make a
  * container exit 2, or make an enumeration fail, is the runtime's business and cannot be written
@@ -199,7 +201,9 @@ function checkTransfers(backend) {
  * `probe` is the one thing an adapter must supply: `(backend, { exitCode, aborted }) => result`, arranging
  * for the backend's own `runContainer` to produce a container that exits that way. It cannot be written
  * generically -- how you make a container exit 2 is the runtime's business -- and it is the reason this is a
- * function taking probes rather than a fixed suite.
+ * function taking probes rather than a fixed suite. `withBrokenEnumeration` drives the reaper's failure path, and
+ * `readBack(backend)` reports the eight properties read off a live container (see READ_BACK_BY_A_LIVE_PROBE); each
+ * one missing abstains.
  *
  * Returns `{ ok, findings }`. `ok` is false if ANY check failed; a check that abstained does not fail the
  * run but is reported, because a property nobody could verify is not a property that was verified.
@@ -236,27 +240,76 @@ async function conformance(backend, probes) {
 		findings.push(abstain("abortable", "no `probe` supplied, so an abort could not be told from an OOM"));
 	}
 	findings.push(...(await checkReaperTriState(backend, probes)));
+	findings.push(...(await checkReadBack(backend, probes)));
 	return { ok: findings.every((f) => f.ok), findings };
 }
 
 /**
- * The properties this harness DOES NOT verify, and why -- printed alongside the findings so a green run is
- * never mistaken for a conformant backend.
+ * The properties a LIVE PROBE reads back off a real container (issue #278), rather than this harness checking a
+ * report or the declaration itself. For `local` that probe ships: `doctor --live` (`live-probes.mjs`). For any other
+ * runtime the adapter supplies `readBack(backend)`, which must return the same verdicts -- `{ [property]: { ok,
+ * warn?, detail } }`, or `live-probes.mjs`'s array of `{ property, ok, warn?, detail }` -- read off a container its
+ * own `runContainer` path started. Like `probe`, a readBack that fabricates its answer passes while proving nothing.
+ */
+export const READ_BACK_BY_A_LIVE_PROBE = Object.freeze(["isolation", "ephemeral", "mountSet", "egress", "jobToJobIsolation", "imagePinning", "nonRoot", "localFolders"]);
+
+/**
+ * THE READ-BACK. Abstains without a report, and per property for anything the report does not cover or could not
+ * read, because a property nobody read is not one that held. A property read back as NOT holding fails when the
+ * backend declares it `enforced` or `asserted` -- both claim it is provided -- and passes against `absent`, which
+ * claimed nothing.
+ */
+async function checkReadBack(backend, { readBack }) {
+	if (typeof readBack !== "function") {
+		return READ_BACK_BY_A_LIVE_PROBE.map((property) => abstain(property, "no `readBack` probe supplied, so it was not read off a live container (doctor --live reads local's)"));
+	}
+	const raw = await readBack(backend);
+	// OWN properties only, and a property named twice in an array is ambiguous rather than last-wins: a report that
+	// says a property both fails and holds must not be read as holding.
+	const report = Object.create(null);
+	const repeated = new Set();
+	if (Array.isArray(raw)) {
+		for (const v of raw) {
+			const property = v?.property;
+			if (typeof property !== "string") continue;
+			if (Object.hasOwn(report, property)) repeated.add(property);
+			report[property] = v;
+		}
+	} else if (raw && typeof raw === "object") {
+		for (const property of Object.keys(raw)) report[property] = raw[property];
+	}
+	const declares = backend?.declares ?? {};
+	const claimed = (property) => declares[property] === "enforced" || declares[property] === "asserted";
+	// A reading counts only through its OWN `ok`; any truthy `warn`, own or not, means not read back.
+	const failing = (v) => v && typeof v === "object" && Object.hasOwn(v, "ok") && v.ok === false && !v.warn;
+	return READ_BACK_BY_A_LIVE_PROBE.map((property) => {
+		if (repeated.has(property)) {
+			// Ambiguous, but not in the backend's favour: any failing reading among the repeats fails a claimed property.
+			const failed = raw.filter((v) => v?.property === property && failing(v));
+			if (failed.length > 0 && claimed(property)) return fail(property, `declared ${declares[property]}, and among the readings the report names more than once, one does not hold: ${failed[0].detail ?? "no detail"}`);
+			return abstain(property, "the readBack report names it more than once, so which reading holds is not known");
+		}
+		const got = Object.hasOwn(report, property) ? report[property] : undefined;
+		if (!got || typeof got !== "object" || !Object.hasOwn(got, "ok") || typeof got.ok !== "boolean") return abstain(property, "the readBack report does not cover it");
+		// `warn` first: a reading marked not-read-back is never a pass, whatever its `ok` says.
+		if (got.warn) return abstain(property, `${got.detail ?? "not read back"}`);
+		if (got.ok === true) return pass(property, `read back off a live container: ${got.detail ?? "holds"}`);
+		if (claimed(property)) {
+			return fail(property, `declared ${declares[property]}, and read back off a live container as not holding: ${got.detail ?? "no detail"}`);
+		}
+		return pass(property, `read back as not holding, which ${JSON.stringify(declares[property])} does not claim`);
+	});
+}
+
+/**
+ * The properties NEITHER this harness NOR a live read-back verifies, and why -- printed alongside the findings so a
+ * green run is never mistaken for a conformant backend.
  *
- * Every one of these needs a live container on the target runtime, which is exactly what this repo's own
- * offline CI cannot have. Naming them is the difference between a suite that is honest about its reach and
- * one that lets a green tick stand for something it never checked. `verify-image.sh` is the shape the
- * missing half would take, and it "runs ON THE HOST THAT HOLDS THE IMAGE, which is the only place it can".
+ * Eight of the ten that once stood here are now READ_BACK_BY_A_LIVE_PROBE (six in issue #278, `ephemeral` and
+ * `jobToJobIsolation` in issue #344). The two left are not container properties at all, so no container read can
+ * reach them.
  */
 export const UNVERIFIED_BY_THIS_HARNESS = Object.freeze({
-	isolation: "needs a live container: read the capability set and no-new-privileges back from inside it",
-	ephemeral: "needs two runs of the same job id and a check that no container survived the first",
-	mountSet: "needs a live container: enumerate its mounts and assert nothing beyond the declared set",
-	egress: "needs a live container and a blocked destination",
-	jobToJobIsolation: "needs two live containers and an attempted connection between them",
-	imagePinning: "needs a run against an image absent from the target runtime",
-	nonRoot: "needs `id -u` inside a live container (`verify-image.sh` is the shape)",
-	secretsCustody: "needs a canary secret and an audit of every log, record and forge comment the run produced",
-	credentialTransit: "needs to observe what actually crossed the network to the runtime",
-	localFolders: "needs a bind-mounted host folder and a write read back outside the container",
+	secretsCustody: "not a container property: needs a canary secret and an audit of every log, record and forge comment the run produced",
+	credentialTransit: "not a container property: what crossed the network to the runtime; local's is observed per job from the docker CLI's endpoint instead",
 });