@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/redact-secrets.mjs

@@ -0,0 +1,219 @@
+import { egressEnv } from "./egress.mjs";
+import { FORGE_HOST_VARS } from "./forges.mjs";
+import { KEYLESS_ENV_NAME } from "./reserved-env.mjs";
+
+/**
+ * Take a job's own secrets out of text the agent wrote, before that text leaves the host (issue #643,
+ * `DES-LIVE-TRANSCRIPT-STREAM`).
+ *
+ * The live transcript is agent-writable, so it is untrusted data, and it can hold anything the agent saw: a
+ * `printenv`, a token pasted into a curl, a header in a tool's error. `scrubCredentials` (redact.mjs) handles URL
+ * userinfo and home names only, and is the wrong tool here: it keeps the useful half of a fault line, where this
+ * removes VALUES this worker itself handed the container. Two rules, applied in this order:
+ *
+ *   1. Every secret VALUE of at least `MIN_SECRET_LENGTH` characters, in three spellings: literal, JSON-escaped
+ *      (as `JSON.stringify` writes it inside a string, which is how a tool call's arguments reach the stream) and
+ *      URL-encoded (`encodeURIComponent`, both hex cases, which is how a token in a query string looks). Longest
+ *      first, so a value that contains another is taken whole rather than leaving its tail behind.
+ *   2. Known token SHAPES, for a secret this job was never handed (a token the agent found in a repository, or one
+ *      an operator forwarded under a name this rule cannot see): GitHub's five prefixes and fine-grained PATs,
+ *      GitLab PATs, Anthropic and OpenAI style keys, Slack bot and user tokens, this project's own console tokens,
+ *      AWS access key ids, the credential half of a `Bearer` or `Authorization:` header, and the userinfo of a
+ *      URL (`scheme://user:password@`).
+ *
+ * A match becomes `[redacted]`. A header keeps its scheme (`Authorization: Basic [redacted]`), because the scheme
+ * is what tells a reader which kind of credential was there, and it is never itself secret.
+ *
+ * WHY THE LENGTH FLOOR. A value shorter than eight characters is a port, a flag or a word, and replacing every
+ * occurrence of it would make the transcript unreadable while protecting nothing a guess could not reach. Real
+ * credentials are longer: the shortest this worker hands out is a minted forge token.
+ *
+ * NOT DEFENDED, named here and in SECURITY.md: a secret the agent TRANSFORMS (base64, reversed, split across two
+ * tool calls, one character per line) is not caught by either rule, and cannot be by any rule that does not know
+ * the transformation. Redaction bounds an accident; it is not a boundary against an agent trying to leak.
+ */
+
+/** The shortest value rule 1 takes. Shorter values pass through untouched. */
+export const MIN_SECRET_LENGTH = 8;
+
+/** What every match becomes. */
+export const REDACTED = "[redacted]";
+
+/**
+ * The token shapes of rule 2. Each body has a floor long enough that an ordinary identifier with the same prefix
+ * (`sk-learn`, `ghp_test`) is left alone, and each is anchored so a prefix inside a longer word (`task-...`,
+ * `disk-...`) does not match.
+ */
+const TOKEN_SHAPES = [
+	/(?<![A-Za-z0-9_])gh[pousr]_[A-Za-z0-9]{16,}/g,
+	/(?<![A-Za-z0-9_])github_pat_[A-Za-z0-9_]{16,}/g,
+	/(?<![A-Za-z0-9_])glpat-[A-Za-z0-9_-]{16,}/g,
+	// `sk-ant-` is matched by the `sk-` shape too; it is listed so the intent survives a later tightening of that one.
+	/(?<![A-Za-z0-9_])sk-ant-[A-Za-z0-9_-]{16,}/g,
+	/(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{16,}/g,
+	/(?<![A-Za-z0-9_])xox[bp]-[A-Za-z0-9-]{10,}/g,
+	/(?<![A-Za-z0-9_])pdc_[A-Za-z0-9_-]{16,}/g,
+	/(?<![A-Za-z0-9])AKIA[0-9A-Z]{16}(?![0-9A-Z])/g,
+];
+
+/** `Authorization: <scheme> <credential>`, any case, quoted or not; the scheme is kept. */
+const AUTHORIZATION_HEADER = /(authorization["']?\s*[:=]\s*["']?)([A-Za-z][A-Za-z0-9_-]*)(\s+["']?)([^\s"',;]+)/gi;
+/** An `Authorization` header with no scheme: the whole value is the credential (`Authorization: <credential>`). */
+const AUTHORIZATION_BARE = /(authorization["']?\s*[:=]\s*["']?)([^\s"',;]{8,})(?=\s*(?:["',;]|$))/gim;
+/** A bare `Bearer <credential>`, where no `Authorization` precedes it (a curl `-H` split, a log line). */
+const BEARER = /(\bbearer\s+)([A-Za-z0-9._~+/=-]{8,})/gi;
+
+/**
+ * The userinfo of a URL, `scheme://user:password@` (or a token alone before the `@`), which becomes
+ * `scheme://[redacted]@`: a proxy URL an operator forwarded with credentials, a clone URL with a token in it. The
+ * URL grammar of `scrubCredentials` (redact.mjs), with the scheme REQUIRED: there a fault line is short and the
+ * cost of eating an e-mail address is small, while a transcript is full of addresses and `user@host` prose that
+ * carry no credential. The run stops at the first `/`, `?` or `#` (the host's end), so an `@` in a path or a query
+ * is never taken, and takes up to the LAST `@` before it, so a password holding a raw `@` goes whole.
+ */
+const URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/?#"'`<>]*@/gi;
+
+/** A string's three spellings that rule 1 matches. */
+function spellingsOf(value) {
+	const json = JSON.stringify(value).slice(1, -1);
+	const url = encodeURIComponent(value);
+	const lowerUrl = url.replace(/%[0-9A-F]{2}/g, (pct) => pct.toLowerCase());
+	return [value, json, url, lowerUrl];
+}
+
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * `makeRedactor({ values, extraPatterns? })` returns `(text) => text`. `values` is every secret this job holds
+ * (`secretValuesOf` below builds it from the container env); non-strings and values under the floor are dropped.
+ * `extraPatterns` are further global regexps whose whole match is redacted. Never throws: a non-string input is
+ * stringified first.
+ */
+export function makeRedactor({ values = [], extraPatterns = [] } = {}) {
+	const forms = new Set();
+	for (const value of values) {
+		if (typeof value !== "string" || value.length < MIN_SECRET_LENGTH) continue;
+		// Every spelling is at least as long as the value, so the floor above covers them all.
+		for (const form of spellingsOf(value)) forms.add(form);
+	}
+	// Longest first, so the alternation takes the longest value at any position: JavaScript's alternation is
+	// ordered, not leftmost-longest, so `abcdefgh|abcdefghij` would leave `ij` behind.
+	const sorted = [...forms].sort((a, b) => b.length - a.length);
+	const literal = sorted.length > 0 ? new RegExp(sorted.map(escapeRegExp).join("|"), "g") : null;
+	const shapes = [...TOKEN_SHAPES, ...extraPatterns.filter((p) => p instanceof RegExp && p.global)];
+	return function redact(text) {
+		let out = String(text ?? "");
+		if (literal) out = out.replace(literal, REDACTED);
+		out = out.replace(AUTHORIZATION_HEADER, (_, head, scheme, gap, credential) => (credential === REDACTED ? `${head}${scheme}${gap}${credential}` : `${head}${scheme}${gap}${REDACTED}`));
+		out = out.replace(AUTHORIZATION_BARE, (_, head, credential) => (credential === REDACTED ? `${head}${credential}` : `${head}${REDACTED}`));
+		out = out.replace(BEARER, (_, head, credential) => (credential === REDACTED ? `${head}${credential}` : `${head}${REDACTED}`));
+		out = out.replace(URL_USERINFO, (_, scheme) => `${scheme}${REDACTED}@`);
+		for (const shape of shapes) out = out.replace(shape, REDACTED);
+		return out;
+	};
+}
+
+/**
+ * The container env keys that carry NO secret: everything `buildContainerEnv` (env-allowlist.mjs) writes from a
+ * structural input, so a path, a flag, a model name or a count is never redacted out of a transcript.
+ *
+ * THE RULE IS INVERTED ON PURPOSE: every key NOT listed here is secret-bearing. That covers, by construction, the
+ * minted forge token under each of its forge's names, the provider credential under whatever name pi reads it,
+ * every `PI_FORWARD_ENV` variable, every resolved trigger secret and every model-endpoint key. A variable added to
+ * the container env later is redacted until someone lists it here, which is the safe direction: a missing entry
+ * here costs readability, a missing entry in an allowlist of secrets would cost a leak.
+ *
+ * Derived where a source exists: the forge host variables from `FORGE_HOST_VARS`. The rest are `buildContainerEnv`'s
+ * own literals, held to it by a test that builds an env with every structural option set and finds no other key
+ * outside the credential.
+ *
+ * NOT the proxy variables (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `NODE_USE_ENV_PROXY`). With the egress policy
+ * armed the worker writes them itself and they are structural, but with `PI_EGRESS=0` an operator may forward them,
+ * and a forwarded proxy URL can carry a password. So they are non-secret only per job, and only with the exact
+ * value the worker wrote: `secretValuesOf`'s `workerSet`, which `runContainer` fills from `egressEnv` for that job.
+ */
+export const NON_SECRET_ENV_KEYS = new Set([
+	// Issue #693: a memory-derived concurrency count, never a credential; keep it in the structural venue env.
+	"PI_CODEMODE_MAX_WORKERS",
+	"PI_PROVIDER",
+	"PI_MODEL",
+	"PI_FORK_ENTRY",
+	"PI_FORK_POSITION",
+	"PI_THINKING_LEVEL",
+	"PI_MAX_TURNS",
+	"PI_MAX_TOKENS",
+	"PI_MAX_COST_MICROS",
+	"PI_JOB_ID",
+	"PLAYWRIGHT_BROWSERS_PATH",
+	"PLAYWRIGHT_MCP_BROWSER",
+	"PLAYWRIGHT_MCP_SANDBOX",
+	"PI_GLOBAL_ALLOW_EXTENSIONS",
+	"PI_PACKAGES",
+	"PI_SESSION_FILE",
+	"PI_FLOW",
+	"PI_COMMAND",
+	"PI_EXCLUDE_TOOLS",
+	"PI_EXCLUDE_EXTENSIONS",
+	"PI_EXCLUDE_EXTENSION_TOOLS",
+	"PI_EXCLUDE_TOOLS_STRICT",
+	"PI_MCP_SERVERS",
+	"PI_AWAIT_INPUT",
+	// Approval env holds declared actions and decision identifiers only; human text stays in event.json.
+	"PI_APPROVAL_GATES",
+	"PI_APPROVAL_DECISION",
+	"PI_REPORT_PROGRESS",
+	"PI_RECOVER",
+	"PI_RECOVERING",
+	"PI_STEER",
+	"PI_ALLOWED_MODELS",
+	"PI_OFFLINE",
+	"PI_EXIT_AUTH",
+	// Issue #686: names the transcript channel (`stderr`), never a secret; on openshell it must ride the exec's --env.
+	"PI_TRANSCRIPT",
+	// Issue #704 part 3: `1`, the bundle env file's flag, never a secret; on openshell it must ride the exec's --env.
+	"PI_BUNDLE_ENV",
+	// Issue #683: the runner's layout name, `sandbox` on the openshell venue.
+	"PI_JOB_LAYOUT",
+	// Issue #730: `1`, the readable runner's flag, never a secret; on openshell it must ride the exec's --env.
+	"PI_RUNNER_OBSERVABLE",
+	"HOME",
+	KEYLESS_ENV_NAME,
+	...FORGE_HOST_VARS,
+]);
+
+/** The variables the worker writes when the egress policy is armed, by name: what `workerSet` may vouch for. */
+export const EGRESS_ENV_KEYS = Object.freeze(Object.keys(egressEnv({ armed: true })));
+
+/**
+ * The secret values of one job: every container env value whose key is not in `NON_SECRET_ENV_KEYS`, plus
+ * `extra` (the minted token and the exit-line key, which `runContainer` holds outside the env: the key never
+ * enters it at all). `workerSet` is the env the worker itself wrote for this job's egress (`egressEnv`, empty when
+ * the policy is off): a key in it counts as structural only while its value is exactly the one written there.
+ * Strings only; the length floor is the redactor's.
+ */
+export function secretValuesOf(env = {}, extra = [], { workerSet = {} } = {}) {
+	const values = [];
+	for (const [key, value] of Object.entries(env ?? {})) {
+		if (NON_SECRET_ENV_KEYS.has(key)) continue;
+		if (EGRESS_ENV_KEYS.includes(key) && Object.hasOwn(workerSet ?? {}, key) && workerSet[key] === value) continue;
+		if (typeof value === "string" && value !== "") values.push(value);
+	}
+	for (const value of extra) if (typeof value === "string" && value !== "") values.push(value);
+	// The password inside a URL-shaped value (a forwarded proxy, a database URL) is a secret on its own: a tool can
+	// print it without its URL (`curl -U user:password`, "the password is ..."). Added raw and percent-decoded.
+	for (const value of [...values]) {
+		const m = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/([^/@\s]+)@/.exec(value);
+		if (!m) continue;
+		const colon = m[1].indexOf(":");
+		if (colon < 0) continue;
+		const password = m[1].slice(colon + 1);
+		if (password !== "") values.push(password);
+		try {
+			const decoded = decodeURIComponent(password);
+			if (decoded !== password && decoded !== "") values.push(decoded);
+		} catch {
+			// not valid percent-encoding: the raw form is already listed
+		}
+	}
+	return values;
+}

package/src/reserve-estimate.mjs

@@ -0,0 +1,101 @@
+/**
+ * What a job will hold when the worker reserves for it (issue #642): the figure the operator console shows before a
+ * paid action (a re-run, an answer to a parked run) is confirmed. CONST-BUDGET-BEFORE-TOKENS is unchanged: the worker
+ * still reserves at pickup, and this only SAYS beforehand what that reserve will be.
+ *
+ * The rule is the worker's, imported rather than restated, which is the whole point of this module:
+ *   - the per-job dollar cap is `effectiveCostCapMicros(trigger's maxCostUsd, deployment's maxCostUsd)` (money.mjs),
+ *     the smaller of the two, each counted only when set: exactly what `effectiveJobOf` (index.mjs) gives `runJob`;
+ *   - a job that cannot spend reserves nothing: `zeroRatedFor` below is the processor's own test (its reserve step
+ *     calls it), a cap of 0 or every callable model served by a declared endpoint and zero-rated (model-endpoints.mjs);
+ *   - every job takes one job-count slot in each window that applies.
+ *
+ * The deployment's settings resolve as the worker's do, `overlay > env > default` per key (runtime-settings.mjs over
+ * config.mjs), with an empty env value unset (`usdSetting`).
+ */
+
+import { effectiveCostCapMicros } from "./money.mjs";
+import { splitModelEntry } from "./model-ref.mjs";
+import { zeroRatedVerdict } from "./model-endpoints.mjs";
+import { DEFAULT_MODEL, DEFAULT_PROVIDER, allowedModelsFrom } from "./config.mjs";
+
+/**
+ * The models a job may call (issue #501, #503 part 7), as `{ provider, id }` refs: its main model, and every entry of
+ * its effective allowed-model list when it has one. A list entry that does not split is kept as `null`, which the
+ * zero-rated check reads as "not zero-rated" (fail closed). Moved here from processor.mjs (issue #642), which imports
+ * it, so the estimate and the reserve judge the same refs.
+ */
+export function callableModelRefs(job) {
+	const refs = [{ provider: job.provider, id: job.model }];
+	for (const entry of Array.isArray(job.models) ? job.models : []) {
+		const ref = splitModelEntry(entry);
+		refs.push(ref === null ? null : { provider: ref.provider, id: ref.model });
+	}
+	return refs;
+}
+
+/**
+ * Can this EFFECTIVE job (provider, model, models and `maxCostMicros` resolved) spend nothing? `{ zeroRated: true }`
+ * for a cap that is already 0 (nothing to reserve), else `zeroRatedVerdict` over its callable models and the pickup's
+ * endpoint snapshot `{ models, endpoints }` (null: none, so never zero-rated). The processor's reserve step and the
+ * console's estimate both call this, so the two cannot disagree on the rule.
+ */
+export function zeroRatedFor(job, { modelEndpoints = null, builtinModel = () => null } = {}) {
+	if (job.maxCostMicros === 0) return { zeroRated: true };
+	return zeroRatedVerdict({ models: modelEndpoints?.models ?? null, endpoints: modelEndpoints?.endpoints ?? [], refs: callableModelRefs(job), builtinModel });
+}
+
+/** An env dollar value as config.mjs's `usdSetting` reads it: unset or empty is null. Validated by the cap below. */
+function envUsd(raw) {
+	return raw === undefined || raw === "" ? null : raw;
+}
+
+/**
+ * The reserve for `jobData` (the job's data as it will be queued), against the deployment's settings overlay and env:
+ * `{ slots: 1, dollarsMicros, capMicros, zeroRated }`, or `{ invalid }` when the deployment's own dollar setting does
+ * not parse (the worker refuses every job then, `settings-overlay-invalid`).
+ *
+ *   - `capMicros`: the per-job cap the runner enforces before every priced call, or null for none.
+ *   - `dollarsMicros`: what the worker holds in each dollar window that applies (the deployment's, a scoped or model
+ *     row's): 0 for a zero-rated job, else the cap; null when there is no cap (then no window can be set either, the
+ *     dollar invariant). With no dollar window set the worker holds nothing in dollars, and the runner still stops
+ *     the job at `capMicros`.
+ *   - `zeroRated`: whether the job can spend nothing at all.
+ *
+ * `modelEndpoints` (`{ models, endpoints }`, the worker's pickup snapshot) and `builtinModel` are the zero-rated
+ * check's inputs; without them a job is judged not zero-rated, the fail-closed direction (the estimate then names the
+ * larger figure, never a smaller one than the worker holds).
+ */
+export function estimateReserve(jobData, { overlay = {}, env = {}, modelEndpoints = null, builtinModel = () => null } = {}) {
+	const data = jobData ?? {};
+	const o = overlay ?? {};
+	// The deployment's allowed-model list (PI_ALLOWED_MODELS, env only, never the overlay), the worker's `effectiveJobOf`
+	// fallback when the job names none: with it, every listed model must be zero-rated too, since the job may switch to
+	// any of them. An env list the worker would refuse at boot cannot be judged at all, and judging it as "no list" would
+	// NARROW the refs to the main model alone (a smaller figure than a list could give), so it is judged not zero-rated:
+	// the estimate then names the cap, never less than a worker could hold.
+	let allowed = null;
+	let allowedInvalid = false;
+	try {
+		allowed = allowedModelsFrom(env ?? {});
+	} catch {
+		allowedInvalid = true;
+	}
+	const models = data.models ?? allowed ?? null;
+	let capMicros;
+	try {
+		capMicros = effectiveCostCapMicros(data.maxCostUsd, o.maxCostUsd ?? envUsd(env?.PI_MAX_COST_USD));
+	} catch (e) {
+		return { invalid: e?.message ?? String(e) };
+	}
+	const job = {
+		...data,
+		provider: data.provider ?? o.provider ?? env?.PI_PROVIDER ?? DEFAULT_PROVIDER,
+		model: data.model ?? o.model ?? env?.PI_MODEL ?? DEFAULT_MODEL,
+		...(models !== null ? { models } : {}),
+		maxCostMicros: capMicros,
+	};
+	if (capMicros === null) return { slots: 1, dollarsMicros: null, capMicros: null, zeroRated: false };
+	const zero = allowedInvalid && (data.models ?? null) === null ? { zeroRated: false } : zeroRatedFor(job, { modelEndpoints, builtinModel });
+	return { slots: 1, dollarsMicros: zero.zeroRated ? 0 : capMicros, capMicros, zeroRated: zero.zeroRated === true };
+}

package/src/reserved-env.mjs

@@ -32,8 +32,16 @@ export const KEYLESS_ENV_NAME = "PI_DISPATCH_KEYLESS";
  * a variable added to the closed map and not to this list fails there rather than becoming a hole here.
  */
 export const CONTAINER_ENV_NAMES = new Set([
+	// Issue #730: the worker's choice of the readable runner node on the OpenShell venues (image/entrypoint.sh). Reserved,
+	// so neither `run.secrets` nor `PI_FORWARD_ENV` can make a job's key holders readable on any venue.
+	"PI_RUNNER_OBSERVABLE",
+	// Issue #693: derived from the resolved job memory, never chosen by a trigger or forwarded host value.
+	"PI_CODEMODE_MAX_WORKERS",
 	"PI_PROVIDER",
 	"PI_MODEL",
+	"PI_FORK_ENTRY",
+	"PI_FORK_POSITION",
+	"PI_THINKING_LEVEL",
 	"PI_MAX_TURNS",
 	"PI_MAX_TOKENS",
 	"PI_JOB_ID",
@@ -43,17 +51,44 @@ export const CONTAINER_ENV_NAMES = new Set([
 	"PI_FLOW",
 	"PI_COMMAND",
 	"PI_EXCLUDE_TOOLS",
-	"PI_AWAIT_INPUT",
+	// Issue #800: a trigger binding one through run.secrets could name what its own exclusions leave out, or stop a job.
+	"PI_EXCLUDE_EXTENSIONS",
+	"PI_EXCLUDE_EXTENSION_TOOLS",
+	"PI_EXCLUDE_TOOLS_STRICT",
+	"PI_AWAIT_INPUT", "PI_APPROVAL_GATES", "PI_APPROVAL_DECISION",
+	// Issue #644: a trigger binding it through run.secrets would offer itself a tool the operator did not arm.
+	"PI_REPORT_PROGRESS",
+	// Issue #645: a trigger binding either through run.secrets would arm checkpoints the operator did not, or make a fresh
+	// run believe it is a continuation and resume a checkpoint that is not its own.
+	"PI_RECOVER",
+	"PI_RECOVERING",
+	// Issue #646: a trigger binding it through run.secrets would tell the runner to watch an inbox the operator did not
+	// arm, on a run the worker never opened one for.
+	"PI_STEER",
+	// Issue #683: which file layout the runner reads. A trigger binding it through run.secrets would point the runner at
+	// a tree the worker never wrote, or, on a copying venue, back at /job, where nothing was uploaded.
+	"PI_JOB_LAYOUT",
 	"PI_MCP_SERVERS",
 	// Issues #501, #502: the per-job dollar cap (written by the worker since #501, from the trigger's and the
 	// deployment's caps) and the allowed-model list (reserved until #502 writes it). Neither can be bound through
 	// `run.secrets`: a trigger setting its own cap, or its own list, would be the policy choosing itself.
 	"PI_MAX_COST_MICROS",
 	"PI_ALLOWED_MODELS",
+	"PI_MODEL_ROLES_FILE",
+	"PI_AGENTS_FILE",
 	// Issue #545: tells the runner the exit line's key waits on stdin. A trigger setting it would block its own runner
 	// on a stdin no one writes, or turn the signed line off.
 	"PI_EXIT_AUTH",
+	// Issue #686: tells the runner to mirror its session file over stderr. A trigger setting it would send records no
+	// worker reads into the job log, or, with the image's key, stream a transcript the operator did not arm.
+	"PI_TRANSCRIPT",
+	// Issue #704 part 3: tells the runner to read a project secret bundle's plain variables from the job directory's
+	// bundle-env.json. A trigger setting it would make a runner refuse on a file nobody wrote, or read one it should not.
+	"PI_BUNDLE_ENV",
 	"PI_OFFLINE",
+	// Issue #796: names a canary's candidate. A trigger setting it would make a run report on a path nobody installed.
+	"PI_PACKAGE_CANARY",
+	"PI_SUBSCRIPTION_AUTH",
 	"PLAYWRIGHT_BROWSERS_PATH",
 	"PLAYWRIGHT_MCP_BROWSER",
 	"PLAYWRIGHT_MCP_SANDBOX",

package/src/retention.mjs

@@ -0,0 +1,67 @@
+/**
+ * How long the queue keeps a finished job, and how many runs the shared run index holds (issue #761). A LEAF with no
+ * imports: the worker, the receiver and the admin read the same values from here, so a value changed in one place
+ * cannot leave another reading the old one.
+ *
+ * `FORGE_JOB_RETENTION_*` is the dedup window of `REQ-DEDUP-BY-DELIVERY-GUID`: a forge job's id is the delivery's own
+ * id, and BullMQ's dedup is only "does the job key still exist", so the time a finished job is kept IS how long a
+ * redelivery is refused. 31 days is comfortably longer than any forge's redelivery window: GitHub documents "You can
+ * redeliver webhook deliveries that occurred in the past 3 days" and "GitHub does not automatically redeliver failed
+ * deliveries". Every marker that stands in for a job key once it is gone (a steered delivery's marker, the poller's
+ * cursor, the approval's finished mark, the console trail's claim) is derived from it, so shortening it shortens all of
+ * them together, and lengthening it cannot leave one of them shorter than the job it guards. So is the life of a finished
+ * job's model attempt key (`MODEL_ATTEMPT_FINISHED_TTL_MS`, below), which must outlive the finished job itself.
+ *
+ * BullMQ's `removeOnComplete.age` / `removeOnFail.age` are in SECONDS and a Valkey `PX` is in milliseconds, so both are
+ * exported and each site takes the one its call wants, never a conversion of its own.
+ */
+
+/** The forge job retention in days: the delivery dedup window (`REQ-DEDUP-BY-DELIVERY-GUID`). */
+export const FORGE_JOB_RETENTION_DAYS = 31;
+/** The same, in seconds: BullMQ's `removeOnComplete.age` / `removeOnFail.age`, a Valkey `EX`. */
+export const FORGE_JOB_RETENTION_S = FORGE_JOB_RETENTION_DAYS * 86_400;
+/** The same, in milliseconds: a Valkey `PX`, an age compared with `Date.now()`. */
+export const FORGE_JOB_RETENTION_MS = FORGE_JOB_RETENTION_S * 1000;
+
+/**
+ * How long a finished job's model attempt key is kept, in MILLISECONDS (the `PEXPIRE` of model-attempts.mjs, issue #812):
+ * a day past a forge job's retention, the longest age the queue keeps a finished job for, so the key outlives every
+ * finished job a console retry can still bring back to read it.
+ */
+export const MODEL_ATTEMPT_FINISHED_TTL_MS = FORGE_JOB_RETENTION_MS + 86_400_000;
+
+/**
+ * A local or cron job's retention, in seconds. Local jobs are not redelivered, so their window only has to cover a
+ * repeated `pi-dispatch run` and the console's re-run, not a forge's redelivery. Named here so the console can say how
+ * long a re-run's data is kept by the same values the queue uses.
+ */
+export const LOCAL_JOB_KEPT_COMPLETED_S = 24 * 3600;
+export const LOCAL_JOB_KEPT_FAILED_S = 7 * 24 * 3600;
+
+/**
+ * The shared run index's member cap (`PI_RUN_MIRROR_MAX_RUNS`). Every writer trims the index to its OWN cap, so in a
+ * fleet the lowest setting wins, and each trim raises the horizon, so a reader sees a cut rather than idle time.
+ * The floor is the console's widest read (1,000 runs): a smaller index would cut that read short. The ceiling bounds the
+ * portfolio snapshot's single read of the whole index.
+ */
+export const RUN_MIRROR_MAX_RUNS_DEFAULT = 5_000;
+export const RUN_MIRROR_MAX_RUNS_MIN = 1_000;
+export const RUN_MIRROR_MAX_RUNS_MAX = 20_000;
+
+/**
+ * `PI_RUN_MIRROR_MAX_RUNS` read leniently, for a reader that must not throw (the admin's paths): unset or empty is the
+ * default; a value outside the bounds, or not a plain integer, is the default with `problem` naming why. The worker
+ * reads the same key strictly (`config.mjs`) and refuses to start on a bad value, so a lenient reader only ever meets
+ * one the worker already refused.
+ */
+export function runMirrorMaxRunsOf(raw) {
+	if (raw === undefined || raw === null || raw === "") return { value: RUN_MIRROR_MAX_RUNS_DEFAULT };
+	// The worker's own rule (`boundedInt`): a plain integer as written, so "05000" or "1e4" is refused there and the
+	// default here, never two answers to one value.
+	const text = String(raw).trim();
+	const n = /^\d+$/.test(text) ? Number(text) : Number.NaN;
+	if (!Number.isSafeInteger(n) || String(n) !== text || n < RUN_MIRROR_MAX_RUNS_MIN || n > RUN_MIRROR_MAX_RUNS_MAX) {
+		return { value: RUN_MIRROR_MAX_RUNS_DEFAULT, problem: `not an integer ${RUN_MIRROR_MAX_RUNS_MIN}-${RUN_MIRROR_MAX_RUNS_MAX}` };
+	}
+	return { value: n };
+}