@edgehero/pi-dispatch 4.3.1 → 5.1.0

package/src/dollar-budget.mjs

@@ -28,6 +28,7 @@
  * `redis` is any ioredis-compatible client, injected so the logic is testable without a server.
  */
 
+import { createHash } from "node:crypto";
 import { DAY_TTL_SECONDS, MONTH_TTL_SECONDS, WEEK_TTL_SECONDS, dayKey, monthKey, weekKey } from "./budget.mjs";
 import { MICROS_PER_USD, optionalUsdMicros } from "./money.mjs";
 
@@ -366,8 +367,216 @@ export const MODEL_BASIS = Object.freeze(["metered", "floor", "refunded"]);
  * The run record's `dollars` object (INT-RUN-HISTORY-FILE-CONTRACT): an explicit literal of integers and fixed
  * tokens. `modelBasis` is how the job's MODEL windows settled (issue #502 part 6): `metered` when every one settled
  * to its own usage row, `floor` when any kept at least its reservation, `refunded` when they were given back, and
- * `null` when the job held no model window.
+ * `null` when the job held no model window. `reservedIn` (issue #761) is `deploymentWindowsOf`'s answer, carried
+ * only when it is one, so a record of a job that reserved in no deployment window keeps the shape it had.
  */
-export function dollarsRecord({ reservedMicros, settledMicros, basis, modelBasis = null }) {
-	return { reservedMicros, settledMicros, basis, modelBasis: MODEL_BASIS.includes(modelBasis) ? modelBasis : null };
+export function dollarsRecord({ reservedMicros, settledMicros, basis, modelBasis = null, reservedIn = null }) {
+	return { reservedMicros, settledMicros, basis, modelBasis: MODEL_BASIS.includes(modelBasis) ? modelBasis : null, ...(reservedIn ? { reservedIn } : {}) };
+}
+
+// ---- which deployment windows a record's money is in (issue #761, the dollar window reset check) ----
+//
+// A dollar counter holds the history a cap is judged against, and Valkey is its only copy: a flushed, replaced or
+// restored Valkey, an evicted key or a hand edit reopens the cap with nothing saying so. A record cannot be bucketed by
+// its own times to find out (the reservation's clock is neither `startedAt` nor `endedAt`, and a window whose cap was
+// set mid-window was never written by the records before it), so a record says which deployment windows its settled
+// amount is in, `dollars.reservedIn`, and doctor sums this host's records per window against the counter
+// (`dollarWindowFloors`). Only the deployment's day, week and month: a scoped, project or model window's key is a hash
+// per ledger, and a job-count window holds no amount a record states.
+
+/** The deployment's three dollar windows, in the order a hold reserves them (`activeWindows`). */
+export const DEPLOYMENT_WINDOWS = Object.freeze(["day", "week", "month"]);
+
+/** A Valkey endpoint tag: 16 lowercase hex characters (`valkeyEndpointTag`). */
+export const VALKEY_TAG_RE = /^[0-9a-f]{16}$/;
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// The inverse of budget.mjs's `dayKey`, `weekKey` and `monthKey` under the deployment's own prefix, exactly: a scoped
+// or model key (`budget:usd:s:<hash>`, `budget:usd:mdl:<hash>`) starts with the same prefix and matches none of them.
+const WINDOW_KEY_RES = Object.freeze({
+	day: new RegExp(`^${escapeRe(DOLLAR_KEY_PREFIX)}:(\\d{4}-\\d{2}-\\d{2})$`),
+	week: new RegExp(`^${escapeRe(DOLLAR_KEY_PREFIX)}:w:(\\d{4}-\\d{2}-\\d{2})$`),
+	month: new RegExp(`^${escapeRe(DOLLAR_KEY_PREFIX)}:m:(\\d{4}-\\d{2})$`),
+});
+
+/** Which deployment window `key` is and its bucket id (`{ window, bucket }`, the text after the prefix), or null. */
+export function deploymentWindowOfKey(key) {
+	if (typeof key !== "string") return null;
+	for (const window of DEPLOYMENT_WINDOWS) {
+		const m = key.match(WINDOW_KEY_RES[window]);
+		if (m) return { window, bucket: m[1] };
+	}
+	return null;
+}
+
+/**
+ * The deployment's three windows at `now`, `{ day, week, month }`, each `{ key, bucket, startMs, endMs, ttlSeconds }`:
+ * the key a reservation at `now` writes (budget.mjs's key functions, so a reader and the worker cannot disagree about a
+ * boundary), its bucket id, when the bucket begins and ends (UTC: the day, the week from Monday, the month), and the
+ * TTL the worker sets on the key's first write.
+ */
+export function deploymentWindowsAt(now) {
+	const d = new Date(now);
+	const y = d.getUTCFullYear();
+	const mo = d.getUTCMonth();
+	const day = Date.UTC(y, mo, d.getUTCDate());
+	const monday = day - ((new Date(day).getUTCDay() + 6) % 7) * 86_400_000;
+	const at = (key, startMs, endMs, ttlSeconds) => ({ key, bucket: deploymentWindowOfKey(key)?.bucket ?? null, startMs, endMs, ttlSeconds });
+	return {
+		day: at(dayKey(d, DOLLAR_KEY_PREFIX), day, Date.UTC(y, mo, d.getUTCDate() + 1), DAY_TTL_SECONDS),
+		week: at(weekKey(d, DOLLAR_KEY_PREFIX), monday, monday + 7 * 86_400_000, WEEK_TTL_SECONDS),
+		month: at(monthKey(d, DOLLAR_KEY_PREFIX), Date.UTC(y, mo, 1), Date.UTC(y, mo + 1, 1), MONTH_TTL_SECONDS),
+	};
+}
+
+/**
+ * The tag of the Valkey a deployment's counters live in: the first 16 hex characters of SHA-256 over `host:port/db`, so
+ * two deployments that share a logs directory and a worker name (the default per-account `~/.pi-dispatch/logs` and the
+ * hostname) but not a Valkey never add up each other's records. `endpoint` is a VALKEY_URL or a client's connection
+ * options (`{ host, port, db }`, connection.mjs `parseConnection`, which reads them off the URL by the rules below), so
+ * the worker, which holds the options its clients connect with, and doctor, which holds the URL it talks to, compute the
+ * same tag for the same endpoint. Both take the JUDGED address (`pinnedValkeyUrl`: the literal a local Valkey is pinned
+ * to on Linux), the one the worker really dials. A unix socket (`{ path }`, which no client of this project builds
+ * today) is tagged by its path. Credentials and the scheme are never part of it; the host is lowercased, an IPv6
+ * literal's brackets dropped, and a missing host, port or database is ioredis's and `parseConnection`'s default
+ * (127.0.0.1, 6379, 0). Null for anything else (a URL that does not parse, a database that is not a number). A tag that
+ * differs where the endpoint is the same (`localhost` against `127.0.0.1` on a host that pins nothing) only leaves
+ * records out of the floor, which can miss a reset and never invents one. The console's Spend page tags the
+ * VALKEY_URL it reads the counters at as it holds it: its client pins the address on connect but never rewrites the
+ * URL. There a tag that differs only leaves a record counted by its end time, as the page counted before (issue #807).
+ */
+export function valkeyEndpointTag(endpoint) {
+	let host;
+	let port;
+	let db;
+	if (typeof endpoint === "string") {
+		let u;
+		try {
+			u = new URL(endpoint);
+		} catch {
+			return null;
+		}
+		host = u.hostname;
+		port = u.port;
+		db = u.pathname && u.pathname !== "/" ? u.pathname.slice(1) : "";
+	} else if (endpoint !== null && typeof endpoint === "object") {
+		if (typeof endpoint.path === "string" && endpoint.path !== "") return hash16(`unix:${endpoint.path}`);
+		({ host, port, db } = endpoint);
+	} else {
+		return null;
+	}
+	const h = String(host ?? "").replace(/^\[(.*)\]$/, "$1").toLowerCase() || "127.0.0.1";
+	const p = port === undefined || port === null || port === "" ? 6379 : Number(port);
+	const n = db === undefined || db === null || db === "" ? 0 : Number(db);
+	if (!Number.isSafeInteger(p) || p < 0 || !Number.isSafeInteger(n) || n < 0) return null;
+	return hash16(`${h}:${p}/${n}`);
+}
+
+function hash16(text) {
+	return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+/**
+ * The record's `dollars.reservedIn` for a hold (issue #761): `{ day?, week?, month?, valkey }`, the bucket of each
+ * DEPLOYMENT window whose counter holds at least the amount the record states, and the endpoint tag of the Valkey it is
+ * in (`valkeyEndpointTag`). Null when there is no such window: a zero hold (no `ledgers`), a hold with no deployment
+ * ledger, a malformed tag, or every key below the record. PURE.
+ *
+ *   - `hold` is the hold the settlement or release WALKED (`settleDollars`' `hold`: the job's part for a settle, the
+ *     whole hold for a release), so `applied` counts along its `keys`. The deployment ledger is the one whose
+ *     `keyPrefix` is exactly `DOLLAR_KEY_PREFIX`, never a prefix match: every dollar key starts with it.
+ *   - `applied` is how many of those keys the step completed (0 when no step ran); `target` what this job's share of an
+ *     adjusted key now is (the settled amount, 0 for a release); `recorded` the record's `settledMicros`.
+ *
+ * A window is in only when its key holds at least `recorded` of this job's money: `target` for a key the step already
+ * moved, the reservation otherwise. That is what keeps doctor's sum below the counter on a healthy deployment where a
+ * step stopped part-way: a settle whose fault left later keys at the reservation while the record states a metered cost
+ * ABOVE it (an overshoot is charged in full), and a release that gave back the first keys before the fault while the
+ * record states the whole reservation. Both leave their window out, which only lowers the floor.
+ */
+export function deploymentWindowsOf(hold, { applied = 0, target, recorded, valkey } = {}) {
+	if (typeof valkey !== "string" || !VALKEY_TAG_RE.test(valkey)) return null;
+	const ledger = (Array.isArray(hold?.ledgers) ? hold.ledgers : []).find((l) => l?.keyPrefix === DOLLAR_KEY_PREFIX);
+	if (!ledger || !Array.isArray(ledger.keys)) return null;
+	const reserved = hold.amountMicros;
+	if (!Number.isSafeInteger(reserved) || !Number.isSafeInteger(recorded) || !Number.isSafeInteger(applied)) return null;
+	const walked = Array.isArray(hold.keys) ? hold.keys : [];
+	const found = {};
+	for (const key of ledger.keys) {
+		const at = deploymentWindowOfKey(key);
+		if (at === null) continue;
+		const i = walked.indexOf(key);
+		const holds = i >= 0 && i < applied ? target : reserved;
+		if (Number.isSafeInteger(holds) && holds >= recorded) found[at.window] = at.bucket;
+	}
+	const windows = DEPLOYMENT_WINDOWS.filter((w) => Object.hasOwn(found, w));
+	return windows.length === 0 ? null : { ...Object.fromEntries(windows.map((w) => [w, found[w]])), valkey };
+}
+
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const MONTH_RE = /^\d{4}-(0[1-9]|1[0-2])$/;
+/** `text` as a real UTC calendar date (`2026-02-30` is none), or null. */
+function calendarDate(text) {
+	if (typeof text !== "string" || !DATE_RE.test(text)) return null;
+	const d = new Date(`${text}T00:00:00.000Z`);
+	return Number.isFinite(d.getTime()) && d.toISOString().slice(0, 10) === text ? d : null;
+}
+
+/**
+ * A record's `dollars.reservedIn` rebuilt from its own keys, or null (INT-RUN-HISTORY-FILE-CONTRACT): `day` a real
+ * calendar date, `week` a real date that is a Monday, `month` a real month, at least one of them, and `valkey` a tag
+ * (`VALKEY_TAG_RE`). Anything else, a member of the wrong shape included, is null as a whole: a record that carries one
+ * no release wrote says nothing trustworthy about where its money is. Only OWN keys are read, so a value inherited
+ * through the prototype is no member. The one rule the record writer, doctor's sum and the console's Spend page
+ * (admin `spendSummaryOf`, issue #807) read it by.
+ */
+export function reservedInOf(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+	const own = (key) => (Object.hasOwn(value, key) ? value[key] : undefined);
+	const valkey = own("valkey");
+	if (typeof valkey !== "string" || !VALKEY_TAG_RE.test(valkey)) return null;
+	const out = {};
+	const day = own("day");
+	if (day !== undefined) {
+		if (calendarDate(day) === null) return null;
+		out.day = day;
+	}
+	const week = own("week");
+	if (week !== undefined) {
+		if (calendarDate(week)?.getUTCDay() !== 1) return null;
+		out.week = week;
+	}
+	const month = own("month");
+	if (month !== undefined) {
+		if (typeof month !== "string" || !MONTH_RE.test(month)) return null;
+		out.month = month;
+	}
+	return Object.keys(out).length === 0 ? null : { ...out, valkey };
+}
+
+/**
+ * Per deployment window in `buckets` (`{ day?, week?, month? }`, each the CURRENT bucket id), the micro-dollars this
+ * host's own records settled into it: the sum of `dollars.settledMicros` over the records whose `host` is `host`, whose
+ * `reservedIn` (`reservedInOf`) names that bucket for that window, and whose `valkey` is `valkey`. PURE.
+ *
+ * The counter is at least this sum on a healthy deployment: a reservation adds R, a settlement adds S - R and the record
+ * carrying S is written after it, a refunded record is 0, and nothing else lowers a key (`reservedIn` already leaves out
+ * a window a step stopped part-way in). Everything that is not counted (another host's records, a record from before
+ * `reservedIn`, an earlier attempt a retry overwrote, a hold that crashed, a record over the read's size cap, retention
+ * shorter than the window) makes the sum smaller, never larger. So a counter below it lost history.
+ */
+export function dollarWindowFloors(records, { host, valkey, buckets }) {
+	const floors = {};
+	for (const w of DEPLOYMENT_WINDOWS) if (typeof buckets?.[w] === "string") floors[w] = 0;
+	for (const r of Array.isArray(records) ? records : []) {
+		if (r === null || typeof r !== "object" || r.host !== host) continue;
+		const d = r.dollars;
+		if (d === null || typeof d !== "object" || !Number.isSafeInteger(d.settledMicros) || d.settledMicros < 0) continue;
+		const at = reservedInOf(d.reservedIn);
+		if (at === null || at.valkey !== valkey) continue;
+		for (const w of Object.keys(floors)) {
+			if (at[w] === buckets[w] && Number.isSafeInteger(floors[w] + d.settledMicros)) floors[w] += d.settledMicros;
+		}
+	}
+	return floors;
 }

package/src/endpoint-status.mjs

@@ -0,0 +1,100 @@
+/** Endpoint occupancy is a display of the admission map, never another source of admission state (#775). */
+import { isPerMachineHost } from "./backends.mjs";
+import { HOST_SET, HOST_TTL_MS, hostKey } from "./host-registry.mjs";
+import { MODEL_ENDPOINT_ID_RE, MAX_SLOTS } from "./model-endpoints.mjs";
+import { WORKER_NAME_RE } from "./worker-name.mjs";
+
+export const ENDPOINT_STATUS_VERSION = 1;
+export const ENDPOINT_STATUS_MAX = 32;
+export const ENDPOINT_STATUS_HOSTS_MAX = 64;
+const integer = (n) => Number.isSafeInteger(n) && n >= 0;
+
+/** Re-read the loaded file and the SAME map both queue processors claim on every registry beat. */
+export function endpointStatusFields(endpoints, slots, multiHost) {
+	const rows = [...(endpoints ?? [])].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+	const listed = rows.slice(0, ENDPOINT_STATUS_MAX).map((ep) => ({ id: ep.id, slots: ep.slots, used: slots.count(ep.id), fleet: multiHost && !isPerMachineHost(ep.host) ? 1 : 0 }));
+	return { endpointsVersion: ENDPOINT_STATUS_VERSION, endpointsStartedAt: ({ startedAt } = {}) => startedAt ?? "", endpoints: listed.length ? JSON.stringify(listed) : "", endpointsMore: Math.max(0, rows.length - listed.length) };
+}
+
+/** Unknown versions/fields are never interpreted as an empty host. No path, address or operator text survives. */
+export function parseEndpointStatus(row) {
+	const absent = { state: "not-reported", endpoints: null, endpointsMore: null };
+	if (!row || row.endpointsVersion === undefined || row.endpointsVersion === "") return absent;
+	if (String(row.endpointsVersion) !== String(ENDPOINT_STATUS_VERSION)) return { ...absent, state: /^\d+$/.test(String(row.endpointsVersion)) && Number(row.endpointsVersion) > ENDPOINT_STATUS_VERSION ? "unsupported" : "unreadable" };
+	// HSET preserves fields unknown to an older worker. Its new startedAt must invalidate old occupancy.
+	if (!/^(?:0|[1-9]\d*)$/.test(String(row.endpointsStartedAt)) || String(row.endpointsStartedAt) !== String(row.startedAt)) return { ...absent, state: "unreadable" };
+	if (row.endpoints === undefined) return absent;
+	const more = /^(?:0|[1-9]\d*)$/.test(String(row.endpointsMore)) ? Number(row.endpointsMore) : NaN;
+	if (!integer(more)) return { ...absent, state: "unreadable" };
+	if (row.endpoints === "" && more === 0) return { ...absent, endpointsMore: 0 };
+	try {
+		if (typeof row.endpoints !== "string" || row.endpoints.length > 8192) throw Error();
+		const entries = JSON.parse(row.endpoints);
+		if (!Array.isArray(entries) || entries.length > ENDPOINT_STATUS_MAX) throw Error();
+		let previous = "";
+		const endpoints = entries.map((ep) => {
+			if (!ep || typeof ep !== "object" || Array.isArray(ep) || typeof ep.id !== "string" || !MODEL_ENDPOINT_ID_RE.test(ep.id) || ep.id <= previous || !Number.isInteger(ep.slots) || ep.slots < 1 || ep.slots > MAX_SLOTS || !integer(ep.used) || ep.used > MAX_SLOTS || ![0, 1].includes(ep.fleet)) throw Error();
+			previous = ep.id;
+			return { id: ep.id, slots: ep.slots, used: ep.used, fleet: ep.fleet };
+		});
+		return { state: "reported", endpoints, endpointsMore: more };
+	} catch { return { ...absent, state: "unreadable" }; }
+}
+
+function bounded(promise, ms) {
+	let timer;
+	return Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(Error("endpoint status timeout")), ms); })]).finally(() => clearTimeout(timer));
+}
+
+/** Read at most 64 rows, known live hosts first, without pruning or touching the registry's other projections. */
+export async function readEndpointStatus(redis, options = {}) {
+	let stopped = false;
+	try { return await bounded(readEndpointStatusInner(redis, { ...options, stopped: () => stopped }), options.timeoutMs ?? 2500); }
+	catch { return { state: "unknown", hosts: [], more: 0, partial: true }; }
+	finally { stopped = true; }
+}
+
+async function readEndpointStatusInner(redis, { hosts = [], now = () => Date.now(), timeoutMs = 2500, stopped } = {}) {
+	let indexed = [];
+	let partial = false;
+	let cardinality = null;
+	try {
+		cardinality = await bounded(redis.scard(HOST_SET), timeoutMs);
+		if (!integer(cardinality)) throw Error();
+		let cursor = "0";
+		for (let page = 0; page < 4 && !stopped(); page++) {
+			const answer = await bounded(redis.sscan(HOST_SET, cursor, "COUNT", ENDPOINT_STATUS_HOSTS_MAX), timeoutMs);
+			if (!Array.isArray(answer) || typeof answer[0] !== "string" || !Array.isArray(answer[1])) throw Error();
+			indexed.push(...answer[1].slice(0, ENDPOINT_STATUS_HOSTS_MAX));
+			if (answer[1].length > ENDPOINT_STATUS_HOSTS_MAX) partial = true;
+			cursor = answer[0];
+			if (cursor === "0") break;
+			if (page === 3) partial = true;
+		}
+	} catch { partial = true; }
+	const valid = (name) => typeof name === "string" && WORKER_NAME_RE.test(name);
+	if (indexed.some((name) => !valid(name))) partial = true;
+	const known = [...new Set(hosts.map((h) => typeof h === "string" ? h : h?.name).filter(valid))].sort();
+	const names = [...new Set([...known, ...indexed.filter(valid).sort()])];
+	const more = Math.max(0, Math.max(cardinality ?? 0, names.length) - Math.min(names.length, ENDPOINT_STATUS_HOSTS_MAX));
+	const selected = names.slice(0, ENDPOINT_STATUS_HOSTS_MAX);
+	if (!selected.length) return { state: partial ? "unknown" : "reported", hosts: [], more, partial: partial || more > 0 };
+	if (stopped()) return { state: "unknown", hosts: [], more, partial: true };
+	const rows = await Promise.all(selected.map(async (name) => {
+		let row;
+		let ttl;
+		try {
+			[row, ttl] = await bounded(Promise.all([redis.hgetall(hostKey(name)), redis.pttl(hostKey(name))]), timeoutMs);
+		} catch { partial = true; return { name, at: null, ageMs: null, state: "unreadable", endpoints: null, endpointsMore: null }; }
+		if (!row || Object.keys(row).length === 0 || ttl === -2) {
+			return known.includes(name) ? { name, at: null, ageMs: null, state: "not-reported", endpoints: null, endpointsMore: null } : null;
+		}
+		const at = /^(?:0|[1-9]\d*)$/.test(String(row.beatAt)) && integer(Number(row.beatAt)) ? Number(row.beatAt) : null;
+		const ageMs = Number.isSafeInteger(ttl) && ttl >= 0 && ttl <= HOST_TTL_MS ? HOST_TTL_MS - ttl : null;
+		const parsed = parseEndpointStatus(row);
+		if (ageMs === null || row.name !== name) { parsed.state = "unreadable"; parsed.endpoints = null; partial = true; }
+		if (["unsupported", "unreadable"].includes(parsed.state) || parsed.endpointsMore > 0) partial = true;
+		return { name, at, ageMs, ...parsed };
+	}));
+	return { state: partial && !rows.filter(Boolean).length ? "unknown" : "reported", hosts: rows.filter(Boolean), more, partial: partial || more > 0 };
+}

package/src/env-allowlist.mjs

@@ -1,3 +1,4 @@
+// env-internal PI_SUBSCRIPTION_AUTH: host-approved access snapshot metadata, never an operator override.
 /**
  * Build the EXACT environment a job container receives. Never a pass-through.
  *
@@ -29,6 +30,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { findEnvKeys } from "@earendil-works/pi-ai/compat";
 import { getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
+import { codemodeWorkersOf, DEFAULT_JOB_SIZE } from "./job-size.mjs";
 import { egressEnv } from "./egress.mjs";
 import { RECEIVER_ONLY_VARS, forgeSpec } from "./forges.mjs";
 import { apiKeyVariable } from "./provider-key.mjs";
@@ -351,6 +353,13 @@ function resolveEnvName(provider) {
 	return apiKeyVariable(providerKeyCandidates(provider));
 }
 
+/** PI_JOB_LAYOUT's value for `layout`: absent for the default, the name for `sandbox`, refused for anything else. */
+function layoutEnv(layout) {
+	if (layout === "mounts") return undefined;
+	if (layout === "sandbox") return "sandbox";
+	throw new Error(`buildContainerEnv: unknown job layout ${JSON.stringify(layout)} (want "mounts" or "sandbox")`);
+}
+
 /**
  * Assemble the container env. `hostEnv` is the worker's process.env; `job` carries the resolved
  * config and the per-job scoped token (GitHub-backed jobs, and local cron jobs that opted in via
@@ -367,18 +376,25 @@ function resolveEnvName(provider) {
  * `allowGlobalExtensions` defaults to TRUE here, matching loadConfig's default (REQ-GLOBAL-PI-OVERLAY): a
  * caller that says nothing gets the operator's staged setup, and only an explicit `false` withholds it.
  */
-export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCostMicros = null, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], mcpServers = [], awaitInput = false, allowedModels = null, authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync, modelEndpoints = null, exitAuth = false }) {
+export function buildContainerEnv({ size = DEFAULT_JOB_SIZE, provider, secondaryProvider = null, model, maxTurns, maxTokens, maxCostMicros = null, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], packageCanaryPath = undefined, forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], excludeExtensions = [], excludeExtensionTools = [], excludeToolsStrict = false, mcpServers = [], awaitInput = false, approvalGates = null, approvalDecision = null, reportProgress = false, recover = false, recovering = false, steer = false, layout = "mounts", allowedModels = null, authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync, modelEndpoints = null, exitAuth = false, transcriptStderr = false, steerStdin = false, bundleEnvFile = false, observableRunner = false, fork = null, thinkingLevel = null, subscriptionAuth = [] }) {
 	// The provider credential(s), by pi's expected variable name(s) -- from the worker env, or (when
 	// PI_AUTH_FROM_PI is set and the env has none) host-side from pi's auth.json. Throws (config) if
 	// neither source yields one, which the processor turns into a policy refusal that refunds any reserve
 	// (issue #310); the same call is made by its free credential gate, before anything is reserved at all.
 	// `modelEndpoints` is the pickup's snapshot (issue #503): the keyless branch answers `PI_DISPATCH_KEYLESS` in this
 	// map, so the variable is set exactly when the gate passed keyless and is absent on every other job.
-	const credEnv = resolveProviderCredential({ provider, hostEnv, authFromPi, agentDir, readFile, forwardEnv, modelEndpoints });
+	const selectedAuth = subscriptionAuth.find((entry) => entry.provider === provider);
+	const credEnv = selectedAuth ? selectedAuth.env : resolveProviderCredential({ provider, hostEnv, authFromPi, agentDir, readFile, forwardEnv, modelEndpoints });
+	// A reviewed watch classifier may use another provider. Resolve only that provider, never a blanket key copy.
+	const secondaryAuth = subscriptionAuth.find((entry) => entry.provider === secondaryProvider);
+	const secondaryCredEnv = secondaryAuth ? secondaryAuth.env : secondaryProvider && secondaryProvider !== provider ? resolveProviderCredential({ provider: secondaryProvider, hostEnv, authFromPi, agentDir, readFile, forwardEnv: [], modelEndpoints }) : {};
 
 	const env = {
 		PI_PROVIDER: provider,
 		PI_MODEL: model,
+		PI_FORK_ENTRY: recovering === true ? undefined : fork?.fromEntry,
+		PI_FORK_POSITION: recovering === true ? undefined : fork?.position,
+		PI_THINKING_LEVEL: thinkingLevel ?? undefined,
 		PI_MAX_TURNS: String(maxTurns),
 		// The optional per-job token budget (issue #25). Absent/null => variable omitted (docker-run skips
 		// undefined), so the runner attaches a pure meter with no cap. Never an empty string.
@@ -400,9 +416,14 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 		// never PI_PACKAGES=. The delimiter is ":" because these are CONTAINER (POSIX) paths -- never the
 		// host's path.delimiter, which is ";" on Windows.
 		PI_PACKAGES: packagePaths.length > 0 ? packagePaths.join(":") : undefined,
-		// The persisted transcript inside the /session mount (REQ-RESUMABLE-SESSION). Emitted ONLY when
-		// this job actually has one -- absent means the runner builds pi's ephemeral in-memory session,
-		// which is every job before this feature and every job whose trigger did not arm run.resume. Never
+		// Issue #796: which of those paths is a canary's candidate, so the runner can say whether it loaded. Only on a canary job.
+		PI_PACKAGE_CANARY: packageCanaryPath,
+		// The transcript file inside the /session mount (REQ-RESUMABLE-SESSION). Emitted ONLY when this job
+		// actually has one -- absent means the runner builds pi's ephemeral in-memory session. Since issue #643
+		// every prepared job has one (a resume job's staged transcript, or every other job's empty live file,
+		// which the worker tails for the live stream and, since issue #644, for run progress), with one exception: with
+		// both PI_LIVE_TRANSCRIPTS=0 and PI_RUN_PROGRESS=0 no live file is staged (start.mjs hands the preparer
+		// `stageLive: null`), so a non-resume job then has none, as before the feature. Otherwise absence is a caller that staged none, or a staging that failed. Never
 		// an empty string, for PI_PACKAGES' reason: an empty value is a third state neither side reads the
 		// same way, and the one reading a container must not have to infer which was meant.
 		PI_SESSION_FILE: sessionFile || undefined,
@@ -429,6 +450,13 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 		// second-validator rule directly above). Absent means the full pinned default set, never an empty
 		// string, for PI_PACKAGES' reason.
 		PI_EXCLUDE_TOOLS: excludeTools.length > 0 ? excludeTools.join(",") : undefined,
+		// The trigger's run.excludeExtensions and run.excludeExtensionTools (issue #800): the overlay names the runner leaves out
+		// before any factory runs, and the tools it adds to the list above. Comma-safe for that list's reason (the loader's grammar
+		// holds no comma). Absent means none, never an empty string, for PI_PACKAGES' reason. PI_EXCLUDE_TOOLS_STRICT is "1" only
+		// where a name of the second list that no staged package or overlay extension brought can only be wrong (run-container.mjs says when).
+		PI_EXCLUDE_EXTENSIONS: excludeExtensions.length > 0 ? excludeExtensions.join(",") : undefined,
+		PI_EXCLUDE_EXTENSION_TOOLS: excludeExtensionTools.length > 0 ? excludeExtensionTools.join(",") : undefined,
+		PI_EXCLUDE_TOOLS_STRICT: excludeToolsStrict === true ? "1" : undefined,
 		// The trigger's run.mcp (REQ-MCP-OPERATOR-SERVERS): the overlay servers the job's session connects, so the
 		// runner can hold `/job/mcp.json` to the names the worker meant. Comma-safe for excludeTools' reason (the loader
 		// admits only lowercase letters, digits and `-`). Absent means none, never an empty string.
@@ -436,6 +464,26 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 		// The trigger's run.awaitInput (issue #625): "1" offers the job the tool a parked run ends on. Absent means not
 		// armed, never "0" or an empty string, for PI_PACKAGES' reason.
 		PI_AWAIT_INPUT: awaitInput === true ? "1" : undefined,
+		PI_APPROVAL_GATES: approvalGates ? JSON.stringify(approvalGates) : undefined,
+		// Human text travels in the existing read-only event file, never the gateway's logged exec argv.
+		PI_APPROVAL_DECISION: approvalDecision ? JSON.stringify({ requestId: approvalDecision.requestId, action: approvalDecision.action, toolCallId: approvalDecision.toolCallId, decision: approvalDecision.decision }) : undefined,
+		// The trigger's run.progress (issue #644): "1" offers the job the report_progress tool. Absent means not armed,
+		// PI_AWAIT_INPUT's rule.
+		PI_REPORT_PROGRESS: reportProgress === true ? "1" : undefined,
+		// Issue #645, durable runs, two inputs the runner reads apart. PI_RECOVER: the trigger armed run.recover, so the
+		// runner keeps checkpoints a lost run can continue from. PI_RECOVERING: THIS container is that continuation, so
+		// the runner resumes the checkpoint instead of starting the prompt over. Each "1" or absent, PI_AWAIT_INPUT's rule;
+		// strictly `=== true`, so a truthy non-boolean an upstream bug passed arms nothing.
+		PI_RECOVER: recover === true ? "1" : undefined,
+		PI_RECOVERING: recovering === true ? "1" : undefined,
+		// Issue #646: the trigger armed run.steer, so the runner delivers the files the worker writes into its read-only
+		// /inbox mount. "1" or absent, PI_AWAIT_INPUT's rule, strictly `=== true` for PI_RECOVER's reason.
+		PI_STEER: steer === true ? "1" : undefined,
+		// Issue #683: which file layout the runner reads (worker/src/job-layout.mjs), set only for a venue that copies the
+		// job's files (`sandbox`). Absent is `mounts`, so every binding venue's env is byte-identical to one built before
+		// the variable existed. Any other value is the caller's bug and is refused rather than written: the runner would
+		// refuse it too, but only inside a container the budget already paid for.
+		PI_JOB_LAYOUT: layoutEnv(layout),
 		// The job's EFFECTIVE allowed-model list (issue #502): its trigger's `run.models`, else the deployment's
 		// PI_ALLOWED_MODELS. Comma-joined `provider/model` entries, which the runner splits at each entry's first `/`
 		// (image/runner/src/config.mjs). Comma is safe because both list parsers refuse an entry carrying one. NULL is
@@ -453,6 +501,7 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 
 	// The provider credential(s), under pi's expected variable name(s), so pi's own auth resolution finds them.
 	Object.assign(env, credEnv);
+	Object.assign(env, secondaryCredEnv);
 
 	// Operator-declared extra vars (PI_FORWARD_ENV), forwarded by EXACT name -- the allowlist
 	// no-broad-env-into-container prescribes, not a host pass-through. This is how a CUSTOM provider's
@@ -494,9 +543,20 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 	// PI_SESSION_FILE and PI_FLOW already keep. The resolver guarantees non-empty; this is the defense in
 	// depth at the DI seam that the empty-token guard keeps for the mint.
 	for (const [name, value] of Object.entries(secrets ?? {})) {
+		if (secondaryProvider && providerKeyCandidates(secondaryProvider).includes(name)) throw configError(`watch classifier credential variable ${name} is reserved`);
 		if (typeof value === "string" && value !== "") env[name] = value;
 	}
 
+	// An explicit subscription binding is authoritative, including against host API keys and trigger secrets.
+	// Only access snapshots cross this boundary; the runner receives closed metadata to check before loading code.
+	if (subscriptionAuth.length > 0) {
+		for (const snapshot of subscriptionAuth) {
+			for (const name of providerKeyCandidates(snapshot.provider)) delete env[name];
+			Object.assign(env, snapshot.env);
+		}
+		env.PI_SUBSCRIPTION_AUTH = JSON.stringify(subscriptionAuth.map(({ provider, connectionId, adapter, generation, expiresAt, deadlineAt, root, digest }) => ({ provider, connectionId, adapter, generation, expiresAt, deadlineAt, ...(root ? { root, digest } : {}) })));
+	}
+
 	// The shipped egress policy's variables (REQ-EGRESS-ALLOWLIST), AFTER the PI_FORWARD_ENV loop so a
 	// forwarded name can never override them -- the same ordering, for the same reason, as the minted token
 	// below (and loadConfig refuses those names outright while the policy is armed anyway).
@@ -544,9 +604,39 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 	// the cap above, and ONLY for a run the worker actually hands a key, so a runner never blocks on a stdin no one
 	// writes. `=== true`, so only run-container's own boolean asks for it.
 	// env-internal PI_EXIT_AUTH: written into the job's closed env map here, never read from the worker's environment.
-	if (exitAuth === true) env.PI_EXIT_AUTH = "stdin";
+	// Issue #686: `stdin-frames` names the stdin frame channel instead, the key as frame 1 and the pipe left open for
+	// message frames: only for an attempt run-container armed for stdin steering (`steerStdin`, a copying venue and an
+	// image declaring it), and only beside PI_STEER=1, so every other attempt's value stays `stdin`, byte-identical.
+	if (exitAuth === true) env.PI_EXIT_AUTH = steerStdin === true && steer === true ? "stdin-frames" : "stdin";
 	else delete env.PI_EXIT_AUTH;
 
+	// Issue #686: the runner mirrors its session file over stderr as signed records, for an attempt run-container armed
+	// (a copying venue, an image that declares `transcriptStderr`, and a key). Settled here like PI_EXIT_AUTH, and only
+	// beside it: a record is signed with that key, so without one the runner would mirror nothing anyway. `=== true`.
+	// env-internal PI_TRANSCRIPT: written into the job's closed env map here, never read from the worker's environment.
+	if (transcriptStderr === true && exitAuth === true) env.PI_TRANSCRIPT = "stderr";
+	else delete env.PI_TRANSCRIPT;
+
+	// Issue #704 part 3: the runner reads a project secret bundle's plain variables from the job directory's
+	// bundle-env.json, for an attempt run-container armed (a venue that hands them by file, `openshell`, and a bundle
+	// with plain variables). Settled after both loops like the two above, so no forwarded or secret value can set it.
+	// env-internal PI_BUNDLE_ENV: written into the job's closed env map here, never read from the worker's environment.
+	if (bundleEnvFile === true) env.PI_BUNDLE_ENV = "1";
+	else delete env.PI_BUNDLE_ENV;
+
+	// Issue #730: the readable runner node (image/entrypoint.sh), for a venue whose connections are mediated by a broker
+	// that reads the caller's memory (OpenShell, both modes), and no other. Settled after both loops like the flags above,
+	// so no forwarded or secret value can set it, and deleted otherwise: on every other venue the key holders stay on
+	// the exec-only node.
+	// env-internal PI_RUNNER_OBSERVABLE: written into the job's closed env map here, never read from the worker's environment.
+	if (observableRunner === true) env.PI_RUNNER_OBSERVABLE = "1";
+	else delete env.PI_RUNNER_OBSERVABLE;
+
+	// Issue #693: only the resolved container size chooses this concurrency limit. Set after forwarding and secrets
+	// so even a caller bypassing their reservation cannot replace it with a host or trigger value.
+	// env-internal PI_CODEMODE_MAX_WORKERS: written into the job's closed env map here, never read from the worker's environment.
+	env.PI_CODEMODE_MAX_WORKERS = String(codemodeWorkersOf(size.memMiB));
+
 	// Issue #500: the runner sets these in its own environment, for its child processes, and no value from outside
 	// may arrive first. Both lists refuse them upstream (config.mjs for PI_FORWARD_ENV, the triggers loader for
 	// run.secrets, through RUNNER_ENV_NAMES); this is the line that holds if either refusal is ever bypassed.

package/src/env-file.mjs

@@ -775,7 +775,7 @@ function keyAlreadySet(text, key, platform) {
  *   a `# KEY=` comment inside a multi-line value, each left the key unset while the writer reported it written.
  *   `verify` lets a caller add its own condition on the new text.
  */
-function planEnvEdit(raw, path, key, value, { overwrite = false, platform = process.platform, verify } = {}) {
+export function planEnvEdit(raw, path, key, value, { overwrite = false, platform = process.platform, verify } = {}) {
 	const refusal = envFileEditRefusal(raw, path);
 	if (refusal !== null) return { error: refusal };
 	const text = typeof raw === "string" ? raw : Buffer.from(raw).toString("utf8");
@@ -2065,14 +2065,16 @@ export function decodeEnvFile(content, { loader = "systemd" } = {}) {
  * effect, and the reader and writer name it rather than let an operator believe it does anything. PI_ENV_SETUP is on
  * both lists: it is unit configuration and never honoured from the file. The cmd list is compared ignoring case, as
  * `set` does. Kept beside the wrappers' text by a test, which fails when either wrapper's own variables change.
+ * PI_WRAPPER_NO_DOTENV (issue #708) joins both: the console's unit sets it, the wrappers test it BEFORE the load and
+ * unset it after, so a `.env` line naming it can neither start nor stop the load.
  */
 export const WRAPPER_INTERNAL_KEYS = Object.freeze({
-	shell: Object.freeze(["PI_ENV_SETUP", "env_setup", "signaled", "child", "rc"]),
-	cmd: Object.freeze(["PI_ENV_SETUP", "ENV_SETUP", "RC", "ERRORLEVEL"]),
+	shell: Object.freeze(["PI_ENV_SETUP", "PI_WRAPPER_NO_DOTENV", "env_setup", "signaled", "child", "rc"]),
+	cmd: Object.freeze(["PI_ENV_SETUP", "PI_WRAPPER_NO_DOTENV", "ENV_SETUP", "RC", "ERRORLEVEL"]),
 });
 
 /** What a line assigning one of the wrapper's own variables is, and what to do, in the words doctor and the writer use. */
-const WRAPPER_INTERNAL_WHAT = (name) => `assigns ${name}, a variable the service wrapper keeps for itself (deploy/worker-env-wrapper.sh on macOS, .cmd on Windows) and assigns again after loading this file, so the line has no effect${/^pi_env_setup$/i.test(name) ? "; PI_ENV_SETUP is never honoured from this file" : ""}`;
+const WRAPPER_INTERNAL_WHAT = (name) => `assigns ${name}, a variable the service wrapper keeps for itself (deploy/worker-env-wrapper.sh on macOS, .cmd on Windows) and assigns again after loading this file, so the line has no effect${/^pi_env_setup$/i.test(name) ? "; PI_ENV_SETUP is never honoured from this file" : /^pi_wrapper_no_dotenv$/i.test(name) ? "; PI_WRAPPER_NO_DOTENV is unit configuration (the console's service sets it) and never honoured from this file" : ""}`;
 const WRAPPER_INTERNAL_FIX = "remove the line (a setup script is named with pi-dispatch service install --env-setup <path>, never in .env)";
 
 /** A `envFileWrapperInternal` finding as one sentence: the line, what it is, and the fix. */

package/src/envelope.mjs

@@ -290,7 +290,7 @@ function jobPathCandidates(path, cwd, env, statSync) {
  * to write instead, when there is one. The FILE must exist (the check runs with a successful load) and must have one
  * link: a hard link elsewhere is the same file under a name this check cannot see, and it could sit in a job path.
  */
-function canonicalEnvelopePath(path, realpath, statSync) {
+function canonicalEnvelopePath(path, realpath, statSync, directory = false) {
 	const text = String(path);
 	if (!isAbsolute(text)) throw configError(`the envelope path ${JSON.stringify(text)} must be absolute: write its canonical path, with no symlink, "." or ".." in it`);
 	let real;
@@ -304,6 +304,8 @@ function canonicalEnvelopePath(path, realpath, statSync) {
 	}
 	const stat = statSync(text, { bigint: true });
 	// Before the link count: a directory's nlink counts its subdirectories, so "has 3 hard links" would misname it.
+	// `directory`: the console's device store is a folder, judged by the same identity rules. A folder has no link count to speak of.
+	if (directory && stat.isDirectory()) return text;
 	if (!stat.isFile()) {
 		throw configError(`the envelope path ${JSON.stringify(text)} is not a regular file; point it at the envelope file itself`);
 	}
@@ -366,8 +368,8 @@ export function fileIdentity(stat) {
  * relative, and when a path cannot be read for a reason other than its absence. `realpathSync`, `statSync`, `cwd` and
  * `env` are injectable for tests.
  */
-export function envelopeInsideJobPaths(envelopePath, { cronFolders = [], runRoots = [], skillsDirs = [], globalPiDir = null } = {}, { realpathSync = fsRealpathSync.native, statSync = fsStatSync, cwd = process.cwd(), env = process.env } = {}) {
-	const real = canonicalEnvelopePath(envelopePath, realpathSync, statSync);
+export function envelopeInsideJobPaths(envelopePath, { cronFolders = [], runRoots = [], skillsDirs = [], globalPiDir = null } = {}, { realpathSync = fsRealpathSync.native, statSync = fsStatSync, cwd = process.cwd(), env = process.env, directory = false } = {}) {
+	const real = canonicalEnvelopePath(envelopePath, realpathSync, statSync, directory);
 	// A relative run root is refused under an envelope, as `PI_GLOBAL_PI_DIR` and `run.skillsDir` already must be
 	// absolute: the worker would judge it against its own working directory, while the admin's `dispatch_run` resolves
 	// it in the operator's pi process, so the two could mean different folders.

package/src/file-expect.mjs

@@ -0,0 +1,47 @@
+/**
+ * The re-check a confirmed write makes right before its rename (issue #642): the files the change was BUILT from, as
+ * `{ path, text }` snapshots taken before an operator's confirm (the admin's `writeInputs`, stored in the console's
+ * ticket), compared with the files as they are now. A difference refuses, with nothing written, so a confirm applies
+ * exactly what was previewed and a second session's write in between is a refusal, never a silent lost update.
+ *
+ * One encoding, the admin's `fileSnapshot` (admin/src/read-model.mjs), and a test holds the two to it: the text, `null`
+ * for a file that does not exist (ENOENT and only ENOENT), or `UNREADABLE` plus the error code for any other read
+ * failure, a string no file's text can equal. A snapshot taken by one and compared by the other must agree, because the
+ * console takes it through the admin and the triggers and settings writers compare it here.
+ *
+ * Pure apart from the reads, and import-free, so `runtime-settings.mjs` (which the admin bundles) can take it.
+ */
+
+/** What `fileSnapshot` returns for a file that is there but cannot be read: a string no file's text can equal. */
+const UNREADABLE = "\u0000unreadable:";
+
+/** A file's text, `null` when it does not exist, or `UNREADABLE` + the error code for any other read failure. */
+export function fileSnapshot(fs, path) {
+	try {
+		return fs.readFileSync(path, "utf8");
+	} catch (e) {
+		if (e?.code === "ENOENT") return null;
+		return `${UNREADABLE}${typeof e?.code === "string" ? e.code : "error"}`;
+	}
+}
+
+/**
+ * The refusal for the first snapshot in `expect` whose file changed, or null when every one still holds (and when
+ * `expect` is not an array: no expectation, nothing to refuse). Every confirmed write says a lost race in these words:
+ * the triggers and settings writers here, `writePauseWindows` and `replaceFile` through the package's `./file-expect`.
+ *
+ * A difference one side of which is a failed read is no lost race, and "another session wrote it" would send a person
+ * looking for a session that never ran, so it says what happened. Two failed reads with one code still compare equal: a
+ * writer that means to replace the file has read it first, and refuses there.
+ */
+export function expectRefusal(fs, expect) {
+	if (!Array.isArray(expect)) return null;
+	for (const input of expect) {
+		const now = fileSnapshot(fs, input?.path);
+		if (now === input?.text) continue;
+		const failed = [now, input?.text].find((snapshot) => typeof snapshot === "string" && snapshot.startsWith(UNREADABLE));
+		if (failed !== undefined) return `${input?.path} could not be read (${failed.slice(UNREADABLE.length)}) when this change was checked against it; nothing was written. Look again and retry`;
+		return `${input?.path} changed after this change was built from it (another session wrote it); nothing was written. Look again and retry`;
+	}
+	return null;
+}