@edgehero/pi-dispatch 2.0.0 → 3.0.0

package/src/pi-model-loader.mjs

@@ -0,0 +1,77 @@
+/**
+ * pi's own model loader, from the pi-coding-agent installed beside the worker, for `doctor` (issue #502's open
+ * question: can the worker's view of the overlay `models.json` disagree with pi's?).
+ *
+ * THE CHOICE, and why. The issue suggests running pi's loader in the job image. Doctor does run that image already,
+ * for the egress canary, but a probe that mounts the operator's overlay into it needs the canary's venue, job-user and
+ * SELinux handling, and every doctor run would pay a container start for it. The worker and the job image are built
+ * from one lockfile, so the pi-coding-agent that a checkout of this repository installs at the workspace root after
+ * `npm ci` is the pi the image carries, and doctor asks that one, in-process. Its version is named on doctor's line.
+ * Where it is not installed (a worker installed on its own: the worker package depends on pi-ai only), doctor says
+ * the comparison was not made rather than guessing. And only the PINNED pi counts (PR #551's review): an `npm i -g`
+ * layout resolves whatever pi-coding-agent sits beside the worker, a global pi CLI of any version, so the loader
+ * reports the worker's pinned pi-ai (its exact dependency; pi-ai and pi-coding-agent are released in lockstep, and a
+ * test holds this pin equal to the runner's pi-coding-agent pin, which is the image's) and doctor compares nothing
+ * when the pi-coding-agent version differs from it.
+ *
+ * Its own module because it is the one place doctor's code must touch `process.env`: pi reads `PI_OFFLINE` from the
+ * process environment, and the runtime is created with it set so asking about models can never reach the network.
+ * It is restored straight after.
+ *
+ * NOTHING ON DISK (PR #551's review, round 2). The runtime is handed an in-memory credential store and an in-memory
+ * models store. With pi's file-backed defaults it wrote an `auth.json` into a temporary directory, and pi's file
+ * backend creates the parent directory before it writes, so a write landing after the cleanup brought the directory
+ * back (17 were found in a TMPDIR); the default models store would also have written `models-store.json` beside the
+ * operator's overlay file. Neither store holds anything the question needs: composition reads the config only.
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * `{ version, pinned, read(path) }`, or null when pi-coding-agent cannot be resolved from here. `version` is the
+ * resolved pi-coding-agent's, `pinned` the worker package's exact `@earendil-works/pi-ai` dependency. `read` answers
+ * `{ loads, has(provider, id) }`: `loads` is `ModelConfig.load(path).getError() === undefined`, and `has` asks a
+ * `ModelRuntime` created over the file (pi's provider composition included) for the model, with in-memory credential
+ * and models stores, so nothing is read from or written to disk beyond the file itself.
+ */
+export async function loadPiModelLoader({ resolveEntry = (name) => import.meta.resolve(name), workerPackage = new URL("../package.json", import.meta.url) } = {}) {
+	let ModelConfig;
+	let ModelRuntime;
+	let AuthStorage;
+	let InMemoryCodingAgentModelsStore;
+	let version;
+	let pinned = null;
+	try {
+		pinned = JSON.parse(readFileSync(workerPackage, "utf8"))?.dependencies?.["@earendil-works/pi-ai"] ?? null;
+	} catch {
+		// No pin to compare against: doctor then says it cannot tell, rather than comparing with any pi.
+	}
+	try {
+		const entry = resolveEntry("@earendil-works/pi-coding-agent");
+		({ ModelConfig } = await import(new URL("core/model-config.js", entry).href));
+		({ ModelRuntime } = await import(new URL("core/model-runtime.js", entry).href));
+		({ AuthStorage } = await import(new URL("core/auth-storage.js", entry).href));
+		({ InMemoryCodingAgentModelsStore } = await import(new URL("core/models-store.js", entry).href));
+		version = JSON.parse(readFileSync(new URL("../package.json", entry), "utf8")).version;
+	} catch {
+		return null;
+	}
+	return {
+		version,
+		pinned,
+		async read(path) {
+			const config = await ModelConfig.load(path);
+			const loads = config.getError() === undefined;
+			// env-internal PI_OFFLINE: pi's own switch, set here so asking pi about models never reaches the network.
+			const offline = process.env.PI_OFFLINE;
+			process.env.PI_OFFLINE = "1";
+			try {
+				const runtime = await ModelRuntime.create({ modelsPath: path, credentials: AuthStorage.inMemory(), modelsStore: new InMemoryCodingAgentModelsStore(), refreshOnCreate: false });
+				return { loads, has: (provider, id) => runtime.getModel(provider, id) !== undefined };
+			} finally {
+				if (offline === undefined) delete process.env.PI_OFFLINE;
+				else process.env.PI_OFFLINE = offline;
+			}
+		},
+	};
+}

package/src/podman-stack.mjs

@@ -26,6 +26,7 @@ import { execFileSync } from "node:child_process";
 import { connect as netConnect } from "node:net";
 import { dirname, join } from "node:path";
 import { DEFAULT_EGRESS_PROXY, egressProxyName } from "./egress.mjs";
+import { MODEL_ENDPOINTS_INCLUDE_NAME } from "./model-endpoints.mjs";
 import { VALKEY_PASSWORD_KEY, valkeyEnvFileText } from "./valkey-auth.mjs";
 import { SYSTEMD_HAZARD_SHAPES, decodeEnvFile, envFileHazard, envFileSystemdHazard, envFileValueLines, invisibleCharacter, quotedRegions, readEnvAssignments } from "./env-file.mjs";
 import { NETNS_KEEPER, NETNS_KEEPER_FORMAT, NETNS_KEEPER_NOW_FORMAT, STARTED_AT_FORMAT, NETNS_KEEPER_MIN_AGE_MS, NETNS_KEEPER_AFTER_PROXY_GRACE_MS, judgeNetnsKeeper, podmanNeedsNetnsKeeper, makeDetachGate, detachBlockedSentence, DETACH_GATE_READ_TIMEOUT_MS, DETACH_GATE_READ_MAX_BUFFER, runtimeFromFacts } from "./netns-keeper.mjs";
@@ -89,9 +90,17 @@ export const QUADLET_FILES = Object.freeze({
 /** Every Quadlet file this project ships, for uninstall and status, which act on what exists rather than on a plan. */
 export const ALL_QUADLET_FILES = Object.freeze(Object.values(QUADLET_FILES));
 
-/** The two placeholders the proxy's template carries, and what each becomes (TEMPLATE_PINS in service.mjs pins both). */
+/** The three placeholders the proxy's template carries, and what each becomes (TEMPLATE_PINS in service.mjs pins them). */
 export const PROXY_CONF_PLACEHOLDER = "/opt/pi-dispatch/deploy/egress-proxy.conf";
 export const ALLOWLIST_PLACEHOLDER = "/opt/pi-dispatch/egress-allowlist.conf";
+/**
+ * The declared model endpoints' rules (issue #503): the deployment folder's own `model-endpoints.conf`, mounted
+ * directly as the allowlist is, never copied like the rules are. `pi-dispatch egress render` rewrites that file in
+ * place and the proxy's reload reads the mounted inode, so a copy here would be a file the render never wrote. The
+ * rules are copied only because `z` cannot relabel a root-owned package file; this one is the operator's, as the
+ * allowlist is.
+ */
+export const MODEL_ENDPOINTS_PLACEHOLDER = "/opt/pi-dispatch/model-endpoints.conf";
 
 /**
  * Where the proxy's RULES are mounted from: an account-owned COPY of the package's `egress-proxy.conf`, never the
@@ -691,8 +700,9 @@ export function planStack({ components, templatesDir, deployDir, home, fs, readT
 	if (components.keeper) picked.push(QUADLET_FILES.keeperNetwork, QUADLET_FILES.keeper);
 	const conf = proxyConfCopyPath(home);
 	const allowlist = join(deployDir, "egress-allowlist.conf");
+	const endpointsInclude = join(deployDir, MODEL_ENDPOINTS_INCLUDE_NAME);
 	if (components.proxy) {
-		for (const p of [conf, allowlist]) {
+		for (const p of [conf, allowlist, endpointsInclude]) {
 			if (UNSAFE_VOLUME_PATH.test(p)) {
 				return { error: `the egress proxy's Quadlet unit would mount ${JSON.stringify(p)}, and a Quadlet Volume= cannot carry a colon, whitespace, %, $, a quote, a backslash or a control byte in a path (each is split or expanded on the way to podman run). Move the deployment folder, or start the proxy by hand (docs/podman.md)` };
 			}
@@ -702,7 +712,10 @@ export function planStack({ components, templatesDir, deployDir, home, fs, readT
 		let text = String(readTemplate(file));
 		if (file === QUADLET_FILES.proxy.file) {
 			// Function replacements: a computed path is the REPLACEMENT, and String.replace reads `$&` out of a string one.
-			text = text.replace(`Volume=${PROXY_CONF_PLACEHOLDER}:`, () => `Volume=${conf}:`).replace(`Volume=${ALLOWLIST_PLACEHOLDER}:`, () => `Volume=${allowlist}:`);
+			text = text
+				.replace(`Volume=${PROXY_CONF_PLACEHOLDER}:`, () => `Volume=${conf}:`)
+				.replace(`Volume=${ALLOWLIST_PLACEHOLDER}:`, () => `Volume=${allowlist}:`)
+				.replace(`Volume=${MODEL_ENDPOINTS_PLACEHOLDER}:`, () => `Volume=${endpointsInclude}:`);
 		}
 		if (file === QUADLET_FILES.valkey.file && Number.isInteger(components.valkeyPort) && components.valkeyPort !== DEFAULT_VALKEY_PORT) {
 			// Issue #464: VALKEY_URL's loopback port, where this account's own Valkey is published (the container still

package/src/portfolio-snapshot.mjs

@@ -0,0 +1,304 @@
+/**
+ * The portfolio snapshot, `/job/portfolio.json` (issue #505, INT-CONTAINER-JOB-INPUTS): what a flagged cron job's agent
+ * reads to write a priorities plan (INT-PRIORITIES-PLAN-CONTRACT). A job container is queue-blind on purpose
+ * (DES-JOB-OUTBOX-CHAINING), so the facts a project manager needs are written into its read-only `/job` instead: the
+ * envelope's numbers, the applied split, what each project has spent in the window, and how its runs went.
+ *
+ * THE CONTENT RULE, and why it is strict. The agent reads this file as facts. So it holds ids, digests, integers, ISO
+ * instants and fixed enum tokens only, plus two kinds of operator configuration: project ids and a member's label
+ * (`github:acme/web` as projects.json stores it, or `local:<basename>` for a folder, the `targetFor` rule), and a label
+ * holding a control, format, bidi or unassigned character is replaced by the member's ref. It holds no
+ * issue text, no title, no task, no plan `reason` and no path: each is text an agent or a forge user wrote, and the next
+ * manager run would read it as if it were a fact. Every value is rebuilt here from named fields, charset-checked, and
+ * nothing is spread from a record, a state or a row.
+ *
+ * Money is integer micro-dollars, from the FLEET-WIDE counters (the `budget:usd:s:*` keys every host reserves and
+ * settles in), so the numbers are complete on every host. A counter holds what was spent AND what running jobs still
+ * hold: that is the number the next job is admitted against, so it is the one a manager should plan with. Run counts
+ * come from the local run history merged with the Valkey run mirror; without a mirror (no `PI_WORKER_NAME`) they are
+ * this host's alone, and `fleet.runsComplete` says so.
+ */
+
+import * as nodeFs from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { AUDIT_OUTCOMES, STATE_WRITERS, memberDollarKeyPrefix } from "./allocation.mjs";
+import { dayKey, monthKey, weekKey } from "./budget.mjs";
+import { OTHER, PLAN_FIELDS, PLAN_RULES, envelopeEntries, scopeRef } from "./priorities.mjs";
+import { InfraRetry } from "./processor.mjs";
+import { isProjectId } from "./project-id.mjs";
+import { RUNS_INDEX_MAX, mergeRuns, readMirroredRuns } from "./run-mirror.mjs";
+import { scopeDollarKeyPrefix } from "./scoped-limits.mjs";
+
+/** The snapshot's shape version. */
+export const PORTFOLIO_SNAPSHOT_VERSION = 1;
+/** The largest snapshot written, in bytes. Over it the job is refused before it spends. */
+export const PORTFOLIO_SNAPSHOT_MAX_BYTES = 64 * 1024;
+/** The refusal of a job whose snapshot would be larger than `PORTFOLIO_SNAPSHOT_MAX_BYTES`. */
+export const PORTFOLIO_SNAPSHOT_OVERSIZE = "portfolio-snapshot-oversize";
+/** How far back `runs7d` counts. */
+export const RUNS_WINDOW_DAYS = 7;
+/** The run outcomes `runs7d` counts. */
+export const RUN_OUTCOMES = Object.freeze(["completed", "policy", "failed"]);
+/** The `byReason` key a reason that is not a plain token is counted under: the token rule, never the text. */
+export const OTHER_REASON = "other";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const TOKEN_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const HEX16_RE = /^[0-9a-f]{16}$/;
+const INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+// What a label may not hold: every control, format character (the bidi controls included), surrogate, private-use or
+// unassigned code point, and the line and paragraph separators. Each can change what a reader sees.
+const LABEL_REFUSED = /[\p{Cc}\p{Cf}\p{Cs}\p{Co}\p{Cn}\p{Zl}\p{Zp}]/u;
+
+const asDate = (now) => (now instanceof Date ? now : new Date(now));
+const instant = (value) => (typeof value === "string" && INSTANT_RE.test(value) && Number.isFinite(Date.parse(value)) ? value : null);
+const micros = (value) => (Number.isSafeInteger(value) && value >= 0 ? value : null);
+const ymd = (ms) => new Date(ms).toISOString().slice(0, 10);
+
+/** The envelope window that holds `now`: `{ kind, start, end }`, `end` the first day after it (UTC dates). */
+export function windowBounds(kind, now) {
+	const d = asDate(now);
+	const day = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+	if (kind === "day") return { kind, start: ymd(day), end: ymd(day + DAY_MS) };
+	if (kind === "week") {
+		const monday = day - ((new Date(day).getUTCDay() + 6) % 7) * DAY_MS;
+		return { kind, start: ymd(monday), end: ymd(monday + 7 * DAY_MS) };
+	}
+	if (kind === "month") return { kind, start: ymd(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1)), end: ymd(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1)) };
+	throw new TypeError(`unknown envelope window: ${kind}`);
+}
+
+/** A counter key of `prefix` for the envelope window holding `now`, by budget.mjs's own key functions. */
+function windowKey(prefix, kind, now) {
+	return kind === "day" ? dayKey(now, prefix) : kind === "week" ? weekKey(now, prefix) : monthKey(now, prefix);
+}
+
+/** A counter's value as micro-dollars: absent is 0 (nothing reserved yet), anything that is no integer is 0. */
+function counterMicros(raw) {
+	if (raw === null || raw === undefined) return 0;
+	const n = Number(raw);
+	return Number.isSafeInteger(n) && n > 0 ? n : 0;
+}
+
+/**
+ * A member's label: a forge member as projects.json stores it, a folder as `local:<basename>` (never the path). A label
+ * holding a character `LABEL_REFUSED` names, or longer than 200 code points, is the member's ref instead.
+ */
+export function memberLabel(member) {
+	const label = isAbsolute(member) ? `local:${basename(member)}` : member;
+	return LABEL_REFUSED.test(label) || [...label].length > 200 ? scopeRef(member) : label;
+}
+
+/** An empty `runs7d`. */
+function emptyRuns() {
+	return { completed: 0, policy: 0, failed: 0, byReason: {} };
+}
+
+/** `byReason` with its keys sorted, so the bytes do not depend on the order runs were read in. */
+function sortedCounts(counts) {
+	return Object.fromEntries(Object.keys(counts).sort().map((k) => [k, counts[k]]));
+}
+
+/**
+ * Count runs by envelope entry: a record's `project` when the envelope names it, else `_other`. Only the three outcomes
+ * and a reason that is a plain token are read; a reason that is not one counts under `other`, so no text a record could
+ * carry (a planted title included) reaches the snapshot.
+ */
+function countRuns(records, entries, sinceMs) {
+	const out = Object.fromEntries(entries.map((id) => [id, emptyRuns()]));
+	for (const r of records) {
+		const at = Date.parse(r?.endedAt ?? r?.startedAt ?? "");
+		if (!Number.isFinite(at) || at < sinceMs) continue;
+		if (!RUN_OUTCOMES.includes(r?.outcome)) continue;
+		const id = isProjectId(r?.project) && r.project !== OTHER && entries.includes(r.project) ? r.project : OTHER;
+		const row = out[id];
+		row[r.outcome] += 1;
+		if (r.reason !== null && r.reason !== undefined) {
+			const key = typeof r.reason === "string" && TOKEN_RE.test(r.reason) ? r.reason : OTHER_REASON;
+			row.byReason[key] = (row.byReason[key] ?? 0) + 1;
+		}
+	}
+	for (const id of entries) out[id].byReason = sortedCounts(out[id].byReason);
+	return out;
+}
+
+/** The applied plan as the snapshot shows it, or null for the neutral split (then a plan's `basis` is null). */
+function planOf(state) {
+	if (typeof state?.planId !== "string" || !HEX16_RE.test(state.planId)) return null;
+	return {
+		id: state.planId,
+		writer: STATE_WRITERS.includes(state.writer) ? state.writer : null,
+		appliedAt: instant(state.appliedAt),
+		validUntil: instant(state.validUntil),
+		clamped: state.clamped === true,
+	};
+}
+
+/** The last attempt of this trigger's portfolio jobs, from an `alloc:log` row: enum tokens and an id only. */
+function lastAttemptOf(row) {
+	if (!row || typeof row !== "object") return null;
+	const out = {
+		at: instant(row.at),
+		outcome: AUDIT_OUTCOMES.includes(row.outcome) ? row.outcome : null,
+		reason: typeof row.reason === "string" && TOKEN_RE.test(row.reason) ? row.reason : null,
+		planId: typeof row.planId === "string" && HEX16_RE.test(row.planId) ? row.planId : null,
+	};
+	if (PLAN_FIELDS.includes(row.field)) {
+		out.field = row.field;
+		out.rule = PLAN_RULES.includes(row.rule) ? row.rule : null;
+	}
+	return out;
+}
+
+/** When the next plan may apply: the last plan plus the interval, or null when no writer's plan has applied. */
+function planAllowedAfter(state, envelope) {
+	const last = Date.parse(state?.lastPlanAt ?? "");
+	const hours = envelope?.delegation?.minIntervalHours;
+	if (!Number.isFinite(last) || !Number.isInteger(hours)) return null;
+	return new Date(last + hours * 60 * 60 * 1000).toISOString();
+}
+
+/**
+ * Build the snapshot object. `envelope` and `digest` are this host's (envelope.mjs), `projects` the parsed projects.json,
+ * `limits` the parsed scoped-limits.json (a member's spend is read from the key its matched row settles in,
+ * `memberDollarKeyPrefix`, the one enforcement uses),
+ * `allocation` `{ state, lastAttempt }` (the applied state `alloc:plan` and the newest `alloc:log` row of this trigger's
+ * portfolio jobs), `redis` the client the counters are read from (one MGET), `runs` `{ records, complete }` (the merged
+ * history) and `now` the clock. Throws on a Valkey fault; the caller turns that into an InfraRetry.
+ */
+export async function buildPortfolioSnapshot({ envelope, digest, projects = [], limits = null, allocation = {}, redis, runs = { records: [], complete: false }, now }) {
+	const at = asDate(now);
+	const state = allocation.state ?? null;
+	const kind = envelope.window;
+	const entries = envelopeEntries(envelope);
+	const byId = new Map((Array.isArray(projects) ? projects : []).filter((p) => isProjectId(p?.id)).map((p) => [p.id, p]));
+
+	// Every counter in ONE read: each entry's project key, then each member that has a repo share.
+	const keys = [];
+	const rows = entries.map((id) => {
+		const projectKey = keys.push(windowKey(scopeDollarKeyPrefix(`project:${id}`), kind, at)) - 1;
+		const members = id === OTHER ? [] : (byId.get(id)?.members ?? []).filter((m) => typeof m === "string" && m !== "");
+		const memberRows = members
+			.map((m) => {
+				const ref = scopeRef(m);
+				const weight = state?.repoWeights?.[id]?.[ref];
+				return { ref, label: memberLabel(m), weight: Number.isInteger(weight) ? weight : null, allocation: micros(state?.repos?.[id]?.[ref]), key: Number.isInteger(weight) ? keys.push(windowKey(memberDollarKeyPrefix(m, { limits }), kind, at)) - 1 : null };
+			})
+			.sort((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
+		return { id, projectKey, memberRows };
+	});
+	const values = keys.length > 0 ? await redis.mget(...keys) : [];
+	const counted = countRuns(Array.isArray(runs.records) ? runs.records : [], entries, at.getTime() - RUNS_WINDOW_DAYS * DAY_MS);
+
+	return {
+		version: PORTFOLIO_SNAPSHOT_VERSION,
+		generatedAt: at.toISOString(),
+		window: windowBounds(kind, at),
+		envelope: {
+			digest: typeof digest === "string" && HEX16_RE.test(digest) ? digest : null,
+			totalMicros: envelope.totalMicros,
+			maxStepPct: envelope.delegation?.maxStepPct ?? null,
+			minIntervalHours: envelope.delegation?.minIntervalHours ?? null,
+			maxPlanDays: envelope.delegation?.maxPlanDays ?? null,
+			planAllowedAfter: planAllowedAfter(state, envelope),
+		},
+		plan: planOf(state),
+		lastAttempt: lastAttemptOf(allocation.lastAttempt),
+		projects: rows.map(({ id, projectKey, memberRows }) => ({
+			id,
+			floorMicros: envelope.floors[id],
+			weight: Number.isInteger(state?.weights?.[id]) ? state.weights[id] : envelope.defaultWeights[id],
+			allocationMicros: micros(state?.allocations?.[id]),
+			spentMicros: counterMicros(values[projectKey]),
+			members: memberRows.map((m) => ({ ref: m.ref, label: m.label, ...(m.weight === null ? {} : { weight: m.weight, allocationMicros: m.allocation, spentMicros: counterMicros(values[m.key]) }) })),
+			runs7d: counted[id],
+		})),
+		fleet: { runsComplete: runs.complete === true },
+	};
+}
+
+/**
+ * The run records of this host's history (`PI_LOGS_DIR/*.json`) that ended at or after `sinceMs`: `{ records, complete }`.
+ * A file older than the window by its mtime is not opened (a record is written when its run ends). Never throws: a
+ * missing directory is no runs, and any other fault reads as `complete: false`.
+ */
+export function readLocalRuns({ logsDir, sinceMs, fs = nodeFs }) {
+	let names;
+	try {
+		names = fs.readdirSync(logsDir);
+	} catch (error) {
+		return { records: [], complete: error?.code === "ENOENT" };
+	}
+	const records = [];
+	let complete = true;
+	for (const name of names) {
+		if (!name.endsWith(".json")) continue;
+		try {
+			const st = fs.statSync(join(logsDir, name));
+			if (!st.isFile() || st.mtimeMs < sinceMs) continue;
+			const rec = JSON.parse(fs.readFileSync(join(logsDir, name), "utf8"));
+			if (rec && typeof rec === "object" && typeof rec.jobId === "string") records.push(rec);
+		} catch (error) {
+			// A record reaped between the listing and the read is simply gone; anything else leaves the count short.
+			if (error?.code !== "ENOENT") complete = false;
+		}
+	}
+	return { records, complete };
+}
+
+/**
+ * The prepare-time builder the wiring hands `prepareLocalWorkspace` (through `makePrepareWorkspace`), as
+ * `(job) => null | { body } | { outcome: "policy", reason }`. Called only for a job the processor confirmed as a
+ * portfolio job at pickup, and it confirms again here: the LIVE triggers file must still flag the job's entry
+ * (`checkPortfolioFlag`), else nothing is written and null comes back. Null too when this host has no envelope any more:
+ * the plan would be refused as `delegation-off`, so there is nothing true to show.
+ *
+ * Every Valkey read (the reconcile, `alloc:log`, the counters) that fails throws InfraRetry: the job has not reserved
+ * anything yet, so it is retried rather than run on a snapshot with holes. The run mirror is a view and never throws; a
+ * mirror that could not be read makes `runsComplete` false. A snapshot over 64 KiB is refused as
+ * `portfolio-snapshot-oversize`, before any spend, and the log line names the project count.
+ */
+export function makePortfolioSnapshot({ checkPortfolioFlag, governing, projects = () => [], limits = () => null, allocation, redis, logsDir, mirror = false, readMirror = readMirroredRuns, fs = nodeFs, now = () => new Date(), log = () => {} }) {
+	return async function portfolioSnapshot(job) {
+		const flagged = await Promise.resolve()
+			.then(() => checkPortfolioFlag(job))
+			.catch(() => false);
+		if (flagged !== true) {
+			log("portfolio_snapshot_skipped", { why: "flag-not-live" });
+			return null;
+		}
+		const g = governing?.() ?? null;
+		if (!g?.envelope) {
+			log("portfolio_snapshot_skipped", { why: "no-envelope" });
+			return null;
+		}
+		const at = now();
+		const sinceMs = at.getTime() - RUNS_WINDOW_DAYS * DAY_MS;
+		let snapshot;
+		try {
+			const { state } = await allocation.reconcile({ envelope: g.envelope, digest: g.digest, now: at });
+			if (!state) throw new Error("the applied state was written by a newer build");
+			const last = await allocation.lastAttempt({ kind: "portfolio-job", triggerId: job?.trigger?.id });
+			const local = readLocalRuns({ logsDir, sinceMs, fs });
+			let mirrored = [];
+			let complete = false;
+			if (mirror) {
+				const read = await readMirror(redis, { limit: RUNS_INDEX_MAX, sinceMs, now: () => at.getTime() });
+				mirrored = read.runs;
+				complete = local.complete && (read.degraded === "ok" || read.degraded === "off");
+			}
+			const records = mergeRuns(local.records, mirrored, { limit: Number.POSITIVE_INFINITY });
+			snapshot = await buildPortfolioSnapshot({ envelope: g.envelope, digest: g.digest, projects: projects(), limits: limits(), allocation: { state, lastAttempt: last }, redis, runs: { records, complete }, now: at });
+		} catch (error) {
+			log("portfolio_snapshot_failed", { code: typeof error?.code === "string" ? error.code : "error" });
+			throw new InfraRetry("the portfolio snapshot could not be read", { cause: error });
+		}
+		const body = JSON.stringify(snapshot, null, 2);
+		const bytes = Buffer.byteLength(body, "utf8");
+		if (bytes > PORTFOLIO_SNAPSHOT_MAX_BYTES) {
+			log("refused_portfolio_snapshot_oversize", { projects: snapshot.projects.length, bytes, max: PORTFOLIO_SNAPSHOT_MAX_BYTES });
+			return { outcome: "policy", reason: PORTFOLIO_SNAPSHOT_OVERSIZE };
+		}
+		return { body };
+	};
+}