@edgehero/pi-dispatch 1.0.0 → 1.2.0

package/src/session-store.mjs

@@ -44,6 +44,54 @@ import { sessionKeyFor } from "./session-key.mjs";
 export const SESSION_FILE_NAME = "current.jsonl";
 const PI_VERSION_FILE = "pi-version";
 const LOCK_FILE = "lock";
+/**
+ * How many times in a row this key's transcript has been HANDED TO A CONTAINER. A counter rather than a
+ * derivation, because there is nothing to derive it from: the run record deliberately carries no session
+ * key (DES-SESSION-KEY-IS-DERIVED-NOT-INDEXED), so counting past runs would need the key->record index
+ * that entry refuses. One integer beside the transcript it describes is not that index; it is keyed state
+ * written where the key already is, and it answers exactly one question rather than being a query
+ * surface. Maintained even when no bound is set, deliberately -- see the write in promoteSession.
+ *
+ * IT COUNTS THE HOST'S DELIVERIES, NOT PI'S CONTINUATIONS, and that is the whole security of this bound.
+ * It counted pi's `resumed` first, on the reasoning that a transcript pi declined to continue extended
+ * nothing. That reasoning is wrong here, because the agent owns /session and therefore chooses what pi
+ * makes of the file: a transcript carrying a valid header and payload on lines pi's parser DROPS is
+ * delivered by the host every run while pi reports zero messages, so the counter reset every run and the
+ * chain bound never fired -- measured, not theorised. The host's own decision to hand the file over is
+ * the one fact in this exchange that nothing inside the container can influence.
+ */
+const RESUME_CHAIN_FILE = "resume-chain";
+/**
+ * How full the context was when the run that wrote this transcript ended, as `<tokens> <window>`. Both
+ * numbers, not a precomputed percentage: the denominator is what makes the numerator readable later, and
+ * an operator looking at a refusal should be able to see what it was judged against.
+ *
+ * Reported BY THE CONTAINER, which is the only place the number exists: pi computes it from the session
+ * it is holding. That puts it at the same trust level as `turns` and `tokens`, and the residual is
+ * recorded in OQ-003 rather than papered over -- there is no host-side alternative that is not equally
+ * agent-influenced, since the transcript itself is agent-written.
+ */
+const CONTEXT_FILE = "context";
+/** Both sidecar formats are a handful of bytes. Generous, and still nowhere near a job's wall clock. */
+const SIDECAR_MAX_BYTES = 4096;
+/**
+ * The host-effective provider and model as one token, or null when the job names neither.
+ *
+ * CONSERVATIVE BY CONSTRUCTION: the sidecar is whitespace-delimited, so a value carrying a space would
+ * split the record and be read back as a different field. Rather than escape, refuse: anything outside
+ * the charset the run record already validates model ids against is no identity, and no identity means
+ * the reading stays usable rather than being thrown away.
+ */
+function modelIdentity(job) {
+	const provider = typeof job?.provider === "string" ? job.provider : "";
+	const model = typeof job?.model === "string" ? job.model : "";
+	if (provider === "" || model === "") return null;
+	// Lowercased first, the same normalisation the run record's own model ids get, so a trigger written
+	// `Claude-Sonnet` and one written `claude-sonnet` are one model rather than two -- and so that a
+	// perfectly ordinary id does not fall out of the charset below and silently stop stamping.
+	const id = `${provider}/${model}`.toLowerCase();
+	return /^[a-z0-9][a-z0-9._:/-]{0,127}$/.test(id) ? id : null;
+}
 
 /**
  * Read-path outcomes. Every one is a named cold start rather than a bare `false`: a feature that fails
@@ -56,6 +104,9 @@ export function makeSessionStore({
 	sessionsDir,
 	ttlDays,
 	maxBytes,
+	maxAgeDays = 0,
+	maxResumeChain = 0,
+	maxContextPct = null,
 	log = () => {},
 	now = () => Date.now(),
 	fs = { copyFileSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync },
@@ -83,11 +134,16 @@ export function makeSessionStore({
 			// CLI run, an unresolvable head ref), so it gets no mount and no transcript on disk.
 			if (key === null) return null;
 
+			// The model this job will actually run, for the context bound. A key is (kind, repo, ref) and
+			// carries NO model, so two triggers on one issue can name different ones, and the same token
+			// count is 78% of a 32k window and 2.5% of a 1M one. Carried on the session object rather than
+			// read again at promote time, so the reading is stamped with the model that produced it.
+			const modelId = modelIdentity(job);
 			const hostDir = join(jobDir, "session");
 			const staged = join(hostDir, SESSION_FILE_NAME);
 			fs.mkdirSync(hostDir, { recursive: true, mode: 0o700 });
 
-			const verdict = readCanonical(key, piVersion);
+			const verdict = readCanonical(key, piVersion, modelId);
 			if (verdict.resume) {
 				fs.copyFileSync(canonicalFile(key), staged);
 			} else {
@@ -98,7 +154,7 @@ export function makeSessionStore({
 				fs.writeFileSync(staged, "");
 			}
 			log("session_resolved", { key, resume: verdict.resume, reason: verdict.reason });
-			return { hostDir, key, ...verdict };
+			return { hostDir, key, modelId, ...verdict };
 		} catch (err) {
 			// A history fault must never fail the prepare that asked.
 			log("session_store_failed", { phase: "resolve", reason: err?.message });
@@ -114,7 +170,7 @@ export function makeSessionStore({
 	 * one key is a real shape (REQ-QUEUE-BURST-NO-DROP), and last-write-wins there would interleave two
 	 * agents' turns into one transcript.
 	 */
-	function promoteSession(session, { piVersion = null } = {}) {
+	function promoteSession(session, { piVersion = null, context = null } = {}) {
 		// The second DI-seam backstop, and unreachable for the same reason as the `!sessionsDir` return
 		// above: sessionKeyFor is total and binary (null, or 32 hex chars), so resolveSession returns null
 		// rather than a keyless session, and processor.mjs only calls this when prepare handed it one. Kept
@@ -137,16 +193,42 @@ export function makeSessionStore({
 			let fd;
 			try {
 				fd = fs.openSync(lock, "wx"); // exclusive create IS the lock; no daemon, no lease
-			} catch {
+			} catch (err) {
+				// EEXIST is the only failure that MEANS locked. A read-only directory, a full disk or a
+				// vanished store all failed to create the lock too, and reporting those as `locked` sends an
+				// operator looking for a stuck lock file that does not exist. Anything else falls through to
+				// the outer catch and reports `promote-failed`, which is what actually happened.
+				if (err?.code !== "EEXIST") throw err;
 				log("session_promote_skipped", { key: session.key, reason: "locked" });
 				return { promoted: false, reason: "locked" };
 			}
 			try {
 				// Atomic swap: a reader either sees the old file or the new one, never a half-written one.
 				const tmp = `${canonicalFile(session.key)}.incoming`;
+				try {
+					// `copyFileSync` follows a link at the DESTINATION, so a link planted at this name would
+					// receive the whole transcript and leave the canonical path pointing at it. The key
+					// directory's name is derived rather than random, so the path is precomputable by anyone
+					// who knows the repository and the branch; unlinking removes the link, never its target.
+					fs.unlinkSync(tmp);
+				} catch {
+					// Absent is the desired state.
+				}
 				fs.copyFileSync(staged, tmp);
 				fs.renameSync(tmp, canonicalFile(session.key));
 				fs.writeFileSync(join(dir, PI_VERSION_FILE), String(piVersion ?? ""));
+				// The two sidecars, immediately after the swap and under the same lock. NOT part of the swap
+				// itself, which is one rename and cannot be widened: what the lock buys them is that no
+				// other job can interleave, and what the ordering buys them is that they never describe a
+				// transcript older than the one now in place.
+				//
+				// EACH IS CAUGHT SEPARATELY, and that is not defensiveness for its own sake. These writes
+				// run AFTER the transcript is already promoted, so letting one throw would return
+				// `promote-failed` for a promotion that demonstrably happened -- a record that says the next
+				// run will cold start when it will in fact resume, which is worse than the bookkeeping loss
+				// it is reporting.
+				writeSidecar(dir, RESUME_CHAIN_FILE, session.key, chainValue(session));
+				writeContextSidecar(dir, session, context);
 			} finally {
 				fs.closeSync(fd);
 				try {
@@ -164,6 +246,79 @@ export function makeSessionStore({
 		}
 	}
 
+	/**
+	 * The counter's next value. `session.resume` is the HOST's own decision to hand this key's transcript
+	 * to a container, which is the only half of the exchange the container cannot influence; `resumed` (the
+	 * container's verdict) is deliberately ignored for the counter and kept in the signature only because
+	 * the record's own merge still wants it. A cold start resets, so a lineage always gets a fresh start
+	 * from its next COMPLETED run -- a run that never completes promotes nothing and resets nothing, which
+	 * is the safe direction: the key simply keeps cold-starting.
+	 */
+	function chainValue(session) {
+		return String(session.resume === true ? readResumeChain(session.key) + 1 : 0);
+	}
+
+	/**
+	 * One sidecar write. Two properties, both deliberate.
+	 *
+	 * **It cannot write THROUGH a link.** `writeFileSync` follows one, which would turn a planted symlink
+	 * in a key directory into a truncating write of any worker-writable file, with the container's own
+	 * integers as the payload. Writing a temp and renaming over the name replaces whatever is there --
+	 * link included -- with a regular file, and never opens the link's target. The temp is unlinked first
+	 * for the same reason, since a planted link at THAT name would be the same hole one step along. The
+	 * read side's `lstat` guard is the other half of this; neither is sufficient alone.
+	 *
+	 * **It is never fatal.** This runs AFTER the transcript is already promoted, so throwing would return
+	 * `promote-failed` for a promotion that demonstrably happened, telling an operator the next run will
+	 * cold start when it will in fact resume. The bookkeeping loss is logged and the truth is kept.
+	 */
+	function writeSidecar(dir, name, key, value) {
+		const file = join(dir, name);
+		const tmp = `${file}.incoming`;
+		try {
+			try {
+				fs.unlinkSync(tmp);
+			} catch {
+				// Absent is the desired state.
+			}
+			fs.writeFileSync(tmp, value);
+			fs.renameSync(tmp, file);
+		} catch (err) {
+			log("session_sidecar_failed", { key, file: name, reason: err?.message });
+		}
+	}
+
+	/**
+	 * The context sidecar, whose three cases are all different.
+	 *
+	 * A run that RESUMED and measured nothing keeps the previous reading: the transcript it promoted is
+	 * the old one extended, so the last real measurement is the closest true statement available, and a
+	 * zero would read as "the context emptied", which cannot have happened.
+	 *
+	 * A COLD START, though, promoted a transcript that shares nothing with the one the old reading
+	 * described, so the reading must GO. Keeping it is what turned a single high measurement into a key
+	 * that refused itself forever: the gate read a stale number, cold-started, and the cold start left the
+	 * same number behind for the next run to read. That loop had no exit that did not involve deleting the
+	 * store by hand.
+	 */
+	function writeContextSidecar(dir, session, context) {
+		const file = join(dir, CONTEXT_FILE);
+		if (session.resume !== true) {
+			try {
+				fs.unlinkSync(file);
+			} catch {
+				// Absent is the desired state, so failing to remove what is not there is success.
+			}
+			return;
+		}
+		if (!context) return;
+		// The model rides along because the ratio is meaningless without it: a key is (kind, repo, ref) and
+		// carries no model, so two triggers on one issue can run different ones, and 25k tokens is 78% of a
+		// 32k window and 2.5% of a 1M one. A reading from another model is not a reading about this one.
+		const stamp = session.modelId ? ` ${session.modelId}` : "";
+		writeSidecar(dir, CONTEXT_FILE, session.key, `${context.tokens} ${context.window}${stamp}`);
+	}
+
 	function keyDir(key) {
 		return join(sessionsDir, key);
 	}
@@ -172,7 +327,7 @@ export function makeSessionStore({
 	}
 
 	/** The read path, gate by gate. The FIRST miss wins and names itself. */
-	function readCanonical(key, piVersion) {
+	function readCanonical(key, piVersion, modelId) {
 		const file = canonicalFile(key);
 		const check = inspectFile(file);
 		if (!check.ok) return COLD(check.reason);
@@ -184,26 +339,150 @@ export function makeSessionStore({
 		// repair that mid-run, so a version change is a cold start rather than a mid-run failure. An
 		// image that declares no version never resumes -- the safe direction, never "assume it matches".
 		if (piVersion === null) return COLD("pi-version-changed");
-		let stamped = null;
-		try {
-			stamped = String(fs.readFileSync(join(keyDir(key), PI_VERSION_FILE), "utf8")).trim();
-		} catch {
-			return COLD("pi-version-changed");
+		// Through the same guarded read as the two sidecars below it. This one predates them and was the
+		// one unguarded read left in the key directory; a symlink here would have decided a gate on the
+		// contents of some other file entirely.
+		const stamped = readSidecar(key, PI_VERSION_FILE);
+		if (stamped === null || stamped !== piVersion) return COLD("pi-version-changed");
+
+		// How many times in a row this key has already been resumed. Placed HERE, ahead of the header read,
+		// for two reasons. It is a small sidecar read exactly like the pi-version arm above it, so refusing
+		// on it skips pulling a transcript that may be megabytes; and unlike every other arm it asks about
+		// the LINEAGE rather than the file, so it needs nothing the file could tell it.
+		//
+		// The cost of that placement, stated rather than left to be discovered: a transcript that is both
+		// chain-exhausted AND corrupt reports the chain. That is the intentional refusal of the two, and the
+		// corruption is not hidden, only deferred -- this cold start's own promotion resets the counter, so
+		// the very next run reads the file and reports `unparseable`.
+		//
+		// FAILS OPEN on absence, which is the opposite of the age gate one arm down and deliberate. Every
+		// key that existed before this counter did has no file, and reading that as "already exhausted"
+		// would cold-start an operator's entire store the day they set the bound.
+		if (maxResumeChain > 0 && readResumeChain(key) >= maxResumeChain) return COLD("resume-chain-too-long");
+
+		// How full the context already is, against a ceiling the HOST owns. Not a duplicate of pi's own
+		// compaction threshold and deliberately not read from it: pi's is settable in a serviced repo's
+		// .pi/settings.json, so it is a line the repository can move, and this one cannot be. Past that
+		// threshold what a resumed job replays is not the transcript but a model-written summary of it,
+		// produced while that model was reading attacker-authored text (OQ-003), so this is a safety bound
+		// before it is an economic one.
+		//
+		// FAILS OPEN and INVENTS NO DENOMINATOR. No sidecar (every key promoted before this shipped, and
+		// every key under an image whose runner predates it), a compaction that left pi's own count
+		// unknown, or a window of zero all mean the gate has nothing to act on, and a gate with nothing to
+		// act on passes. A bytes-against-window guess was rejected rather than used as a fallback: the
+		// transcript is the whole branch INCLUDING what compaction folded away, so it over-reads exactly
+		// past the threshold this exists to catch, and there is no bytes-to-tokens calibration here to
+		// make it mean anything.
+		if (maxContextPct !== null) {
+			const seen = readContext(key);
+			// A reading STAMPED WITH ANOTHER MODEL is not a reading about this one, and using it is wrong in
+			// both directions: it refuses a job whose window is far larger than the one that was measured,
+			// and it passes one whose window is far smaller. Unknown on either side stays usable, so a
+			// deployment that names no model per trigger keeps the bound it had.
+			const foreign = seen !== null && seen.modelId !== null && modelId !== null && seen.modelId !== modelId;
+			if (seen !== null && !foreign && (seen.tokens * 100) / seen.window >= maxContextPct) return COLD("context-too-full");
 		}
-		if (stamped !== piVersion) return COLD("pi-version-changed");
 
-		// Cheapest real shape check, and the last one: the first line must be a pi session header. Anything
-		// else the runner would throw on, so refusing here keeps the container's degrade path for genuine
-		// surprises rather than for a file we could already tell was wrong.
+		// Cheapest real shape check, and the last one before the header's own contents are used: the first
+		// line must be a pi session header. Anything else the runner would throw on, so refusing here keeps
+		// the container's degrade path for genuine surprises rather than for a file we could already tell
+		// was wrong.
+		let header = null;
 		try {
 			const head = String(fs.readFileSync(file, "utf8")).split("\n", 1)[0];
-			if (JSON.parse(head)?.type !== "session") return COLD("unparseable");
+			header = JSON.parse(head);
+			if (header?.type !== "session") return COLD("unparseable");
 		} catch {
 			return COLD("unparseable");
 		}
+
+		// The CONVERSATION's age, and it is a DIFFERENT CLOCK from `expired` above rather than a finer
+		// setting of it. The TTL reads the transcript's mtime, which the PROMOTE rename refreshes -- and only
+		// that: `copyFileSync` stamps its destination, never its source, so the resolve half leaves the
+		// canonical file's mtime alone (measured, because the obvious reading of the two call sites says
+		// otherwise). So `expired` is time since the last COMPLETED run on this key, and a lineage whose runs
+		// keep completing never expires however old its first turn is. pi's header carries the instant the
+		// session was created, so this
+		// costs no new persisted state -- the line is already read and parsed one gate up, and until now
+		// only its `type` was looked at.
+		//
+		// The arm is LAST because the earlier gates are cheaper and because a corrupt file is corrupt rather
+		// than old: `unparseable` must keep winning over this, or a damaged transcript would be reported as
+		// a lineage that aged out.
+		//
+		// UNREADABLE FAILS CLOSED, on the pi-version gate's precedent one arm up: a header with no usable
+		// timestamp cannot be shown to be young enough, and "assume it matches" is the direction that
+		// silently keeps resuming. Like `pi-version-changed`, one token covers all three causes (absent,
+		// wrong type, unparseable).
+		//
+		// A timestamp in the FUTURE passes, deliberately. It buys nothing to refuse one: the agent owns
+		// /session, so anything able to write a future timestamp is equally able to write the current one,
+		// and refusing would convert ordinary clock skew between a container and its host into a cold start
+		// for every key on the deployment.
+		if (maxAgeDays > 0) {
+			const started = Date.parse(typeof header.timestamp === "string" ? header.timestamp : "");
+			if (!Number.isFinite(started)) return COLD("conversation-too-old");
+			if (now() - started > maxAgeDays * 86400000) return COLD("conversation-too-old");
+		}
 		return { resume: true, reason: "resumed", bytes: check.bytes };
 	}
 
+	/**
+	 * Every sidecar read goes through here, and it is the same load-bearing check `inspectFile` makes on
+	 * the transcript: **`lstat`, regular files only.** The canonical store is host-only and never mounted,
+	 * so nothing in a container can plant a link here -- but the directory NAME is derived rather than
+	 * random (`sha256(kind, repo, ref)`), so anyone who knows the repository and the branch can compute it
+	 * and pre-create the path. `readFileSync` and `writeFileSync` both follow links, which would turn a
+	 * planted symlink into a read of any worker-readable file on the gate's path, and a promotion into a
+	 * truncating write of any worker-writable one. The transcript has been guarded against exactly this
+	 * since the feature shipped; these files inherit it rather than being the exception.
+	 *
+	 * SIZE-BOUNDED for the same reason the transcript is. Both formats are a handful of bytes, `maxBytes`
+	 * does not cover them, and reading a 2.5 GiB file on the job's own path costs half a minute of wall
+	 * clock before any container starts.
+	 */
+	function readSidecar(key, name) {
+		try {
+			const file = join(keyDir(key), name);
+			const st = fs.lstatSync(file);
+			if (!st.isFile() || st.size === 0 || st.size > SIDECAR_MAX_BYTES) return null;
+			return String(fs.readFileSync(file, "utf8")).trim();
+		} catch {
+			return null;
+		}
+	}
+
+	/**
+	 * The consecutive-delivery counter for a key, or 0 when there is not a readable one. Never throws and
+	 * never guesses: a missing, empty, corrupt or negative counter is 0, so the only way to be refused by
+	 * the chain bound is for this store to have written a number that reaches it.
+	 */
+	function readResumeChain(key) {
+		const raw = readSidecar(key, RESUME_CHAIN_FILE);
+		if (raw === null) return 0;
+		const n = Number.parseInt(raw, 10);
+		// `String(n) === raw` is the same anti-truncation guard config.mjs applies to every integer knob,
+		// and it is what keeps a corrupt "3.5" from being read as a chain of three.
+		return Number.isInteger(n) && n > 0 && String(n) === raw ? n : 0;
+	}
+
+	/**
+	 * The stored context occupancy for a key, or `null` when there is no measurement. Never throws, never
+	 * guesses, and never returns a partial: anything it cannot read as two positive integers is no
+	 * measurement at all, which the caller treats as "pass" rather than as zero.
+	 */
+	function readContext(key) {
+		const raw = readSidecar(key, CONTEXT_FILE);
+		if (raw === null) return null;
+		const [rawTokens, rawWindow, rawModel] = raw.split(/\s+/);
+		const tokens = Number.parseInt(rawTokens, 10);
+		const window = Number.parseInt(rawWindow, 10);
+		if (!Number.isInteger(tokens) || !Number.isInteger(window) || tokens < 0 || window <= 0) return null;
+		if (String(tokens) !== rawTokens || String(window) !== rawWindow) return null;
+		return { tokens, window, modelId: rawModel ?? null };
+	}
+
 	/**
 	 * lstat, REGULAR FILES ONLY -- and this is the one line in the file that is load-bearing security
 	 * rather than hygiene.

package/src/start.mjs

@@ -13,6 +13,7 @@ import { makeForgejoAuth } from "./forgejo-auth.mjs";
 import { makeForgejoHost } from "./forgejo-host.mjs";
 import { makeAzureAuth } from "./azure-auth.mjs";
 import { makeAzureHost } from "./azure-host.mjs";
+import { makeEgressPreflight } from "./egress.mjs";
 import { makeImagePreflight } from "./image-preflight.mjs";
 import { createWorker } from "./index.mjs";
 import { makeCollectChain } from "./outbox.mjs";
@@ -112,6 +113,22 @@ export function makeReaper({ log }) {
 				await exec("docker", ["rm", "-f", name]);
 				log("reaped_container", { name });
 			}
+			// REQ-EGRESS-ALLOWLIST: the per-job networks those containers were on. Swept AFTER the containers,
+			// because a network with a member still attached cannot be removed -- and swept by the SAME
+			// `pi-job-` filter, so the namespace rule that keeps an operator's live sandbox safe from the
+			// container reaper keeps their sandbox NETWORK safe too, with no second rule to remember.
+			//
+			// A crashed worker is the case this exists for: `runContainer`'s own finally removes the network
+			// on every ordinary path, so anything still here outlived a process that did not get to run it.
+			// A network still in use by something else fails to remove and is skipped, which is correct: this
+			// is a best-effort sweep and never a reason not to boot.
+			const { stdout: nets } = await exec("docker", ["network", "ls", "--filter", "name=pi-job-", "--format", "{{.Name}}"]);
+			for (const net of nets.split("\n").map((n) => n.trim()).filter(Boolean)) {
+				try {
+					await exec("docker", ["network", "rm", net]);
+					log("reaped_network", { network: net });
+				} catch {} // still in use, or already gone -- either way not this boot's problem
+			}
 		} catch (err) {
 			log("reaper_skipped", { reason: err?.message });
 		}
@@ -146,6 +163,7 @@ export async function startWorker(
 		makeSandboxReaper: makeSandboxReaperFn = makeSandboxReaper,
 		makeRunContainer: makeRunContainerFn = makeRunContainer,
 		makeImagePreflight: makeImagePreflightFn = makeImagePreflight,
+		makeEgressPreflight: makeEgressPreflightFn = makeEgressPreflight,
 		makeGitLabAuth: makeGitLabAuthFn = makeGitLabAuth,
 		makeGitLabHost: makeGitLabHostFn = makeGitLabHost,
 		makeForgejoAuth: makeForgejoAuthFn = makeForgejoAuth,
@@ -280,6 +298,9 @@ export async function startWorker(
 		sessionsDir: config.sessionsDir,
 		ttlDays: config.sessionsTtlDays,
 		maxBytes: config.sessionMaxBytes,
+		maxAgeDays: config.sessionMaxAgeDays,
+		maxResumeChain: config.sessionMaxResumeChain,
+		maxContextPct: config.sessionMaxContextPct,
 		log,
 	});
 	// Boot sweep, beside the log reaper and for the same reason it is beside rather than inside it: these
@@ -386,6 +407,12 @@ export async function startWorker(
 			// one who removes it would stay admitted. Contrast the staged-package manifest, correctly read once at
 			// boot because it is deploy-time state under a :ro mount; the host's image set is not.
 			imagePreflight: makeImagePreflightFn({ image: config.jobImage }),
+			// REQ-EGRESS-ALLOWLIST, and built here for the same reason the image preflight is: one deployment
+			// value, one place, so the gate that checks the proxy and the runner that attaches to its network
+			// cannot disagree about which proxy is meant. Nothing is memoised here either -- an operator who
+			// starts the proxy mid-day must not stay refused, and one who stops it must not stay admitted.
+			// Unarmed it spawns nothing at all, so a deployment without a policy pays for none of this.
+			egressPreflight: makeEgressPreflightFn({ proxy: config.egressProxy, armed: config.egress }),
 			// Completed-only, so a policy or infra exit leaves the canonical transcript byte-identical and a
 			// retry starts from what the first attempt did (CONST-RETRY-INFRA-ONLY).
 			promoteSession: sessionStore.promoteSession,
@@ -397,6 +424,8 @@ export async function startWorker(
 			runContainer: makeRunContainerFn({
 				image: config.jobImage,
 				hostEnv: env,
+				egress: config.egress, // REQ-EGRESS-ALLOWLIST: the per-job network and the proxy variables
+				egressProxy: config.egressProxy,
 				openJobLog,
 				globalPiDir: config.globalPiDir, // REQ-GLOBAL-PI-OVERLAY: :ro overlay mount when configured
 				allowGlobalExtensions: config.allowGlobalExtensions,

package/src/triggers.mjs

@@ -278,8 +278,9 @@ function validatePackagesFlag(run, at, path) {
  * had. `validateReplicas` states the argument in one line and it applies verbatim here: a field accepted
  * where it does nothing is how an operator comes to trust one that does nothing.
  *
- * "NOT YET COVERED", not impossible -- validateReplicas' own distinction, kept because the two are
- * different facts and an operator planning work needs the right one. The local key already exists and is
+ * "NOT YET COVERED", not impossible -- a distinction this file keeps because the two are different facts
+ * and an operator planning work needs the right one. `run.replicas` carried the same wording for the same
+ * reason until #187 closed its gap; this one is still open, which is why the phrasing outlived it. The local key already exists and is
  * the strongest key in this feature: session-key.mjs keys a cron job on its scheduler id, which is
  * operator-authored, unique across the file, stable across fires, and chosen by nobody untrusted. Nothing
  * reaches it. Wiring `resolveSession` into the local path is a feature, and this line is what stops the
@@ -427,8 +428,9 @@ const INSTRUCTIONS_MAX = 2000;
  * `run.instructions` (issue #60): one line of operator standing text, rendered into the USER prompt's
  * envelope above the fenced data region.
  *
- * REFUSED on cron, and it is a DIFFERENT refusal from run.replicas' "not yet covered": cron already has
- * an operator-authored free-text field landing in the same region of the same file. A local job's prompt
+ * REFUSED on cron, and it is a DIFFERENT refusal from the "not yet covered" shape (run.resume's, since
+ * #187 retired run.replicas'): cron already has an operator-authored free-text field landing in the same
+ * region of the same file. A local job's prompt
  * is `flow hint + pointer + run.task` with no envelope, no data heading and no fence (prepare.mjs), so
  * there is no "standing" region distinct from the task for a second field to occupy. Two fields writing
  * one region with an undefined combination order is worse than a field that does nothing, because both
@@ -597,12 +599,12 @@ function validateRepository(run, onType, at, path) {
  *
  * WHY EACH REFUSAL:
  *   - a LOCAL (cron) trigger: its `/workspace` IS the operator's folder, bind-mounted read-write and edited
- *     in place, so two replicas would stomp each other's working tree with no gate and no undo. A github
+ *     in place, so two replicas would stomp each other's working tree with no gate and no undo. A forge
  *     job gets its own `mkdtemp`'d clone, which is the entire reason this is safe there and not here.
- *     Checked FIRST so a cron trigger gets that reason rather than the forge-coverage one below.
- *   - a non-github forge: every forge mints its branch through the same `issueBranch`, so extending this is
- *     mechanical -- but it is not done, and the message says "not yet covered" rather than "impossible"
- *     because those are different facts and an operator planning work needs the right one.
+ *     Checked FIRST, and since #187 that ordering carries the whole kind gate rather than merely picking
+ *     which reason a cron trigger hears. Every forge mints its branch through the same `issueBranch`, so
+ *     anything that is not `local` is now allowed; move this below the range check and a cron entry
+ *     carrying `replicas: 2` would be ACCEPTED, not refused with a different message.
  *   - a non-integer, `< 2`, or `> REPLICAS_MAX`. `1` is REFUSED rather than accepted: a one-member replica
  *     set is a field that does nothing, and this validator's whole job is to make sure nothing does nothing.
  *   - `run.resume: true`. A resumed run continues ONE lineage; replicas exist to fork it. This is the
@@ -624,9 +626,6 @@ function validateReplicas(run, at, path) {
 	if (run.kind === "local") {
 		throw configError(`${at}: run.replicas is not available on a cron trigger -- a local job's /workspace IS the operator's folder, bind-mounted read-write, so two replicas would edit one working tree with no gate and no undo: ${path}`);
 	}
-	if (run.kind !== "github") {
-		throw configError(`${at}: run.replicas is not yet covered for ${run.kind} triggers (github only in this version); every forge mints its branch the same way, so this is a gap to close, not a limit: ${path}`);
-	}
 	if (!Number.isInteger(replicas) || replicas < 2 || replicas > REPLICAS_MAX) {
 		throw configError(`${at}: run.replicas must be an integer between 2 and ${REPLICAS_MAX} when present -- ${REPLICAS_MAX} is the ceiling because PI_CONCURRENCY defaults to 3, so a further replica would queue instead of racing, and 1 is refused because a one-member replica set is a flag that does nothing (got ${JSON.stringify(replicas)}): ${path}`);
 	}

package/src/up.mjs

@@ -24,6 +24,7 @@ import { spawn as nodeSpawn } from "node:child_process";
 import { chmodSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { connect as netConnect } from "node:net";
 import { join } from "node:path";
+import { egressArmed as egressArmedFn } from "./egress.mjs";
 import { updateEnvFile } from "./env-file.mjs";
 
 // The one image up may ever fetch, and the local name jobs run under. Literal on purpose (not
@@ -63,6 +64,31 @@ const VALKEY_RUN_ARGS = [
 	"yes",
 ];
 
+// deploy/docker-compose.yml's `egress` profile, reproduced as one docker run (REQ-EGRESS-ALLOWLIST):
+// same digest-pinned image, same two mounts, same explicit container name, same restart policy, on the
+// same upstream network. Written out here for the same reason VALKEY_RUN_ARGS is -- an operator who runs
+// `up` and one who runs compose must end up with the same component, and two ways of starting one thing
+// is two places for it to drift.
+//
+// The per-job networks are NOT here: the worker creates one per job and attaches this container to it for
+// the life of that run. This is only the proxy and its way out.
+const EGRESS_NETWORK_ARGS = ["network", "create", "pi-dispatch-egress-out"];
+const EGRESS_RUN_ARGS = [
+	"run",
+	"-d",
+	"--name",
+	"pi-dispatch-egress-proxy",
+	"--restart",
+	"unless-stopped",
+	"--network",
+	"pi-dispatch-egress-out",
+	"-v",
+	"./deploy/egress-proxy.conf:/etc/squid/squid.conf:ro",
+	"-v",
+	"./egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro",
+	"ubuntu/squid@sha256:6a097f68bae708cedbabd6188d68c7e2e7a38cedd05a176e1cc0ba29e3bbe029",
+];
+
 export async function runUp(argv = [], deps = {}) {
 	const {
 		env = process.env,
@@ -173,6 +199,38 @@ export async function runUp(argv = [], deps = {}) {
 		summary.push(["WEBHOOK_SECRET", "no .env here — skipped (set it wherever your env lives)"]);
 	}
 
+	// (e2) the egress policy's proxy, and ONLY when the operator has already armed it. up never invents
+	// operator policy -- the same doctrine that keeps it pulling this repo's own image and no other -- so a
+	// deployment that has not set PI_EGRESS hears nothing about this at all.
+	//
+	// AFTER init, deliberately: init has just scaffolded egress-allowlist.conf, and starting a proxy whose
+	// allowlist file does not exist gets a directory created by docker where a file belonged and a squid
+	// that fails confusingly. If the file is still missing, this step declines itself and says which file.
+	if (egressArmedFn(env)) {
+		if ((await runCmd(spawn, "docker", ["inspect", "--format={{.State.Running}}", "pi-dispatch-egress-proxy"])) === 0) {
+			out("\n✓ Egress proxy already present (pi-dispatch-egress-proxy)\n");
+			summary.push(["egress", "proxy already present — left untouched"]);
+		} else if (!fs.existsSync(join(cwd, "egress-allowlist.conf"))) {
+			out("\n✗ the egress policy is on but egress-allowlist.conf is not here — not starting a proxy with no allowlist\n");
+			summary.push(["egress", "skipped — no egress-allowlist.conf in this folder; run `pi-dispatch init` here, then `up` again"]);
+		} else if (
+			await consent("The egress policy is on (PI_EGRESS=0 opts out) but the allowlist proxy is not running. up would start it (same semantics as deploy/docker-compose.yml --profile egress):", [`docker ${EGRESS_NETWORK_ARGS.join(" ")}`, `docker ${quoteArgs(EGRESS_RUN_ARGS)}`], { yes, out, prompt })
+		) {
+			// The network may already exist from a previous run; that is not a failure, so its code is not
+			// checked. The proxy is what matters and it is checked.
+			await runStreamed(spawn, "docker", EGRESS_NETWORK_ARGS, out);
+			if ((await runStreamed(spawn, "docker", EGRESS_RUN_ARGS, out)) !== 0) {
+				out("✗ could not start the egress proxy — continuing; doctor below will re-check it\n");
+				summary.push(["egress", "start failed — every job refuses pre-spend until it is up (costs no budget, runs nothing)"]);
+			} else {
+				summary.push(["egress", "started pi-dispatch-egress-proxy on pi-dispatch-egress-out"]);
+			}
+		} else {
+			out("skipped — start it later with `docker compose -f deploy/docker-compose.yml --profile egress up -d`\n");
+			summary.push(["egress", "skipped (declined) — every job is refused pre-spend until the proxy is up (PI_EGRESS=0 opts out)"]);
+		}
+	}
+
 	// (f) doctor — always, verbatim: up converges what it can, doctor is the judge of what remains
 	// (provider key, forge env, overlay …), and its verdict is up's exit code.
 	out("\ndoctor:\n");