@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/src/run-container.mjs

@@ -1,18 +1,32 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { readFileSync, rmSync } from "node:fs";
+import { mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { DOCKER_NEVER_STARTED_EXITS } from "./backends.mjs";
-import { CONTAINER_HOME, memoryBytesOfArgs } from "./container-spec.mjs";
+import { CONTAINER_GLOBAL_PI_DIR, CONTAINER_HOME, memoryBytesOfArgs } from "./container-spec.mjs";
+import { layoutFor } from "./job-layout.mjs";
 import { cpuCeilingCenti, cpuRangeRefusal, DEFAULT_JOB_SIZE } from "./job-size.mjs";
 import { buildDockerRunArgs, CONTAINER_SESSION_FILE, insideDir } from "./docker-run.mjs";
-import { createJobNetwork, networkNameFor, removeJobNetwork } from "./egress.mjs";
+import { configError } from "./config.mjs";
+import { createJobNetwork, egressEnv, networkNameFor, removeJobNetwork } from "./egress.mjs";
 import { buildContainerEnv } from "./env-allowlist.mjs";
+import { authenticExitLines } from "./run-history.mjs";
+import { extensionsNotHere, leavesOut, leftOutOf, rebuildLoaded } from "./loaded-record.mjs";
+import { withCanaryPath } from "./package-canary.mjs";
+import { parsePackageCanary } from "./package-canary-record.mjs";
+import { EXCLUDABLE_TOOL_NAMES } from "./triggers.mjs";
 import { resolveJobImage } from "./image-preflight.mjs";
+import { LIVE_FILE_NAME, stageLiveFile } from "./live-transcript.mjs";
+import { steerTargetOf } from "./inbox-relay.mjs";
 import { InfraRetry } from "./processor.mjs";
+import { makeRedactor, secretValuesOf } from "./redact-secrets.mjs";
+import { makeSteerAck } from "./steer-ack.mjs";
+import { keyFrame } from "./steer-framing.mjs";
+import { makeStderrTranscript } from "./stderr-transcript.mjs";
 
 /**
  * The real `runContainer` the processor injects. Launches one job container and returns
- * `{ code, aborted, turns, tokens, session, usage, context, exitReason, resources?, exitOomKilled?, memoryLimit? }`, where `aborted` records whether the WORKER initiated the stop (docker stop on
+ * `{ code, aborted, turns, tokens, session, usage, context, exitReason, resources?, exitOomKilled?, memoryLimit?, progress? }`, where `aborted` records whether the WORKER initiated the stop (docker stop on
  * the 30-min timeout or graceful shutdown), which the processor classifies as POLICY (no retry) per
  * INT-RUNNER-EXIT-CODE-PROTOCOL. The numeric `code` alone cannot say this: a worker SIGKILL and a
  * kernel OOM both surface as 137, so the abort FLAG -- not the code -- is the discriminator.
@@ -42,7 +56,14 @@ export function makeRunContainer({
 	// REQ-GLOBAL-PI-OVERLAY: container paths of the operator-staged packages. An array, or a RESOLVER called
 	// once per job (issue #102): the wired worker passes a resolver so a re-stage lands on the next job with
 	// no restart, while the array form stays valid for every caller that has a fixed set.
+	// Issue #800: a resolver may carry `rowOf(path)`, the `{ name, version }` its last read holds for a path, which names
+	// the runner's positional rows, and `stageRead()`, false when this read could not say what is staged. On the resolver,
+	// not a second option, because every venue passes this one function through untouched, and a second option could reach a
+	// venue without it and record a job's packages with no names.
 	packagePaths = [],
+	// Issue #800: the names in `<overlay>/extensions`, which an overlay name on the exit line has to be one of. A seam for
+	// the tests. A folder that cannot be read holds nothing the worker can vouch for, so a name then reads as invalid.
+	readOverlayExtensions = (dir) => readdirSync(dir),
 	forwardEnv = [],
 	authFromPi = false, // fall back to ~/.pi/agent/auth.json for the provider key when the env has none
 	forgeHosts = {}, // per-forge self-hosted instance URLs, so a forge CLI in the container talks to the right one
@@ -69,7 +90,72 @@ export function makeRunContainer({
 	// the wiring drops the cached runtime facts the ceiling came from and the next pickup reads them again. The local
 	// venue's is the job-user resolver's `invalidate`; a no-op elsewhere (Podman accepts any `--cpus`, measured).
 	onCpuCeilingStale = () => {},
+	// Issue #643: `({ file, jobId, redact, job }) => { start, finish, progressSummary? } | null`, the live transcript
+	// publisher's opener (live-transcript.mjs `makeLiveTranscriptOpener`), which since issue #644 also reads run progress.
+	// Null publishes nothing: a deployment with PI_LIVE_TRANSCRIPTS=0 and PI_RUN_PROGRESS=0, one without a Valkey client,
+	// and every caller that predates the feature.
+	openLiveTranscript = null,
+	// Issue #645: stages the live transcript file for a `run.recover` job the preparer staged none for (both live switches
+	// off). A seam so a test can refuse it.
+	stageLive = stageLiveFile,
+	// Issue #645: the bound on each step of stopping a container whose unpause never took.
+	checkpointStopTimeoutMs = 15_000,
+	// Issue #646: `({ runId, jobId, inboxDir, targetKey, ref, forge }) => relay`, the inbox relay's opener (inbox-relay.mjs
+	// `makeInboxRelay`, bound in start.mjs to the worker's Valkey client and host name). Null arms no job: a steer job is
+	// then run without steering and its record says `steerSkipped: "no-transcript"`, never a silent no-op. Issue #686: a
+	// stdin-steered attempt opens it with `inboxDir: null` and `frames: { exitKey, macRunId }`, then `attach`es the pipe.
+	openInboxRelay = null,
+	// Issue #646: the host fs the inbox directory is made and removed through. A seam for the tests.
+	inboxFs = { mkdirSync, rmSync },
+	// Issue #683: the venue's file layout (job-layout.mjs). `mounts` for every binding venue, byte-identical to before;
+	// `sandbox` for a copying one (`openshell`), which moves the session file and the staged packages' container paths
+	// under /sandbox and writes PI_JOB_LAYOUT.
+	layout = "mounts",
+	// Issue #683: the container's memory bound in bytes, given the argv and the options it was built from. Both binding
+	// builders spell it `--memory=`, so the default reads the argv; a venue whose argv carries no such flag (an `exec`
+	// into a sandbox sized at create) says it from the job's size instead.
+	memoryLimitOf = (args) => memoryBytesOfArgs(args),
+	// Issue #683: a copying venue's own steps around the CLI child, each awaited. `stageRun({ args, opts })` runs after the
+	// argv is built and before the spawn (the venue's create, policy read-back and upload); a throw there is
+	// `container-never-started`, refunded and retried, since nothing ran. `collectRun(result)` runs once the child has
+	// closed (the download), and returns the result to resolve with. `teardownRun()` runs in the `finally`, on every
+	// path a `stageRun` was begun on (the delete). Each is handed THIS attempt's build options (`opts`, the name among
+	// them), so a venue running several jobs at once acts on its own sandbox only. Absent, a binding venue's run is
+	// exactly what it was.
+	stageRun = null,
+	collectRun = null,
+	teardownRun = null,
+	// Issue #686: how this venue's session file reaches the host while the job runs. `file` for every binding venue (the
+	// live tail reads the bind-mounted file, byte-identical to before); `stdio` for a copying one (`openshell`), whose
+	// runner mirrors the file's lines over the CLI's stderr as records signed with the exit key, which this side
+	// verifies and pushes into the same publisher (stderr-transcript.mjs). A CONSTRUCTION option, the venue's own
+	// statement beside `layout`, rather than read off the call bag's `binds`: `binds` reaches a steer job only (the
+	// registry adds it for that one question), while every job of a copying venue needs this answer, and a venue that
+	// copies but cannot mirror (none today) is then named for what it is (`venue-copies`) instead of guessed from a flag.
+	transcript = "file",
+	// Issue #686: the stderr demux's factory (stderr-transcript.mjs). A seam so a test can make it fail.
+	makeDemux = makeStderrTranscript,
+	// Review round 1, M1: how long a stdin-steered attempt's pipe stays open after an exit-shaped line that does not verify.
+	stdinExitGraceMs = 5_000,
+	// Issue #686 part 3, review round 2 of #714: `({ opts, aborted }) => boolean`, a binding venue whose box OUTLIVES its CLI
+	// child (`openshell-bind`: the sandbox stays after the exec, and a process the agent left behind can still write the
+	// bound host tree). Awaited once the child has closed and BEFORE the transcript's final read and the sink's close, so
+	// the last lines and the processor's reads both see a tree nothing writes any more. `false` (not confirmed gone) puts
+	// `lingering: true` on the result, which the processor reads (no exit checkpoint; the named result where a retry
+	// would be wrong). Absent, every venue's run is exactly what it was.
+	settleRun = null,
+	// Issue #704 part 3: this venue hands a project secret bundle's plain variables to the runner by FILE (the job
+	// directory's bundle-env.json, which its `stageRun` writes), so an attempt with plain bundle variables gets
+	// PI_BUNDLE_ENV=1. A construction option, the venue's own statement like `transcript`: every binding venue passes
+	// them as env and leaves it off, so its env is byte-identical.
+	bundleEnvFile = false,
+	// Issue #730: this venue's connections are mediated by a broker that must read the caller's memory (OpenShell), so
+	// every attempt gets PI_RUNNER_OBSERVABLE=1 and its key holders start from the readable node. Every other venue
+	// leaves it off and its env is byte-identical.
+	observableRunner = false,
 }) {
+	// Refused at construction rather than written into a job's env: a guessed layout reads nothing.
+	const paths = layoutFor(layout);
 	// async so a synchronous throw (e.g. buildContainerEnv on an unconfigured provider) surfaces as
 	// a rejection, uniformly awaitable by the processor and by tests.
 	// `relabel` (issue #355) is the processor's, off the same job-user answer as `user`: true where the daemon confines
@@ -88,7 +174,27 @@ export function makeRunContainer({
 	// `unenforced` (issue #596) is the size flags this runtime said it drops (`unenforcedSizeFlags`: `--memory-swap` where
 	// Docker reports SwapLimit false, `--cpu-shares` where it reports CPUShares false), logged per job as
 	// `size_bound_unenforced` so a run past its size's bound is named where it happens. The flags stay on the argv.
-	return async function runContainer({ job, token, prepared, secrets = {}, name, signal, user = null, home = null, relabel = false, modelEndpoints = null, exitAuth = false, size = DEFAULT_JOB_SIZE, hostCpus = null, cpuBudgetCenti = null, unenforced = [] }) {
+	// `jobId` (issue #643) is the queue's job id, which names the live transcript stream as it names the run record
+	// (`run:live:` and `runs:rec:`, both through `sanitizeJobId`); absent, no stream is published.
+	// `onLive(finish)` (issue #644) hears this attempt's bounded, idempotent publisher finish once the publisher is open, so
+	// the processor can end it when it stops waiting for a container whose stop did not take (index.mjs
+	// `boundAfterAbort`). Without it the publisher ends only on the CLI child's `close` or `error`, which never comes
+	// for that container: the progress key's heartbeat rewrote it as running for its whole 7-day window.
+	// `checkpoint` (issue #645) is the processor's open args for the run checkpointer (`{ runId, attempt, baseSha, branch,
+	// secretValues, meta }`), honoured only beside `recover: true`; `pause`/`unpause` are this job's venue's freezer verbs,
+	// which the backend registry puts on the call bag (absent for a venue that cannot freeze: no live checkpoints then).
+	// `binds` (issue #646) is the venue's own statement that it bind-mounts (the backend bundle's `binds`, which the registry
+	// puts on the call bag of a steer job only): a copying venue would upload `/inbox` once, at the start, so no message
+	// written later would ever arrive. Absent is false: a job is steer-armed only on a venue that SAYS it binds.
+	// `transcriptStderr` (issue #686) is the processor's, off the image preflight like `exitAuth`: true when the job image
+	// declares `transcriptStderr`, so its runner can mirror the session file over stderr. Read only on a `stdio` venue.
+	// `steerStdin` (issue #686, part 2) is the processor's too: true when the job image declares `steerStdin`, so its
+	// runner reads steer messages as MAC'd frames on stdin. Read only for a steer job on a venue that copies (`binds` not
+	// true); a binding venue keeps the read-only mount whatever the image declares.
+	// `bundleKeys` (issue #704 part 3) is the processor's `{ endpoints, plain }` split of a project secret bundle's received
+	// variables: handed on in the build options for a venue whose own layer holds credentials (openshell), which binds the
+	// first kind to their hosts and passes the second as values. Every other venue ignores it: the values are in `secrets`.
+	return async function runContainer({ job, token, prepared, secrets = {}, bundleKeys = null, name, signal, user = null, home = null, relabel = false, modelEndpoints = null, exitAuth = false, transcriptStderr = false, steerStdin = false, size = DEFAULT_JOB_SIZE, hostCpus = null, cpuBudgetCenti = null, unenforced = [], jobId = null, onLive = null, recover = false, recovering = false, checkpoint = null, pause = null, unpause = null, binds = false, subscriptionAuth = [] }) {
 		if (signal?.aborted) return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null, context: null, exitReason: null }; // killed before it could start
 		// Minted per attempt, held in this closure and the sink's, and handed to the container on its stdin only: never in
 		// the argv (a host `ps` shows it), never in the env (the container's /proc/1/environ shows it), never logged.
@@ -100,15 +206,193 @@ export function makeRunContainer({
 			throw new Error(`runContainer: a job user (${user}) must be paired with HOME=${CONTAINER_HOME}`);
 		}
 
+		// Issue #643: the directory holding this job's transcript file, mounted at /session. A resume job's is its staged
+		// transcript, exactly as before; every other job's is the empty live file the preparer staged beside it
+		// (`prepared.live`, live-transcript.mjs `stageLiveFile`). Resume itself stays keyed on `prepared.session` alone:
+		// `awaitInput` below, the promotion and the record's `session` read nothing else.
+		let transcriptDir = prepared.session?.hostDir ?? prepared.live?.hostDir ?? null;
+		// Issue #645: an armed job keeps its transcript on the host whatever the live switches say. The checkpoints copy it,
+		// a salvage reads it from a crashed attempt's job dir, and the live checkpoints are driven by its lines, so with
+		// PI_LIVE_TRANSCRIPTS=0 and PI_RUN_PROGRESS=0 (no file staged by the preparer) it is staged here. Not for a resume
+		// job, whose staged transcript already is the file.
+		const armed = recover === true && checkpoint !== null && typeof checkpoint === "object";
+
+		// Issue #686 (DES-OPENSHELL-VENUE): whether this attempt's transcript comes over the CLI's stderr. Decided BEFORE
+		// steering, because a stdin-steered attempt's acks come back through it. Asked only where
+		// something would read it (an opener and a job id) on a venue whose session file is not on the host while it runs,
+		// and armed only when every part exists: the venue mirrors (`transcript: "stdio"`), the image's runner can
+		// (`transcriptStderr`), and there is an exit key to verify the records with. A missing part is a NAMED skip
+		// (`live_transcript_skipped`); the job still runs, with no live transcript and no progress, as before this issue.
+		const liveReadable = typeof openLiveTranscript === "function" && jobId !== null && jobId !== undefined;
+		let liveSkipped = null;
+		if (liveReadable && (transcript === "stdio" || layout !== "mounts")) {
+			if (transcript !== "stdio") liveSkipped = "venue-copies";
+			else if (transcriptStderr !== true) liveSkipped = "no-capability";
+			else if (exitKey === null) liveSkipped = "no-exit-key";
+		}
+		const stdioArmed = liveReadable && transcript === "stdio" && liveSkipped === null;
+		if (liveSkipped !== null) log("live_transcript_skipped", { container: name, reason: liveSkipped });
+
+		// Issue #646 (DES-STEER-VIA-READONLY-INBOX-MOUNT): whether this attempt is steer-ARMED. Asked by the job's data
+		// (`steer: true`, which the trigger's `run.steer` puts there and the image preflight already checked the image for),
+		// and armed only when every part of the channel exists: a venue that binds mounts, an exit key to verify the
+		// delivery acks with, and something to read those acks (a transcript tail) and to write the files (the relay).
+		// Each missing part is a NAMED skip on the record (`steerSkipped`); the job still runs, as it would without
+		// `run.steer`, and a message for it is refused at push because nothing ever registers it as open.
+		//
+		// Issue #686 (INT-STEER-INBOX-CONTRACT's second transport): on a venue that COPIES (`binds` not true) the inbox part
+		// is the exec's stdin instead of the mount, when the image's runner reads frames (`steerStdin`). Its parts are the
+		// same key, a relay, and the stdio transcript (`stdioArmed`, above), which is where the acks come back; without that
+		// the attempt is `no-transcript`, as a binding venue without a tail is. An image without `steerStdin` there is
+		// skipped exactly as before, `venue-copies`. A binding venue never takes this path, whatever the image declares.
+		const steerAsked = job?.steer === true;
+		const viaStdin = binds !== true && steerStdin === true;
+		let steerSkipped = null;
+		if (steerAsked) {
+			if (binds !== true && steerStdin !== true) steerSkipped = "venue-copies";
+			else if (exitKey === null) steerSkipped = "no-exit-key";
+			else if (typeof openInboxRelay !== "function" || typeof openLiveTranscript !== "function" || jobId === null || jobId === undefined) steerSkipped = "no-transcript";
+			else if (viaStdin && !stdioArmed) steerSkipped = "no-transcript";
+		}
+		if (transcriptDir === null && (recover === true || (steerAsked && steerSkipped === null)) && typeof stageLive === "function") {
+			try {
+				transcriptDir = stageLive(prepared.jobDir)?.hostDir ?? null;
+			} catch {
+				transcriptDir = null;
+			}
+		}
+		if (steerAsked && steerSkipped === null && transcriptDir === null) steerSkipped = "no-transcript";
+		// The inbox: `<jobDir>.inbox`, BESIDE the job directory (`/job` is merge-gated input only, and the processor removes
+		// the job directory itself), mode 0700, made fresh per attempt (a retry's messages are written again into its own),
+		// removed in this function's `finally`. Then the relay, built now (it starts with the container) because the env
+		// and the argv below depend on whether the attempt is armed.
+		const inboxDir = `${prepared.jobDir}.inbox`;
+		let inboxMade = false;
+		let relay = null;
+		// The stdin transport has no directory: its messages go down the pipe.
+		if (steerAsked && steerSkipped === null && !viaStdin) {
+			try {
+				inboxFs.rmSync(inboxDir, { recursive: true, force: true });
+				inboxFs.mkdirSync(inboxDir, { mode: 0o700 });
+				inboxMade = true;
+			} catch {
+				steerSkipped = "no-inbox";
+			}
+		}
+		if (steerAsked && steerSkipped === null) {
+			try {
+				// `runId` is the RUN's id (`jobId` here is `runIdOf(job)`, index.mjs), so a #645 recovery writes the same inbox.
+				// Issue #686: the stdin transport's relay MACs each frame under this attempt's key and the container's PI_JOB_ID
+				// (`name`, as the ack's `ackRunId`); a binding venue's relay is opened with exactly the arguments it always was.
+				relay = openInboxRelay({ runId: jobId, jobId, inboxDir: viaStdin ? null : inboxDir, ...steerTargetOf(job), ...(viaStdin ? { frames: { exitKey, macRunId: name } } : {}) }) ?? null;
+			} catch {
+				relay = null;
+			}
+			if (relay === null) steerSkipped = "no-transcript";
+		}
+		const steerArmed = steerAsked && steerSkipped === null;
+		// Issue #686: this attempt's key goes down stdin as frame 1 and the pipe stays OPEN for the relay's frames.
+		const stdinSteered = steerArmed && viaStdin;
+		if (steerSkipped !== null) log("steer_skipped", { container: name, reason: steerSkipped });
+		// The ack consumer, handed to the live tail below. It verifies under THIS attempt's exit key, against the very string
+		// put in the container's PI_JOB_ID (`jobId: name` in the env below), which is what the runner MACs: one value on both
+		// sides by construction. The per-attempt key is the domain separation between attempts; the string only has to match.
+		const steerAck = steerArmed ? makeSteerAck({ exitKey, ackRunId: name, relay, jobId, log }) : null;
+
+		const removeInbox = () => {
+			if (!inboxMade) return;
+			try {
+				inboxFs.rmSync(inboxDir, { recursive: true, force: true });
+			} catch {
+				// best effort: a leftover directory holds framed text the worker wrote, beside the job dir the sweep removes
+			}
+		};
+
 		// Closed env allowlist: only the provider key + the declared PI_* vars. Throws (config) if
 		// the provider is unconfigured, which the processor turns into a policy refusal that refunds the
 		// reserve. That sentence was aspirational until issue #310: the processor did not read the
 		// `piDispatchConfig` tag at all, so the throw fell through to a bare rethrow with the budget kept.
 		// The common case no longer reaches here either, because the processor probes the same resolution
 		// among its free gates, ahead of the mint and the clone.
-		const env = buildContainerEnv({
+		// Issue #646: a throw from here to the spawn (an unconfigured provider, a refused argv, a network that would not build)
+		// happens before the `finally` below exists, so the inbox directory made above is removed on the way out.
+		const beforeSpawn = (fn) => {
+			try {
+				return fn();
+			} catch (error) {
+				removeInbox();
+				throw error;
+			}
+		};
+		// Issue #796: a canary's candidate in place of the staged copy, by this layout's own `/job` path, so that it means the same on every venue.
+		const canaryPlan = prepared.packageCanary ?? null;
+		const withCanary = (list) => (canaryPlan ? withCanaryPath(list, canaryPlan, paths.job).paths : list);
+		const canaryPathOf = () => (canaryPlan ? withCanaryPath([], canaryPlan, paths.job).candidate : undefined);
+		// The staged set, read once for this job (issue #102), so the rows that name a package below are the read that chose
+		// its path. `!== false`, because staged packages LOAD unless a trigger explicitly opts out
+		// (INT-TRIGGERS-FILE-CONTRACT). The strictness that used to live in this `=== true` did not disappear, it moved:
+		// parseTriggers refuses any non-boolean run.packages fail-loud at load, so a hand-edited string "false" never becomes
+		// job data this comparison could misread as an opt-out. The opt-out short-circuits BEFORE the resolver runs: a trigger
+		// that withheld the staged set has no reason to make the worker read the manifest on its behalf.
+		const everyStaged = beforeSpawn(() => (job.packages === false ? [] : typeof packagePaths === "function" ? packagePaths() : packagePaths));
+		// Issue #800: run.excludeExtensions, by the manifest name of the read that chose these paths. Here and not in the resolver, which has
+		// no job. A path this cannot name is refused rather than loaded: a resolver with no `rowOf` is no wired worker, and loading what the
+		// file takes away is the one answer this must never give. The processor reads the tag as a free refusal.
+		const excludedNames = Array.isArray(job.excludeExtensions) ? job.excludeExtensions : [];
+		const stagedRowOf = (p) => (typeof packagePaths === "function" ? (packagePaths.rowOf?.(p) ?? null) : null);
+		const stagedPaths = excludedNames.length === 0 ? everyStaged : beforeSpawn(() => everyStaged.filter((p) => {
+			const row = stagedRowOf(p);
+			if (row === null) throw configError("run.excludeExtensions names extensions, and this worker cannot tell which staged package a path is");
+			return !excludedNames.includes(row.name);
+		}));
+		// Issue #683: the staged packages' container paths are the overlay's, so on the sandbox layout their prefix moves with
+		// it (`/opt/pi-global` to `/sandbox/pi-global`). A path not under the overlay is passed as it was.
+		const movedPath = (p) => (layout !== "mounts" && typeof p === "string" && p.startsWith(`${CONTAINER_GLOBAL_PI_DIR}/`) ? `${paths.global}${p.slice(CONTAINER_GLOBAL_PI_DIR.length)}` : p);
+		const jobPackagePaths = withCanary(stagedPaths.map(movedPath));
+		// Issue #800: what the runner's `loaded` is checked against (loaded-record.mjs), from what this attempt hands the job.
+		const stagedRows = new Map(stagedPaths.map((p) => [movedPath(p), stagedRowOf(p)]));
+		let overlayExtensions = [];
+		let overlayListed = true;
+		try {
+			overlayExtensions = globalPiDir ? readOverlayExtensions(join(globalPiDir, "extensions")) : [];
+		} catch (error) {
+			overlayExtensions = [];
+			// No folder is no extensions, as `readOverlayExtensionRows` reads it: an overlay of packages alone holds none, so a typo there is a name this host does
+			// not hold, and reading it as could-not-say would record it as left out. Only a read that failed some other way holds nothing to vouch for.
+			overlayListed = error?.code === "ENOENT";
+		}
+		// Issue #800: which of those names this host holds neither way, for the record. Only where both sides were read: a job with its packages
+		// withheld never reads the stage, a manifest that did not read says nothing is staged only by accident, and a folder that could not be listed
+		// holds nothing this can vouch for, so none of them says a name is absent. `=== false`, so an array of paths or a resolver with no such word stands as read.
+		const stageRead = typeof packagePaths !== "function" || packagePaths.stageRead?.() !== false;
+		const excludedNotHere = job.packages !== false && overlayListed && stageRead ? extensionsNotHere(excludedNames, { packages: everyStaged.map(stagedRowOf), overlay: overlayExtensions }) : [];
+		const excludedTools = Array.isArray(job.excludeExtensionTools) ? job.excludeExtensionTools : [];
+		// Whether a name in run.excludeExtensionTools that no staged package or overlay extension brought stops this job (`exclude-tool-not-loaded`): only one that should have
+		// held every extension it could. A trigger withholding packages or leaving one out, a host with the overlay shut, a chained child (its
+		// parent's list, for a job that may load less) and a restricted run may each lack the tool with the name right, so there it is only said.
+		const excludeToolsStrict = excludedTools.length > 0 && job.packages !== false && excludedNames.length === 0 && allowGlobalExtensions !== false && job.parentJobId === undefined && !(job.watch || job.answerDraft || job.questionGrouping);
+		const loadedKnown = {
+			packages: jobPackagePaths.map((p) => (p === canaryPathOf() ? parsePackageCanary(job.packageCanary) : (stagedRows.get(p) ?? null))),
+			overlayExtensions,
+			servers: Array.isArray(job.mcp) ? job.mcp : [],
+			ownTools: EXCLUDABLE_TOOL_NAMES,
+			// The closure's value, not the job's below: this worker's switch (the host's, or a canary replay's) and a restricted
+			// job's forced one are different statements.
+			leftOut: leftOutOf(job, { allowGlobalExtensions, excludedNotHere }),
+			// What the line's `unmatched` positions index: PI_EXCLUDE_EXTENSION_TOOLS, as this attempt hands it over.
+			excludeExtensionTools: excludedTools,
+			// A word from a closed list, never line text: the line is what is not trusted here.
+			onViolation: (why) => log("loaded_invalid", { container: name, why }),
+			// How many and no name: the record says only that a name was left out, and this says why.
+			onWithheld: (count) => log("loaded_names_withheld", { container: name, count }),
+		};
+		const env = beforeSpawn(() => buildContainerEnv({
+			size,
 			provider: job.provider,
+			...(job.answerDraft && job.answerDecisionModel ? { secondaryProvider: job.answerDecisionModel.provider } : job.questionGrouping && job.questionGroupModel ? { secondaryProvider: job.questionGroupModel.provider } : job.watch && job.watchDecisionModel ? { secondaryProvider: job.watchDecisionModel.provider } : {}),
 			model: job.model,
+			fork: job.fork ?? null,
+			thinkingLevel: job.thinkingLevel ?? null,
 			maxTurns: job.maxTurns,
 			maxTokens: job.maxTokens, // optional per-job token budget (issue #25); undefined => runner meter only
 			maxCostMicros: job.maxCostMicros ?? null, // issue #501: effectiveJobOf's min of trigger and deployment; null => no cap
@@ -120,21 +404,20 @@ export function makeRunContainer({
 			hostEnv,
 			egress, // REQ-EGRESS-ALLOWLIST: emits HTTPS_PROXY/HTTP_PROXY/NO_PROXY/NODE_USE_ENV_PROXY, or nothing
 			egressProxy,
-			allowGlobalExtensions, // REQ-GLOBAL-PI-OVERLAY: false emits the explicit PI_GLOBAL_ALLOW_EXTENSIONS=0 opt-out
+			allowGlobalExtensions: job.answerDraft || job.watch || job.questionGrouping ? false : allowGlobalExtensions,
 			// REQ-GLOBAL-PI-OVERLAY: the per-job value comes off `job` (like maxTurns), the staged set off
 			// the closure (like allowGlobalExtensions) -- so a trigger can withhold what the operator staged.
-			// `!== false`, because staged packages LOAD unless a trigger explicitly opts out
-			// (INT-TRIGGERS-FILE-CONTRACT). The strictness that used to live in this `=== true` did not
-			// disappear, it moved: parseTriggers refuses any non-boolean run.packages fail-loud at load, so a
-			// hand-edited string "false" never becomes job data this comparison could misread as an opt-out.
-			// The opt-out short-circuits BEFORE the resolver runs: a trigger that withheld the staged set has no
-			// reason to make the worker read the manifest on its behalf.
-			packagePaths: job.packages === false ? [] : typeof packagePaths === "function" ? packagePaths() : packagePaths,
-			forwardEnv, // extra host var names to forward (e.g. a custom provider's key)
-			// REQ-RESUMABLE-SESSION: the fixed container path, emitted only when this job HAS a transcript.
-			// The constant is imported rather than re-typed so the mount below and this variable name one
-			// path -- two literals is how they drift with both suites green.
-			sessionFile: prepared.session ? CONTAINER_SESSION_FILE : undefined,
+			packagePaths: jobPackagePaths,
+			packageCanaryPath: canaryPathOf(),
+			forwardEnv: job.answerDraft || job.watch || job.questionGrouping ? [] : forwardEnv,
+			// REQ-RESUMABLE-SESSION: the fixed container path, emitted only when this job HAS a transcript file, which
+			// since issue #643 is every prepared job (the live file), resume or not. The constant is imported rather than
+			// re-typed so the mount below and this variable name one path -- two literals is how they drift with both
+			// suites green. On an empty file the runner opens a fresh session there (image/runner/src/session.mjs), the
+			// same path a cold-starting resume job takes, so the image needs no change.
+			// Issue #683: under the layout's session directory, which on `mounts` is CONTAINER_SESSION_FILE exactly.
+			sessionFile: transcriptDir ? (layout === "mounts" ? CONTAINER_SESSION_FILE : `${paths.session}/current.jsonl`) : undefined,
+			layout,
 			// Issue #189: the flow name, structurally, so the runner can verify it against the loaded
 			// skill set. Off `job` like maxTurns; absent (a bare run.task cron job) emits no variable.
 			flow: typeof job.flow === "string" && job.flow.trim() !== "" ? job.flow : undefined,
@@ -146,15 +429,33 @@ export function makeRunContainer({
 			// non-empty validated array; the guard is the same defensive shape `flow` above wears, so a
 			// hand-built job with junk in the field emits no variable rather than an empty one.
 			excludeTools: Array.isArray(job.excludeTools) && job.excludeTools.length > 0 ? job.excludeTools : undefined,
+			excludeExtensions: excludedNames.length > 0 ? excludedNames : undefined,
+			excludeExtensionTools: excludedTools.length > 0 ? excludedTools : undefined,
+			excludeToolsStrict,
 			// REQ-MCP-OPERATOR-SERVERS: the trigger's MCP server names, off `job` like excludeTools.
 			mcpServers: Array.isArray(job.mcp) && job.mcp.length > 0 ? job.mcp : undefined,
 			// Issue #625: whether the runner offers the tool a parked run ends on. Only beside a staged transcript: the
 			// runner refuses the flag without one (await-input-without-session), so a job whose resume degraded to no
 			// mount is not armed into that refusal.
 			awaitInput: job.awaitInput === true && prepared.session ? true : undefined,
+			approvalGates: job.gates ?? null,
+			approvalDecision: job.approvalDecision ?? null,
+			// Issue #644: whether the runner offers `report_progress`, off `job` like awaitInput (env-allowlist.mjs maps it to
+			// PI_REPORT_PROGRESS=1). The worker reads the phases it reports only for the same job (`job.progress` below).
+			reportProgress: job.progress === true ? true : undefined,
+			// Issue #645, durable runs: off the call bag, NOT off `job`. Whether this attempt keeps checkpoints and whether it
+			// is the continuation of a lost one are the processor's decisions, made against the checkpoint store and the
+			// image's `recover` capability; a `job.recover` read here would arm a container the processor never cleared.
+			// Strict `=== true` both ways, so a truthy non-boolean arms nothing.
+			recover: recover === true,
+			recovering: recovering === true,
+			// Issue #646: PI_STEER=1, only for an ARMED attempt (above), never off `job.steer` alone: the runner refuses the
+			// flag without a readable /inbox and a key, and a job the worker could not arm must not be refused for it.
+			steer: steerArmed,
 			// Issue #502: the effective allowed-model list, off `job` like excludeTools. index.mjs `effectiveJobOf` folds
 			// the deployment's PI_ALLOWED_MODELS in under the trigger's own, so `job.models` is already the one list.
 			allowedModels: Array.isArray(job.models) && job.models.length > 0 ? job.models : null,
+			subscriptionAuth,
 			authFromPi, // source the provider key from pi's auth.json when the env has none
 			// REQ-TRIGGER-SECRETS: this trigger's resolved secrets, fetched by the processor BEFORE anything
 			// spent. Off the call bag rather than off `job` or the closure: it is neither a per-job fact the
@@ -163,7 +464,22 @@ export function makeRunContainer({
 			home: user !== null ? home : null, // issue #341: HOME only beside --user, assigned after the forward loops
 			modelEndpoints, // issue #503: the keyless branch of the credential, from the gate's own snapshot
 			exitAuth: exitKey !== null, // issue #545: PI_EXIT_AUTH=stdin, only when a key is actually handed over below
-		});
+			// Issue #686: PI_TRANSCRIPT=stderr, only for an attempt armed above, never off the image's label alone: the
+			// worker must be reading the records, or they would reach the job log as noise.
+			transcriptStderr: stdioArmed,
+			// Issue #686: PI_EXIT_AUTH=stdin-frames, only for an attempt armed above for stdin steering (beside PI_STEER=1).
+			steerStdin: stdinSteered,
+			bundleEnvFile: bundleEnvFile === true && Array.isArray(bundleKeys?.plain) && bundleKeys.plain.length > 0,
+			observableRunner: observableRunner === true,
+		}));
+		// Issue #800: a tool name is the one string on the line nothing here can compare with anything, so at least it must
+		// not hold this job's own secrets. Built off THIS job's env, as the transcript's is below. If it cannot be built, nothing
+		// can be judged: every name reads as one it would change and is withheld, and a `pi` reads as invalid, rather than as fine.
+		try {
+			loadedKnown.redact = makeRedactor({ values: secretValuesOf(env, [token, exitKey], { workerSet: egressEnv({ proxy: egressProxy, armed: egress }) }) });
+		} catch {
+			loadedKnown.redact = () => "";
+		}
 
 		// `-net` on this container's own name (egress.mjs). null when no policy is armed, and docker-run's
 		// guard then omits the flag entirely, so the argv is byte-identical to one built before this feature.
@@ -172,6 +488,9 @@ export function makeRunContainer({
 		// Issue #345: BESIDE the job directory, never inside the `/job:ro` mount. Removed first because the docker CLI refuses
 		// to start with an existing cidfile; every attempt's job dir is a fresh mkdtemp, so a leftover is not expected, and
 		// this keeps one from turning into a start failure if a caller ever reuses a directory.
+		// env-internal PI_MODEL_ROLES_FILE: closed read-only job input, set by the worker.
+		// env-internal PI_AGENTS_FILE: base-commit agent snapshot beside the role map.
+		if (job.modelRoles) { env.PI_MODEL_ROLES_FILE = `${paths.job}/model-roles.json`; env.PI_AGENTS_FILE = `${paths.job}/agents.json`; }
 		const cidFile = `${prepared.jobDir}.cid`;
 		try {
 			fs.rmSync(cidFile, { force: true });
@@ -179,7 +498,7 @@ export function makeRunContainer({
 			// an unremovable stale file makes the run itself fail to start, which is reported as that
 		}
 
-		const args = buildArgs({
+		const buildOpts = {
 			// Same split as packagePaths above: the per-job value off `job`, the deployment value off the closure,
 			// so a trigger can name its own toolchain (INT-TRIGGERS-FILE-CONTRACT). Resolved through the SAME
 			// function the pre-spend preflight uses (image-preflight.mjs), so the tag that was checked is the tag
@@ -189,9 +508,11 @@ export function makeRunContainer({
 			jobDir: prepared.jobDir,
 			workspace: prepared.workspace,
 			outboxDir: prepared.outboxDir, // undefined for github jobs -> docker-run's guard skips the /outbox mount
-			// The job's OWN copy, under jobDir -- never the shared store. Undefined when the trigger did not
-			// arm run.resume or no key resolved, and docker-run's guard then skips the mount entirely.
-			sessionDir: prepared.session?.hostDir,
+			// The job's OWN copy, under jobDir -- never the shared store. Undefined only when no transcript file was staged
+			// (a caller that predates issue #643, or a staging that failed), and docker-run's guard then skips the mount.
+			sessionDir: transcriptDir ?? undefined,
+			// Issue #646: the inbox, read-only at /inbox, for an armed attempt only; undefined leaves the argv byte-identical.
+			steerInboxDir: steerArmed && !stdinSteered ? inboxDir : undefined,
 			globalPiDir, // undefined/null -> docker-run's guard skips the /opt/pi-global mount
 			name,
 			size, // issue #596: memory, swap equal to it, the CPU weight and /dev/shm, through containerSpec's one function
@@ -207,15 +528,19 @@ export function makeRunContainer({
 			// Both facts, the kind the preparers branch on AND containment in this job's own directory, so a kind added later
 			// that works on a folder in place fails closed rather than relabelling it.
 			workspaceOwned: job?.kind !== "local" && insideDir(prepared.jobDir, prepared.workspace),
+			workspaceReadOnly: Boolean(job.answerDraft || job.watch || job.questionGrouping),
 			// Issue #545: `-i`, so the container's stdin is the pipe the key is written to. Absent otherwise, and the argv is
 			// byte-identical to one built before the signed exit line.
 			...(exitKey !== null ? { extraFlags: ["-i"] } : {}),
-		});
+			// Issue #704 part 3: absent without a bundle, so every other build is byte-identical.
+			...(bundleKeys !== null && typeof bundleKeys === "object" ? { bundleKeys } : {}),
+		};
+		const args = beforeSpawn(() => buildArgs(buildOpts));
 
 		// Issue #596: the memory bound this container actually got, in bytes, read off the argv the runtime is handed (both
 		// builders spell it `--memory=`, from the job's size), never re-derived from the environment or the size. The
 		// processor confirms an OOM only when the run's peak reached 90% of it. null when the argv names none.
-		const memoryLimit = memoryBytesOfArgs(args);
+		const memoryLimit = memoryLimitOf(args, buildOpts);
 		if (!args.some((a) => typeof a === "string" && a.startsWith("--cpus="))) log("cpu_ceiling_unknown", { container: name });
 		if (Array.isArray(unenforced) && unenforced.length > 0) log("size_bound_unenforced", { container: name, flags: unenforced.filter((f) => typeof f === "string" && /^--[a-z-]{1,32}$/.test(f)) });
 
@@ -228,20 +553,228 @@ export function makeRunContainer({
 		// A failure to build it is INFRA, not policy: nothing has been spent, a retry may well succeed, and
 		// `container-never-started` is literally true, so the reservation is given back (processor.mjs).
 		if (network && !(await createJobNetwork(spawnFn, { network, proxy: egressProxy, bin }))) {
+			removeInbox();
 			throw new InfraRetry("container-never-started", { reason: "container-never-started" });
 		}
 
+		// Issue #683: a copying venue's create and upload, before anything spawns the job. Its teardown is owed from the
+		// moment it begins, so a stage that fails half way (a sandbox made, an upload refused) is still deleted.
+		let staged = false;
+		const teardown = async () => {
+			if (!staged || typeof teardownRun !== "function") return;
+			try {
+				await teardownRun({ opts: buildOpts });
+			} catch {
+				// best effort: the reaper deletes what this left, by the job's label
+			}
+		};
+		if (typeof stageRun === "function") {
+			staged = true;
+			try {
+				// Issue #684: the job and the pickup's endpoint snapshot ride with it, for the venue's per-job network policy.
+				await stageRun({ args, opts: buildOpts, signal, job, modelEndpoints });
+			} catch (cause) {
+				await teardown();
+				removeInbox();
+				if (network) await removeJobNetwork(spawnFn, { network, proxy: egressProxy, bin });
+				if (cause instanceof InfraRetry) throw cause;
+				throw new InfraRetry("container-never-started", { cause, reason: "container-never-started" });
+			}
+			// A stop that landed while the venue was still creating or uploading (the job's timeout, a shutdown): its own
+			// stop found nothing to delete yet, so nothing would stop the exec. The run ends here, as stopped, and the
+			// teardown deletes what the stage made.
+			if (signal?.aborted) {
+				await teardown();
+				removeInbox();
+				if (network) await removeJobNetwork(spawnFn, { network, proxy: egressProxy, bin });
+				return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null, context: null, exitReason: null };
+			}
+		}
+
+		// Issue #643: the live transcript publisher, opened only beside a transcript file, an opener and a job id. Its
+		// redactor is built from THIS job's env (the secret-bearing keys, redact-secrets.mjs) plus the two credentials that
+		// are not in it by name or at all: the minted token and the exit-line key. An opener that throws costs the stream,
+		// never the run.
+		let live = null;
+		// Question grouping reads the canonical (raw) transcript after promotion. Keep the exact job-env
+		// redactor available even when live streaming is disabled: token shapes alone miss forwarded values.
+		try { Object.defineProperty(prepared, "questionRedact", { value: makeRedactor({ values: secretValuesOf(env, [token, exitKey], { workerSet: egressEnv({ proxy: egressProxy, armed: egress }) }) }), configurable: true }); }
+		catch { log("question_redactor_unavailable", {}); }
+		if (job.watch) Object.defineProperty(prepared, "watchRedact", { value: makeRedactor({ values: secretValuesOf(env, [token, exitKey], { workerSet: egressEnv({ proxy: egressProxy, armed: egress }) }) }), configurable: true });
+		// Issue #645: a container whose unpause failed UNPAUSE_TRIES times never runs again, and the worker would wait on it
+		// for the whole job timeout. It is killed (SIGKILL reaches a frozen container: the runtime thaws it to deliver it),
+		// then removed if the kill was refused, and the run ends as an infrastructure exit (`checkpointStopped`).
+		let checkpointStopped = false;
+		const stopFrozen = async () => {
+			checkpointStopped = true;
+			log("checkpoint_container_stopped", { container: name });
+			const killed = await dockerStep(spawnFn, ["kill", name], checkpointStopTimeoutMs, bin);
+			if (killed.code !== 0) await dockerStep(spawnFn, ["rm", "-f", name], checkpointStopTimeoutMs, bin);
+		};
+		// Issue #686: on a copying venue the host file is the upload's copy, never written while the job runs, so it is not
+		// tailed: the transcript is the stderr records' (`stdioArmed`) or there is none (`liveSkipped`).
+		if (liveReadable && liveSkipped === null && (stdioArmed || transcriptDir)) {
+			try {
+				// `workerSet`: the proxy variables count as structural only with the values this worker wrote for this job's
+				// egress; a proxy URL an operator forwarded with PI_EGRESS=0 is redacted like any other forwarded value.
+				const workerSet = egressEnv({ proxy: egressProxy, armed: egress });
+				// `job` (issue #644) for its two switches, `progress` (read phases) and `statusComment` (the forge comment).
+				// `checkpoint` (issue #645): the open args this side adds to the processor's, the container's name and venue
+				// verbs, the workspace and job dir, and `onStop` for an unpause that never took. Only for an armed job.
+				const checkpointArgs = armed
+					? {
+							...checkpoint,
+							containerName: name,
+							pause: typeof pause === "function" ? pause : null,
+							unpause: typeof unpause === "function" ? unpause : null,
+							workspace: prepared.workspace ?? null,
+							jobDir: prepared.jobDir ?? null,
+							onStop: () => stopFrozen(),
+						}
+					: null;
+				// The stdio source has no file; a checkpoint copies a host file, so none is opened on it (a copying venue refuses
+				// `run.recover` before spend). The steer acks ride it as they ride a tailed file (issue #686): the records are
+				// the session's lines, so a delivered message's `custom_message` reaches the ack consumer the same way.
+				const source = stdioArmed ? { source: "stdio", file: null } : { file: join(transcriptDir, LIVE_FILE_NAME) };
+				live = openLiveTranscript({ ...source, jobId, redact: makeRedactor({ values: secretValuesOf(env, [token, exitKey], { workerSet }) }), job, ...(checkpointArgs && !stdioArmed ? { checkpoint: checkpointArgs } : {}), ...(steerAck ? { steer: steerAck } : {}) }) ?? null;
+			} catch {
+				live = null;
+			}
+		}
+		// Issue #644: no publisher means no progress, so a trigger's `run.statusComment` cannot be honoured. Said once, by
+		// reason: both switches off (no opener), or no transcript file or job id to read progress from. Issue #686: a
+		// copying venue's skipped transcript is `no-transcript` too (its own reason is on `live_transcript_skipped`); before
+		// the openshell bundle was handed the opener it read `progress-off` there, which named the wrong switch.
+		if (job?.statusComment === true && live === null) log("status_comment_skipped", { jobId: jobId ?? null, reason: typeof openLiveTranscript === "function" ? "no-transcript" : "progress-off" });
+		// Bounded and never throwing (live-transcript.mjs); called at most once, and always BEFORE this function resolves,
+		// so before the processor's `finally` removes the job directory the file lives in.
+		const finishLive = async (outcome) => {
+			try {
+				await live?.finish(outcome);
+			} catch {}
+		};
+		// Issue #646: an armed attempt whose tail could not be opened can deliver messages that no ack will ever count; they
+		// settle as late. Said, never silent.
+		if (steerArmed && live === null) log("steer_acks_unread", { container: name });
+		// Issue #646: the relay's end, AFTER the tail's final read (`finishLive`), so a last-moment ack is handed to the relay
+		// and marked before the liveness keys go; the settle step's close (index.mjs) then sees it as delivered. Once.
+		let relayStopping = null;
+		const stopRelay = () => {
+			relayStopping ??= (async () => {
+				try {
+					await steerAck?.drain();
+				} catch {}
+				try {
+					await relay?.stop();
+				} catch {}
+			})();
+			return relayStopping;
+		};
+		// Issue #645: the checkpoint handle the opener built for an armed job, or null. Never throws (run-checkpoint.mjs).
+		const ckpt = live?.checkpoint && typeof live.checkpoint.close === "function" ? live.checkpoint : null;
+		const closeCheckpoint = async () => {
+			try {
+				return await ckpt?.close();
+			} catch {
+				return null;
+			}
+		};
+		// What the processor is handed: `exit()` once the container is dead (an infra exit of an armed job), `close()`
+		// before its cleanup, `stats()` for the record's counts. Spread only when there is a handle, so every other run
+		// resolves the very object it always did.
+		const checkpointResult = ckpt
+			? {
+					checkpoint: {
+						exit: (opts) => ckpt.exit(opts),
+						close: () => closeCheckpoint(),
+						stats: () => ckpt.stats(),
+					},
+				}
+			: {};
+		if (live !== null && typeof onLive === "function") {
+			try {
+				onLive(finishLive);
+			} catch {}
+		}
+
 		// Host-side per-job log sink, teed off `onOutput`. `name` is `pi-job-<jobId>`; the sink
 		// sanitizes internally. No container mount, no env var -- the sink lives on this side only.
-		const sink = openJobLog(name, { exitKey });
+		// Issue #683: a staged venue's teardown is owed from here, so a synchronous throw before the `try` below still
+		// deletes what the stage made.
+		let sink;
+		try {
+			sink = openJobLog(name, { exitKey, ...(job.watch || job.answerDraft ? { suppressCapture: true } : {}) });
+		} catch (error) {
+			await teardown();
+			removeInbox();
+			throw error;
+		}
 		// Issue #596: the head of the CLI's stderr, kept only to recognise the runtime's refusal of a stale `--cpus`
 		// (`cpuRangeRefusal`). Bounded, and never logged: only the count it names leaves this function.
 		let stderrHead = "";
 		const STDERR_HEAD_MAX = 4096;
+		// Issue #686: an armed attempt's stderr goes through the record demux first. Records are verified under THIS
+		// attempt's exit key against the string in the container's PI_JOB_ID (`name`, as the steer ack's `ackRunId`), and
+		// their lines pushed into the publisher; every other byte is passed on unchanged to the tee and the head below.
+		// Demuxed even when the opener returned no publisher, so the records never reach the job log or the terminal.
+		const demux = stdioArmed
+			? makeDemux({
+					key: exitKey,
+					runId: name,
+					onBaseline: (size) => live?.setBaseline?.(size),
+					onLine: (line, end) => live?.push?.(line, end),
+					onGap: (missing) => live?.skip?.(missing),
+					onReset: (size) => live?.reset?.(size),
+				})
+			: null;
+		let demuxEnded = false;
+		// A demux that threw is not asked again for this attempt (none is known to throw). Its error carries what that chunk
+		// had already passed on and the part of it not yet read, so the output is exactly: those passed bytes, then what it
+		// held (`end()`), then the unread rest, then every later chunk as it comes. No byte twice, and no completed
+		// record's bytes. A throw that carries neither (not the demux's own) passes the chunk on whole.
+		let demuxFailed = false;
+		const endDemux = () => {
+			if (demux === null || demuxEnded) return Buffer.alloc(0);
+			demuxEnded = true;
+			const counts = demux.stats();
+			// Counts only, never a payload: a forged record is the agent's text.
+			if (counts.unverified > 0) log("transcript_record_unverified", { container: name, count: counts.unverified });
+			if (counts.replayed > 0 || counts.gaps > 0 || counts.oversize > 0) log("transcript_record_dropped", { container: name, replayed: counts.replayed, gaps: counts.gaps, oversize: counts.oversize });
+			return demux.end();
+		};
 
 		const run = new Promise((resolve, reject) => {
 			const child = spawnFn(bin, args, { stdio: [exitKey !== null ? "pipe" : "ignore", "pipe", "pipe"] });
-			if (exitKey !== null) {
+			// Issue #686: a stdin-steered attempt's key is frame 1, written at the spawn, and the pipe is NOT closed: it is
+			// handed to the relay, which writes each message as a frame after it and closes the pipe at its stop. The relay
+			// writes nothing before the publisher's baseline (the runner's signed baseline record and the lines up to it, so a
+			// resumed transcript's acks are known first). The runner reads exactly frame 1 before pi loads, so the key is out
+			// of the pipe before any tool exists, as on every other attempt.
+			if (stdinSteered) {
+				child.stdin?.on("error", () => {});
+				const first = keyFrame(exitKey);
+				try {
+					child.stdin?.write(first);
+				} catch {}
+				relay?.attach?.(child.stdin, { written: first.length });
+				// The baseline, when this side already knows it: a job with no staged session (not a resume, not a recovery)
+				// uploads the empty live file the preparer made, so its transcript has no prior line and nothing to
+				// re-baseline against. Released here, at the spawn, rather than when the runner's baseline record comes back
+				// over stderr (about 600 ms in, measured on Docker): a message queued before the start then reaches the runner
+				// before its first agent_start, where pi polls its steering queue once before the first model call, instead
+				// of racing the run. A staged transcript waits for the record as before (the ack's `onBaseline` is once only).
+				if (!prepared.session && recover !== true) {
+					try {
+						steerAck?.onBaseline();
+					} catch {}
+				}
+			}
+			try {
+				live?.start();
+			} catch {}
+			// Issue #646: registered live with the container, so a push is accepted only while there is a run to read it.
+			void relay?.start();
+			if (exitKey !== null && !stdinSteered) {
 				// Written and closed at once: the runner drains stdin to EOF before anything else runs, so the key is out of
 				// the pipe before any tool exists. A CLI that died first makes this EPIPE, which is the run failing, reported
 				// by `error` or `close` below; the listener only keeps the write's own error from crashing the worker.
@@ -250,25 +783,122 @@ export function makeRunContainer({
 			}
 			// A throwing sink.write is swallowed so a misbehaving sink cannot break the tee or hang the run.
 			const tee = (chunk) => {
-				onOutput(chunk);
+				if (!job.watch && !job.answerDraft) onOutput(chunk);
 				try {
 					sink.write(chunk);
 				} catch {}
 			};
 			child.stdout?.on("data", tee);
-			child.stderr?.on("data", (chunk) => {
+			// Review round 1, M1: a stdin-steered attempt's pipe is ended as soon as the runner's exit line is out, so a CLI
+			// that waited for EOF before it exits could never wait on the relay (OpenShell 0.1.4 does not wait, measured on
+			// the real gateway; this is the defence, and the close at the relay's stop stays). A line that VERIFIES under the
+			// attempt's key ends it at once; an exit-shaped line that does not (the supervisor's unkeyed one, a forgery) ends
+			// it after `stdinExitGraceMs`, so a forged line can only cut steering short, never hold the pipe open. Lines are
+			// cut on newlines from a bounded buffer; a line past the bound is skipped.
+			if (stdinSteered) {
+				let held = "";
+				let graceTimer = null;
+				const STDIN_LINE_MAX = 256 * 1024;
+				let stdinClosed = false;
+				// Said once, by which line ended it: a pipe ended early is steering cut short for the rest of the attempt, and
+				// every message accepted after it settles `late` (the relay writes nothing more).
+				const closeNow = (reason) => {
+					if (graceTimer) clearTimeout(graceTimer);
+					graceTimer = null;
+					if (stdinClosed) return;
+					stdinClosed = true;
+					log("steer_stdin_closed", { container: name, reason });
+					try {
+						relay?.closeStdin?.();
+					} catch {}
+				};
+				child.stdout?.on("data", (chunk) => {
+					held += String(chunk);
+					let nl = held.indexOf("\n");
+					while (nl !== -1) {
+						const line = held.slice(0, nl);
+						held = held.slice(nl + 1);
+						if (line.includes('{"event":"exit"')) {
+							if (authenticExitLines(line, exitKey) !== "") closeNow("exit-verified");
+							else if (graceTimer === null && !stdinClosed) {
+								graceTimer = setTimeout(() => closeNow("exit-unverified"), stdinExitGraceMs);
+								graceTimer.unref?.();
+							}
+						}
+						nl = held.indexOf("\n");
+					}
+					if (held.length > STDIN_LINE_MAX) held = "";
+				});
+				child.on("close", () => {
+					if (graceTimer) clearTimeout(graceTimer);
+				});
+			}
+			const stderrOut = (chunk) => {
+				if (chunk.length === 0) return;
 				if (stderrHead.length < STDERR_HEAD_MAX) stderrHead = (stderrHead + String(chunk)).slice(0, STDERR_HEAD_MAX);
 				tee(chunk);
+			};
+			child.stderr?.on("data", (chunk) => {
+				if (demux === null || demuxFailed) {
+					if (stderrHead.length < STDERR_HEAD_MAX) stderrHead = (stderrHead + String(chunk)).slice(0, STDERR_HEAD_MAX);
+					tee(chunk);
+					return;
+				}
+				let out;
+				try {
+					out = demux.push(chunk);
+				} catch (error) {
+					demuxFailed = true;
+					log("transcript_demux_failed", { container: name });
+					const carried = Buffer.isBuffer(error?.passed) && Buffer.isBuffer(error?.rest);
+					out = carried ? Buffer.concat([error.passed, endDemux(), error.rest]) : Buffer.concat([endDemux(), Buffer.from(chunk)]);
+				}
+				stderrOut(out);
 			});
 			// docker not found / daemon down -- a transient infra fault, so tag it retryable
 			// (CONST-RETRY-INFRA-ONLY). `reason` also cues the processor to release the budget slot,
 			// since a container that never started spent nothing.
 			child.on("error", (err) => {
+				stderrOut(endDemux());
+				void closeCheckpoint();
+				void finishLive("failed").then(stopRelay);
 				sink.close().catch(() => {}); // best-effort teardown; a rejecting close cannot leak an unhandled rejection
 				reject(new InfraRetry("container-never-started", { cause: err, reason: "container-never-started" }));
 			});
 			child.on("close", async (code) => {
 				const aborted = signal?.aborted === true; // capture BEFORE the await
+				// Issue #686: the demux's held tail (a last line with no newline) goes out before anything closes, and every
+				// record it completed is in the publisher before the final flush below.
+				stderrOut(endDemux());
+				// Issue #686 part 3, review round 2: the venue's box ended and confirmed gone first (see `settleRun`).
+				let settled = null;
+				if (typeof settleRun === "function") {
+					try {
+						settled = (await settleRun({ opts: buildOpts, aborted })) === true;
+					} catch {
+						settled = false;
+					}
+				}
+				const lingered = settled === false ? { lingering: true } : {};
+				// Issue #645: no live checkpoint starts once the container is gone (a quiet point in the final read would
+				// pause a dead container). Closing first, and awaiting it after the final read, lets a live one in flight
+				// finish, its pointer included, before this promise resolves and the processor's cleanup can run.
+				const ckptClosed = closeCheckpoint();
+				// Issue #643, ORDER LOAD-BEARING: the transcript's last lines are read and published HERE, before the sink
+				// closes and before this promise resolves, because the processor removes the job directory (and the file in
+				// it) as soon as it has the result. The outcome is the exit's own reading, the most this side knows.
+				await finishLive(liveOutcomeOf(code, aborted, neverStartedExits));
+				// Issue #644: the run record's `progress`, read once the final snapshot was taken. Only when the opener ran the
+				// progress reducer for this job; absent otherwise, so every other run resolves the object it always did.
+				let progress = null;
+				try {
+					progress = live?.progressSummary?.() ?? null;
+				} catch {
+					progress = null;
+				}
+				const ranProgress = progress !== null && typeof progress === "object" ? { progress } : {};
+				await ckptClosed;
+				const stoppedForCheckpoint = checkpointStopped ? { checkpointStopped: true } : {};
 				// A rejecting sink.close is swallowed so a misbehaving sink cannot hang the run; turns/tokens/session/usage/context/exitReason fall back to null.
 				let turns = null;
 				let tokens = null;
@@ -279,23 +909,39 @@ export function makeRunContainer({
 				// RUNNER_POLICY_REASONS set and to a line that itself said code 2. The processor still decides
 				// the retry class from `code` alone; this only picks the label inside exit 2.
 				let exitReason = null;
+				let approval = null;
+				let answerDraftDigest = null;
+				let questionRefDigest = null;
 				// Issue #501 (PR #542's review, round 3): the decisive exit line's own `code` (decisiveExitLine), which the
 				// dollar settlement compares with the container's real exit code before it trusts that line's cost.
 				let exitLineCode = null;
 				// Issue #507: the cost guard's rule on a `cost-cap` line, already filtered by parseExitWhy to COST_CAP_WHYS.
 				let exitWhy = null;
+				let providerFailure = null;
+				let modelRoles = null;
+				let toolsStarted = null;
+				let replaySafe = null;
 				// Issue #545: null (no key issued), "verified" or "unverified" (a key, and no exit line carried it).
 				let exitAuthResult = null;
 				// Issue #596: what the container used, off its exit line (parseExitResources), or null.
 				let resources = null;
 				// Issue #596: the image's supervisor reported the runner killed for memory (parseExitOomKilled).
 				let exitOomKilled = false;
+				// Issue #645: a recovered run's runner counts (parseExitRecovery), `{ orphans, replayed, interrupted, notStarted }`
+				// each an integer or null, or null when the line carried none.
+				let recovery = null;
+				// Issue #646: a steer-armed runner's inbox counts (parseExitSteer), `{ delivered, pending }`, or null.
+				let steerCounts = null;
+				// Issue #796: what the runner said of a canary's candidate (parseExitCanaryLoad), or null.
+				let canaryLoad = null;
+				// Issue #800: the runner's `loaded` as it wrote it, off a verified line only, for `rebuildLoaded` below.
+				let lineLoaded = null;
 				try {
 					// `context = null` is a DEFAULT rather than a plain destructure: an injected sink that
 					// predates the field returns no such key, and `undefined` would then reach the record's
 					// shape where every other absence is spelled `null`.
 					// `exitReason` defaults the same way, for the same reason.
-					({ turns, tokens, session, usage, context = null, exitReason = null, exitLineCode = null, exitWhy = null, exitAuth: exitAuthResult = null, resources = null, exitOomKilled = false } = await sink.close());
+					({ canaryLoad = null, loaded: lineLoaded = null, turns, tokens, session, usage, context = null, exitReason = null, exitLineCode = null, exitWhy = null, modelRoles = null, providerFailure = null, toolsStarted = null, replaySafe = null, exitAuth: exitAuthResult = null, resources = null, exitOomKilled = false, recovery = null, steer: steerCounts = null, approval = null, answerDraftDigest = null, questionRefDigest = null } = await sink.close());
 				} catch {
 					turns = null;
 					tokens = null;
@@ -303,10 +949,19 @@ export function makeRunContainer({
 					usage = null;
 					context = null;
 					exitReason = null;
+					approval = null;
 					exitLineCode = null;
 					exitWhy = null;
+					providerFailure = null;
+					modelRoles = null;
+					toolsStarted = null;
+					replaySafe = null;
 					resources = null;
 					exitOomKilled = false;
+					recovery = null;
+					steerCounts = null;
+					canaryLoad = null;
+					lineLoaded = null;
 					// The sink could not say, and a key was issued: nothing it returned was verified.
 					exitAuthResult = exitKey !== null ? "unverified" : null;
 				}
@@ -319,19 +974,57 @@ export function makeRunContainer({
 					usage = null;
 					context = null;
 					exitReason = null;
+					approval = null;
 					exitLineCode = null;
 					exitWhy = null;
+					providerFailure = null;
+					modelRoles = null;
+					toolsStarted = null;
+					replaySafe = null;
 					resources = null;
 					exitOomKilled = false;
+					recovery = null;
+					steerCounts = null;
+					canaryLoad = null;
+					lineLoaded = null;
 				}
 				// Spread only when a key was issued, so a run without one resolves the very object it always did.
 				const auth = exitKey !== null ? { exitAuth: exitAuthResult } : {};
+				if (job.answerDraft && code === 0 && exitKey !== null && exitAuthResult === "verified" && /^[a-f0-9]{64}$/.test(answerDraftDigest ?? "")) Object.defineProperty(prepared, "answerDraftDigest", { value: answerDraftDigest, configurable: true });
+				if (job.awaitInput && code === 0 && exitReason === "awaiting-input" && exitKey !== null && exitAuthResult === "verified" && /^[a-f0-9]{64}$/.test(questionRefDigest ?? "")) Object.defineProperty(prepared, "questionRefDigest", { value: questionRefDigest, configurable: true });
 				// `exitWhy` only when the line named one, so every other run resolves the object it always did.
-				const why = exitWhy !== null ? { exitWhy } : {};
+				const why = { ...(exitKey !== null && exitAuthResult === "verified" && modelRoles ? { modelRoles } : {}), ...(exitWhy !== null ? { exitWhy } : {}), ...(exitKey !== null && exitAuthResult === "verified" && providerFailure ? { providerFailure } : {}), ...(exitKey !== null && exitAuthResult === "verified" && typeof toolsStarted === "boolean" ? { toolsStarted } : {}), ...(exitKey !== null && exitAuthResult === "verified" && typeof replaySafe === "boolean" ? { replaySafe } : {}) };
 				// `resources` (issue #596) only when the exit line carried a block, so every other run resolves the object it always did.
 				// `memoryLimit` only beside the OOM report, the one place it is read, for the same reason.
 				const used = { ...(resources !== null && resources !== undefined ? { resources } : {}), ...(exitOomKilled === true ? { exitOomKilled: true, memoryLimit } : {}) };
-				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage, context, exitReason, exitLineCode, ...why, ...used, ...auth } : { code: code ?? 1, aborted: false, turns, tokens, session, usage, context, exitReason, exitLineCode, ...why, ...used, ...auth });
+				// `recovery` (issue #645) only when the exit line carried the block, so every other run resolves the object it always did.
+				const recovered = recovery !== null && typeof recovery === "object" ? { recovery } : {};
+				// Issue #646, review finding F3: the deliveries the runner's SIGNED exit line names are marked before the relay
+				// stops. The transcript is the agent's to break (a symlink swapped in makes the tail refuse it), so the acks
+				// it carries are not the only witness: the exit line is signed with the key the agent never sees, and with a
+				// key issued every field above is nulled unless it verified. The tail's acks are drained first, so these marks
+				// only add what the transcript could not say. Then the relay stops, after which the settle step closes.
+				if (steerArmed && exitAuthResult === "verified" && Array.isArray(steerCounts?.deliveredIds)) {
+					try {
+						await steerAck?.drain();
+					} catch {}
+					for (const id of steerCounts.deliveredIds) {
+						try {
+							await relay?.delivered(id);
+						} catch {}
+					}
+				}
+				await stopRelay();
+				// Issue #646: only for a job that asked for steering, so every other run resolves the object it always did.
+				// `steer` is the runner's own count (advisory, like `recovery`), without the ids; `steerSkipped` the verdict.
+				const steerShown = steerCounts !== null && typeof steerCounts === "object" ? { delivered: steerCounts.delivered ?? null, pending: steerCounts.pending ?? null } : null;
+				const steered = steerAsked ? { ...(steerArmed && steerShown !== null ? { steer: steerShown } : {}), ...(steerSkipped !== null ? { steerSkipped } : {}) } : {};
+				// Issue #712: the named live-transcript skip, for the record's `liveSkipped`, only when there was one.
+				// Issue #800: what the job loaded, when the line said or the worker has something of its own to say; otherwise the run
+				// resolves the object it always did, and the processor's image-only value stands.
+				const loadedShown = lineLoaded !== null || leavesOut(loadedKnown.leftOut) ? { loaded: rebuildLoaded(lineLoaded, loadedKnown) } : {};
+				const liveShown = { ...(liveSkipped !== null ? { liveSkipped } : {}), ...(canaryLoad !== null ? { canaryLoad } : {}), ...loadedShown };
+				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage, context, exitReason, exitLineCode, ...(approval ? { approval } : {}), ...why, ...used, ...auth, ...ranProgress, ...recovered, ...steered, ...liveShown, ...checkpointResult, ...stoppedForCheckpoint, ...lingered } : { code: code ?? 1, aborted: false, turns, tokens, session, usage, context, exitReason, exitLineCode, ...(approval ? { approval } : {}), ...why, ...used, ...auth, ...ranProgress, ...recovered, ...steered, ...liveShown, ...checkpointResult, ...stoppedForCheckpoint, ...lingered });
 			});
 		});
 
@@ -358,8 +1051,11 @@ export function makeRunContainer({
 			if (!result.aborted && (neverStartedExits ?? []).includes(result.code) && (await stopDetached({ spawnFn, cidFile, fs, bin, ...detachedCheck }))) {
 				return { ...result, detached: true };
 			}
+			// Issue #683: a copying venue brings its outputs back before the processor reads them. Its own throw stands.
+			if (typeof collectRun === "function") return await collectRun(result, { opts: buildOpts });
 			return result;
 		} finally {
+			await teardown();
 			if (network) {
 				await removeJobNetwork(spawnFn, {
 					network,
@@ -374,10 +1070,30 @@ export function makeRunContainer({
 			} catch {
 				// best effort: a leftover file is removed before this job's next attempt starts
 			}
+			// Issue #646: the relay is stopped on every path (a throw before the spawn included), then its directory goes.
+			await stopRelay();
+			removeInbox();
 		}
 	};
 }
 
+/**
+ * The `end` entry's outcome from what `runContainer` knows when the container exits (issue #643): a worker stop and
+ * the runner's exit 2 are policy, exit 0 completed, exit 1 failed, and anything else (an OOM kill, a runtime's own
+ * code) `unknown`, since only the processor's classification can say more. One exception to `unknown`: an exit this
+ * runtime spells "never started" (`neverStartedExits`, 125 to 127 on Docker) is `failed`, the same word the spawn
+ * error path uses, because the container never ran: the attempt is over and did nothing, and the processor retries it
+ * as infrastructure under the same job id, whose first write then replaces this stream.
+ */
+export function liveOutcomeOf(code, aborted, neverStartedExits = []) {
+	if (aborted) return "policy";
+	if (code === 0) return "completed";
+	if (code === 2) return "policy";
+	if (code === 1) return "failed";
+	if (Array.isArray(neverStartedExits) && neverStartedExits.includes(code)) return "failed";
+	return "unknown";
+}
+
 /** The detached check's whole bound, retries included, so a daemon that stopped answering cannot hold the slot for long. */
 export const DETACHED_CHECK_TIMEOUT_MS = 10_000;
 /** The least time any single step of it is given, so the last one tried at the deadline is not killed before it is sent. */