@edgehero/pi-dispatch 2.1.0 → 3.1.0

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 };
+	};
+}

package/src/prepare-local.mjs

@@ -1,7 +1,8 @@
 import { GIT_READ_FLAGS } from "./git-hardening.mjs";
 import { execFile } from "node:child_process";
 import * as realFs from "node:fs";
-import { basename, join } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { envelopeProtectedIdentities, fileIdentity } from "./envelope.mjs";
 import { promisify } from "node:util";
 import { materializePiDir } from "./materialize.mjs";
 import { InfraRetry } from "./processor.mjs";
@@ -9,6 +10,22 @@ import { isDeterminateFsCode } from "./transient.mjs";
 
 const exec = promisify(execFile);
 
+/** The run-record reason for a local job whose folder has no `.git` at its root (issue #524). */
+export const LOCAL_FOLDER_NOT_A_REPO = "local-folder-not-a-repo";
+/** The run-record reason for a local job whose repository has no commit at HEAD yet (issue #524). */
+export const LOCAL_FOLDER_NO_COMMIT = "local-folder-no-commit";
+/** The run-record reason for a local job whose repository git cannot resolve HEAD in, other than an unborn HEAD (issue #524). */
+export const LOCAL_FOLDER_UNREADABLE_REPO = "local-folder-unreadable-repo";
+/**
+ * The run-record reason for a local job whose folder is NAMED inside a job path (a `PI_DISPATCH_RUN_ROOTS` root or a cron
+ * trigger's `run.folder`) and RESOLVES, at prepare, to a directory outside it (issue #504 part B). A job container can
+ * write inside its own folder, so it can swap a link below a job path after the folder was checked; such a folder is
+ * refused rather than mounted wherever the link now points.
+ */
+export const LOCAL_FOLDER_ESCAPED = "local-folder-escaped";
+/** The run-record reason for a local job whose resolved folder is the envelope's folder or a directory above it (issue #504 part B). */
+export const LOCAL_FOLDER_HOLDS_ENVELOPE = "local-folder-holds-envelope";
+
 /**
  * Prepare a LOCAL-FOLDER job. This is the zero-GitHub path: no token, no clone, no PR. The folder
  * on the operator's own machine becomes /workspace (bind-mounted read-write), edited in place.
@@ -27,11 +44,62 @@ const exec = promisify(execFile);
  * default keeps a directly-constructed call (tests, older wiring) honest: a job with no derived
  * context is a manual run.
  */
-export async function prepareLocalWorkspace({ folder, task, jobDir, git = defaultGit, event = { source: "manual" }, fs = realFs }) {
-	requirePath(fs, folder, `local folder does not exist: ${folder}`, "the local folder");
-	requirePath(fs, join(folder, ".git"), `local folder is not a git repository (v1 requires one): ${folder}`, "the local folder's .git");
+export async function prepareLocalWorkspace({ folder: named, task, jobDir, git = defaultGit, event = { source: "manual" }, fs = realFs, jobPaths = null, envelopeFile = null, portfolio = null }) {
+	requirePath(fs, named, `local folder does not exist: ${named}`, "the local folder");
+	// Issue #504 part B: the folder is RESOLVED here, once, and the resolved path is the one everything below reads and the
+	// one the container mounts (`workspace`). The raw string was mounted before, so a link below a job path swapped after
+	// the folder was checked (by the admin's run-root check at enqueue, or by nothing at all for a chained child) would
+	// have mounted whatever it pointed to, read-write. Resolving narrows the window to the moments between this line and
+	// the container start, and the two checks below judge the folder that will be mounted. Residual, named: a link above
+	// the resolved folder swapped inside that window is followed by the runtime when it mounts.
+	const folder = resolveFolder(fs, named);
+	const placement = judgePlacement(fs, named, folder, { jobPaths: typeof jobPaths === "function" ? jobPaths() : jobPaths, envelopeFile });
+	if (placement) return { outcome: "policy", reason: placement };
+	// Issue #524: a folder that is not a repository is its own determinate refusal, RETURNED with its own reason
+	// (CONST-RETRY-INFRA-ONLY), not a config throw. As a throw it reached the processor's config arm, which can only
+	// say "this deployment is misconfigured" (`config-refused`), about a folder the operator can fix with `git init`.
+	// Returned here it is a prepare-stage policy refusal like `sha-gone`: before the budget reserve, so it spends
+	// nothing, and `prepare.mjs` removes the job dir it made. The reason is a fixed token and carries no path, so the
+	// worker log and the run record stay as PII-free as they are. `pi-dispatch run` refuses the same folder before
+	// queueing; this is the check for a folder that stopped being a repository between queue and pickup, and for a
+	// cron trigger's folder, which nothing checks when it fires.
+	if (!presentAt(fs, join(folder, ".git"), "the local folder's .git")) return { outcome: "policy", reason: LOCAL_FOLDER_NOT_A_REPO };
 
-	const sha = (await git(folder, ["rev-parse", "HEAD"])).trim();
+	// Issue #524: a HEAD git cannot resolve escaped as an untagged throw, a failed job with no reason. It is now
+	// refused by name, RETURNED before the reserve and before anything is written, like the not-a-repo one above,
+	// but only once the files git needs have been read back under `presentAt`'s rule (PR #528's review, round 2).
+	// git's exit code says "could not", never "why": `rev-parse --verify --quiet` exits 1 for an unborn HEAD AND for
+	// a missing commit object, a garbage branch ref, an unreadable `refs/heads`; it exits 128 for an empty `.git`
+	// AND for an EACCES on `.git/HEAD` or `.git/objects`, with the same "not a git repository" either way (all
+	// measured, git 2.x). Its text is no help either: a locale translates it, and it names host paths.
+	//   - `local-folder-no-commit` only for a truly unborn HEAD: the follow-up `rev-parse --verify --quiet HEAD`
+	//     also exits 1 AND `symbolic-ref -q HEAD` succeeds (HEAD names a branch that does not exist yet). A HEAD
+	//     that resolves to a missing object or a non-commit, or a branch ref that cannot be read, is not "commit
+	//     once" and must not be told so.
+	//   - `local-folder-unreadable-repo` for every other 1 or 128.
+	// Before either refusal, `assertGitFilesReadable` reads what git needed. An error outside the determinate
+	// allow-list (`transient.mjs`: EACCES and EIO are deliberately transient) throws InfraRetry, so a filesystem
+	// that cannot answer right now is retried rather than refused for good. Any other git failure (a missing git
+	// binary, a signal) still throws as it did.
+	let sha;
+	try {
+		sha = (await git(folder, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"])).trim();
+	} catch (error) {
+		if (error?.code !== 1 && error?.code !== 128) throw error;
+		assertGitFilesReadable(fs, folder);
+		if (error.code === 1 && (await unbornHead(git, folder))) return { outcome: "policy", reason: LOCAL_FOLDER_NO_COMMIT };
+		return { outcome: "policy", reason: LOCAL_FOLDER_UNREADABLE_REPO };
+	}
+
+	// Issue #505: a confirmed portfolio job's snapshot, built BEFORE anything is written, so a refusal
+	// (`portfolio-snapshot-oversize`) or an InfraRetry (Valkey) leaves nothing behind but the directory prepare.mjs removes.
+	// Null from the builder means the live file no longer flags the job (or this host lost its envelope): no snapshot, and
+	// the job runs as an ordinary cron job.
+	let snapshot = null;
+	if (typeof portfolio === "function") {
+		snapshot = await portfolio();
+		if (snapshot?.outcome === "policy") return snapshot;
+	}
 
 	fs.mkdirSync(jobDir, { recursive: true });
 	// The outbox is the container's only signal channel back to the worker (INT-OUTBOX-CONTRACT). It is
@@ -57,14 +125,108 @@ export async function prepareLocalWorkspace({ folder, task, jobDir, git = defaul
 	const eventBody = {
 		source: event.source,
 		...(event.trigger ? { trigger: event.trigger } : {}),
-		folder: basename(folder),
+		folder: basename(named),
 		sha,
 		...(event.source === "cron" ? { scheduledFor: event.scheduledFor ?? null, previousRunAt: event.previousRunAt ?? null } : {}),
 	};
 	fs.writeFileSync(join(jobDir, "event.json"), JSON.stringify(eventBody, null, 2), { mode: 0o444 });
+	// /job/portfolio.json (INT-CONTAINER-JOB-INPUTS), 0o444 beside event.json, so it reaches the container on the existing
+	// read-only /job mount with no new mount. Its presence is also what composes the portfolio persona in the runner.
+	if (typeof snapshot?.body === "string") fs.writeFileSync(join(jobDir, "portfolio.json"), snapshot.body, { mode: 0o444 });
 
 	// The folder itself is /workspace (rw). No clone: local jobs edit in place.
-	return { workspace: folder, jobDir, outboxDir, sha, materialised: written };
+	// `portfolio: true` only when the snapshot was written (issue #505): the plan collector requires prepare to have
+	// agreed, beside the pickup and the live file at collection, so a job that ran without the facts writes no plan.
+	return { workspace: folder, jobDir, outboxDir, sha, materialised: written, ...(typeof snapshot?.body === "string" ? { portfolio: true } : {}) };
+}
+
+/**
+ * The folder's real path (`realpathSync.native`). A determinate absence here (the folder vanished, or a link in it now
+ * dangles) is the "does not exist" config refusal `requirePath` gives; any other error is retried, `presentAt`'s rule.
+ */
+function resolveFolder(fs, named) {
+	try {
+		return (fs.realpathSync?.native ?? fs.realpathSync)(named);
+	} catch (error) {
+		if (isDeterminateFsCode(error?.code)) {
+			const refusal = new Error(`local folder does not exist: ${named}`);
+			refusal.piDispatchConfig = true;
+			throw refusal;
+		}
+		throw new InfraRetry(`could not resolve the local folder (${error?.code ?? "unknown"}): ${basename(named)}`);
+	}
+}
+
+/** `p` is `root` or lies below it, as text. Both absolute and resolved. */
+function insideOrEqual(p, root) {
+	return p === root || p.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+
+/** The identity of a path (`dev:ino`, links followed), or null when it cannot be read. */
+function identityAt(fs, path) {
+	try {
+		return fileIdentity(fs.statSync(path, { bigint: true }));
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Where the RESOLVED folder may be mounted from (issue #504 part B), or the refusal reason:
+ *   - `local-folder-escaped`: the folder is named inside a job path (its text, or its text against a job path's real
+ *     path, lies inside a run root or a cron folder, or an ancestor of its text has a job path's identity) and its
+ *     resolved path lies inside none of those job paths, judged
+ *     by identity up the resolved path, so a firmlink or a case variant is the directory it names. A job path is a
+ *     place a job can write; a link a job planted there must not carry another job's folder out of it. A folder named
+ *     outside every job path (an operator's own `pi-dispatch run`) is not held to them, since nothing there is a job's;
+ *   - `local-folder-holds-envelope`: the resolved folder is the envelope file's folder or a directory above it
+ *     (`envelopeProtectedIdentities`), so the job could write its own bounds.
+ * `jobPaths` is `{ runRoots, cronFolders }` (schedules.mjs `envelopeJobPaths`), or null for none.
+ */
+function judgePlacement(fs, named, folder, { jobPaths, envelopeFile }) {
+	const real = (p) => {
+		try {
+			return (fs.realpathSync?.native ?? fs.realpathSync)(p);
+		} catch {
+			return null;
+		}
+	};
+	const areas = [...(jobPaths?.runRoots ?? []), ...(jobPaths?.cronFolders ?? [])].filter((p) => typeof p === "string" && p.trim() !== "" && isAbsolute(p));
+	const text = resolve(named);
+	// The identities of the named path's own ancestors, walked up its TEXT (each stat follows links, as the kernel does):
+	// "named inside" is decided by identity too, so a case variant of a run root on a case-insensitive volume, or a
+	// firmlink spelling of it, is inside it, where a string comparison let it skip the check (PR #574's review).
+	const namedAncestors = new Set();
+	for (let p = text; areas.length > 0; p = dirname(p)) {
+		const id = identityAt(fs, p);
+		if (id !== null) namedAncestors.add(id);
+		if (dirname(p) === p) break;
+	}
+	const holding = areas.filter((area) => {
+		const r = real(area);
+		if (insideOrEqual(text, resolve(area)) || (r !== null && insideOrEqual(text, r))) return true;
+		const id = identityAt(fs, area);
+		return id !== null && namedAncestors.has(id);
+	});
+	if (holding.length > 0) {
+		const ids = new Set(holding.map((area) => identityAt(fs, area)).filter((id) => id !== null));
+		let inside = false;
+		for (let p = folder; ; p = dirname(p)) {
+			const id = identityAt(fs, p);
+			if (id !== null && ids.has(id)) {
+				inside = true;
+				break;
+			}
+			if (dirname(p) === p) break;
+		}
+		if (!inside) return LOCAL_FOLDER_ESCAPED;
+	}
+	if (envelopeFile !== null && envelopeFile !== undefined) {
+		const protectedIds = envelopeProtectedIdentities(envelopeFile, { realpathSync: fs.realpathSync?.native ?? fs.realpathSync, statSync: fs.statSync });
+		const id = identityAt(fs, folder);
+		if (id !== null && protectedIds.has(id)) return LOCAL_FOLDER_HOLDS_ENVELOPE;
+	}
+	return null;
 }
 
 /**
@@ -82,14 +244,23 @@ export async function prepareLocalWorkspace({ folder, task, jobDir, git = defaul
  * `.git` is a FILE in a worktree and in a submodule, and a symlinked project folder is ordinary.
  */
 function requirePath(fs, path, absentMessage, what) {
+	if (presentAt(fs, path, what)) return;
+	const refusal = new Error(absentMessage);
+	refusal.piDispatchConfig = true;
+	throw refusal;
+}
+
+/**
+ * True when something is at `path`, false when it is determinately absent, and a THROWN InfraRetry when the
+ * filesystem could not answer. The second half of `requirePath`, split out so the `.git` check can return its own
+ * refusal instead of throwing one, with the same rule about which errors mean absent (issue #316, below).
+ */
+function presentAt(fs, path, what) {
 	try {
 		fs.statSync(path);
+		return true;
 	} catch (error) {
-		if (isDeterminateFsCode(error?.code)) {
-			const refusal = new Error(absentMessage);
-			refusal.piDispatchConfig = true;
-			throw refusal;
-		}
+		if (isDeterminateFsCode(error?.code)) return false;
 		// Not absent, just unreachable right now. Throw the retryable class so the queue tries again
 		// instead of spending the delivery on a verdict that is wrong by the time it is posted.
 		// BASENAME, not the path (issue #289): an InfraRetry survives retries and its message becomes the
@@ -101,6 +272,70 @@ function requirePath(fs, path, absentMessage, what) {
 	}
 }
 
+/**
+ * True only for an unborn HEAD: one that names a branch with no commit yet (issue #524, PR #528's review). Both
+ * answers are git's exit codes. `rev-parse --verify --quiet HEAD` exits 0 when HEAD names SOME object, which after
+ * `HEAD^{commit}` failed means a missing or non-commit object; `symbolic-ref -q HEAD` fails for a detached HEAD and
+ * for a branch ref git cannot read (measured: a garbage ref and an EACCES `refs/heads` both exit 128 there).
+ */
+async function unbornHead(git, folder) {
+	try {
+		await git(folder, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+		return false;
+	} catch (error) {
+		if (error?.code !== 1) return false;
+	}
+	try {
+		await git(folder, ["symbolic-ref", "-q", "HEAD"]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Read back the files git needs to resolve HEAD, under `presentAt`'s rule: an absence the allow-list calls
+ * determinate is fine (the refusal stands), anything else throws InfraRetry so the job is retried (PR #528's review,
+ * round 2). `.git`; when it is a file (a worktree or submodule), the gitdir it names; `<gitdir>/HEAD`;
+ * `<gitdir>/config` when present; and the branch ref HEAD names, which is where an unreadable `refs/heads` shows.
+ * A ref that is absent is ordinary (an unborn branch, or one only in packed-refs). Messages carry basenames only.
+ */
+function assertGitFilesReadable(fs, folder) {
+	const dotGit = join(folder, ".git");
+	const st = statOrRetry(fs, dotGit);
+	if (!st) return;
+	let gitDir = dotGit;
+	if (st.isFile?.()) {
+		const pointer = readOrRetry(fs, dotGit);
+		const named = pointer === null ? null : /^gitdir:\s*(.+)$/m.exec(pointer)?.[1]?.trim();
+		if (!named) return;
+		gitDir = resolve(folder, named);
+		if (!statOrRetry(fs, gitDir)) return;
+	}
+	const head = readOrRetry(fs, join(gitDir, "HEAD"));
+	readOrRetry(fs, join(gitDir, "config"));
+	const ref = head === null ? null : /^ref:\s*(refs\/\S+)\s*$/m.exec(head)?.[1];
+	if (ref && !ref.split("/").includes("..")) readOrRetry(fs, join(gitDir, ref));
+}
+
+function statOrRetry(fs, path) {
+	try {
+		return fs.statSync(path);
+	} catch (error) {
+		if (isDeterminateFsCode(error?.code)) return null;
+		throw new InfraRetry(`could not read the local folder's git files (${error?.code ?? "unknown"}): ${basename(path)}`);
+	}
+}
+
+function readOrRetry(fs, path) {
+	try {
+		return fs.readFileSync(path, "utf8");
+	} catch (error) {
+		if (isDeterminateFsCode(error?.code)) return null;
+		throw new InfraRetry(`could not read the local folder's git files (${error?.code ?? "unknown"}): ${basename(path)}`);
+	}
+}
+
 async function defaultGit(gitDir, args) {
 	// This was the one copy of seven missing `core.fsmonitor=false`, which is why the flags are imported
 	// now rather than restated (issue #286's sweep). Nothing was exploitable -- the only command below is