@edgehero/pi-dispatch 0.1.0

package/src/packages.mjs

@@ -0,0 +1,188 @@
+/**
+ * Staged pi packages (issue #58): pinned third-party pi packages that live INSIDE the operator's global
+ * overlay at `<PI_GLOBAL_PI_DIR>/packages/<dir>/`. That overlay is already mounted `/opt/pi-global:ro`
+ * into every job container (REQ-GLOBAL-PI-OVERLAY), so staged packages need no new mount and no new
+ * trust boundary -- they ride the one the overlay already established.
+ *
+ * A staged package is a SELF-CONTAINED directory (its `package.json` plus its own `node_modules/`).
+ * pi's package resolver treats any spec that is not `npm:`/`git:`/a URL as a LOCAL path: it resolves the
+ * directory in place -- no install, no network, no writes -- and a `pi` manifest there contributes
+ * extensions, skills, prompts and themes. That is precisely what lets a job container load them with
+ * network egress denied, which is the whole point of staging at all.
+ *
+ * Versions are EXACT, never a range (CONST-PI-VERSION-PINNED): a floating range turns a silent upstream
+ * minor into every queued job becoming a no-op with NO signal -- the queue still reports success, the
+ * worst failure class available. Pinning converts that into an operator-visible edit of a version string.
+ *
+ * Two directions, two error policies:
+ *   - `parsePackagesFile` reads the OPERATOR's `pi-packages.json` before anything is staged. Pure and
+ *     fs-free (mirrors triggers.mjs), fail-loud `configError` naming the offending package.
+ *   - `readStageManifest` reads the file the STAGER wrote, at job-wiring time. It NEVER throws: a corrupt
+ *     manifest must degrade to "no staged packages", not crash the worker mid-queue.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { configError } from "./config.mjs";
+// ENTRY_NAME_RE / ADMIN_RE are import-pi's -- imported rather than re-declared so the staged dir charset
+// and the admin block cannot drift between the stager and this validator (doctor.mjs sets the precedent
+// of importing from import-pi.mjs).
+import { ADMIN_RE, ENTRY_NAME_RE } from "./import-pi.mjs";
+// The container-side mount point is docker-run.mjs's fact -- IMPORTED, never re-typed, so the mount and the
+// packages root below cannot drift apart while both test suites stay green. docker-run.mjs is dependency-free
+// (it builds an argv array and nothing else), so this costs no cycle and no weight in the admin's bundle.
+import { CONTAINER_GLOBAL_PI_DIR } from "./docker-run.mjs";
+
+/** Staged packages live under `<globalPiDir>/packages/` -- a subdir of the overlay, not a new mount. */
+export const PACKAGES_SUBDIR = "packages";
+/** The stager's receipt, written alongside the staged dirs: what was staged, at which exact version. */
+export const STAGE_MANIFEST = "packages.json";
+/** Where the staged packages land inside the job container -- the overlay mount plus the one subdir. */
+export const CONTAINER_PACKAGES_ROOT = `${CONTAINER_GLOBAL_PI_DIR}/${PACKAGES_SUBDIR}`;
+
+/** An exact semver -- prerelease and build metadata allowed, ranges/tags/wildcards are not. */
+export const EXACT_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/** An npm package name: lowercase, optionally `@scope/`-prefixed. */
+export const NPM_NAME_RE = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+/** npm's hard limit on a package name; a longer one could never have been published. */
+const MAX_NAME_LENGTH = 214;
+/** The staged dir name doubles as a path segment in the container, so it stays short and flat. */
+const MAX_DIR_LENGTH = 64;
+
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * The default staged dir for a package name: `@scope/name` -> `scope__name`. A flat, slash-free segment,
+ * because the staged dir is one path component under `packages/` -- keeping the scope in the name (rather
+ * than nesting a `scope/` dir) keeps `<packages>/<dir>` a single validated segment on both host and
+ * container.
+ */
+export function stagedDirName(name) {
+	return String(name).replace(/^@/, "").replace(/\//g, "__");
+}
+
+/**
+ * Parse, validate, and normalize the operator's packages file TEXT. Returns `[{ name, version, dir }]`
+ * with unknown fields dropped. Throws `configError` (fail-loud) naming the offending package. `path` is
+ * for error messages only -- this function touches no filesystem.
+ */
+export function parsePackagesFile(text, path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw configError(`packages file is not valid JSON: ${path} (${error.message})`);
+	}
+
+	const entries = parsed?.packages;
+	if (!Array.isArray(entries)) {
+		throw configError(`packages file must have a "packages" array: ${path}`);
+	}
+
+	const seenDirs = new Map();
+	return entries.map((entry, index) => normalizePackage(entry, index, path, seenDirs));
+}
+
+function normalizePackage(entry, index, path, seenDirs) {
+	const at = `package at index ${index}`;
+
+	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+		throw configError(`${at}: must be an object: ${path}`);
+	}
+
+	const { name, version } = entry;
+	if (!isNonEmptyString(name)) {
+		throw configError(`${at}: "name" must be a non-empty string: ${path}`);
+	}
+	if (name.length > MAX_NAME_LENGTH) {
+		throw configError(`package "${name.slice(0, 40)}...": name exceeds npm's ${MAX_NAME_LENGTH}-character limit: ${path}`);
+	}
+	if (!NPM_NAME_RE.test(name)) {
+		throw configError(`package "${name}": name must be a valid npm package name (lowercase, optionally "@scope/"-prefixed): ${path}`);
+	}
+	// The admin package can enqueue paid jobs -- staging it into an overlay that every job container reads
+	// is the same recursion vector import-pi already blocks for the admin extension.
+	if (ADMIN_RE.test(name)) {
+		throw configError(`package "${name}": refused -- the pi-dispatch admin package must never be staged into a job overlay (it can enqueue paid jobs: a recursion vector): ${path}`);
+	}
+
+	if (!isNonEmptyString(version)) {
+		throw configError(`package "${name}": "version" must be a non-empty string (an exact version, e.g. "1.4.2"): ${path}`);
+	}
+	// Exact versions only (CONST-PI-VERSION-PINNED). Stated in full because the refusal looks pedantic
+	// until you know the failure mode it prevents.
+	if (!EXACT_VERSION_RE.test(version)) {
+		throw configError(
+			`package "${name}": version must be an EXACT version like "1.4.2", got ${JSON.stringify(version)} -- ` +
+				`a floating range turns a silent upstream minor into every queued job becoming a no-op with no signal, ` +
+				`and the queue still reports success (CONST-PI-VERSION-PINNED): ${path}`,
+		);
+	}
+
+	if (entry.dir !== undefined && !isNonEmptyString(entry.dir)) {
+		throw configError(`package "${name}": "dir" must be a non-empty string when present: ${path}`);
+	}
+	const dir = entry.dir ?? stagedDirName(name);
+	// Length first: the charset regex also caps at 64, but "too long" and "bad characters" are different
+	// operator mistakes and deserve different fixes.
+	if (dir.length > MAX_DIR_LENGTH) {
+		throw configError(`package "${name}": dir ${JSON.stringify(dir)} exceeds ${MAX_DIR_LENGTH} characters -- set a shorter explicit "dir": ${path}`);
+	}
+	if (!ENTRY_NAME_RE.test(dir)) {
+		throw configError(`package "${name}": dir ${JSON.stringify(dir)} is not a safe directory name (letters, digits, "._-", no slashes, no "..") -- set an explicit "dir": ${path}`);
+	}
+	if (ADMIN_RE.test(dir)) {
+		throw configError(`package "${name}": dir ${JSON.stringify(dir)} is refused -- the admin name is blocked in a job overlay: ${path}`);
+	}
+	if (seenDirs.has(dir)) {
+		throw configError(`package "${name}": dir "${dir}" is already used by "${seenDirs.get(dir)}" -- two packages cannot share one staged dir; set an explicit "dir" on one of them: ${path}`);
+	}
+	seenDirs.set(dir, name);
+
+	return { name, version, dir };
+}
+
+/**
+ * Read the stager's manifest from `<globalPiDir>/packages/packages.json`. Returns `{ stagedAt, packages }`
+ * or `null` when there is nothing usable there. NEVER throws -- this runs on the job path, where a corrupt
+ * or half-written manifest must mean "no staged packages" rather than a crashed worker.
+ *
+ * Entries are re-validated on the way in (the file is a host artifact that an operator may have hand-edited
+ * between stage time and job time): a `dir` that is not a plain segment would otherwise flow straight into
+ * a container path.
+ */
+export function readStageManifest({ globalPiDir, readFile = readFileSync, fileExists = existsSync } = {}) {
+	if (!globalPiDir) return null;
+	const path = join(globalPiDir, PACKAGES_SUBDIR, STAGE_MANIFEST);
+	try {
+		if (!fileExists(path)) return null;
+		const parsed = JSON.parse(readFile(path, "utf8"));
+		if (parsed === null || typeof parsed !== "object" || !Array.isArray(parsed.packages)) return null;
+
+		const packages = [];
+		for (const entry of parsed.packages) {
+			if (entry === null || typeof entry !== "object") return null;
+			const { name, version, dir } = entry;
+			if (!isNonEmptyString(name) || !isNonEmptyString(version) || !isNonEmptyString(dir)) return null;
+			if (!ENTRY_NAME_RE.test(dir) || dir.length > MAX_DIR_LENGTH) return null;
+			packages.push({ name, version, dir });
+		}
+		return { stagedAt: typeof parsed.stagedAt === "string" ? parsed.stagedAt : null, packages };
+	} catch {
+		return null; // missing, unreadable, or garbage -- all mean "nothing staged"
+	}
+}
+
+/**
+ * The CONTAINER paths of the staged packages, in manifest order -- what gets handed to pi as local package
+ * specs. Built with template literals and never `path.join`: the worker may run on Windows, where `join`
+ * yields backslashes, and these are paths INSIDE a Linux container.
+ */
+export function containerPackagePaths(manifest) {
+	const packages = manifest?.packages;
+	if (!Array.isArray(packages)) return [];
+	return packages.filter((p) => isNonEmptyString(p?.dir)).map((p) => `${CONTAINER_PACKAGES_ROOT}/${p.dir}`);
+}

package/src/pause-windows.mjs

@@ -0,0 +1,218 @@
+/**
+ * Scoped pause windows (REQ-SCOPED-PAUSE-WINDOWS): hold a folder/repo's runs "between certain times" and
+ * resume automatically after. One `pause-windows.json` of `{ scope, from, to, tz?, days?, dateFrom?, dateTo? }`
+ * entries; the worker defers a job whose scope is inside an active window via BullMQ's own delayed set
+ * (DES-SCOPED-PAUSE-VIA-MOVE-TO-DELAYED). Deferred, never dropped — a paused github issue job runs after the
+ * window, not lost.
+ *
+ * This module is pure and fs-injectable (mirrors triggers.mjs/schedules.mjs): `parsePauseWindows` validates
+ * the file TEXT fail-loud, `loadPauseWindows` layers the one fs read on top, and `pauseUntilMs` is the
+ * timezone-aware predicate the processor gate consumes. Timezones are handled with the built-in `Intl`
+ * (no dependency, DST-correct via a one-pass offset correction).
+ *
+ * Custom: pause windows validated inline per triggers.mjs/config.mjs precedent; zod not in deps
+ */
+
+import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { configError } from "./config.mjs";
+
+// Sunday-first to match JS getUTCDay() and the Intl weekday index used in zonedParts().
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const DAY_SET = new Set(DAYS);
+
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+
+/** "HH:MM" -> minutes since midnight in [0,1439]; throws `configError` on anything malformed. */
+function parseHHMM(value, label, at, path) {
+	const m = isNonEmptyString(value) ? /^([0-9]{1,2}):([0-9]{2})$/.exec(value.trim()) : null;
+	if (!m) throw configError(`${at}: ${label} must be "HH:MM": ${JSON.stringify(value)} (${path})`);
+	const h = Number(m[1]);
+	const min = Number(m[2]);
+	if (h > 23 || min > 59) throw configError(`${at}: ${label} out of range 00:00-23:59: ${JSON.stringify(value)} (${path})`);
+	return h * 60 + min;
+}
+
+/** Validate a "YYYY-MM-DD" calendar date; throws `configError` when malformed. */
+function assertDate(value, label, at, path) {
+	const m = /^([0-9]{4})-([0-9]{2})-([0-9]{2})$/.exec(String(value).trim());
+	const mo = m && Number(m[2]);
+	const d = m && Number(m[3]);
+	if (!m || mo < 1 || mo > 12 || d < 1 || d > 31) {
+		throw configError(`${at}: ${label} must be "YYYY-MM-DD": ${JSON.stringify(value)} (${path})`);
+	}
+}
+
+/** Confirm an IANA zone by constructing a formatter (throws for an unknown zone); returns the zone. */
+function validateTz(tz, at, path) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: tz });
+		return tz;
+	} catch {
+		throw configError(`${at}: tz is not a valid IANA timezone: ${JSON.stringify(tz)} (${path})`);
+	}
+}
+
+/**
+ * Parse, validate, and normalize the pause-windows file text. Returns an array of normalized windows
+ * (unknown fields dropped; `fromMin`/`toMin` precomputed). Throws `configError` (fail-loud) on any malformed
+ * entry. `path` is for messages only.
+ */
+export function parsePauseWindows(text, path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw configError(`pause-windows file is not valid JSON: ${path} (${error.message})`);
+	}
+	const windows = parsed?.windows;
+	if (!Array.isArray(windows)) {
+		throw configError(`pause-windows file must have a "windows" array: ${path}`);
+	}
+	return windows.map((w, index) => normalizeWindow(w, index, path));
+}
+
+function normalizeWindow(w, index, path) {
+	const at = `pause window at index ${index}`;
+	if (w === null || typeof w !== "object") throw configError(`${at}: must be an object: ${path}`);
+	if (!isNonEmptyString(w.scope)) throw configError(`${at}: scope must be a non-empty string: ${path}`);
+
+	const fromMin = parseHHMM(w.from, "from", at, path);
+	const toMin = parseHHMM(w.to, "to", at, path);
+	// A from==to window would pause 24h forever and busy-defer; refuse it — remove the trigger instead.
+	if (fromMin === toMin) {
+		throw configError(`${at}: from and to must differ (a 24h pause is not expressible; remove the trigger): ${path}`);
+	}
+
+	const tz = w.tz === undefined ? "UTC" : validateTz(w.tz, at, path);
+
+	let days = null;
+	if (w.days !== undefined) {
+		if (!Array.isArray(w.days) || w.days.length === 0) {
+			throw configError(`${at}: days must be a non-empty array of weekday names (mon..sun): ${path}`);
+		}
+		days = w.days.map((d) => {
+			const key = String(d).trim().toLowerCase().slice(0, 3);
+			if (!DAY_SET.has(key)) throw configError(`${at}: unknown weekday ${JSON.stringify(d)} (use mon..sun): ${path}`);
+			return key;
+		});
+	}
+
+	let dateFrom = null;
+	let dateTo = null;
+	if (w.dateFrom !== undefined) { assertDate(w.dateFrom, "dateFrom", at, path); dateFrom = String(w.dateFrom).trim(); }
+	if (w.dateTo !== undefined) { assertDate(w.dateTo, "dateTo", at, path); dateTo = String(w.dateTo).trim(); }
+	if (dateFrom && dateTo && dateFrom > dateTo) throw configError(`${at}: dateFrom must be <= dateTo: ${path}`);
+
+	const norm = { scope: w.scope.trim(), from: w.from.trim(), to: w.to.trim(), fromMin, toMin, tz };
+	if (days) norm.days = days;
+	if (dateFrom) norm.dateFrom = dateFrom;
+	if (dateTo) norm.dateTo = dateTo;
+	return norm;
+}
+
+/**
+ * Load and validate the pause-windows file named by `config.pauseWindowsFile`. Returns `[]` when the file is
+ * unset (the feature is disabled — a valid deployment). `readFileSync`/`existsSync` are injectable for tests.
+ */
+export function loadPauseWindows(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+	const path = config.pauseWindowsFile;
+	if (path === null || path === undefined) return [];
+	if (!existsSync(path)) throw configError(`pause-windows file does not exist: ${path}`);
+	return parsePauseWindows(readFileSync(path, "utf8"), path);
+}
+
+// ── the timezone-aware predicate ────────────────────────────────────────────────────────────────────────
+
+const WEEKDAY_INDEX = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+
+/** The wall-clock parts of instant `ms` in `tz`: `{ y, mo, d, hh, mi, dow }` (dow 0=Sun..6=Sat). */
+function zonedParts(tz, ms) {
+	const fmt = new Intl.DateTimeFormat("en-US", {
+		timeZone: tz, hour12: false,
+		year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", weekday: "short",
+	});
+	const p = {};
+	for (const part of fmt.formatToParts(new Date(ms))) p[part.type] = part.value;
+	let hh = Number(p.hour);
+	if (hh === 24) hh = 0; // some ICU builds render midnight as "24"
+	return { y: Number(p.year), mo: Number(p.month), d: Number(p.day), hh, mi: Number(p.minute), dow: WEEKDAY_INDEX[p.weekday] };
+}
+
+/**
+ * Epoch ms for a wall-clock time `(y,mo,d,hh,mi)` in `tz`. One-pass offset correction: format the naive-UTC
+ * guess back in `tz`, diff to recover the zone offset, subtract. Correct except the ~1h DST-transition seam,
+ * which is immaterial for a pause boundary.
+ */
+function wallToMs(tz, y, mo, d, hh, mi) {
+	const guess = Date.UTC(y, mo - 1, d, hh, mi);
+	const shown = zonedParts(tz, guess);
+	const shownAsUtc = Date.UTC(shown.y, shown.mo - 1, shown.d, shown.hh, shown.mi);
+	return guess - (shownAsUtc - guess);
+}
+
+/** The date `delta` days from `parts`' date, computed at local noon to dodge DST edges. Returns zoned parts. */
+function shiftDay(tz, parts, delta) {
+	const noon = wallToMs(tz, parts.y, parts.mo, parts.d, 12, 0);
+	return zonedParts(tz, noon + delta * 86400000);
+}
+
+function ymd(parts) {
+	return `${String(parts.y).padStart(4, "0")}-${String(parts.mo).padStart(2, "0")}-${String(parts.d).padStart(2, "0")}`;
+}
+
+/** Whether a window occurrence STARTING on `parts`' day is allowed by its `days` and `dateFrom`/`dateTo`. */
+function qualifies(w, parts) {
+	if (w.days && !w.days.includes(DAYS[parts.dow])) return false;
+	const date = ymd(parts);
+	if (w.dateFrom && date < w.dateFrom) return false;
+	if (w.dateTo && date > w.dateTo) return false;
+	return true;
+}
+
+/** The end epoch ms of the window occurrence active at `nowMs`, or null if `now` is not inside `w`. Exported
+ * so the admin panel can mark a single window "currently paused · resumes in …" without a synthetic job. */
+export function windowEndAt(w, nowMs) {
+	const p = zonedParts(w.tz, nowMs);
+	const nowMin = p.hh * 60 + p.mi;
+	const endAt = (dateParts) => wallToMs(w.tz, dateParts.y, dateParts.mo, dateParts.d, Math.floor(w.toMin / 60), w.toMin % 60);
+
+	if (w.fromMin < w.toMin) {
+		// Same-day window: [from, to) today, starting today.
+		if (nowMin >= w.fromMin && nowMin < w.toMin && qualifies(w, p)) return endAt(p);
+		return null;
+	}
+	// Overnight window (from > to): started tonight (>= from, today qualifies) -> ends tomorrow at `to`,
+	// or started last night (< to, yesterday qualified) -> ends today at `to`.
+	if (nowMin >= w.fromMin && qualifies(w, p)) return endAt(shiftDay(w.tz, p, 1));
+	if (nowMin < w.toMin && qualifies(w, shiftDay(w.tz, p, -1))) return endAt(p);
+	return null;
+}
+
+/**
+ * The scope key a window matches against: the folder for a local job, the repo for any forge-backed one.
+ * Keyed on local rather than on a list of forges, so a new forge is scoped by its `repo` automatically --
+ * an enumeration that forgot one would make that forge's jobs unpausable, which is a silent failure.
+ */
+export function scopeOf(job) {
+	return job?.kind === "local" ? job?.folder : job?.repo;
+}
+
+/**
+ * When, in epoch ms, the current pause for this job's scope ends — or `null` when the job is not paused. A
+ * job is paused if `now` falls inside any scope-matching window (`scope === "*"` matches every scope); the
+ * latest end among active windows is returned so a single deferral clears them all (re-checked on wake).
+ */
+export function pauseUntilMs(windows, job, nowMs) {
+	if (!Array.isArray(windows) || windows.length === 0) return null;
+	const scope = scopeOf(job);
+	if (!isNonEmptyString(scope)) return null;
+	let end = null;
+	for (const w of windows) {
+		if (w.scope !== "*" && w.scope !== scope) continue;
+		const e = windowEndAt(w, nowMs);
+		if (e !== null && (end === null || e > end)) end = e;
+	}
+	return end;
+}

package/src/prepare-github.mjs

@@ -0,0 +1,260 @@
+/*
+ * prepare-github.mjs — build the read-only /job inputs for a GitHub-triggered job by cloning the
+ * serviced repo AT A PINNED SHA onto the host, then materialising its .pi/ and writing the prompt.
+ *
+ * This is the highest-risk host operation in the worker: it places attacker-influenced repository
+ * bytes on the host filesystem before any container exists. Two properties make it safe, and both
+ * are structural, not content filters:
+ *
+ *   1. THE CLONE RUNS NO REPO-SUPPLIED CODE. Every git invocation carries
+ *      `-c core.hooksPath=/dev/null -c core.fsmonitor=false -c protocol.ext.allow=never
+ *      -c credential.helper=` and `--no-pager`, and the fetch is `--no-recurse-submodules`. Hooks,
+ *      the fsmonitor daemon, ext-protocol transports, credential helpers, and submodules are the
+ *      paths by which a repo runs code during clone/checkout; all are disabled. `.pi/` is then read
+ *      by object id via materializePiDir (`git cat-file`), never through the working tree, so no
+ *      symlink/filter/hook runs there either. Per CONST-ISOLATION-CONTAINER-PER-JOB the agent runs
+ *      in the container; the host only assembles the box's inputs and must not itself execute repo
+ *      code.
+ *
+ *   2. THE TOKEN NEVER LANDS ANYWHERE THE AGENT OR THE REPO CAN READ IT. The per-job credential
+ *      reaches git ONLY through a GIT_ASKPASS helper's env var (GIT_ASKPASS_TOKEN), never in argv, a
+ *      remote URL, or the persisted `.git/config` (the remote is the tokenless
+ *      `https://github.com/<owner>/<name>.git`, with no `x-access-token@` and no `url.*.insteadOf`).
+ *      The askpass script itself holds no token — it prints the env var — and lives in a host temp
+ *      dir OUTSIDE jobDir and workspace/, removed in a `finally`. jobDir is mounted `/job` :ro and IS
+ *      agent-readable, so nothing token-bearing is written under it. See CONST-TOKEN-SCOPED-PER-JOB
+ *      and no-token-in-agent-reachable-file.
+ *
+ * The /job inputs written here are exactly INT-CONTAINER-JOB-INPUTS: `prompt.md` (the user prompt,
+ * issue text as DATA), `event.json` (the INT-WEBHOOK-PAYLOAD-SUBSET body fields only — never a
+ * header, never the `X-Hub-Signature-256` signature, never the token; on issue_comment jobs the
+ * named subset includes the invoking `comment` body fields, and the one non-webhook addition is
+ * `matched` — the filter's decision record of which triggers.json entry fired, by raw file index,
+ * harness-computed rather than taken from any payload), and `pi/` (materialised persona/skills).
+ * Neither the token nor any issue text is logged.
+ *
+ * A determinate gone-SHA (the default branch advanced past the resolved tip before the fetch) is a
+ * POLICY outcome, returned as `{ outcome: "policy", reason: "sha-gone" }` — NOT thrown, so the
+ * processor does not retry a job that can never fetch that commit. Every other fetch failure
+ * (DNS/connection/timeout/5xx/auth) throws InfraRetry and is retried. The discipline mirrors
+ * github-host.mjs's 404-vs-other split: only the determinate class becomes policy.
+ */
+
+import { execFile } from "node:child_process";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { buildGithubPrompt } from "./github-prompt.mjs";
+import { materializePiDir } from "./materialize.mjs";
+import { InfraRetry } from "./processor.mjs";
+
+const exec = promisify(execFile);
+
+// The -c flags that make a clone/checkout run no repo-supplied code, applied to EVERY git invocation
+// through `hardened()` below so they cannot be omitted at a call site. Matches materialize.mjs's bar
+// (hooksPath, fsmonitor, --no-pager) plus the clone-specific transport/credential locks.
+const HARDEN_FLAGS = [
+	"-c",
+	"core.hooksPath=/dev/null",
+	"-c",
+	"core.fsmonitor=false",
+	"-c",
+	"protocol.ext.allow=never",
+	"-c",
+	"credential.helper=",
+	"--no-pager",
+];
+
+/** Prepend the hardening flags to a bare git subcommand's args. */
+function hardened(args) {
+	return [...HARDEN_FLAGS, ...args];
+}
+
+// stderr fragments that mean the resolved SHA is provably gone from the remote: the default branch
+// advanced and git can no longer fetch/realise that commit. These are DETERMINATE, so they map to a
+// policy refusal, never a retry. Any other failure stays retryable (see fetch catch below).
+const SHA_GONE_MARKERS = [
+	"couldn't find remote ref",
+	"not our ref",
+	"unadvertised object",
+	"did not send all necessary objects",
+	"reference is not a tree",
+];
+
+/** True only when a git error's output names one of the determinate gone-SHA conditions. */
+function isShaGone(error) {
+	const text = `${error?.stderr ?? ""}\n${error?.message ?? ""}`.toLowerCase();
+	return SHA_GONE_MARKERS.some((marker) => text.includes(marker));
+}
+
+/**
+ * Prepare a GITHUB job's read-only /job inputs. Clones `job.repo` at the caller-resolved default-
+ * branch SHA into `jobDir/workspace`, materialises `.pi/` into `jobDir/pi`, and writes `prompt.md`
+ * and `event.json`. Mirrors prepare-local's jobDir-in shape and return object.
+ *
+ * Collaborators are injected so tests run offline against fakes and never touch a real network/git:
+ *   - `git(cwd, args, { env })`      transport for a single git invocation; default runs the real
+ *                                     binary via execFile (no shell). Args arrive already hardened.
+ *   - `resolveDefaultBranchSha(repo, token) => { sha }`  fresh default-branch tip (github-host).
+ *   - `materialize({ gitDir, sha, destDir }) => string[]`  the .pi/ materialiser (git cat-file).
+ *   - `writeFile` / `mkdir`          fs writes for the job inputs (default sync fs).
+ *
+ * On a determinate gone-SHA returns `{ outcome: "policy", reason: "sha-gone" }`. On success returns
+ * `{ workspace, jobDir, sha, materialised }`.
+ */
+export async function prepareGithubWorkspace(
+	job,
+	token,
+	{
+		jobDir,
+		git = defaultGit,
+		resolveDefaultBranchSha,
+		materialize = materializePiDir,
+		writeFile = writeFileSync,
+		mkdir = mkdirSync,
+		// How this forge names a clone URL, and how it phrases the agent's envelope. Injected rather than
+		// forked into a second copy of this function: everything else here -- the askpass helper, the
+		// hardening flags, the gone-SHA markers, the pinned detached checkout, the :ro event.json -- is
+		// git and this project, not GitHub, and a second copy is a second place to fix a clone bug.
+		remoteUrlFor = (j) => `https://github.com/${String(j.repo).split("/")[0]}/${String(j.repo).split("/")[1]}.git`,
+		buildPrompt = buildGithubPrompt,
+		// REQ-RESUMABLE-SESSION. Both default to inert, so an unwired caller prepares what it always did.
+		resolvePullRequestHead = null,
+		resolveSession = () => null,
+		piVersion = null,
+	} = {},
+) {
+	// Fresh API resolve of the commit to clone at — never a webhook field, never the triggering branch.
+	const { sha } = await resolveDefaultBranchSha(job, token);
+
+	const workspace = join(jobDir, "workspace");
+	mkdir(workspace, { recursive: true });
+
+	// The remote URL is TOKENLESS; the credential comes from the askpass helper's env, never from here.
+	const remoteUrl = remoteUrlFor(job);
+
+	const askpass = createAskpassHelper();
+	try {
+		await git(workspace, hardened(["init"]));
+		await git(workspace, hardened(["remote", "add", "origin", remoteUrl]));
+
+		// The token reaches git ONLY here, via GIT_ASKPASS_TOKEN read by the helper — never argv/URL.
+		const netEnv = {
+			...process.env,
+			GIT_TERMINAL_PROMPT: "0",
+			GIT_ASKPASS: askpass.path,
+			GIT_ASKPASS_TOKEN: token,
+		};
+
+		try {
+			await git(
+				workspace,
+				hardened(["fetch", "--depth=1", "--no-tags", "--no-recurse-submodules", "origin", sha]),
+				{ env: netEnv },
+			);
+			await git(workspace, hardened(["checkout", "--detach", "FETCH_HEAD"]));
+		} catch (error) {
+			// Determinate gone-SHA => policy, no retry. Anything else (DNS/connection/timeout/5xx/auth)
+			// => retryable infra. The cause carries git's output for debugging; it is token-free by
+			// construction (tokenless remote URL + askpass), and BullMQ persists only message+stack.
+			if (isShaGone(error)) {
+				return { outcome: "policy", reason: "sha-gone" };
+			}
+			throw new InfraRetry(`prepare-github: fetch failed for ${job.repo}`, { cause: error });
+		}
+
+		// .pi/ is read by object id from the pinned SHA — symlink/submodule/exec safe, no working tree.
+		const materialised = await materialize({ gitDir: workspace, sha, destDir: jobDir });
+
+		// Which transcript, if any, this job continues. The head ref for a pull/merge-request target is
+		// resolved from the FORGE, not the payload -- an issue_comment on a PR carries no head at all, and
+		// head.repo.full_name in a webhook body is attacker-supplied. Both this lookup and the store itself
+		// degrade to a cold start rather than failing the job: a cache miss must never cost a run.
+		let resolved = {};
+		if (job.resume === true && job.target?.type === "pull_request" && resolvePullRequestHead) {
+			try {
+				resolved = (await resolvePullRequestHead(job, token)) ?? {};
+			} catch {
+				resolved = {};
+			}
+		}
+		const session = job.resume === true ? resolveSession(job, { jobDir, resolved, piVersion }) : null;
+
+		// Issue text is DATA: it enters the USER prompt (buildGithubPrompt), never a system prompt.
+		writeFile(
+			join(jobDir, "prompt.md"),
+			// `replica`/`replicas` (REQ-REPLICA-RUNS) are host-assigned integers off job.data, so they are safe
+			// to interpolate, and they are what makes this job's branch differ from its sibling's. This is the
+			// SHARED forge preparer, so the gitlab/forgejo/azure builders receive the two keys and destructure
+			// them away -- harmless, and always undefined while replicas are github-only.
+			buildPrompt({ flow: job.flow, target: job.target, comment: job.trigger?.comment, resumed: session?.resume === true, replica: job.replica, replicas: job.replicas }),
+			{ mode: 0o444 },
+		);
+
+		// The INT-WEBHOOK-PAYLOAD-SUBSET body fields ONLY — no header, no signature, no token. `matched`
+		// is the single harness-computed addition: the filter's decision record, not a webhook field.
+		//
+		// `replica`/`replicas` are DELIBERATELY ABSENT, and that is a choice rather than an oversight. This
+		// literal is the webhook's own body plus one decision record; an execution knob is not a fact about
+		// the delivery. The agent already learns its index from the prompt and `PI_JOB_ID` already ends
+		// `-r2`, so nothing here needs it -- and INT-CONTAINER-JOB-INPUTS and INT-WEBHOOK-PAYLOAD-SUBSET stay
+		// untouched, which is worth more than the convenience.
+		const subset = {
+			event: job.trigger?.event,
+			action: job.trigger?.action,
+			delivery: job.trigger?.deliveryId,
+			repository: { full_name: job.repo },
+			...(job.target?.type === "pull_request" ? { pull_request: prEventBody(job.target) } : { issue: { number: job.target?.number, title: job.target?.title, body: job.target?.body } }),
+			...(job.trigger?.comment ? { comment: { body: job.trigger.comment.body, author_association: job.trigger.comment.author_association } } : {}),
+			sender: { id: job.trigger?.sender?.id },
+			...(job.trigger?.matched ? { matched: job.trigger.matched } : {}),
+		};
+		writeFile(join(jobDir, "event.json"), JSON.stringify(subset, null, 2), { mode: 0o444 });
+
+		return { workspace, jobDir, sha, materialised, ...(session ? { session } : {}) };
+	} finally {
+		// The askpass machinery must not outlive the prepare, and must never be agent-reachable.
+		rmSync(askpass.dir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * The `pull_request` body for event.json, from the job's PR target. `head`/`base` are attacker-controlled
+ * fork DATA carried for the flow's own `gh` use; they are surfaced here, never used as a clone ref. Absent
+ * when the target lacks them (a comment-triggered PR job resolves them from the number via `gh`).
+ */
+function prEventBody(target) {
+	const body = { number: target.number, title: target.title, body: target.body };
+	if (target.head) body.head = target.head;
+	if (target.base) body.base = target.base;
+	return body;
+}
+
+/**
+ * Write the GIT_ASKPASS helper to a fresh host temp dir OUTSIDE jobDir/workspace. The script holds no
+ * token: it prints GIT_ASKPASS_TOKEN, which git sets in the child's env only for the network fetch.
+ * Returns `{ dir, path }`; the caller removes `dir` in a finally.
+ */
+function createAskpassHelper() {
+	const dir = mkdtempSync(join(tmpdir(), "pi-askpass-"));
+	const path = join(dir, "askpass.sh");
+	writeFileSync(path, "#!/bin/sh\nprintf '%s' \"$GIT_ASKPASS_TOKEN\"\n", { mode: 0o700 });
+	chmodSync(path, 0o700);
+	return { dir, path };
+}
+
+/**
+ * Transport for one git invocation. `args` arrive already hardened by `hardened()`. Runs the real
+ * binary via execFile (array args, NO shell); `cwd` is the workspace and `env` is passed only for the
+ * network fetch (the askpass env), so local calls inherit the ambient environment.
+ */
+async function defaultGit(cwd, args, { env } = {}) {
+	const { stdout } = await exec("git", args, {
+		cwd,
+		encoding: "utf8",
+		maxBuffer: 16 * 1024 * 1024,
+		env,
+	});
+	return stdout;
+}