@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/session-key.mjs

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { issueBranch } from "./branch.mjs";
+import { cronRunOf } from "./bullmq-internals.mjs";
 import { isForgeKind } from "./forges.mjs";
 
 /**
@@ -37,6 +38,14 @@ import { isForgeKind } from "./forges.mjs";
 /** Long enough that a collision is not a thing to reason about, short enough to read in a log line. */
 const KEY_LENGTH = 32;
 
+/**
+ * What a key LOOKS like, derived from KEY_LENGTH rather than restated, because the session reaper (issue #645) uses it
+ * to decide which names in PI_SESSIONS_DIR are keys at all: a hand copy of `32` that drifted from this would make the
+ * reaper ignore every real key (they would all read as `not-a-key`) or judge names this module never mints.
+ */
+export const SESSION_KEY_PATTERN = new RegExp(`^[0-9a-f]{${KEY_LENGTH}}$`);
+export const FORK_SESSION_KEY_PATTERN = new RegExp(`^([0-9a-f]{${KEY_LENGTH}})\\.([0-9a-f]{32})$`);
+
 /**
  * @param {object} job - The job data (`kind`, `repo`, `target`, `trigger`).
  * @param {object} [resolved] - `{ headRef, headRepo }` for a pull/merge-request target, from the FORGE
@@ -46,6 +55,20 @@ const KEY_LENGTH = 32;
 export function sessionKeyFor(job, resolved = {}) {
 	const parts = keyParts(job, resolved);
 	if (parts === null) return null;
+	const forkRef = job?.target?.type === "pull_request" ? /^pi\/issue-([1-9][0-9]*)-fork-([0-9a-f]{32})$/.exec(resolved.headRef ?? "") : null;
+	if (forkRef) {
+		const root = hashParts([parts[0], parts[1], issueBranch(forkRef[1])]);
+		return `${root}.${forkRef[2]}`;
+	}
+	const key = hashParts(parts);
+	if (job?.fork !== undefined) {
+		if (!job.fork || job.fork.rootKey !== key || typeof job.fork.id !== "string" || !/^[0-9a-f]{32}$/.test(job.fork.id)) return null;
+		return `${key}.${job.fork.id}`;
+	}
+	return key;
+}
+
+function hashParts(parts) {
 	// NUL-delimited so ("a", "bc") and ("ab", "c") cannot collide -- the same reasoning job-id.mjs uses.
 	return createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, KEY_LENGTH);
 }
@@ -106,3 +129,40 @@ export function keyParts(job, resolved = {}) {
 	// kind that is neither a forge nor local lands here too, which is the safe direction: no session.
 	return null;
 }
+
+/**
+ * A RUN RECORD's session key, re-derived the way `sessionKeyFor` derives a job's (DES-SESSION-KEY-IS-DERIVED-NOT-INDEXED):
+ * a forge ISSUE from kind + repo + its number, a cron run from its scheduler id. Null where the record cannot say: a
+ * pull or merge request's key needs its head ref, which the record deliberately does not carry (it is attacker-chosen
+ * text, and the record holds none, INT-RUN-HISTORY-FILE-CONTRACT).
+ *
+ * It lives HERE, beside `sessionKeyFor`, and not in the admin's read model where it started (issue #647): the admin's
+ * parked-chain counter and the terminal `pi-dispatch chat` fork both need it, and two copies of a key rule are two
+ * places for a cross-issue transcript mix-up to start. Still derived, never looked up: there is no index to consult.
+ *
+ * @param {object} record - A run record (`kind`, `target`, `jobId`, `triggerType`).
+ * @returns {string|null} The 32-hex key, or null.
+ */
+export function sessionKeyOfRecord(record) {
+	if (record?.fork !== undefined) {
+		const root = sessionKeyOfRecord({ ...record, fork: undefined });
+		return root && typeof record.fork?.id === "string" && /^[0-9a-f]{32}$/.test(record.fork.id) ? `${root}.${record.fork.id}` : null;
+	}
+	const kind = record?.kind;
+	if (kind === "local") {
+		// The scheduler id is the middle of a cron (`repeat:`) or manual-fire (`manual:`) job id; the trailing number is
+		// the fire's own, which differs every time and must not split one schedule's sessions. Any id length: a record
+		// is this deployment's own history, and every release before issue #761 took a cron id of any length.
+		const run = cronRunOf(record?.jobId);
+		return run ? sessionKeyFor({ kind: "local", trigger: { id: run.id } }) : null;
+	}
+	if (!isForgeKind(kind) || typeof record?.target !== "string") return null;
+	// `!` (a GitLab merge request, an Azure pull request) never matches: a request's key needs the head ref.
+	const m = /^(.+)#(\d+)$/.exec(record.target);
+	if (!m) return null;
+	// `#` is the issue separator on every forge; GitHub and Forgejo also spell a pull request with it, and only the
+	// trigger type can say which (a `pull_request` trigger). A comment on a pull request stays ambiguous, so a key that
+	// names no directory reads as unknown to its callers, never as a session.
+	if (record.triggerType === "pull_request") return null;
+	return sessionKeyFor({ kind, repo: m[1], target: { type: "issue", number: Number(m[2]) } });
+}

package/src/session-store.mjs

@@ -16,7 +16,7 @@ import {
 import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { scrubCredentials } from "./redact.mjs";
-import { sessionKeyFor } from "./session-key.mjs";
+import { FORK_SESSION_KEY_PATTERN, SESSION_KEY_PATTERN, sessionKeyFor } from "./session-key.mjs";
 import { resolveBackendName } from "./backend-registry.mjs";
 import { UNATTRIBUTED_BACKEND } from "./backends.mjs";
 import { MODEL_REF_PATTERN } from "./model-ref.mjs";
@@ -439,7 +439,10 @@ export function makeSessionStore({
 				fs.writeFileSync(staged, "");
 			}
 			log("session_resolved", { key, resume: verdict.resume, reason: verdict.reason });
-			return { hostDir, key, modelId, venue, ...verdict };
+			// Bind answer lineage to the descriptor's transcript, not an earlier park lookup. Another flow on
+			// this issue may have promoted a different park while this job was passing its admission gates.
+			const parkedSource = verdict.resume ? readBoundParkedSource(key, judged) : null;
+			return { hostDir, key, modelId, venue, ...verdict, ...(parkedSource ? { parkedSource } : {}) };
 		} catch (err) {
 			// A history fault must never fail the prepare that asked.
 			log("session_store_failed", { phase: "resolve", reason: err?.message });
@@ -549,7 +552,7 @@ export function makeSessionStore({
 		return st.isDirectory() ? `${st.dev}:${st.ino}` : null;
 	}
 
-	function promoteSession(session, { piVersion = null, context = null, parked = false } = {}) {
+	function promoteSession(session, { piVersion = null, context = null, parked = false, parkedSource = 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
@@ -566,6 +569,7 @@ export function makeSessionStore({
 			}
 
 			const dir = keyDir(session.key);
+			if (!ensureForkParents(session.key)) return { promoted: false, reason: "key-not-a-directory" };
 			// LSTAT BEFORE CREATE, and again after (issue #375). Recursive `mkdir` succeeds silently on an
 			// existing link to a directory, so asking it first and checking afterwards would accept exactly the
 			// shape this refuses; asking first means nothing already at the name is ever handed to `mkdir` at all,
@@ -665,7 +669,7 @@ export function makeSessionStore({
 				// (issue #390). Measured with a deterministic probe before this existed: `{"promoted":true,
 				// "reason":"promoted"}` with the transcript in the attacker's directory and the real key holding
 				// only `pi-version`, `resume-chain` and `venue` -- the next job on that key cold-starts as
-				// `absent` while the record says the work was promoted, which is the silent no-op `CLAUDE.md`
+				// `absent` while the record says the work was promoted, which is the silent no-op `AGENTS.md`
 				// calls the worst outcome available. A 45 second unsynchronised live race did not hit the exact
 				// ordering (16,591 promotions, 3 refusals, 0 lies), so this is a deterministic-window finding
 				// rather than a frequent one, and its precondition is the one the whole store concedes: write
@@ -720,7 +724,7 @@ export function makeSessionStore({
 				// it is reporting.
 				writeSidecar(dir, RESUME_CHAIN_FILE, session.key, chainValue(session));
 				writeContextSidecar(dir, session, context);
-				writeParkedSidecar(dir, session, parked);
+				writeParkedSidecar(dir, session, parked, parkedSource);
 			} finally {
 				fs.closeSync(fd);
 				try {
@@ -852,9 +856,12 @@ export function makeSessionStore({
 
 	// Issue #625: `parked` is set by a run that ended awaiting-input, and cleared by every other promotion, so the
 	// marker always describes the transcript beside it. Caught like its siblings: the promotion already happened.
-	function writeParkedSidecar(dir, session, parked) {
+	function writeParkedSidecar(dir, session, parked, parkedSource = null) {
 		if (parked === true) {
-			writeSidecar(dir, PARKED_FILE, session.key, String(now()));
+			const at = now();
+			const transcriptIdentity = readIdentity(canonicalFile(session.key));
+			const source = transcriptIdentity && typeof parkedSource?.runId === "string" && /^[A-Za-z0-9._:-]{1,200}$/.test(parkedSource.runId) ? { v: 2, runId: parkedSource.runId, at, transcriptIdentity } : null;
+			writeSidecar(dir, PARKED_FILE, session.key, source ? JSON.stringify(source) : String(at));
 			return;
 		}
 		try {
@@ -865,8 +872,19 @@ export function makeSessionStore({
 	}
 
 	function keyDir(key) {
+		const fork = FORK_SESSION_KEY_PATTERN.exec(key);
+		if (fork) return join(sessionsDir, fork[1], "forks", fork[2]);
+		if (!SESSION_KEY_PATTERN.test(key)) throw new Error("invalid session key");
 		return join(sessionsDir, key);
 	}
+	function forkParents(key) {
+		const fork = FORK_SESSION_KEY_PATTERN.exec(key);
+		return fork ? [join(sessionsDir, fork[1]), join(sessionsDir, fork[1], "forks")] : [];
+	}
+	function ensureForkParents(key) {
+		for (const dir of forkParents(key)) if (ensureKeyDir(dir) === null) return false;
+		return true;
+	}
 	function canonicalFile(key) {
 		return join(keyDir(key), SESSION_FILE_NAME);
 	}
@@ -950,6 +968,7 @@ export function makeSessionStore({
 	function inspectKeyDir(key) {
 		let st;
 		try {
+			for (const dir of forkParents(key)) if (!fs.lstatSync(dir).isDirectory()) return { ok: false, reason: "key-not-a-directory" };
 			st = fs.lstatSync(keyDir(key));
 		} catch {
 			// EVERY failure reads as `absent`, not only ENOENT, and that is this edge's posture rather than an
@@ -1253,6 +1272,21 @@ export function makeSessionStore({
 			return;
 		}
 		for (const name of names) {
+			// ONLY A KEY-SHAPED NAME IS JUDGED (issue #645). Until then every entry of the store was taken for a key, so a
+			// directory that is not one -- the checkpoint store's default home, `<PI_SESSIONS_DIR>/.checkpoints`, or anything
+			// an operator parks here -- was removed whole once its own directory mtime aged past the TTL, by a pass that only
+			// ever had the right to expire sessions. A key is a hash this store mints (session-key.mjs), so the shape is an
+			// exact test and nothing that is a key can fail it.
+			//
+			// A DOT name is skipped silently: that is the namespace for the store's own siblings (`.checkpoints`) and for
+			// tooling litter (`.DS_Store`), and logging them would put a line in every pass that nobody can act on. Any OTHER
+			// non-key name is a verdict, `session_not_reaped` rather than `session_reaper_skipped`, for the reason the #375
+			// comment below gives: the pass established what the entry is and decided to leave it. Once per name per pass,
+			// which the loop gives for free since `readdirSync` names each entry once.
+			if (!SESSION_KEY_PATTERN.test(name)) {
+				if (!name.startsWith(".")) log("session_not_reaped", { key: name, reason: "not-a-key" });
+				continue;
+			}
 			try {
 				const dir = join(sessionsDir, name);
 				// THE ENTRY ITSELF FIRST (issue #375), so nothing here is ever judged THROUGH a link. Before this,
@@ -1270,6 +1304,7 @@ export function makeSessionStore({
 					log("session_not_reaped", { key: name, reason: "key-not-a-directory" });
 					continue;
 				}
+				const retainForks = reapForks(name, dir, cutoff);
 				let mtimeMs;
 				try {
 					mtimeMs = fs.lstatSync(join(dir, SESSION_FILE_NAME)).mtimeMs;
@@ -1296,7 +1331,7 @@ export function makeSessionStore({
 					// readable transcript -- the sweep's decision then came from a file outside the store entirely.
 					mtimeMs = dst.mtimeMs;
 				}
-				if (mtimeMs < cutoff) {
+				if (mtimeMs < cutoff && !retainForks) {
 					// ONE recursive remove, on the transcript's age where there is one and the directory's own where
 					// there is not (above). Removing the
 					// transcript first (so an absent stamp, which reads as `local`, can never sit beside a readable
@@ -1313,6 +1348,30 @@ export function makeSessionStore({
 		}
 	}
 
+	/** Forks have their own expiry clock; an old original must never recursively remove a newer fork. */
+	function reapForks(rootKey, rootDir, cutoff) {
+		const dir = join(rootDir, "forks");
+		let st;
+		try { st = fs.lstatSync(dir); } catch (error) { if (error.code === "ENOENT") return false; throw error; }
+		if (!st.isDirectory()) return true;
+		for (const id of fs.readdirSync(dir)) {
+			if (!/^[0-9a-f]{32}$/.test(id)) continue;
+			const child = join(dir, id);
+			try {
+				const entry = fs.lstatSync(child);
+				if (!entry.isDirectory()) continue;
+				let modified;
+				try { modified = fs.lstatSync(join(child, SESSION_FILE_NAME)).mtimeMs; }
+				catch (error) { if (error.code !== "ENOENT") throw error; modified = entry.mtimeMs; }
+				if (modified < cutoff) {
+					fs.rmSync(child, { recursive: true, force: true });
+					log("reaped_session", { key: `${rootKey}.${id}` });
+				}
+			} catch (error) { log("session_reaper_skipped", { key: `${rootKey}.${id}`, reason: scrubCredentials(error?.message) }); }
+		}
+		return fs.readdirSync(dir).length > 0;
+	}
+
 	/**
 	 * Whether the key a job resolves to holds a `parked` mark (issue #625): the TRUTH the worker gates a phrase-free reply
 	 * on, where the forge label was only the receiver's hint. Free, read-only and never throws, so it can answer before
@@ -1320,17 +1379,116 @@ export function makeSessionStore({
 	 * which costs a token to read, which is why a phrase-free reply is routed on issues only and this resolves no PR.
 	 * The key's own name must `lstat` as a real directory, resolveSession's first gate, so a planted link answers no.
 	 */
+	function readParkedInfo(job) {
+		if (!sessionsDir || job?.target?.type === "pull_request") return null;
+		const key = sessionKeyFor(job);
+		if (!key) return null;
+		try { if (!inspectKeyDir(key).ok) return null; } catch { return null; }
+		const raw = readSidecar(key, PARKED_FILE);
+		try {
+			const value = JSON.parse(raw);
+			if ([1, 2].includes(value?.v) && /^[A-Za-z0-9._:-]{1,200}$/.test(value.runId ?? "") && Number.isSafeInteger(value.at) && value.at >= 0) return { runId: value.runId, at: value.at };
+		} catch {}
+		// An older timestamp still proves a park, but cannot name a source run or manufacture answer lineage.
+		return null;
+	}
+
+	function readBoundParkedSource(key, transcriptIdentity) {
+		try {
+			const value = JSON.parse(readSidecar(key, PARKED_FILE));
+			if (transcriptIdentity && value?.v === 2 && value.transcriptIdentity === transcriptIdentity && /^[A-Za-z0-9._:-]{1,200}$/.test(value.runId ?? "") && Number.isSafeInteger(value.at) && value.at >= 0) return { runId: value.runId, at: value.at };
+		} catch {}
+		return null;
+	}
+
 	function isParked(job) {
 		if (!sessionsDir || job?.target?.type === "pull_request") return false;
 		const key = sessionKeyFor(job);
 		if (!key) return false;
 		try {
-			if (!fs.lstatSync(keyDir(key)).isDirectory()) return false;
+			if (!inspectKeyDir(key).ok) return false;
 		} catch {
 			return false;
 		}
 		return readSidecar(key, PARKED_FILE) !== null;
 	}
 
-	return { resolveSession, promoteSession, reapSessions, isParked };
+	/**
+	 * Stage a RECOVERED run's transcript (issue #645, durable runs): the checkpoint's `transcript.jsonl`, copied to
+	 * `jobDir/session/current.jsonl`, the path every job's transcript file has (a resume job's staged copy, or the live
+	 * file of issue #643). Returns the session object the processor carries, with `resume: true` and
+	 * `reason: "recovered"`, or `null` when nothing could be staged (the caller then does not start the run: a recovery
+	 * without its conversation is not a recovery).
+	 *
+	 * NOT `resolveSession`, and the store is not read at all: the canonical transcript is the one from BEFORE the crashed
+	 * run, and the checkpoint is that run's own continuation, written by this worker into its checkpoint store and
+	 * hash-checked against its manifest (workspace-checkpoint.mjs `readManifest`). None of resolveSession's gates (age,
+	 * chain, context, venue, pi version) applies: the processor already refused a checkpoint from another pi version or
+	 * venue before calling this.
+	 *
+	 * A KEY FOR A RESUME JOB OR AN EXPLICIT MANAGED FORK. Either consent, with a valid derived key, gives the session
+	 * its key, model and venue, so a completed recovery promotes exactly as the crashed run would have (`promoteSession`
+	 * is unchanged). Any other job gets `key: null`: its transcript is the live file, nothing is promoted, and the
+	 * processor hands it over as `prepared.live`, not as a session. `resolved` is the pull request head the preparer
+	 * resolved from the forge (`recoveryResolved`), never a payload field: the same rule `resolveSession` keys on.
+	 *
+	 * Never throws: a fault is logged by phase and returns null, and anything it staged is removed.
+	 */
+	function stageRecovered({ jobDir, transcriptPath, piVersion: _piVersion = null, job = null, resolved = {} } = {}) {
+		let hostDir = null;
+		let fd = null;
+		try {
+			if (typeof jobDir !== "string" || jobDir === "" || typeof transcriptPath !== "string" || transcriptPath === "") return null;
+			// lstat, and a regular file: a link at the checkpoint's name is not the checkpoint, whatever it points at.
+			const st = fs.lstatSync(transcriptPath);
+			if (!st.isFile()) {
+				log("session_store_failed", { phase: "stage-recovered", reason: "not-a-regular-file" });
+				return null;
+			}
+			hostDir = join(jobDir, "session");
+			fs.mkdirSync(hostDir, { recursive: true, mode: 0o700 });
+			const staged = join(hostDir, SESSION_FILE_NAME);
+			// Copied off the descriptor whose identity was checked, never re-resolved by path (resolveSession's rule).
+			fd = fs.openSync(transcriptPath, "r");
+			const opened = fs.fstatSync(fd);
+			if (!opened.isFile() || identityOf(opened) !== identityOf(st)) {
+				log("session_store_failed", { phase: "stage-recovered", reason: "transcript-replaced" });
+				fs.rmSync(hostDir, { recursive: true, force: true });
+				return null;
+			}
+			copyFromDescriptor(fd, staged, opened.size);
+			// An explicit managed fork is retention consent in its own right. A recovery keeps that fork's namespace
+			// even when the trigger did not opt ordinary runs into canonical resume; sessionKeyFor validates its root/id.
+			const key = sessionsDir && (job?.resume === true || job?.fork !== undefined) ? sessionKeyFor(job, resolved ?? {}) : null;
+			log("session_resolved", { key, resume: true, reason: "recovered" });
+			return {
+				hostDir,
+				key,
+				...(key ? { modelId: modelIdentity(job), venue: normaliseVenue(resolveBackendName(job, defaultBackend)) } : {}),
+				resume: true,
+				reason: "recovered",
+				bytes: opened.size,
+			};
+		} catch (err) {
+			log("session_store_failed", { phase: "stage-recovered", reason: err?.code ?? "error" });
+			if (hostDir !== null) {
+				try {
+					fs.rmSync(hostDir, { recursive: true, force: true });
+				} catch {
+					// the job dir is removed at teardown either way
+				}
+			}
+			return null;
+		} finally {
+			if (fd !== null) {
+				try {
+					fs.closeSync(fd);
+				} catch {
+					// already closed or never valid
+				}
+			}
+		}
+	}
+
+	return { resolveSession, promoteSession, reapSessions, isParked, readParkedInfo, stageRecovered };
 }

package/src/setup-contract.mjs

@@ -0,0 +1,40 @@
+/** Data-only wire vocabulary for the explicitly granted local setup child (#774). */
+export const SETUP_VERSION = 1;
+export const SETUP_LIMITS = Object.freeze({ inputBytes: 64 * 1024, outputBytes: 256 * 1024, keyBytes: 4096, serviceMs: 60_000, doctorMs: 120_000, killGraceMs: 2000, readinessMs: 90_000 });
+export const SETUP_OPERATIONS = Object.freeze(["setup-worker-install", "setup-worker-start", "setup-worker-stop", "setup-worker-restart", "setup-receiver-install", "setup-receiver-start", "setup-receiver-stop", "setup-receiver-restart", "setup-egress-start", "setup-doctor", "setup-provider-key", "setup-provider-key-replace"]);
+export const SETUP_STATES = Object.freeze(["planned", "unchanged", "applied", "refused", "partial", "unknown"]);
+export const SETUP_REASONS = Object.freeze(["ready", "invalid-request", "unsupported", "unavailable", "unsafe-deployment", "unsafe-entry", "foreign-service", "missing-service", "missing-receiver", "service-exists", "manager-unavailable", "unsafe-dependencies", "plan-stale", "setup-busy", "process-failed", "process-timeout", "readback-unavailable", "already-running", "egress-off", "gateway-egress", "remote-runtime", "unsafe-proxy", "proxy-refresh-required", "provider-unsupported", "provider-host-auth", "provider-shadowed", "provider-managed", "key-present", "key-missing", "key-invalid", "env-unsafe", "doctor-incomplete", "doctor-published"]);
+export const SETUP_EFFECTS = Object.freeze(["write-worker-unit", "write-receiver-unit", "start-worker", "start-receiver", "stop-worker", "stop-receiver", "restart-worker", "restart-receiver", "write-stack-files", "start-valkey", "start-proxy", "start-keeper", "write-provider-key", "publish-doctor"]);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const keys = (value, allowed) => object(value) && Object.keys(value).every((key) => allowed.includes(key));
+const short = (value, max = 128) => typeof value === "string" && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+export function validSetupRequest(value) {
+	if (!keys(value, ["version", "id", "phase", "operation", "expected", "input"]) || value.version !== SETUP_VERSION || !/^[a-f0-9]{32}$/.test(value.id ?? "") || !["plan", "apply", "status"].includes(value.phase) || !SETUP_OPERATIONS.includes(value.operation)) return false;
+	if (value.expected !== undefined && !/^[a-f0-9]{64}$/.test(value.expected)) return false;
+	if (value.phase === "apply" && value.expected === undefined) return false;
+	if (value.input !== undefined && (!keys(value.input, ["provider", "key", "value"]) || Object.entries(value.input).some(([key, v]) => typeof v !== "string" || (key !== "value" && !short(v))))) return false;
+	if (!["setup-provider-key", "setup-provider-key-replace"].includes(value.operation) && value.input !== undefined && Object.keys(value.input).length > 0) return false;
+	if (value.phase !== "apply" && value.input?.value !== undefined) return false;
+	return true;
+}
+export function validSetupResult(value) {
+	if (!keys(value, ["version", "id", "operation", "state", "reason", "plan", "effects"]) || value.version !== SETUP_VERSION || !/^[a-f0-9]{32}$/.test(value.id ?? "") || !SETUP_OPERATIONS.includes(value.operation) || !SETUP_STATES.includes(value.state) || !SETUP_REASONS.includes(value.reason)) return false;
+	const effects = (list) => Array.isArray(list) && list.length <= SETUP_EFFECTS.length && new Set(list).size === list.length && list.every((v) => SETUP_EFFECTS.includes(v));
+	if (value.effects !== undefined && !effects(value.effects)) return false;
+	if (value.plan !== undefined) {
+		const p = value.plan;
+		if (!keys(p, ["digest", "component", "manager", "host", "workerName", "account", "effects", "key", "provider", "mode", "aliases", "source"]) || !/^[a-f0-9]{64}$/.test(p.digest ?? "") || !["worker", "receiver", "egress", "doctor", "provider"].includes(p.component) || !["systemd", "launchd"].includes(p.manager) || !short(p.host, 64) || !short(p.account, 64) || !effects(p.effects)) return false;
+		const component = value.operation.startsWith("setup-provider-key") ? "provider" : value.operation === "setup-doctor" ? "doctor" : value.operation.split("-")[1];
+		if (p.component !== component) return false;
+		if (p.workerName !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(p.workerName)) return false;
+		if (p.key !== undefined && !/^[A-Z_][A-Z0-9_]{0,127}$/.test(p.key)) return false;
+		if (p.provider !== undefined && !/^[a-z0-9][a-z0-9._-]{0,127}$/.test(p.provider)) return false;
+		if (p.component === "provider") {
+			if (!p.key || !p.provider || p.mode !== (value.operation === "setup-provider-key-replace" ? "replace" : "add") || !["deployment-env", "pi-api-key", "none"].includes(p.source)) return false;
+			if ((p.mode === "replace") !== (p.source === "deployment-env")) return false;
+			if (!Array.isArray(p.aliases) || p.aliases.length === 0 || p.aliases.length > 128 || new Set(p.aliases).size !== p.aliases.length || !p.aliases.includes(p.provider) || p.aliases.some((name) => !/^[a-z0-9][a-z0-9._-]{0,127}$/.test(name))) return false;
+		} else if (p.mode !== undefined || p.aliases !== undefined || p.source !== undefined || p.key !== undefined || p.provider !== undefined) return false;
+	}
+	return value.state !== "planned" || value.plan !== undefined;
+}
+export { validSetupRequest as validateSetupRequest, validSetupResult as validateSetupResult };

package/src/setup-egress.mjs

@@ -0,0 +1,113 @@
+/** Start-only proxy planning, reusing the shipped argv and Quadlet installer; never a browser `up` pass. */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { deploymentServiceEnv } from "./service-env.mjs";
+import { egressArmed, egressProxyName, DEFAULT_EGRESS_PROXY } from "./egress.mjs";
+import { venuesOf } from "./backends.mjs";
+import { makeDockerEndpointResolver } from "./backend-local.mjs";
+import { makePodmanInfoReader, decidePodmanJobUser } from "./backend-podman.mjs";
+import { EGRESS_NETWORK_ARGS, EGRESS_RUN_ARGS } from "./up.mjs";
+import { EGRESS_PROXY_IMAGE, PROXY_STATE_FORMAT, jobNetworksOf, parseProxyState, rulesIncludeEndpoints, shippedProxyDrift } from "./egress-proxy-state.mjs";
+import { readPackagedProxyConf } from "./egress-conf-copy.mjs";
+import { applyStack, foreignContainers, planStack, stackComponents, managerEnvRefusal, userBusRefusal } from "./podman-stack.mjs";
+
+const digest = (value) => createHash("sha256").update(typeof value === "string" ? value : JSON.stringify(value)).digest("hex");
+const templatesDir = fileURLToPath(new URL("../deploy/", import.meta.url));
+export function setupCommand(bin, args, { cwd, env, timeout = 15_000 } = {}) {
+	return new Promise((done) => {
+		try { execFile(bin, args, { cwd, env, timeout, maxBuffer: 256 * 1024, killSignal: "SIGKILL" }, (error, stdout, stderr) => done({ code: error ? typeof error.code === "number" ? error.code : null : 0, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") })); }
+		catch { done({ code: null, stdout: "", stderr: "" }); }
+	});
+}
+const no = (refusal) => ({ refusal });
+
+export async function planSetupEgress(ctx) {
+	const { CLI_SERVICE_KEYS } = await import("./doctor.mjs");
+	const runtimeKeys = [...new Set([...CLI_SERVICE_KEYS.docker, ...CLI_SERVICE_KEYS.podman])];
+	const runtime = deploymentServiceEnv({ env: ctx.env, dir: ctx.dir, keys: runtimeKeys, fs: ctx.fs, uid: ctx.uid, platform: ctx.platform });
+	if (runtime.untrusted || runtime.unreadable || runtime.unread?.length || runtime.hazardSkipped?.length || runtime.disagreements?.length) return no("unsafe-deployment");
+	const runtimeEnv = runtime.env;
+	const run = ctx.run ?? ((bin, args) => setupCommand(bin, args, { cwd: ctx.dir, env: runtimeEnv }));
+	const read = deploymentServiceEnv({ env: {}, dir: ctx.dir, keys: ["PI_BACKENDS", "PI_EGRESS", "PI_EGRESS_PROXY"], fs: ctx.fs, uid: ctx.uid, platform: ctx.platform });
+	if (read.untrusted || read.unreadable || read.unread?.length || read.hazardSkipped?.length) return no("unsafe-deployment");
+	const env = read.env;
+	const venues = venuesOf(env);
+	if (!egressArmed(env)) return no("egress-off");
+	if (!venues.localUsed && !venues.podmanUsed) return no("gateway-egress");
+	if (egressProxyName(env) !== DEFAULT_EGRESS_PROXY) return no("unsafe-proxy");
+	const files = {};
+	try {
+		for (const rel of ["deploy/egress-proxy.conf", "egress-allowlist.conf", "model-endpoints.conf"]) {
+			const path = join(ctx.dir, rel);
+			const st = ctx.fs.lstatSync(path);
+			if (!st.isFile() || st.isSymbolicLink() || st.uid !== ctx.uid || (st.mode & 0o022)) return no("unsafe-proxy");
+			files[rel] = String(ctx.fs.readFileSync(path, "utf8"));
+		}
+	} catch { return no("unsafe-proxy"); }
+	if (files["deploy/egress-proxy.conf"] !== (ctx.readPackagedConf ?? readPackagedProxyConf)()) return no("proxy-refresh-required");
+	if (!venues.localUsed) {
+		if (ctx.platform !== "linux") return no("unsupported");
+		const info = await (ctx.readPodmanInfo ?? makePodmanInfoReader({ run: (args) => run("podman", args) }))();
+		if (decidePodmanJobUser({ platform: ctx.platform, euid: ctx.uid, egid: process.getegid?.(), read: info }).mode !== "worker") return no("remote-runtime");
+		const home = ctx.serviceDeps?.home ?? homedir();
+		// env-internal USER: this account's manager label, never a declaration of another service account.
+		const account = ctx.serviceDeps?.user ?? process.env.USER;
+		if (userBusRefusal({ env: runtimeEnv, user: account, euid: ctx.uid })) return no("manager-unavailable");
+		const manager = await run("systemctl", ["--user", "show-environment"]);
+		if (manager.code !== 0 || managerEnvRefusal(manager, { home, euid: ctx.uid, user: account, realpath: ctx.fs.realpathSync })) return no("manager-unavailable");
+		const components = stackComponents({ venues, env, includeValkey: false, armed: true });
+		const stack = planStack({ components, templatesDir, deployDir: ctx.dir, home, fs: ctx.fs });
+		if (stack.error || stack.files.some((f) => f.state === "changed") || stack.restart?.length) return no("unsafe-dependencies");
+		for (const f of stack.files) {
+			let path = f.path;
+			while (path !== dirname(home)) {
+				try { const st = ctx.fs.lstatSync(path); if (st.isSymbolicLink() || (st.mode & 0o022) || st.uid !== ctx.uid) return no("unsafe-dependencies"); } catch (e) { if (e.code !== "ENOENT") return no("unsafe-dependencies"); }
+				if (path === home || path === dirname(path)) break;
+				path = dirname(path);
+			}
+		}
+		const foreign = await foreignContainers(stack, (bin, args) => run(bin, args));
+		if (foreign.found.length || foreign.unknown.length) return no("unsafe-proxy");
+		const running = await run("podman", ["inspect", PROXY_STATE_FORMAT, DEFAULT_EGRESS_PROXY]);
+		const state = running.code === 0 ? parseProxyState(running.stdout) : null;
+		if (state && !["running", "exited", "stopped", "created"].includes(state.status)) return no("unsafe-proxy");
+		// Starting a keeper behind an existing proxy can require a disruptive replacement. Leave that repair to the host.
+		if (state?.status === "running" && stack.files.some((f) => f.state === "new")) return no("unsafe-dependencies");
+		return { effects: [...(stack.files.some((f) => f.state === "new") ? ["write-stack-files"] : []), "start-keeper", "start-proxy"], inputs: { runtime: digest(Object.fromEntries(runtimeKeys.map((key) => [key, runtimeEnv[key] ?? null]))), files: Object.fromEntries(Object.entries(files).map(([k, v]) => [k, digest(v)])), stack, state }, egress: { bin: "podman", stack, run, running: state?.status === "running" } };
+	}
+	const endpoint = await (ctx.resolveEndpoint ?? makeDockerEndpointResolver({ run: (args) => run("docker", args) }))();
+	if (endpoint.local !== true) return no("remote-runtime");
+	const daemon = await run("docker", ["info", "--format", "{{.ID}}"]);
+	if (daemon.code !== 0 || !daemon.stdout.trim()) return no("unavailable");
+	const current = await run("docker", ["inspect", PROXY_STATE_FORMAT, DEFAULT_EGRESS_PROXY]);
+	const state = current.code === 0 ? parseProxyState(current.stdout) : null;
+	if (current.code === 0 && !state) return no("unsafe-proxy");
+	if (!state && !/No such (?:object|container)/i.test(current.stderr)) return no("unavailable");
+	if (state) {
+		const drift = shippedProxyDrift(state, { cwd: ctx.dir, realpath: ctx.fs.realpathSync, platform: ctx.platform, rulesInclude: rulesIncludeEndpoints(files["deploy/egress-proxy.conf"]) });
+		if (drift.drift.length || drift.unknown || jobNetworksOf(state).length || !["running", "exited", "created", "stopped"].includes(state.status)) return no("unsafe-proxy");
+	}
+	const image = await run("docker", ["image", "inspect", EGRESS_PROXY_IMAGE]);
+	if (image.code !== 0) return no("unavailable");
+	const network = await run("docker", ["network", "inspect", "pi-dispatch-egress-out"]);
+	if (network.code !== 0 && !/No such network/i.test(network.stderr)) return no("unavailable");
+	return { effects: ["start-proxy"], inputs: { runtime: digest(Object.fromEntries(runtimeKeys.map((key) => [key, runtimeEnv[key] ?? null]))), files: Object.fromEntries(Object.entries(files).map(([k, v]) => [k, digest(v)])), state, daemon: daemon.stdout.trim(), network: network.code === 0 ? digest(network.stdout) : null }, egress: { bin: "docker", run, state, networkMissing: network.code !== 0, running: state?.status === "running" } };
+}
+
+export async function applySetupEgress(plan, ctx) {
+	const e = plan.egress;
+	if (e.running) return { state: "unchanged", reason: "already-running", effects: [] };
+	if (e.bin === "podman") {
+		const result = await applyStack(e.stack, { fs: ctx.fs, run: async (bin, args) => (await e.run(bin, args)).code });
+		if (!result.ok) return { state: result.ran ? "partial" : "unknown", reason: "process-failed", effects: plan.effects };
+	} else {
+		if (e.networkMissing && (await e.run("docker", EGRESS_NETWORK_ARGS)).code !== 0) return { state: "unknown", reason: "process-failed" };
+		const result = await e.run("docker", e.state ? ["start", DEFAULT_EGRESS_PROXY] : EGRESS_RUN_ARGS);
+		if (result.code !== 0) return { state: "partial", reason: "process-failed", effects: plan.effects };
+	}
+	const read = await e.run(e.bin, ["inspect", PROXY_STATE_FORMAT, DEFAULT_EGRESS_PROXY]);
+	return parseProxyState(read.stdout)?.status === "running" ? { state: "applied", reason: "ready", effects: plan.effects } : { state: "unknown", reason: "readback-unavailable", effects: plan.effects };
+}

package/src/setup-host-entry.mjs

@@ -0,0 +1,33 @@
+/** Resolve only the installed worker's own entry; npm's disposable execution cache is never a service target. */
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function setupCachePath(path) {
+	return /(?:^|[/\\])(?:_npx|_cacache|npm-cache|\.cache)(?:[/\\]|$)/.test(String(path));
+}
+export function trustedSetupFile(entry, { uid = process.geteuid?.(), realpath = realpathSync, stat = statSync } = {}) {
+	try {
+		const path = realpath(entry);
+		const facts = stat(path);
+		if (!facts.isFile() || (facts.uid !== uid && facts.uid !== 0) || (facts.mode & 0o022) || setupCachePath(path)) return null;
+		for (let parent = dirname(path); ; parent = dirname(parent)) {
+			const st = stat(parent);
+			if (!st.isDirectory() || (st.uid !== uid && st.uid !== 0) || ((st.mode & 0o022) && !(st.mode & 0o1000))) return null;
+			if (parent === dirname(parent)) break;
+		}
+		return path;
+	} catch { return null; }
+}
+export function resolveSetupWorkerEntry({ entry = fileURLToPath(new URL("./cli.mjs", import.meta.url)), uid = process.geteuid?.(), realpath = realpathSync, readFile = readFileSync, stat = statSync, exists = existsSync } = {}) {
+	try {
+		const path = trustedSetupFile(entry, { uid, realpath, stat });
+		if (path === null) return { refusal: "unsafe-entry" };
+		const metadata = join(dirname(path), "..", "package.json");
+		const pkg = JSON.parse(readFile(metadata, "utf8"));
+		const facts = stat(path);
+		const safeFile = (st) => st.isFile() && (st.uid === uid || st.uid === 0) && !(st.mode & 0o022);
+		if (setupCachePath(path) || !exists(path) || !safeFile(facts) || !safeFile(stat(metadata)) || pkg.name !== "@edgehero/pi-dispatch" || !/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i.test(pkg.version) || !path.endsWith(`${String(path).includes("\\") ? "\\" : "/"}src${String(path).includes("\\") ? "\\" : "/"}cli.mjs`)) return { refusal: "unsafe-entry" };
+		return { entry: path, version: pkg.version };
+	} catch { return { refusal: "unsafe-entry" }; }
+}