@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/fork-store.mjs

@@ -0,0 +1,338 @@
+/**
+ * Immutable, run-addressed fork sources (issue #648). The canonical session moves on every promotion,
+ * so looking up an old run through its session key would silently fork a newer conversation instead.
+ * These private artifacts have their own bounded retention; no index maps jobs to arbitrary paths.
+ * Workspace points are captured ONLY while the caller has quiesced the container. A transcript alone
+ * never establishes that the files at an earlier entry are available.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import { hostname } from "node:os";
+import { join, resolve } from "node:path";
+import { DEFAULT_CHECKPOINT_LIMITS, makeWorkspaceCheckpointer, retryableStoreError } from "./workspace-checkpoint.mjs";
+
+export const FORK_SOURCE_LIMITS = Object.freeze({ maxBytes: 8 * 1024 * 1024, maxStoreBytes: 256 * 1024 * 1024, maxSources: 1024, maxPoints: 64, ttlMs: 7 * 86400_000 });
+const ID = /^[A-Za-z0-9._:-]{1,200}$/;
+const ENTRY = /^[A-Za-z0-9_-]{1,128}$/;
+const HEX = /^[0-9a-f]{64}$/;
+const KEY = /^[0-9a-f]{32}$/;
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._:@/+\-]{0,127}$/;
+const HOST = /^[A-Za-z0-9._-]{1,64}$/;
+const POSITIONS = new Set(["before", "at"]);
+const ENTRY_TYPES = new Set(["message", "thinking_level_change", "model_change", "usage", "compaction", "branch_summary", "custom", "label", "session_info", "custom_message", "context_edit"]);
+const ROLES = new Set(["user", "assistant", "toolResult"]);
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+export const forkSourceKey = (runId) => digest(`fork-source\0${runId}`).slice(0, 32);
+const pointKey = (entryId, position) => digest(`${entryId}\0${position}`);
+const refused = (suffix) => ({ refused: `fork-source-${suffix}` });
+
+function regular(path, max) {
+	const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+	try {
+		const st = fs.fstatSync(fd);
+		if (!st.isFile() || st.size > max) throw new Error("not-bounded-file");
+		const out = Buffer.alloc(st.size);
+		let offset = 0;
+		while (offset < out.length) {
+			const n = fs.readSync(fd, out, offset, out.length - offset, offset);
+			if (!n) throw new Error("short-file");
+			offset += n;
+		}
+		const after = fs.fstatSync(fd);
+		if (st.size !== after.size || st.mtimeMs !== after.mtimeMs) throw new Error("changed-file");
+		return out;
+	} finally { fs.closeSync(fd); }
+}
+function directory(path, create = false) {
+	if (create) {
+		try { if (!fs.lstatSync(path).isDirectory()) throw new Error("not-directory"); }
+		catch (e) { if (e?.code !== "ENOENT") throw e; }
+		fs.mkdirSync(path, { recursive: true, mode: 0o700 });
+	}
+	if (!fs.lstatSync(path).isDirectory()) throw new Error("not-directory");
+}
+function durable(path, bytes) {
+	const fd = fs.openSync(path, "wx", 0o600);
+	try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+function syncDir(path) {
+	const fd = fs.openSync(path, "r");
+	try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+}
+function parseEntries(bytes) {
+	const lines = bytes.toString("utf8").split("\n").filter(Boolean);
+	const header = JSON.parse(lines.shift() ?? "null");
+	if (header?.type !== "session") throw new Error("header");
+	const entries = [];
+	const seen = new Set();
+	for (const line of lines) {
+		const e = JSON.parse(line);
+		if (!ENTRY.test(e.id ?? "") || seen.has(e.id) || (e.parentId !== null && !seen.has(e.parentId))) throw new Error("tree");
+		seen.add(e.id);
+		entries.push({ id: e.id, parentId: e.parentId, type: ENTRY_TYPES.has(e.type) ? e.type : "unknown", ...(e.type === "message" ? { role: ROLES.has(e.message?.role) ? e.message.role : "unknown" } : {}) });
+	}
+	return entries;
+}
+/** Last complete tree path, with every tool call answered, is a usable workspace boundary. */
+export function forkPointEntry(bytes) {
+	try {
+		const raw = bytes.toString("utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+		const entries = raw.slice(1);
+		parseEntries(bytes);
+		const byId = new Map(entries.map((e) => [e.id, e]));
+		const path = [];
+		for (let e = entries.at(-1); e; e = byId.get(e.parentId)) path.unshift(e);
+		const pending = new Set();
+		for (const e of path) {
+			if (e.type !== "message") continue;
+			if (e.message?.role === "assistant") for (const c of e.message.content ?? []) if (c.type === "toolCall") pending.add(c.id);
+			if (e.message?.role === "toolResult") pending.delete(e.message.toolCallId);
+		}
+		return pending.size === 0 ? path.at(-1)?.id ?? null : null;
+	} catch { return null; }
+}
+function validManifest(m) {
+	const fields = ["v", "runId", "sessionKey", "baseSha", "venue", "piVersion", "attempt", "host", "hostQueue", "at", "bytes", "transcriptSha256", "sourceDigest"];
+	return m && Object.keys(m).length === fields.length && fields.every((k) => Object.hasOwn(m, k)) && m.v === 1 && ID.test(m.runId) && KEY.test(m.sessionKey) && SHA.test(m.baseSha) && TOKEN.test(m.venue) && /^\d+\.\d+\.\d+$/.test(m.piVersion) && Number.isSafeInteger(m.attempt) && m.attempt >= 0 && HOST.test(m.host) && (m.hostQueue === null || /^pi-jobs@[A-Za-z0-9._-]{1,64}$/.test(m.hostQueue)) && Number.isSafeInteger(m.at) && m.at >= 0 && Number.isSafeInteger(m.bytes) && m.bytes >= 0 && HEX.test(m.transcriptSha256) && HEX.test(m.sourceDigest);
+}
+
+/**
+ * The sweep's age of a source from its manifest, of ANY version (issue #761): `{ runId, at }` when the manifest carries
+ * an integer `v` of 1 or more, a run id that names this very directory (`forkSourceKey(runId) === key`) and a publish
+ * time that is a safe integer of 0 or more; null otherwise. For the sweep alone, and lenient on purpose: judged by
+ * `validManifest`, a source a newer release published reads as no manifest, so it would be aged by its earlier
+ * `origin.json` (removed while young) or by the folder's mtime, and with no run id its workspace archive would never be
+ * removed. `read` stays strict, so a newer source is still never served here.
+ */
+function sweepAge(m, key) {
+	if (!m || typeof m !== "object" || Array.isArray(m)) return null;
+	if (!Number.isSafeInteger(m.v) || m.v < 1) return null;
+	if (typeof m.runId !== "string" || !ID.test(m.runId) || forkSourceKey(m.runId) !== key) return null;
+	if (!Number.isSafeInteger(m.at) || m.at < 0) return null;
+	return { runId: m.runId, at: m.at };
+}
+
+export function createForkStore({ dir, now = Date.now, limits = {}, hostName = hostname(), hostQueue = null, checkpointer = null, checkpointLimits = {}, readRegular = regular } = {}) {
+	const L = { ...FORK_SOURCE_LIMITS, ...limits };
+	const root = typeof dir === "string" && dir ? resolve(dir) : null;
+	const host = HOST.test(hostName) ? hostName : "unknown";
+	const archive = root ? checkpointer ?? makeWorkspaceCheckpointer({ storeDir: join(root, ".workspaces"), now, hostName: host, keepHistory: true, limits: { ttlMs: L.ttlMs, snapshotTimeoutMs: 5_000, ...checkpointLimits } }) : null;
+	const pathOf = (runId) => join(root, forkSourceKey(runId));
+	const pointsOf = (runId) => join(pathOf(runId), "points");
+	let archiveBusy = false;
+	function dirs(runId, create = false) {
+		if (!root || !ID.test(runId ?? "")) throw new Error("bad-args");
+		directory(root, create);
+		directory(pathOf(runId), create);
+	}
+	function usage() {
+		let bytes = 0, sources = 0;
+		for (const name of fs.readdirSync(root)) {
+			if (!KEY.test(name) || !fs.lstatSync(join(root, name)).isDirectory()) continue;
+			sources++;
+			try { bytes += fs.lstatSync(join(root, name, "transcript.jsonl")).size; } catch {}
+		}
+		return { bytes, sources };
+	}
+	function publish({ runId, sessionKey, transcriptPath, baseSha, venue, piVersion, attempt = 0 } = {}) {
+		if (!root) return refused("unconfigured");
+		let lock;
+		try {
+			directory(root, true);
+			const before = usage();
+			if (!ID.test(runId ?? "") || !KEY.test(sessionKey ?? "") || !SHA.test(baseSha ?? "") || !TOKEN.test(venue ?? "") || !/^\d+\.\d+\.\d+$/.test(piVersion ?? "") || !Number.isSafeInteger(attempt) || attempt < 0) return refused("invalid");
+			const existed = fs.existsSync(pathOf(runId));
+			if (!existed && before.sources >= L.maxSources) return refused("capacity");
+			dirs(runId, true);
+			if (fs.existsSync(join(pathOf(runId), "unsafe-base"))) return { refused: "fork-unsafe-extensions" };
+			lock = fs.openSync(join(pathOf(runId), "publish.lock"), "wx", 0o600);
+			const bytes = readRegular(transcriptPath, L.maxBytes);
+			parseEntries(bytes);
+			const old = read({ runId });
+			if (old.ok) return old.manifest.transcriptSha256 === digest(bytes) ? { ok: true, sourceDigest: old.manifest.sourceDigest, manifest: old.manifest } : refused("immutable");
+			if (fs.existsSync(join(pathOf(runId), "manifest.json"))) return refused("corrupt");
+			if (before.bytes + bytes.length > L.maxStoreBytes) return refused("capacity");
+			const body = { v: 1, runId, sessionKey, baseSha, venue, piVersion, attempt, host, hostQueue, at: now(), bytes: bytes.length, transcriptSha256: digest(bytes) };
+			const manifest = { ...body, sourceDigest: digest(JSON.stringify(body)) };
+			if (!validManifest(manifest)) return refused("invalid");
+			// The manifest rename is the commit point. A crash before it leaves no readable source.
+			fs.rmSync(join(pathOf(runId), "transcript.jsonl"), { force: true });
+			durable(join(pathOf(runId), "transcript.jsonl"), bytes);
+			const incoming = join(pathOf(runId), `manifest.${randomBytes(8).toString("hex")}.incoming`);
+			durable(incoming, JSON.stringify(manifest));
+			fs.renameSync(incoming, join(pathOf(runId), "manifest.json"));
+			syncDir(pathOf(runId));
+			return { ok: true, sourceDigest: manifest.sourceDigest, manifest };
+		} catch (e) { return refused(e?.code === "EEXIST" ? "busy" : "unreadable"); }
+		finally { if (lock !== undefined) { fs.closeSync(lock); fs.rmSync(join(pathOf(runId), "publish.lock"), { force: true }); } }
+	}
+	function read({ runId, sourceDigest, entryId, position = "before" } = {}) {
+		if (!root) return refused("unconfigured");
+		if (!ID.test(runId ?? "") || (sourceDigest !== undefined && !HEX.test(sourceDigest))) return refused("invalid");
+		try {
+			dirs(runId);
+			if (fs.existsSync(join(pathOf(runId), "unsafe-base"))) return { refused: "fork-unsafe-extensions" };
+			const manifest = JSON.parse(readRegular(join(pathOf(runId), "manifest.json"), 8192));
+			if (!validManifest(manifest) || manifest.runId !== runId) return refused("corrupt");
+			const { sourceDigest: expected, ...body } = manifest;
+			if (digest(JSON.stringify(body)) !== expected) return refused("corrupt");
+			if (sourceDigest !== undefined && sourceDigest !== expected) return refused("changed");
+			if (now() - manifest.at > L.ttlMs || manifest.at > now()) return refused("expired");
+			const transcriptPath = join(pathOf(runId), "transcript.jsonl");
+			const bytes = readRegular(transcriptPath, L.maxBytes);
+			if (bytes.length !== manifest.bytes || digest(bytes) !== manifest.transcriptSha256) return refused("corrupt");
+			const entries = parseEntries(bytes);
+			const firstUser = entries.find((e) => e.type === "message" && e.role === "user");
+			// Load at most the point cap once. A long transcript must not turn preview into two
+			// filesystem opens per entry (an 8 MiB transcript can hold thousands of metadata entries).
+			const points = new Map();
+			try {
+				directory(pointsOf(runId));
+				const names = fs.readdirSync(pointsOf(runId)).filter((n) => /^[0-9a-f]{64}\.json$/.test(n));
+				if (names.length > L.maxPoints) return refused("corrupt");
+				for (const name of names) {
+					const p = JSON.parse(readRegular(join(pointsOf(runId), name), 8192));
+					if (ENTRY.test(p.entryId ?? "") && p.position === "at" && name === `${pointKey(p.entryId, p.position)}.json`) {
+						const valid = pointRecord(runId, p.entryId, p.position);
+						if (valid) points.set(p.entryId, valid);
+					}
+				}
+			} catch (e) {
+				if (retryableStoreError(e)) return { unavailable: e.code };
+				if (e?.code !== "ENOENT") return refused("checkpoint-unreadable");
+			}
+			const pointFor = (e, p) => e.id === firstUser?.id && p === "before" ? { base: true } : p === "before" && e.parentId ? points.get(e.parentId) : p === "at" ? points.get(e.id) : null;
+			for (const e of entries) e.positions = [...POSITIONS].filter((p) => pointFor(e, p));
+			const out = { ok: true, manifest, sourceDigest: expected, transcriptPath, entries };
+			if (entryId === undefined) return out;
+			if (!ENTRY.test(entryId) || !POSITIONS.has(position)) return refused("invalid-entry");
+			if (!entries.some((e) => e.id === entryId)) return refused("entry-missing");
+			const point = pointFor(entries.find((e) => e.id === entryId), position);
+			return point ? { ...out, point } : refused("checkpoint-missing");
+		} catch (e) { return retryableStoreError(e) ? { unavailable: e.code } : refused(e?.code === "ENOENT" ? "missing" : "unreadable"); }
+	}
+	function pointRecord(runId, entryId, position) {
+		try {
+			directory(pointsOf(runId));
+			const p = JSON.parse(readRegular(join(pointsOf(runId), `${pointKey(entryId, position)}.json`), 8192));
+			if (Object.keys(p).length !== 6 || p.entryId !== entryId || p.position !== position || !Number.isSafeInteger(p.seq) || p.seq < 1 || !HEX.test(p.transcriptSha256) || !Number.isSafeInteger(p.bytes) || p.bytes < 0 || !SHA.test(p.baseSha)) return null;
+			return p;
+		} catch (error) { if (retryableStoreError(error)) throw error; return null; }
+	}
+	async function primeBase(args = {}) {
+		if (!root || !ID.test(args.runId ?? "")) return refused("invalid");
+		try {
+			directory(root, true);
+			if (!fs.existsSync(pathOf(args.runId)) && usage().sources >= L.maxSources) return refused("capacity");
+			dirs(args.runId, true);
+			const originPath = join(pathOf(args.runId), "origin.json");
+			try { durable(originPath, JSON.stringify({ runId: args.runId, at: now() })); }
+			catch (e) { if (e?.code !== "EEXIST") throw e; }
+		} catch { return refused("unreadable"); }
+		if (archiveBusy) return refused("busy");
+		archiveBusy = true;
+		try {
+			const maxStore = checkpointLimits.maxStoreBytes ?? DEFAULT_CHECKPOINT_LIMITS.maxStoreBytes;
+			const maxBase = checkpointLimits.maxBaseBytes ?? DEFAULT_CHECKPOINT_LIMITS.maxBaseBytes;
+			const before = await archive.usage?.();
+			if (before?.bytes !== undefined && before.bytes + maxBase > maxStore) return refused("capacity");
+			const primed = await archive.primeBase({ ...args, objectFormat: args.objectFormat ?? (args.baseSha?.length === 64 ? "sha256" : "sha1") });
+			const after = primed?.ok ? await archive.usage?.() : null;
+			if (after?.bytes > maxStore) {
+				await archive.remove?.(args.runId);
+				return refused("capacity");
+			}
+			if (primed?.baseHasExtensions) {
+				try { durable(join(pathOf(args.runId), "unsafe-base"), "1\n"); } catch {}
+				return { refused: "fork-unsafe-extensions" };
+			}
+			return primed;
+		} catch { return refused("unreadable"); }
+		finally { archiveBusy = false; }
+	}
+	async function capturePoint({ runId, entryId, position = "at", transcriptPath, offset, ...args } = {}) {
+		if (!root || !ID.test(runId ?? "") || (entryId !== undefined && !ENTRY.test(entryId)) || !POSITIONS.has(position) || !Number.isSafeInteger(offset) || offset <= 0 || offset > L.maxBytes || !["frozen", "dead"].includes(args.quiesced)) return refused("invalid");
+		if (archiveBusy) return refused("busy");
+		archiveBusy = true;
+		try {
+			dirs(runId);
+			directory(pointsOf(runId), true);
+			const bytes = readRegular(transcriptPath, L.maxBytes).subarray(0, offset);
+			if (bytes.length !== offset) return refused("checkpoint-mismatch");
+			entryId ??= forkPointEntry(bytes);
+			if (!ENTRY.test(entryId ?? "")) return refused("checkpoint-unsafe");
+			if (pointRecord(runId, entryId, position)) return { ok: true, unchanged: true };
+			const names = fs.readdirSync(pointsOf(runId)).filter((n) => /^[0-9a-f]{64}\.json$/.test(n));
+			if (names.length >= L.maxPoints) return refused("point-capacity");
+			const entries = parseEntries(bytes);
+			if (entries.at(-1)?.id !== entryId || forkPointEntry(bytes) !== entryId || position !== "at") return refused("checkpoint-mismatch");
+			const current = await archive.readManifest(runId);
+			const seq = current.ok ? current.manifest.seq + 1 : 1;
+			if (seq > L.maxPoints) return refused("point-capacity");
+			const saved = await archive.snapshot({ ...args, runId, seq, transcript: { srcFile: transcriptPath, offset } });
+			if (!saved.ok) return saved;
+			if (saved.manifest.workspace.partial || saved.manifest.workspace.ignoredDropped) return refused("checkpoint-partial");
+			const point = { entryId, position, seq, transcriptSha256: saved.manifest.transcript.sha256, bytes: offset, baseSha: args.baseSha };
+			if (point.transcriptSha256 !== digest(bytes)) return refused("checkpoint-mismatch");
+			durable(join(pointsOf(runId), `${pointKey(entryId, position)}.json`), JSON.stringify(point));
+			syncDir(pointsOf(runId));
+			return { ok: true, point };
+		} catch { return refused("checkpoint-unreadable"); }
+		finally { archiveBusy = false; }
+	}
+	async function readPoint(options) {
+		try {
+			const source = read(options);
+			if (!source.ok) return source;
+			if (archive.readBase) {
+				const base = await archive.readBase(options.runId);
+				if (base?.unavailable) return base;
+				if (!base?.ok || base.baseSha !== source.manifest.baseSha) return refused("base-missing");
+			}
+			if (source.point?.base) return source;
+			if (!source.point) return refused("checkpoint-missing");
+			const saved = await archive.readManifest(options.runId, { seq: source.point.seq });
+			if (saved?.unavailable) return saved;
+			if (saved?.reason === "internal-error") return { unavailable: "checkpoint-unreadable" };
+			if (!saved.ok || saved.manifest.workspace.partial || saved.manifest.workspace.ignoredDropped || saved.manifest.transcript.sha256 !== source.point.transcriptSha256 || saved.manifest.transcript.bytes !== source.point.bytes || saved.manifest.workspace.baseSha !== source.manifest.baseSha) return refused("checkpoint-mismatch");
+			// Bind the archived prefix to THIS immutable source, not merely to an entry id repeated elsewhere.
+			const prefix = readRegular(source.transcriptPath, L.maxBytes).subarray(0, source.point.bytes);
+			if (digest(prefix) !== source.point.transcriptSha256 || forkPointEntry(prefix) !== source.point.entryId) return refused("checkpoint-mismatch");
+			return { ...source, checkpoint: saved.manifest };
+		} catch (error) {
+			return retryableStoreError(error) ? { unavailable: error.code } : { unavailable: "checkpoint-unreadable" };
+		}
+	}
+	async function restorePoint({ intoWorkspace, ...options }) {
+		const source = await readPoint(options);
+		if (!source.ok || source.point.base) return source;
+		const restored = await archive.restore({ runId: options.runId, manifest: source.checkpoint, intoWorkspace });
+		return restored.refused || restored.skipped || restored.unavailable ? restored : { ok: true, ...restored };
+	}
+	async function sweep() {
+		if (!root) return { removed: 0 };
+		let removed = 0;
+		try {
+			directory(root);
+			for (const key of fs.readdirSync(root)) {
+				if (!KEY.test(key) || !fs.lstatSync(join(root, key)).isDirectory()) continue;
+				let runId, at;
+				try { const age = sweepAge(JSON.parse(readRegular(join(root, key, "manifest.json"), 8192)), key); if (age) ({ runId, at } = age); } catch {}
+				if (at === undefined) {
+					try {
+						const origin = JSON.parse(readRegular(join(root, key, "origin.json"), 4096));
+						if (Object.keys(origin).length === 2 && ID.test(origin.runId ?? "") && forkSourceKey(origin.runId) === key && Number.isSafeInteger(origin.at) && origin.at >= 0) { runId = origin.runId; at = origin.at; }
+					} catch {}
+				}
+				if (at === undefined) at = fs.lstatSync(join(root, key)).mtimeMs;
+				if (now() - at <= L.ttlMs) continue;
+				if (runId) await archive.remove(runId);
+				fs.rmSync(join(root, key), { recursive: true, force: true });
+				removed++;
+			}
+			return { removed };
+		} catch { return refused("sweep-failed"); }
+	}
+	return { publish, read, primeBase, capturePoint, readPoint, restorePoint, sweep, baseSourceUrl: (runId) => archive?.baseSourceUrl(runId) };
+}

package/src/get-token.mjs

@@ -120,7 +120,7 @@ export async function makeGitHubAuth(cfg, deps = {}) {
 			// for `{ metadata: "read" }`, so the token it holds for that one question cannot write anything
 			// even if leaked. Job mints never pass this and keep the installation's full grant -- narrowing
 			// is the caller's statement of intent, not a default this mint could guess.
-			const permissions = job?.permissions;
+			const permissions = job?.purpose === "answer-draft" ? { contents: "read", issues: "read", pull_requests: "read", metadata: "read" } : job?.permissions;
 			let minted;
 			try {
 				const appAuth = createAppAuth({ ...auth, request: mintRequest });

package/src/git-dirty.mjs

@@ -1,30 +1,135 @@
 import { execFileSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
 import { GIT_READ_FLAGS } from "./git-hardening.mjs";
 
 /**
  * Report a folder's git working-tree state: `true` = dirty, `false` = clean, `null` = not a usable
- * git repository. Reads the WORKING TREE via `git status --porcelain` — distinct from
- * flow-gate.mjs's object-store read, which reads committed content at a pinned SHA; the two are kept
- * separate on purpose. `exec` is injectable for tests.
+ * git repository. Reads the WORKING TREE via `git status --porcelain`, distinct from flow-gate.mjs's
+ * object-store read, which reads committed content at a pinned SHA; the two are kept separate on purpose.
+ * `exec` and `fs` are injectable for tests.
  *
- * HARDENED, and this is the site where it is not hypothetical. `git status` REFRESHES THE INDEX, so it
- * invokes `core.fsmonitor` -- an operator-supplied command -- where `rev-parse` does not. The folder this
- * reads is the same path a local job mounts at /workspace with write access, so the agent can write
- * `.git/config` and the next `pi-dispatch run` on that folder executes it ON THE HOST, outside any
- * container. This file was invisible to the sweep that hardened its six siblings, because that census
- * grepped for the flags that were PRESENT and this one had none.
+ * THE FOLDER'S OWN GIT CONFIG IS NEVER READ BY THE STATUS. The folder is the path a local job mounts at
+ * /workspace with write access, so the agent can write its `.git/config` and `.git/info/attributes`, and
+ * `git status` hashes every stat-dirty file through the clean filter those name: a command, run ON THE HOST
+ * by the next `pi-dispatch run` or console start. `-c` cannot neutralise a filter whose driver name is not
+ * known in advance, and git has no switch that skips a repository's local config. So the status runs
+ * against a scratch git directory this function writes itself: HEAD at the folder's commit, the folder's
+ * objects reached through `objects/info/alternates`, a copy of its index with every assume-unchanged and
+ * skip-worktree bit cleared (an agent could set them to hide a change), and a config
+ * holding only the `core` settings that change how a file is compared (each value checked to be a plain
+ * word). Its `info/exclude` is not used either. A filter the working tree's `.gitattributes` names then has no
+ * driver here and is not run, unless the operator's own global config defines one by that name: then the operator's
+ * command runs, on content the agent chose (LFS needs exactly that).
+ *
+ * The operator's own global and system config still apply: this runs as the operator (the CLI, the
+ * console), that config is theirs and outside the container, and an LFS repository needs its filter.
+ *
+ * The paths and the commit come from `rev-parse`, hardened, which reads config but refreshes no index and
+ * so runs no filter and no fsmonitor. An unborn HEAD is `null`: every caller refuses that folder first.
  */
-export function gitDirty(folder, { exec = execFileSync } = {}) {
+export function gitDirty(folder, { exec = execFileSync, fs = defaultFs } = {}) {
+	let scratch = null;
 	try {
-		const out = exec("git", [...GIT_READ_FLAGS, "-C", folder, "status", "--porcelain"], { encoding: "utf8" });
-		return out.trim().length > 0;
+		const read = (args) => String(exec("git", [...GIT_READ_FLAGS, "-C", folder, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }));
+		const [gitDir, commonDir, format, head] = read(["rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir", "--show-object-format", "--verify", "HEAD^{commit}"]).split("\n");
+		if (!isAbsolute(gitDir ?? "") || !isAbsolute(commonDir ?? "") || !/^(sha1|sha256)$/.test(format ?? "") || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(head ?? "")) return null;
+		const core = compareSettings(read);
+		scratch = fs.mkdtempSync(join(tmpdir(), "pi-dispatch-git-read-"));
+		fs.mkdirSync(join(scratch, "refs"));
+		fs.mkdirSync(join(scratch, "objects", "info"), { recursive: true });
+		fs.mkdirSync(join(scratch, "info"));
+		fs.writeFileSync(join(scratch, "HEAD"), `${head}\n`);
+		fs.writeFileSync(join(scratch, "objects", "info", "alternates"), `${join(commonDir, "objects")}\n`);
+		const sha256 = format === "sha256";
+		const lines = ["[core]", `\trepositoryformatversion = ${sha256 ? 1 : 0}`, "\tbare = false", ...core.map(([k, v]) => `\t${k} = ${v}`)];
+		if (sha256) lines.push("[extensions]", "\tobjectformat = sha256");
+		fs.writeFileSync(join(scratch, "config"), `${lines.join("\n")}\n`);
+		// `info/exclude` is NOT copied: it lives in the agent-writable `.git`, and `*` there would hide the operator's
+		// untracked work. A personal exclude list then reads as dirty, which is the safe side (`--force` is the way past).
+		copyRegular(fs, join(gitDir, "index"), join(scratch, "index"));
+		// A split index keeps its shared part beside it; without it the copy cannot be read and the answer is null.
+		for (const name of safeList(fs, gitDir)) if (/^sharedindex\.[0-9a-f]{40,64}$/.test(name)) copyRegular(fs, join(gitDir, name), join(scratch, name));
+		const env = { ...withoutGitEnv(process.env), GIT_DIR: scratch, GIT_WORK_TREE: folder, GIT_INDEX_FILE: join(scratch, "index"), GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" };
+		const scratchGit = (args, input) => exec("git", [...GIT_READ_FLAGS, ...args], { encoding: "utf8", env, cwd: scratch, ...(input === undefined ? { stdio: ["ignore", "pipe", "ignore"] } : { input, stdio: ["pipe", "pipe", "ignore"] }) });
+		// The index is agent-written too, and an assume-unchanged or skip-worktree bit hides every later change to that
+		// path from `status`. Both are cleared in the COPY (one flag per call: given together, git applies only one). A
+		// sparse checkout's skipped paths then read as deleted, so dirty: the safe side again.
+		const flagged = String(scratchGit(["ls-files", "-v", "-z"]))
+			.split("\0")
+			.filter((e) => e.length > 2 && e[1] === " " && (e[0] === "S" || (e[0] >= "a" && e[0] <= "z")))
+			.map((e) => e.slice(2));
+		if (flagged.length > 0) {
+			const list = `${flagged.join("\0")}\0`;
+			scratchGit(["update-index", "-z", "--no-skip-worktree", "--stdin"], list);
+			scratchGit(["update-index", "-z", "--no-assume-unchanged", "--stdin"], list);
+		}
+		const out = scratchGit(["-c", "core.untrackedCache=false", "-c", "status.submoduleSummary=false", "status", "--porcelain", "--ignore-submodules=all"]);
+		return String(out).trim().length > 0;
 	} catch {
 		return null;
+	} finally {
+		if (scratch) {
+			try {
+				fs.rmSync(scratch, { recursive: true, force: true });
+			} catch {}
+		}
+	}
+}
+
+const defaultFs = { mkdtempSync, mkdirSync, writeFileSync, rmSync, openSync, fstatSync, closeSync, readFileSync, readdirSync };
+
+/** The `core` settings that change how a working-tree file is compared, never one that names a command. */
+const COMPARE_KEYS = ["autocrlf", "eol", "ignorecase", "precomposeunicode", "filemode", "symlinks", "checkstat", "trustctime"];
+
+/** The folder's values for COMPARE_KEYS, each a plain word, read with `git config` (a read: no filter, no hook). */
+function compareSettings(read) {
+	let out = "";
+	try {
+		out = read(["config", "--get-regexp", `^core\\.(${COMPARE_KEYS.join("|")})$`]);
+	} catch {
+		return []; // exit 1: none set
+	}
+	const seen = new Map();
+	for (const line of out.split("\n")) {
+		const m = /^core\.([a-z]+) ([A-Za-z0-9]{1,16})$/.exec(line.trim());
+		if (m && COMPARE_KEYS.includes(m[1])) seen.set(m[1], m[2]);
+	}
+	return [...seen];
+}
+
+/**
+ * Copies `from` when it is a regular file of at most 512 MiB; anything else is skipped. Opened O_NOFOLLOW and judged by
+ * the descriptor, so a link swapped in after a check can never be read through.
+ */
+function copyRegular(fs, from, to) {
+	let fd = null;
+	try {
+		fd = fs.openSync(from, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+		const st = fs.fstatSync(fd);
+		if (!st.isFile() || st.size > 512 * 1024 * 1024) return;
+		fs.writeFileSync(to, fs.readFileSync(fd));
+	} catch {
+		// absent, a link, or unreadable: the copy is skipped and git answers from what it has
+	} finally {
+		if (fd !== null) fs.closeSync(fd);
+	}
+}
+
+function safeList(fs, dir) {
+	try {
+		return fs.readdirSync(dir);
+	} catch {
+		return [];
 	}
 }
 
+/** The environment without any GIT_* variable, so the caller's own GIT_DIR or index cannot redirect the read. */
+function withoutGitEnv(env) {
+	return Object.fromEntries(Object.entries(env).filter(([k]) => !k.startsWith("GIT_")));
+}
+
 /**
  * Why `folder` cannot be a local job's folder, as one sentence with its fix, or null when it can (issue #524).
  *

package/src/git-hardening.mjs

@@ -31,3 +31,88 @@ export const GIT_SAFE_CONFIG = Object.freeze(["-c", "core.hooksPath=/dev/null",
  * convenience of this one.
  */
 export const GIT_READ_FLAGS = Object.freeze([...GIT_SAFE_CONFIG, "--no-pager"]);
+
+/**
+ * The flags for every git spawned against the WORKSPACE CHECKPOINT STORE (issue #645). Unlike the two
+ * constants above, which guard a read of a repository the worker cloned, the store is written while a
+ * paid job is paused, from a tree the agent fully controls, so the prefix pins every knob that could make
+ * git run a program, sign, prompt, or do background work in the middle of that window:
+ *
+ * - `protocol.ext.allow=never` and an empty `credential.helper`: the store only ever talks `file://`, and
+ *   nothing it does may reach a helper or an `ext::` command.
+ * - `commit.gpgSign`/`tag.gpgSign=false`: `gpg.program` is a command, and a signing default in some
+ *   config would run it on the host.
+ * - `gc.auto=0`, `maintenance.auto=false`: an auto-gc forked mid-snapshot holds the store's packs while
+ *   the checkpointer repacks on its own schedule; two writers on one object store is the race to avoid.
+ * - `core.protectNTFS`/`core.protectHFS=true`: git's own dotgit folding, on whatever the host is, so the
+ *   store refuses the same names `checkpoint-paths.mjs` does.
+ * - `transfer.fsckObjects`/`fetch.fsckObjects=true`: the base fetch is the one place objects arrive from
+ *   outside; a malformed tree there (a `..` entry, a `.GIT`) is refused before it is ever stored.
+ * - `core.untrackedCache=false`: the untracked cache is written into the index of whatever work tree git
+ *   was pointed at; the one command given a work tree (`check-ignore`) must write nothing there.
+ */
+export const STORE_GIT_FLAGS = Object.freeze([
+	...GIT_SAFE_CONFIG,
+	"-c",
+	"protocol.ext.allow=never",
+	"-c",
+	"credential.helper=",
+	"-c",
+	"commit.gpgSign=false",
+	"-c",
+	"tag.gpgSign=false",
+	"-c",
+	"gc.auto=0",
+	"-c",
+	"maintenance.auto=false",
+	"-c",
+	"core.protectNTFS=true",
+	"-c",
+	"core.protectHFS=true",
+	"-c",
+	"transfer.fsckObjects=true",
+	"-c",
+	"fetch.fsckObjects=true",
+	"-c",
+	"core.untrackedCache=false",
+	"--no-pager",
+]);
+
+/**
+ * The environment for a store git, built FROM NOTHING rather than from `process.env`. A spread would carry
+ * whatever the worker's own environment holds into git: `GIT_DIR`/`GIT_WORK_TREE` from a developer shell,
+ * `GIT_SSH_COMMAND`, `GIT_EXTERNAL_DIFF`, `GIT_CONFIG_PARAMETERS` (every one of them a way to run a
+ * program or read another repository), plus every secret the worker holds. A deny list would have to name
+ * all of those and every one git adds later; an allow list of exactly what git needs cannot drift that way.
+ *
+ * `HOME` and `XDG_CONFIG_HOME` both point at an empty per-run directory, so neither `~/.gitconfig` nor
+ * `$XDG_CONFIG_HOME/git/{config,attributes,ignore}` can exist; `GIT_CONFIG_GLOBAL=/dev/null` says the same
+ * for the global file, and the two NOSYSTEM switches for the system ones. `GIT_OPTIONAL_LOCKS=0` keeps a
+ * status-like read from writing an index; `GIT_NO_REPLACE_OBJECTS` stops a `refs/replace` ref swapping the
+ * object a commit names; `GIT_PROTOCOL_FROM_USER=0` turns every "user"-policy protocol off by default (the
+ * two `file://` fetches re-enable `file` explicitly, at their call sites). `LC_ALL=C` keeps any message we
+ * match on in one language.
+ */
+// env-internal PATH: the worker's own search path, passed through so the store git finds its helpers (`git-upload-pack`).
+export function storeGitEnv({ gitDir, home, path = process.env.PATH }) {
+	// Empty and relative PATH entries are dropped: both resolve against the CWD, so a `git-upload-pack`
+	// (or any helper git execs) found there would be whatever the directory git runs in happens to hold.
+	const safePath = String(path ?? "")
+		.split(":")
+		.filter((entry) => entry.startsWith("/"))
+		.join(":");
+	return {
+		PATH: safePath || "/usr/bin:/bin",
+		HOME: home,
+		XDG_CONFIG_HOME: home,
+		GIT_DIR: gitDir,
+		GIT_CONFIG_NOSYSTEM: "1",
+		GIT_CONFIG_GLOBAL: "/dev/null",
+		GIT_ATTR_NOSYSTEM: "1",
+		GIT_TERMINAL_PROMPT: "0",
+		GIT_OPTIONAL_LOCKS: "0",
+		GIT_NO_REPLACE_OBJECTS: "1",
+		GIT_PROTOCOL_FROM_USER: "0",
+		LC_ALL: "C",
+	};
+}