@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/stderr-transcript.mjs

@@ -0,0 +1,318 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * The worker's half of the transcript records (issue #686, `DES-OPENSHELL-VENUE`, `INT-RUNNER-EXIT-CODE-PROTOCOL`'s
+ * transcript records): splits a copying venue's CLI stderr into the runner's signed transcript records and everything
+ * else, verifies each record under this attempt's exit key, and hands the verified ones, in order, to the live
+ * transcript's stdio source (live-transcript.mjs `makeLiveTranscript({ source: "stdio" })`).
+ *
+ * The runner's half is image/runner/src/transcript-mirror.mjs, whose header states the format
+ * (`\x1epidt <seq> <type> <end> <mac> <base64>\n`, types `b` baseline, `l` line, `r` reset). The MAC is restated here
+ * (the worker cannot import the image at run time) and pinned to the runner's by a test, as the steer ack's is. A
+ * verified record proves the CHANNEL (the runner's mirror wrote it, in this order), never the content: the session
+ * file is the agent's to write, so a line has the trust of a line the file tail reads on a binding venue.
+ *
+ * WHY A STREAM DEMUX AND NOT A LINE SPLIT. OpenShell's `sandbox exec` forwards stderr in reads of up to 4 KiB that are
+ * not line-aligned (measured, 0.1.4), so a record arrives cut anywhere, its marker included.
+ *
+ * THE PASS-THROUGH RULE. A record begins at the marker (RS, then `pidt `) wherever it appears, at a line start or after
+ * a foreign write that left no newline (a progress bar's `\r50%`). A byte that is not part of a record is passed on as
+ * soon as it is known not to be one, byte for byte. Only two things are held: the first bytes that still match the
+ * marker (at most its 6), and a record while it still fits the record's grammar (digits, one type letter, digits, 64
+ * hex, base64). The grammar is checked as the bytes arrive, so a record cut by another writer ends at the FIRST byte
+ * that cannot belong to it: the record's bytes before that byte are dropped (counted, never written out), and that
+ * byte and everything after it on the line are passed on as ordinary output. What that means, exactly:
+ *   - a verified record, and a record's bytes before its break, never reach the job log;
+ *   - a broken record's bytes AFTER its break byte do (a foreign `\r` mid-payload sends the rest of the base64 there);
+ *   - a foreign write that lands inside a record and whose head fits the field being read (hex inside the MAC, base64
+ *     inside the payload, digits inside a number) is taken into the record and lost with it, up to the first byte that
+ *     does not fit; a newline where a record cannot end is taken as the broken record's own;
+ *   - every other byte reaches the job log and the terminal unchanged.
+ *
+ * WHAT IS REFUSED, and counted, never published, never logged with its payload: a record that does not parse, one whose
+ * MAC does not verify (a forgery from a tool writing to the container's stderr, or a record another process's write
+ * broke), and one whose `seq` is not above the last accepted one (a replay). A gap in `seq` is allowed (the runner
+ * skips a line past its bound, and a broken record leaves one) and counted; the stdio source shows it as `skipped`.
+ */
+
+export const TRANSCRIPT_RECORD_MARKER = "\x1epidt ";
+const MARKER = Buffer.from(TRANSCRIPT_RECORD_MARKER, "latin1");
+const TRANSCRIPT_DOMAIN = "pi-dispatch-transcript";
+const TYPES = new Set(["b", "l", "r"]);
+
+/**
+ * The most payload bytes one record holds before it is given up on. A genuine record's payload is at most 4/3 of the
+ * runner's longest mirrored line (`TRANSCRIPT_LINE_MAX_BYTES`, 1 MiB) as base64, about 1.4 MiB; 8 MiB is far above
+ * that, so no genuine record meets it, and it bounds what a forged unterminated "record" can make this process hold.
+ * Past it the record is still read to its end (its bytes dropped as they arrive, never held, never passed on) and
+ * counted `oversize`.
+ */
+export const TRANSCRIPT_RECORD_MAX_BYTES = 8 * 1024 * 1024;
+
+/** The runner's `transcriptRecordMac`, restated. */
+export function transcriptRecordMac(key, runId, seq, type, end, payload) {
+	return createHmac("sha256", key).update(`${TRANSCRIPT_DOMAIN}\0${runId}\0${seq}\0${type}\0${end}\0`, "utf8").update(payload).digest("hex");
+}
+
+const NUM_RE = /^(?:0|[1-9][0-9]{0,15})$/;
+const MAC_RE = /^[0-9a-f]{64}$/;
+const B64_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+/**
+ * One record's body (the bytes between the marker and the newline) verified: `{ seq, type, end, payload }` or null.
+ * Constant-time on the MAC; numbers and base64 canonical, so one record has exactly one spelling. A baseline or a
+ * reset carries no payload.
+ */
+export function verifyTranscriptRecord(body, { key, runId }) {
+	if (typeof key !== "string" || key === "" || typeof runId !== "string" || runId === "") return null;
+	const text = Buffer.isBuffer(body) ? body.toString("latin1") : String(body ?? "");
+	const parts = text.split(" ");
+	if (parts.length !== 5) return null;
+	const [seqText, type, endText, mac, b64] = parts;
+	if (!NUM_RE.test(seqText) || seqText === "0" || !TYPES.has(type) || !NUM_RE.test(endText) || !MAC_RE.test(mac) || !B64_RE.test(b64)) return null;
+	const seq = Number(seqText);
+	const end = Number(endText);
+	if (!Number.isSafeInteger(seq) || !Number.isSafeInteger(end)) return null;
+	const payload = Buffer.from(b64, "base64");
+	// Canonical only: base64 has spellings that differ in their unused trailing bits and decode to the same bytes.
+	if (payload.toString("base64") !== b64) return null;
+	if (type !== "l" && payload.length > 0) return null;
+	if (!timingSafeEqual(Buffer.from(transcriptRecordMac(key, runId, seqText, type, endText, payload), "hex"), Buffer.from(mac, "hex"))) return null;
+	return { seq, type, end, payload };
+}
+
+const isDigit = (c) => c >= 0x30 && c <= 0x39;
+const isHex = (c) => isDigit(c) || (c >= 0x61 && c <= 0x66);
+const isB64 = (c) => isDigit(c) || (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a) || c === 0x2b || c === 0x2f || c === 0x3d;
+const isType = (c) => c === 0x62 || c === 0x6c || c === 0x72;
+// Each field before the payload: the bytes it admits and its longest length. Field 4, the payload, is base64 to the newline.
+const FIELDS = [
+	{ ok: isDigit, max: 16 },
+	{ ok: isType, max: 1 },
+	{ ok: isDigit, max: 16 },
+	{ ok: isHex, max: 64 },
+];
+
+/**
+ * `makeStderrTranscript({ key, runId, onLine, onBaseline, onReset, onGap, maxRecordBytes })` ->
+ * `{ push(chunk), end(), stats() }`.
+ *
+ *   - `push(chunk)` takes one stderr chunk and returns the bytes to pass on (a Buffer, possibly empty), in order. The
+ *     verified records it completed are handed out before it returns: `onBaseline(size)`, `onLine(lineBytes, end)`,
+ *     `onReset(size)`, and `onGap(missing)` first when `seq` jumped. A throw from `push` (none is known) leaves the
+ *     state as it was before the call, so the caller can `end()` and pass the chunk on itself without a byte twice.
+ *   - `end()` returns what is still held and is not a record (the head of a line that matched the marker's first
+ *     bytes), so nothing the CLI wrote is lost at close. An unterminated record is dropped and counted.
+ *   - `stats()`: `{ records, unverified, replayed, gaps, oversize }`.
+ *
+ * Every callback is guarded: a throw in one costs that record only, never the demux or the bytes passed on.
+ */
+export function makeStderrTranscript({ key, runId, onLine = () => {}, onBaseline = () => {}, onReset = () => {}, onGap = () => {}, maxRecordBytes = TRANSCRIPT_RECORD_MAX_BYTES } = {}) {
+	// `start`: at a line start, `probe` holding the bytes so far that match the marker's head. `pass`: inside a line that
+	// is not a record, passed through to its newline. `record`: inside a record, in field `field` (0 to 4).
+	let mode = "start";
+	let probe = Buffer.alloc(0);
+	let parts = [];
+	let field = 0;
+	let fieldLen = 0;
+	let held = 0;
+	let discarding = false; // a payload past the bound: read to its end, never held
+	let last = 0;
+	const counts = { records: 0, unverified: 0, replayed: 0, gaps: 0, oversize: 0 };
+	const call = (fn, ...args) => {
+		try {
+			fn(...args);
+		} catch {}
+	};
+
+	const settle = (body) => {
+		const verified = verifyTranscriptRecord(body, { key, runId });
+		if (verified === null) {
+			counts.unverified += 1;
+			return;
+		}
+		if (verified.seq <= last) {
+			counts.replayed += 1;
+			return;
+		}
+		if (verified.seq > last + 1) {
+			// `seq` 1 is always the baseline: when it is the one lost, no LINE is missing for it.
+			const missing = verified.seq - last - 1 - (last === 0 ? 1 : 0);
+			if (missing > 0) {
+				counts.gaps += missing;
+				call(onGap, missing);
+			}
+		}
+		last = verified.seq;
+		counts.records += 1;
+		if (verified.type === "b") call(onBaseline, verified.end);
+		else if (verified.type === "r") call(onReset, verified.end);
+		else if (verified.payload.length > 0) call(onLine, verified.payload, verified.end);
+	};
+
+	const openRecord = () => {
+		mode = "record";
+		probe = Buffer.alloc(0);
+		parts = [];
+		field = 0;
+		fieldLen = 0;
+		held = 0;
+		discarding = false;
+	};
+	/** The record ended before its grammar did: its bytes are dropped and counted, never passed on. */
+	const breakRecord = () => {
+		counts.unverified += 1;
+		parts = [];
+		held = 0;
+	};
+
+	const step = (buf) => {
+		const out = [];
+		let i = 0;
+		try {
+			while (i < buf.length) {
+				if (mode === "pass") {
+					// To the line's end, or to the next RS, whichever is first: a record can follow a foreign write that left
+					// no newline (a progress bar's `\r50%`), and must still be read as one. An RS that does not begin the
+					// marker (`\x1e{` of an RS-delimited JSON stream) is passed on by the probe below, unchanged.
+					const nl = buf.indexOf(0x0a, i);
+					const rs = buf.indexOf(0x1e, i);
+					if (rs !== -1 && (nl === -1 || rs < nl)) {
+						if (rs > i) out.push(buf.subarray(i, rs));
+						i = rs;
+						mode = "start";
+						continue;
+					}
+					if (nl === -1) {
+						out.push(buf.subarray(i));
+						i = buf.length;
+					} else {
+						out.push(buf.subarray(i, nl + 1));
+						i = nl + 1;
+						mode = "start";
+					}
+					continue;
+				}
+				if (mode === "start") {
+					const take = buf.subarray(i, i + (MARKER.length - probe.length));
+					const candidate = probe.length > 0 ? Buffer.concat([probe, take]) : take;
+					if (MARKER.subarray(0, candidate.length).equals(candidate)) {
+						i += take.length;
+						if (candidate.length === MARKER.length) openRecord();
+						else probe = Buffer.from(candidate);
+						continue;
+					}
+					// Not a record: what was held goes out first, then this line from `i` on, newline included. The marker
+					// holds no newline, so the held head never does either, and the line's own newline is found in `pass`.
+					// An RS that failed the probe is passed on here, so `pass` never stops at the same byte twice.
+					if (probe.length > 0) out.push(probe);
+					else if (buf[i] === 0x1e) {
+						out.push(buf.subarray(i, i + 1));
+						i += 1;
+					}
+					probe = Buffer.alloc(0);
+					mode = "pass";
+					continue;
+				}
+				// mode === "record"
+				if (field < 4) {
+					const c = buf[i];
+					const spec = FIELDS[field];
+					if (c === 0x20 && fieldLen > 0 && (field !== 3 || fieldLen === 64)) {
+						parts.push(buf.subarray(i, i + 1));
+						held += 1;
+						field += 1;
+						fieldLen = 0;
+						i += 1;
+						continue;
+					}
+					if (spec.ok(c) && fieldLen < spec.max) {
+						parts.push(buf.subarray(i, i + 1));
+						held += 1;
+						fieldLen += 1;
+						i += 1;
+						continue;
+					}
+					breakRecord();
+					if (c === 0x0a) {
+						i += 1;
+						mode = "start";
+					} else {
+						mode = "pass";
+					}
+					continue;
+				}
+				// The payload: base64 up to the newline, scanned in one run.
+				let j = i;
+				while (j < buf.length && isB64(buf[j])) j += 1;
+				if (j > i) {
+					if (!discarding && held + (j - i) > maxRecordBytes) {
+						discarding = true;
+						parts = [];
+						held = 0;
+					}
+					if (!discarding) {
+						parts.push(buf.subarray(i, j));
+						held += j - i;
+					}
+					i = j;
+					continue;
+				}
+				if (buf[i] === 0x0a) {
+					i += 1;
+					mode = "start";
+					if (discarding) {
+						counts.oversize += 1;
+						discarding = false;
+						parts = [];
+						held = 0;
+						continue;
+					}
+					const body = Buffer.concat(parts);
+					parts = [];
+					held = 0;
+					settle(body);
+					continue;
+				}
+				// A byte no record holds: the record was broken there. Dropped, and this byte on is ordinary output.
+				if (discarding) {
+					counts.oversize += 1;
+					discarding = false;
+					parts = [];
+					held = 0;
+				} else {
+					breakRecord();
+				}
+				mode = "pass";
+			}
+		} catch (cause) {
+			// None is known. What this chunk already passed on, and the part not yet read, ride the error, so the caller
+			// can send exactly those (and `end()`'s held bytes between them): no byte twice, and no completed record's.
+			throw Object.assign(new Error("stderr transcript demux fault", { cause }), { passed: Buffer.concat(out), rest: buf.subarray(i) });
+		}
+		return out.length === 0 ? Buffer.alloc(0) : out.length === 1 ? Buffer.from(out[0]) : Buffer.concat(out);
+	};
+
+	return {
+		push(chunk) {
+			const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk ?? ""), "utf8");
+			// Copies, because `parts` holds views into the chunk: the caller may reuse its buffer.
+			return step(Buffer.from(buf));
+		},
+		end() {
+			let out = Buffer.alloc(0);
+			if (mode === "start" && probe.length > 0) out = probe;
+			if (mode === "record") {
+				if (discarding) counts.oversize += 1;
+				else counts.unverified += 1;
+			}
+			mode = "start";
+			probe = Buffer.alloc(0);
+			parts = [];
+			held = 0;
+			discarding = false;
+			return out;
+		},
+		stats: () => ({ ...counts }),
+	};
+}

package/src/steer-ack.mjs

@@ -0,0 +1,122 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { STEER_ID_RE } from "./steer-framing.mjs";
+
+/**
+ * The worker's half of a steer delivery ack (issue #646, INT-STEER-INBOX-CONTRACT): a third `onParsed` consumer of the
+ * live transcript tail (live-transcript.mjs `makeLiveTranscriptOpener`, beside the progress sink and the checkpoint
+ * handle), which turns each `pi-dispatch-inbox` custom message the runner delivered into `delivered` in the run's inbox.
+ *
+ * WHY A MAC AND NOT THE LINE ITSELF. `/session` is mounted read-write into the job, so the agent can append a
+ * `custom_message` of our type to its own transcript, naming any message id. A delivery counts only when the line's
+ * `details.ack` is `HMAC-SHA256(exitKey, "pi-dispatch-inbox-ack\0" + PI_JOB_ID + "\0" + id)`, compared in constant
+ * time, under the exit key this attempt minted (issue #545): handed to the runner on stdin, held in its non-dumpable
+ * process, never in the agent's reach. A line that does not verify is ignored and counted (`steer_ack_unverified`).
+ * The domain string is the runner's (image/runner/src/inbox.mjs `inboxAck`), and `ackRunId` is exactly the string the
+ * worker put in PI_JOB_ID for this container (run-container.mjs passes the container name), so both sides MAC one
+ * message by construction rather than by two call sites that happen to agree.
+ *
+ * PRIOR LINES. A line that ended at or before the tail's BASELINE (the file's size when this attempt began: a resumed
+ * or a #645-restored transcript) was written by an EARLIER attempt, whose exit key is gone, so its MAC cannot be
+ * checked here. Such a line is never counted as a delivery. Its id only joins the "already in this transcript" set
+ * the relay re-baselines against (inbox-relay.mjs): a message the inbox says is `delivered` whose id is NOT in that
+ * set goes back to `written`, so a recovery from a checkpoint older than the delivery hands it over again. The
+ * residual is deliberate and narrow: the agent can write a prior-looking line only into a transcript a later attempt
+ * restores, and all it buys is that a message which WAS delivered (verified, under that attempt's key) stays so.
+ *
+ * Never throws; the tail swallows a throw anyway, and nothing here may cost the run. Logs carry ids and counts only.
+ */
+
+export const INBOX_CUSTOM_TYPE = "pi-dispatch-inbox";
+const ACK_DOMAIN = "pi-dispatch-inbox-ack";
+
+/** The ack for one message: the runner's `inboxAck`, restated (the worker cannot import the image). Pinned by a test. */
+export function inboxAck(key, ackRunId, id) {
+	return createHmac("sha256", key).update(`${ACK_DOMAIN}\0${ackRunId}\0${id}`, "utf8").digest("hex");
+}
+
+/** Whether `ack` is the ack for `id` under `key`, in constant time. False on any malformed input, never a throw. */
+export function ackVerifies(key, ackRunId, id, ack) {
+	if (typeof key !== "string" || key === "" || typeof ackRunId !== "string" || ackRunId === "") return false;
+	if (typeof id !== "string" || !STEER_ID_RE.test(id)) return false;
+	if (typeof ack !== "string" || !/^[0-9a-f]{64}$/.test(ack)) return false;
+	return timingSafeEqual(Buffer.from(inboxAck(key, ackRunId, id), "hex"), Buffer.from(ack, "hex"));
+}
+
+/**
+ * `makeSteerAck({ exitKey, ackRunId, relay, jobId, log })` -> `{ consume, onBaseline, reset, drain, stats }`.
+ *
+ *   - `consume(parsed, ts, flags)`: the tail's `onParsed`. A prior line feeds the prior set; any other line of our type
+ *     is verified and, when it verifies, handed to `relay.delivered(id)` (which marks the inbox and unlinks the file).
+ *   - `onBaseline()`: the tail's first pass over the staged transcript is done; calls `relay.afterBaseline(prior)`, so
+ *     the relay re-baselines and only then starts writing files.
+ *   - `drain()`: waits for every mark in flight (runContainer awaits it after the tail's final read, before it stops the
+ *     relay, so a last-moment ack is counted before the settle step reads the states). Bounded by the relay's own calls.
+ */
+export function makeSteerAck({ exitKey, ackRunId, relay, jobId = null, log = () => {} } = {}) {
+	const prior = new Set();
+	const priorVerified = new Set();
+	const acked = new Set();
+	const inFlight = new Set();
+	const counts = { verified: 0, unverified: 0, prior: 0 };
+	let baselined = false;
+	let unverifiedSaid = false;
+
+	const hand = (id) => {
+		if (typeof relay?.delivered !== "function") return;
+		let p;
+		try {
+			p = Promise.resolve(relay.delivered(id)).catch(() => {});
+		} catch {
+			return;
+		}
+		inFlight.add(p);
+		p.finally(() => inFlight.delete(p));
+	};
+
+	return {
+		consume(parsed, _ts, flags) {
+			if (parsed?.type !== "custom_message" || parsed.customType !== INBOX_CUSTOM_TYPE) return;
+			const details = parsed.details !== null && typeof parsed.details === "object" ? parsed.details : {};
+			const id = typeof details.id === "string" && STEER_ID_RE.test(details.id) ? details.id : null;
+			if (flags?.prior === true) {
+				if (id !== null && !prior.has(id)) {
+					prior.add(id);
+					counts.prior += 1;
+				}
+				// F5: a prior line whose ack verifies under THIS attempt's key is a delivery the inbox may not have recorded;
+				// the relay marks it at the baseline instead of writing it again. NOTE the reach: the exit key is minted per
+				// attempt, so a line an EARLIER attempt wrote never verifies here, and such a message is handed over again
+				// (a duplicate, framed, never a loss). Counting an unverified prior line instead would let the agent mark a
+				// message delivered that it was never sent, by writing a line into a transcript a recovery restores.
+				if (id !== null && ackVerifies(exitKey, ackRunId, id, details.ack)) priorVerified.add(id);
+				return;
+			}
+			if (id === null || !ackVerifies(exitKey, ackRunId, id, details.ack)) {
+				counts.unverified += 1;
+				// Said once per attempt, then counted: a job that writes forged lines in a loop must not flood the log.
+				if (!unverifiedSaid) {
+					unverifiedSaid = true;
+					log("steer_ack_unverified", { jobId, ...(id !== null ? { id } : {}) });
+				}
+				return;
+			}
+			if (acked.has(id)) return;
+			acked.add(id);
+			counts.verified += 1;
+			hand(id);
+		},
+		onBaseline() {
+			if (baselined) return;
+			baselined = true;
+			try {
+				relay?.afterBaseline?.(new Set(prior), new Set(priorVerified));
+			} catch {}
+		},
+		// A rewritten transcript (the tail's reset) keeps what was already verified: a delivery that happened stays one.
+		reset() {},
+		async drain() {
+			while (inFlight.size > 0) await Promise.allSettled([...inFlight]);
+		},
+		stats: () => ({ ...counts }),
+	};
+}

package/src/steer-cli.mjs

@@ -0,0 +1,213 @@
+/**
+ * `pi-dispatch steer <jobId> [--later] <text…|->` and `pi-dispatch steer --withdraw <jobId> <msgId>` (issue #646,
+ * REQ-STEER-RUNNING-JOB): an operator's message into a running, steer-armed job, and taking one back.
+ *
+ * Modelled on cancel-cli.mjs, and on its footing: VALKEY_URL only (resolved by cli.mjs with the kill switch's rule),
+ * never loadConfig, the job found across every queue this deployment drains. What differs is what the job must BE:
+ *
+ *   - active. A queued job has no run to steer, and a message waiting for it would arrive as the opening of a run
+ *     the person did not start it for. The message is refused, never parked.
+ *   - open: `run:steer:open:<runId>` present. Only the worker's relay sets it, and only for a run that is armed
+ *     (`run.steer`), running, and on a venue that can deliver (bind mounts, an exit key, an image with `steer`). An
+ *     active job without it is refused with the one sentence that names all three causes, since this side cannot
+ *     tell them apart, rather than accepting a message no one will ever write into the run.
+ *
+ * The push is the inbox's own script (steer-inbox.mjs), so a run that closes in the same moment refuses the message
+ * (`closed`/`gone`) instead of swallowing it. After `ok` the command polls up to 10 s for the relay to write it
+ * (`written`) or the agent to take it (`delivered`) and says which; a message still `queued` at the end of the window
+ * was accepted and is said so, with exit 0. A message that turns `late` (the run ended first) is exit 1: it was not seen.
+ *
+ * NEVER PRINTS THE TEXT. Not on success, not in an error: the id, the mode and the state are enough to find it again,
+ * and a terminal scrollback or a CI log is no place for words meant for one run.
+ */
+
+import * as inbox from "./steer-inbox.mjs";
+
+/** Same budget the kill switch and cancel give the host registry. */
+const FLEET_READ_TIMEOUT_MS = 2_000;
+/** The most stdin may carry before scrubbing: four times the text bound, so control bytes the scrub removes still fit. */
+const STDIN_MAX_BYTES = 32 * 1024;
+
+/**
+ * Read stdin up to `maxBytes`: `{ text }`, or `{ over: true }` the moment it passes the bound (the rest is not read).
+ * `stdin` is the seam; it must be an async iterable of Buffers or strings.
+ */
+export async function readStdinBounded(maxBytes = STDIN_MAX_BYTES, stdin = process.stdin) {
+	const chunks = [];
+	let n = 0;
+	for await (const chunk of stdin) {
+		const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
+		n += buf.length;
+		if (n > maxBytes) {
+			stdin.destroy?.();
+			return { over: true };
+		}
+		chunks.push(buf);
+	}
+	return { text: Buffer.concat(chunks).toString("utf8") };
+}
+
+const USAGE_LINE = "pi-dispatch steer <jobId> [--later] <text…|->  or  pi-dispatch steer --withdraw <jobId> <msgId>";
+
+/** The line for a message's state after the push and the poll. */
+function stateLine(id, jobId, mode, state) {
+	const head = `message ${id} for ${jobId} (${mode === "followUp" ? "follow-up" : "steer"}):`;
+	if (state === "delivered") return `${head} delivered. The agent has received it\n`;
+	if (state === "written") {
+		return mode === "followUp"
+			? `${head} written. The run holds it, and the agent reads it once it would otherwise stop\n`
+			: `${head} written. The run holds it, and the agent reads it after its current tool calls\n`;
+	}
+	return `${head} queued. The worker has not written it into the run yet; it is delivered while the run is open, or reported late if the run ends first. See its state with the console\n`;
+}
+
+/**
+ * Run the verb. `positionals` are what follows `steer` once cli.mjs has taken `--valkey-url`, `--later` and
+ * `--withdraw` out. Returns the exit code. Every collaborator is a seam with the production default, cancel's shape.
+ */
+export async function runSteer({ positionals = [], later = false, withdraw = false } = {}, url, { write = (chunk) => process.stdout.write(chunk), errWrite = (chunk) => process.stderr.write(chunk), redisFn, queueFn, parseConnectionFn, readLiveHostsFn, discoverHostQueuesFn, fleetQueueNamesFn, unionQueueNamesFn, readStdin = readStdinBounded, randomBytes, now = Date.now, ackTimeoutMs = 10_000, pollMs = 250, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), refusalFn } = {}) {
+	const fail = (message) => {
+		errWrite(`error: ${message}\n`);
+		return 1;
+	};
+
+	// Everything that can be refused for free is refused before Valkey is touched.
+	const jobId = positionals[0];
+	if (typeof jobId !== "string" || jobId === "") return fail(`a job id is required: ${USAGE_LINE}  (ids are in \`pi-dispatch status\`, the panel, and the run log)`);
+	let msgId = null;
+	let text = null;
+	if (withdraw) {
+		if (later) return fail("--later and --withdraw do not go together: --withdraw takes a message back, whatever its mode");
+		if (positionals.length !== 2) return fail(`--withdraw takes a job id and one message id: ${USAGE_LINE}`);
+		msgId = positionals[1];
+		if (!inbox.STEER_ID_RE.test(msgId)) return fail("the message id is 32 lowercase hex characters, as `pi-dispatch steer` printed it");
+	} else {
+		const words = positionals.slice(1);
+		if (words.length === 0) return fail(`no message: ${USAGE_LINE}  (- reads it from stdin)`);
+		let raw;
+		if (words.length === 1 && words[0] === "-") {
+			const read = await readStdin(STDIN_MAX_BYTES).catch((error) => ({ error }));
+			if (read.error) return fail(`could not read the message from stdin: ${read.error?.message ?? read.error}`);
+			if (read.over) return fail(`stdin carried more than ${STDIN_MAX_BYTES} bytes; a message is at most ${inbox.STEER_TEXT_MAX_BYTES} bytes. Nothing was sent`);
+			raw = read.text;
+		} else {
+			raw = words.join(" ");
+		}
+		const bounded = inbox.boundSteerText(raw);
+		if (bounded.refusal) return fail(bounded.refusal);
+		text = bounded.text;
+	}
+
+	const { parseConnection, makeRedisClient } = await import("./connection.mjs");
+	const { fleetQueueNames, discoverHostQueues, unionQueueNames, makeQueue } = await import("./queue.mjs");
+	const { readLiveHosts } = await import("./host-registry.mjs");
+	const { runIdOf } = await import("./recovery-queue.mjs");
+	const parseConn = parseConnectionFn ?? parseConnection;
+	const mkRedis = redisFn ?? makeRedisClient;
+	const mkQueue = queueFn ?? makeQueue;
+	const liveHosts = readLiveHostsFn ?? readLiveHosts;
+	const discover = discoverHostQueuesFn ?? discoverHostQueues;
+	const fleetNames = fleetQueueNamesFn ?? fleetQueueNames;
+	const unionNames = unionQueueNamesFn ?? unionQueueNames;
+
+	// cancel's rule (issue #464): a refused Valkey is said as the refusal it is, judged only where this command builds
+	// its own clients.
+	const refusalOf =
+		refusalFn ??
+		(redisFn
+			? async () => null
+			: async (u) => {
+					const { judgeValkeyAtStart, defaultValkeyContext } = await import("./connection.mjs");
+					try {
+						await judgeValkeyAtStart(u, defaultValkeyContext(), { waitMs: 0 });
+						return null;
+					} catch (error) {
+						return error?.valkeyRefused ? error.message : null;
+					}
+				});
+	const valkeyRefused = await refusalOf(url);
+	if (valkeyRefused) return fail(valkeyRefused);
+	const probe = mkRedis(url);
+	probe.on?.("error", () => {});
+	const queues = [];
+	try {
+		const [fleet, existing] = await Promise.all([
+			liveHosts(probe, { timeoutMs: FLEET_READ_TIMEOUT_MS }).catch((error) => ({ unreachable: error?.message ?? String(error) })),
+			discover(probe, { timeoutMs: FLEET_READ_TIMEOUT_MS }),
+		]);
+		const blind = fleet?.unreachable ?? null;
+		const names = unionNames(fleetNames(fleet?.hosts), existing);
+		let job = null;
+		for (const name of names) {
+			const q = mkQueue(parseConn(url, { failFast: true }), { name });
+			queues.push(q);
+			job = await q.getJob(jobId);
+			if (job) break;
+		}
+		if (!job) return fail(`no job ${jobId} in ${names.length} queue(s)${blind ? ` [registry unreadable: ${blind}; a host that is not registered may still hold it]` : ""}`);
+		const runId = runIdOf(job);
+
+		if (withdraw) {
+			const res = await inbox.withdrawSteer({ redis: probe, runId, id: msgId });
+			if (res.error) return res.error === "refused" ? fail(res.reason) : fail(`could not withdraw message ${msgId}: Valkey said ${res.error}`);
+			if (res.prior === "queued") {
+				write(`withdrawn message ${msgId} from ${jobId}: it was queued, so the run never sees it (guaranteed)\n`);
+				return 0;
+			}
+			if (res.prior === "written") {
+				write(`withdrawn message ${msgId} from ${jobId}, best effort: it was already written into the run's inbox, so the agent may have read it before the worker removed it. Its transcript says whether it did\n`);
+				return 0;
+			}
+			if (res.prior === "withdrawn") {
+				write(`message ${msgId} of ${jobId} was already withdrawn; nothing was changed\n`);
+				return 0;
+			}
+			if (res.prior === "delivered") return fail(`message ${msgId} was already delivered: the agent has received it, so it cannot be withdrawn. Nothing was changed`);
+			if (res.prior === "late") return fail(`message ${msgId} arrived after the run had ended (late): the agent never saw it, and there is nothing to withdraw`);
+			return fail(`no message ${msgId} in the inbox of ${jobId}`);
+		}
+
+		const state = await job.getState().catch(() => "unknown");
+		if (state !== "active") return fail(`job ${jobId} is ${state}: only a running job takes messages. Nothing was sent`);
+		const open = await inbox.isOpen({ redis: probe, runId });
+		if (open !== true) {
+			if (open === false) return fail("the run is not accepting messages: it is not steer-armed, not running, or its venue cannot deliver");
+			throw Object.assign(new Error(`Valkey said ${open.error}`), { code: open.error });
+		}
+		const mode = later ? "followUp" : "steer";
+		const id = inbox.operatorMessageId(...(randomBytes ? [randomBytes] : []));
+		const entry = { v: 1, id, mode, source: "cli", author: { kind: "operator", by: "cli" }, text, at: now() };
+		const pushed = await inbox.pushSteer({ redis: probe, runId, entry, now });
+		if (pushed?.error === "refused") return fail(pushed.reason);
+		if (pushed?.error) throw Object.assign(new Error(`Valkey said ${pushed.error}`), { code: pushed.error });
+		if (pushed === "gone") return fail("the run stopped accepting messages before this one arrived (it ended, or its worker stopped refreshing it). Nothing was sent");
+		if (pushed === "closed") return fail("the run has finished and its inbox is closed. Nothing was sent");
+		if (pushed === "full") return fail(`the run's inbox is full (at most ${inbox.STEER_MAX_MESSAGES} messages and ${inbox.STEER_TOTAL_MAX_BYTES} bytes per run, withdrawn ones included). Nothing was sent`);
+		if (pushed !== "ok") return fail(`the inbox answered ${String(pushed)} for a new message id; nothing was sent`);
+
+		// Poll for the relay's write. A read fault ends the poll, not the command: the message IS accepted.
+		// Counted in polls rather than against `now()`: a test's fixed clock would otherwise poll forever, and the
+		// window only needs to be roughly ten seconds.
+		let seen = "queued";
+		const polls = Math.max(1, Math.ceil(ackTimeoutMs / pollMs));
+		for (let i = 0; i < polls; i++) {
+			await sleep(pollMs);
+			const s = await inbox.messageState({ redis: probe, runId, id });
+			if (typeof s !== "string") break;
+			seen = s;
+			if (s !== "queued") break;
+		}
+		if (seen === "late") return fail(`message ${id} for ${jobId}: the run ended before the worker could write it (late). The agent did not see it`);
+		if (seen === "withdrawn") {
+			write(`message ${id} for ${jobId}: withdrawn before it was written\n`);
+			return 0;
+		}
+		write(stateLine(id, jobId, mode, seen));
+		return 0;
+	} catch (error) {
+		return fail(error?.valkeyRefused ? error.message : `could not reach Valkey at ${(await import("./connection.mjs")).urlShown(url)}: ${(await import("./valkey-auth.mjs")).valkeyDownHint(url)}\n  ${error.message}`);
+	} finally {
+		probe.disconnect?.();
+		for (const q of queues) await q.close().catch(() => {});
+	}
+}