@edgehero/pi-dispatch 1.10.3 → 2.1.0

package/src/config.mjs

@@ -5,14 +5,16 @@
  * Errors are tagged `piDispatchConfig` so the CLI/entry can print them cleanly and exit non-zero.
  */
 
-import { existsSync } from "node:fs";
-import { hostname } from "node:os";
-import { delimiter } from "node:path";
+import { chmodSync, existsSync, lstatSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { homedir, hostname, tmpdir } from "node:os";
+import { delimiter, isAbsolute, posix } from "node:path";
 import { DEFAULT_BACKEND, backendRefusals, parseBackendFloor, parseBackendList } from "./backends.mjs";
-import { DEFAULT_EGRESS_PROXY, egressArmed } from "./egress.mjs";
+import { egressArmed, egressProxyName } from "./egress.mjs";
 import { MINTED_TOKEN_VARS } from "./forges.mjs";
+import { SWEEP_INTERVAL_HOURS, SWEEP_INTERVAL_MAX_HOURS } from "./retention-sweep.mjs";
 import { parseSecretProfiles } from "./secret-profiles.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, WAIT_INTERVAL_FLOOR_MS, parseWaitProfiles } from "./wait-for.mjs";
+import { imageRefProblem } from "./image-ref.mjs";
 
 export function configError(message) {
 	const error = new Error(message);
@@ -27,14 +29,30 @@ export function configError(message) {
 export const CHAIN_DEPTH_MAX_DEFAULT = 1; // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
 export const CHAIN_MAX_PER_JOB_DEFAULT = 2; // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
 
-function boundedInt(env, name, fallback, min, want) {
+// The failure hook's command (issue #288). Unset/blank -> null (the feature is off). Set -> one
+// ABSOLUTE path, verbatim; a relative path refuses at boot, because resolving it against a service
+// manager's working directory would make the hook fire or vanish depending on who started the worker.
+// `isAbsolute` is the PLATFORM's: on Windows it accepts `C:\...` where the posix one would refuse it,
+// and that half is only testable on Windows itself -- the same only-runnable-there caveat this file
+// already records for the drive-letter split below.
+function parseOnFailure(raw) {
+	if (raw === undefined || raw === "") return null;
+	if (typeof raw !== "string" || !isAbsolute(raw)) {
+		throw configError(`invalid PI_ON_FAILURE: ${JSON.stringify(raw)} (want an absolute path to one executable)`);
+	}
+	return raw;
+}
+
+// `max` is optional and defaults to no upper bound, which is the convention `optionalBoundedInt` below
+// already documents -- so every existing caller is unchanged by its arrival.
+function boundedInt(env, name, fallback, min, want, max = undefined) {
 	const raw = env[name];
 	if (raw === undefined || raw === "") {
 		if (fallback !== undefined) return fallback;
 		throw configError(`missing required env: ${name}`);
 	}
 	const n = Number.parseInt(raw, 10);
-	if (!Number.isInteger(n) || n < min || String(n) !== String(raw).trim()) {
+	if (!Number.isInteger(n) || n < min || (max !== undefined && n > max) || String(n) !== String(raw).trim()) {
 		throw configError(`invalid ${name}: ${JSON.stringify(raw)} (want ${want})`);
 	}
 	return n;
@@ -45,8 +63,8 @@ export function positiveInt(env, name, fallback) {
 }
 
 // min=0: accepts 0 (a sentinel, e.g. "keep forever" for log retention), still rejects negatives and non-integers.
-function nonNegativeInt(env, name, fallback) {
-	return boundedInt(env, name, fallback, 0, "a non-negative integer");
+function nonNegativeInt(env, name, fallback, max = undefined) {
+	return boundedInt(env, name, fallback, 0, max === undefined ? "a non-negative integer" : `an integer 0-${max}`, max);
 }
 
 // An OPTIONAL bounded int: an unset or empty var is `null` (the feature it gates is disabled), a present
@@ -107,10 +125,21 @@ function commaList(raw) {
  * `GITHUB_APP_PRIVATE_KEY_PATH` is deliberately NOT here: a path string with no mount behind it is inert
  * inside a container, and refusing harmless things is how a refusal stops being read.
  *
+ * `VALKEY_PASSWORD` (issue #468) is the queue's password. Whoever holds it can read every queued job (its task text,
+ * its repository), enqueue work this deployment's worker runs with its provider key and forge credentials, and delete
+ * the queue: the very thing the password was added to keep from another account on the host, and so no more a job
+ * container's than theirs.
+ *
  * Kept separate from `MINTED_TOKEN_VARS`, which is defined as "every name any forge's mint can write"
  * and derived from the forge table. This is not that, and folding it in would make that definition a lie.
  */
-export const WORKER_ONLY_SECRET_VARS = new Set(["GITHUB_APP_PRIVATE_KEY"]);
+export const WORKER_ONLY_SECRET_VARS = new Set(["GITHUB_APP_PRIVATE_KEY", "VALKEY_PASSWORD"]);
+
+/** Why each of `WORKER_ONLY_SECRET_VARS` stays in the worker, for the refusal that names it. */
+const WORKER_ONLY_WHY = Object.freeze({
+	GITHUB_APP_PRIVATE_KEY: "the App's signing key mints tokens for every repository the App is installed on",
+	VALKEY_PASSWORD: "the queue's password lets whoever holds it read, enqueue and delete this deployment's jobs",
+});
 
 /**
  * The proxy variables the egress policy writes into the closed container env (REQ-EGRESS-ALLOWLIST).
@@ -133,7 +162,7 @@ function forwardEnvList(raw, egressArmed = false) {
 	const workerOnly = names.filter((n) => WORKER_ONLY_SECRET_VARS.has(n));
 	if (workerOnly.length > 0) {
 		throw configError(
-			`PI_FORWARD_ENV must not forward ${workerOnly.join(", ")} -- the App's signing key mints tokens for every repository the App is installed on, and a job container is the last place it belongs (CONST-TOKEN-SCOPED-PER-JOB)`,
+			`PI_FORWARD_ENV must not forward ${workerOnly.join(", ")} -- ${workerOnly.map((n) => WORKER_ONLY_WHY[n]).join("; ")}, and a job container is the last place it belongs (CONST-TOKEN-SCOPED-PER-JOB)`,
 		);
 	}
 	const egress = egressArmed ? names.filter((n) => EGRESS_ENV_VARS.has(n)) : [];
@@ -200,6 +229,19 @@ function refuseBackendShortfall(config) {
 	if (first) throw configError(first);
 }
 
+/**
+ * PI_JOB_IMAGE as the worker runs it (issue #471): unset or empty is pi-job:latest (`||`, so "" falls back), and any
+ * other value is judged by the one image rule `run.image` is (`image-ref.mjs`). A refused value is a config error at
+ * boot (exit 2), naming the key: before #471 a dash-leading value booted, and every job then handed the runtime a flag
+ * where the image belongs, after its budget slot was reserved.
+ */
+export function jobImageFrom(env) {
+	const image = env.PI_JOB_IMAGE || "pi-job:latest";
+	const problem = imageRefProblem(image);
+	if (problem) throw configError(`PI_JOB_IMAGE ${problem.reason} (got ${JSON.stringify(image)})`);
+	return image;
+}
+
 // The operator's global pi overlay dir (REQ-GLOBAL-PI-OVERLAY). Unset/empty = feature off. When set it
 // must EXIST at boot -- a typo pointing at nothing would silently drop the operator's whole setup on
 // every job, so fail loud like every other config error rather than degrade to nothing.
@@ -278,7 +320,7 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		maxTurns: positiveInt(env, "PI_MAX_TURNS", 30), // pi has no turn limit; we impose one
 		maxTokens: optionalBoundedInt(env, "PI_MAX_TOKENS", 1), // issue #25; null = per-job token budget disabled (lagging in-run backstop)
 		dailyTokenCap: optionalBoundedInt(env, "PI_DAILY_TOKEN_CAP", 1), // issue #25; null = daily token counter disabled (check-AFTER, host-side)
-		jobImage: env.PI_JOB_IMAGE || "pi-job:latest", // || (not ??) so an empty string falls back; "" is falsy and would throw inside buildDockerRunArgs AFTER a budget slot was reserved
+		jobImage: jobImageFrom(env), // || (not ??) so an empty string falls back; "" is falsy and would throw inside buildDockerRunArgs AFTER a budget slot was reserved
 		globalPiDir: resolveGlobalPiDir(env, fileExists), // REQ-GLOBAL-PI-OVERLAY: operator's ~/.pi/agent subset, :ro-mounted; null = off
 		allowGlobalExtensions: globalExtensionsEnabled(env), // REQ-GLOBAL-PI-OVERLAY: ON unless PI_GLOBAL_ALLOW_EXTENSIONS=0
 		// REQ-EGRESS-ALLOWLIST. `egress` gates the whole feature; `egressProxy` names the component the
@@ -294,10 +336,10 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// trigger says otherwise". `parseBackendList` never returns empty, so the fallback is belt-and-braces
 		// against a future edit rather than a reachable branch today.
 		defaultBackend: backends[0] ?? DEFAULT_BACKEND,
-		egressProxy: env.PI_EGRESS_PROXY || DEFAULT_EGRESS_PROXY, // || (not ??) so an empty string falls back
+		egressProxy: egressProxyName(env), // one derivation, shared with the panel's sandbox (#277)
 		forwardEnv: forwardEnvList(env.PI_FORWARD_ENV, egressEnabled(env)), // extra host var NAMES to forward (e.g. a custom provider's key); explicit allowlist, GitHub token names refused
 		authFromPi: env.PI_AUTH_FROM_PI !== "0", // ON by default: use the key in ~/.pi/agent/auth.json when the env has none (api-key only). PI_AUTH_FROM_PI=0 forces env-only.
-		jobsDir: env.PI_JOBS_DIR ?? defaultJobsDir(),
+		jobsDir: jobsDirPath(env),
 		// REQ-RESURRECTABLE-SANDBOX. `||` (not `??`) so an empty string falls back, matching logsDir.
 		sandboxDir: env.PI_SANDBOX_DIR || defaultSandboxDir(env),
 		// Hours a finished run's directory stays re-openable. NOTE THE SENTINEL, which is the OPPOSITE of
@@ -309,18 +351,26 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		sandboxPinDays: nonNegativeInt(env, "PI_SANDBOX_PIN_DAYS", 7), // `--pin` extends to now + this, never to forever
 		sandboxIdleMinutes: nonNegativeInt(env, "PI_SANDBOX_IDLE_MINUTES", 30), // bash's own TMOUT inside a sandbox; 0 = no idle logout
 		triggersFile: env.PI_TRIGGERS_FILE ?? null, // DES-CRON-VIA-BULLMQ-SCHEDULER: unified triggers file; null = cron disabled for the worker (it selects on.type:"cron")
-		pauseWindowsFile: env.PI_PAUSE_WINDOWS_FILE ?? null, // REQ-SCOPED-PAUSE-WINDOWS: per-folder/repo timed pause; null = no scoped pauses
-		scopedLimitsFile: env.PI_SCOPED_LIMITS_FILE ?? null, // issue #242: per-scope run caps + concurrency (INT-SCOPED-LIMITS-FILE-CONTRACT); null = none. The one-job-per-folder mutex for local jobs is code, not configuration, and holds regardless
+		pauseWindowsFile: pauseWindowsFilePath(env), // REQ-SCOPED-PAUSE-WINDOWS: per-folder/repo timed pause; null = no scoped pauses
+		scopedLimitsFile: scopedLimitsFilePath(env), // issue #242: per-scope run caps + concurrency (INT-SCOPED-LIMITS-FILE-CONTRACT); null = none. The one-job-per-folder mutex for local jobs is code, not configuration, and holds regardless
 		schedulerStallMax: positiveInt(env, "PI_SCHEDULER_STALL_MAX", 2), // CONST-RETRY-INFRA-ONLY: per-scheduler stall backstop; positiveInt rejects <1 so a 0 threshold fails closed
-		logsDir: env.PI_LOGS_DIR || defaultLogsDir(), // || (not ??) so an empty string falls back to the default
-		settingsFile: env.PI_SETTINGS_FILE || defaultSettingsFile(), // || (not ??) so an empty string falls back; INT-CONFIG-OVERLAY-CONTRACT
+		logsDir: logsDirPath(env), // || (not ??) inside logsDirPath, so an empty string falls back to the default
+		settingsFile: settingsFilePath(env), // || (not ??) inside settingsFilePath, so an empty string falls back; INT-CONFIG-OVERLAY-CONTRACT
 		captureJobLogs: env.PI_CAPTURE_JOB_LOGS === "1", // no-pii-in-logs: raw job-log capture is opt-in; anything but "1" is off
 		logRetentionDays: nonNegativeInt(env, "PI_LOG_RETENTION_DAYS", 30), // 0 = keep forever
-		// REQ-RESUMABLE-SESSION. NO DEFAULT, deliberately unlike logsDir/jobsDir: unset means the feature
-		// is unavailable, and a trigger that armed run.resume then refuses PRE-SPEND rather than running
-		// silently without persistence. A transcript is the most PII-bearing artifact this system holds --
-		// tool output, file contents, the agent's own reasoning -- and defaulting it into <OS temp>, which
-		// is mode 1777 on POSIX, is not a place to put that by accident.
+		// issue #292, OQ-007: how often the three host-side retention sweeps re-run while the worker is up.
+		// 0 = BOOT-ONLY, which is byte-identical to every version before this one -- start.mjs does not even
+		// CONSTRUCT the sweep at 0, so no timer, no closer and no second invocation of any reaper is reachable.
+		// The ceiling is enforced because setInterval clamps a delay past 2^31-1 ms to 1ms (see
+		// SWEEP_INTERVAL_MAX_HOURS); a hot loop over the filesystem is a worse failure than a slow sweep.
+		sweepIntervalHours: nonNegativeInt(env, "PI_SWEEP_INTERVAL_HOURS", SWEEP_INTERVAL_HOURS, SWEEP_INTERVAL_MAX_HOURS),
+		// REQ-RESUMABLE-SESSION. NO DEFAULT AT ALL, deliberately unlike every sibling above: unset means the
+		// feature is unavailable, and a trigger that armed run.resume then refuses PRE-SPEND rather than
+		// running silently without persistence. A transcript is the most PII-bearing artifact this system
+		// holds -- tool output, file contents, the agent's own reasoning -- and a DEFAULT would turn that
+		// refusal into a silent success on a path nobody chose. That reasoning stands on its own and does
+		// not rest on where the other stores default: issue #290 moved logs and settings to ~/.pi-dispatch
+		// and this one still has no default, for the same reason it never did.
 		sessionsDir: env.PI_SESSIONS_DIR || null,
 		sessionsTtlDays: nonNegativeInt(env, "PI_SESSIONS_TTL_DAYS", 14), // 0 = keep forever
 		// A bound on how large a transcript may be before it stops being resumed. Not disk hygiene: an
@@ -395,6 +445,16 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// broken check loud in minutes instead of silent for a day (OQ-027: most CLIs exit 1 for everything).
 		waitMaxChecks: positiveInt(env, "PI_WAIT_MAX_CHECKS", 96),
 		waitMaxFaults: positiveInt(env, "PI_WAIT_MAX_FAULTS", 5),
+		// Issue #288, the operator's failure hook: ONE command, exec'd with id-only argv when a paid job
+		// reaches a terminal failure. Unset = off, byte-identically. Set = must be an ABSOLUTE path,
+		// refused at boot otherwise (parseWaitProfiles' fail-loud posture, and sharper here: a silently
+		// dropped hook is a notification the operator believes is wired, discovered at the failure it was
+		// wired for). Existence/executability are probed at FIRE time, not boot, so a script installed
+		// mid-day works and one deleted mid-day logs `unresolvable` rather than pretending.
+		onFailure: parseOnFailure(env.PI_ON_FAILURE),
+		// Bounds a LEAKED CHILD after the job, not a pre-spend wait -- which is why this differs from its
+		// two 10s twins in what it protects: nothing here holds a slot or delays a container.
+		onFailureTimeoutMs: positiveInt(env, "PI_ON_FAILURE_TIMEOUT_MS", 10000),
 		github: { ...loadGitHubAuth(env, fileExists), allowGhResume: env.PI_SESSIONS_ALLOW_GH_SOURCE === "1" },
 		gitlab: loadGitLabAuth(env),
 		forgejo: loadForgejoAuth(env),
@@ -498,28 +558,433 @@ export function loadGitHubAuth(env, fileExists) {
 	return { source, patVar, appId, installationId, privateKeyPath, privateKey };
 }
 
-// env-internal TMPDIR, TEMP: the OS temp dir, read to place the default job, log, graph and settings
-// paths below. Not a variable of this project's and not a deployment knob: PI_JOBS_DIR, PI_LOGS_DIR,
-// PI_GRAPH_DIR and PI_SETTINGS_FILE are how an operator moves any of them, and .env.example says so.
-function defaultJobsDir() {
-	// Under the OS temp dir by default. Holds only the read-only /job inputs (prompt + .pi/); the
+// env-internal TMPDIR, TEMP: the OS temp dir, read to place the default job, sandbox and graph paths
+// below -- and, only on a host with no home directory to name, as the last-resort fallback for the
+// durable state root. Not a variable of this project's and not a deployment knob: PI_JOBS_DIR,
+// PI_LOGS_DIR, PI_GRAPH_DIR and PI_SETTINGS_FILE are how an operator moves any of them, and
+// .env.example says so.
+
+/** This process's effective uid, the one its files are created as, or null where the platform has none (Windows). */
+function currentUid() {
+	return typeof process.geteuid === "function" ? process.geteuid() : null;
+}
+
+/**
+ * The per-account root under the OS temp dir that the default jobs, sandbox and graph paths live in (issue #464):
+ * `<tmp>/pi-dispatch-<uid>`, or `<tmp>/pi-dispatch` where the platform has no uid (Windows, whose TEMP is per user).
+ *
+ * Per ACCOUNT because the OS temp dir is shared by every account on a host. The old `<tmp>/pi-dispatch` was created by
+ * whichever account ran a job first (mode 775 or 755 under that account), and every other account's jobs then failed
+ * `EACCES` at `mkdtemp`, their worker service included, while doctor said ready (measured on Fedora 44 and Ubuntu
+ * 24.04). Not `$XDG_RUNTIME_DIR`: that is a small tmpfs (10% of RAM by default) that a retained sandbox, a whole repo
+ * clone, would fill, it is removed at the account's last logout without linger, and a shell reached through `sudo -iu`
+ * has none, so the worker and doctor could disagree about where the jobs are. `ensureAccountTempRoot` creates this
+ * directory 0700 and refuses one this account does not own, since anyone can create a name under a sticky /tmp first.
+ */
+export function accountTempRoot(env = process.env, uid = currentUid()) {
+	const suffix = Number.isInteger(uid) && uid >= 0 ? `-${uid}` : "";
+	return `${tempRoot(env)}/pi-dispatch${suffix}`;
+}
+
+function defaultJobsDir(env = process.env, uid = currentUid()) {
+	// Under the OS temp dir by default, and it STAYS there (issue #290 moved only the two durable
+	// stores). Holds only the read-only /job inputs (prompt + .pi/), rebuilt from scratch every job; the
 	// workspace for a local job is the operator's own folder, not here.
-	return `${process.env.TMPDIR ?? process.env.TEMP ?? "/tmp"}/pi-dispatch/jobs`.replace(/\\/g, "/");
+	//
+	// Takes `env` because its caller `defaultSandboxDir` advertises one and could not honour it while
+	// this function read `process.env` directly -- an injected TMPDIR was silently ignored one frame in.
+	return `${accountTempRoot(env, uid)}/jobs`;
+}
+
+/**
+ * The per-job directory root, ONE derivation (issue #278). `doctor --live` builds its fixture here, and a probe that
+ * derived the path on its own could disagree with the worker about `PI_JOBS_DIR=""` (kept as given, `??` not `||`,
+ * as `loadConfig` always has) or an injected `TMPDIR`, and read back a directory no job uses. `loadConfig` read
+ * `defaultJobsDir()` without its `env` before this, which ignored an injected TMPDIR exactly as `defaultSandboxDir`'s
+ * comment below records for itself; identical on the real path, where env is process.env.
+ */
+export function jobsDirPath(env = process.env, uid = currentUid()) {
+	return env.PI_JOBS_DIR ?? defaultJobsDir(env, uid);
+}
+
+/**
+ * The jobs dir, made ready for this account's jobs, or a thrown Error saying why it cannot be (issue #464). A jobs dir
+ * inside the per-account root (`accountTempRoot`, where the default lives) secures that root first; then the jobs dir
+ * is created (0700 where it is new) and must be a directory this account owns. A `PI_JOBS_DIR` elsewhere that another
+ * account owns is refused too: the owner of the directory holding a job's inputs can rename them and put its own in
+ * their place. `fs` is a seam; with no uid (Windows) nothing is checked and the dir is created as before. A refusal is a
+ * `configError` (determinate: the next try meets the same owner); a failed mkdir is thrown as the fs error it is.
+ */
+export function ensureJobsDir(jobsDir, { env = process.env, uid = currentUid(), fs = { mkdirSync, lstatSync, statSync, chmodSync } } = {}) {
+	ensureUnderAccountRoot(jobsDir, { env, uid, fs });
+	fs.mkdirSync(jobsDir, { recursive: true, mode: 0o700 });
+	if (!Number.isInteger(uid)) return;
+	const st = fs.statSync(jobsDir);
+	if (!st.isDirectory()) throw configError(`the jobs dir ${jobsDir} is not a directory`);
+	if (st.uid !== uid) throw configError(`the jobs dir ${jobsDir} is owned by uid ${st.uid}, not by this account (uid ${uid}), and that account could replace a job's inputs: ${jobsDirOwnerFix(jobsDir, false)}`);
+}
+
+/**
+ * The sandbox dir (retained workspaces), checked at boot as the jobs dir is (issue #464, gate round 1): inside the
+ * per-account root that root is secured first; a sandbox dir that exists must be a directory this account owns. Not
+ * created here: the retention step makes it 0700 when it first keeps a run (`retainJobDir`), and asks the owner again
+ * then. The owner of the directory holding a retained workspace can rename it and plant a manifest of its own in its
+ * place, which `pi-dispatch sandbox` then lists and opens (measured: an explicit PI_SANDBOX_DIR another account made
+ * 0777 was used, and that account swapped the entry). A `configError`, since a restart meets the same owner.
+ */
+export function ensureSandboxDir(sandboxDir, { env = process.env, uid = currentUid(), fs = { mkdirSync, lstatSync, statSync, chmodSync } } = {}) {
+	ensureUnderAccountRoot(sandboxDir, { env, uid, fs });
+	if (!Number.isInteger(uid)) return;
+	let st;
+	try {
+		st = fs.statSync(sandboxDir);
+	} catch (err) {
+		if (err?.code === "ENOENT") return;
+		throw configError(`the sandbox dir ${sandboxDir} could not be read (${err?.code ?? err?.message}): point PI_SANDBOX_DIR at a directory this account owns`);
+	}
+	if (!st.isDirectory()) throw configError(`the sandbox dir ${sandboxDir} is not a directory: point PI_SANDBOX_DIR at a directory this account owns`);
+	if (st.uid !== uid) throw configError(`the sandbox dir ${sandboxDir} is owned by uid ${st.uid}, not by this account (uid ${uid}), and that account could swap a retained workspace for one of its own: ${sandboxDirOwnerFix(sandboxDir)}`);
+}
+
+/** The remedy for a sandbox dir another account owns, shared with doctor. */
+export function sandboxDirOwnerFix(dir) {
+	return `point PI_SANDBOX_DIR at a directory this account owns (or remove the line for the default), or chown ${dir} to this account`;
 }
 
-export function defaultSandboxDir(env = process.env) {
+/**
+ * Secure the per-account root (`ensureAccountTempRoot`) when `path` lies in it, else do nothing (issue #464). The one
+ * rule for every default that can live there: the jobs, sandbox and graph dirs, and, on an account with no home, the
+ * run history and the settings overlay (`defaultStateDir`). Returns whether it did.
+ */
+export function ensureUnderAccountRoot(path, { env = process.env, uid = currentUid(), fs = { mkdirSync, lstatSync, statSync, chmodSync } } = {}) {
+	const root = accountTempRoot(env, uid);
+	const p = String(path ?? "").replace(/\\/g, "/");
+	if (p !== root && !p.startsWith(`${root}/`)) return false;
+	ensureAccountTempRoot(root, { uid, fs });
+	return true;
+}
+
+/** The remedy for a jobs dir (`inRoot` false) or a per-account root (`inRoot` true) another account owns, shared with doctor. */
+export function jobsDirOwnerFix(dir, inRoot) {
+	return inRoot
+		? `another account created ${dir} before this one; remove it as its owner or as root (sudo rm -rf ${dir}), or set PI_JOBS_DIR in .env to a directory this account owns`
+		: `point PI_JOBS_DIR at a directory this account owns, or chown ${dir} to this account`;
+}
+
+/**
+ * Create `root` mode 0700 when it is absent, and refuse it unless it is a real directory (never a symlink, lstat) owned
+ * by `uid`; one this account owns with group or other bits is tightened to 0700. Exported for the admin's graph dir,
+ * which lives under the same root. Throws a `configError` naming the path and the remedy.
+ *
+ * lstat FIRST, never a recursive mkdir first (gate round 1, measured on Fedora 44): with fs.protected_symlinks on (the
+ * default on Fedora and Ubuntu), following another account's symlink under the sticky /tmp fails EACCES, and the
+ * recursive mkdir's own stat of the existing name did exactly that, so a symlink squat reached the worker as a raw
+ * EACCES (exit 1, a systemd restart loop) and each job as a generic failure instead of this refusal. The root itself is
+ * made with a plain mkdir, so a name another account creates between the lstat and the mkdir is EEXIST, judged again.
+ */
+export function ensureAccountTempRoot(root, { uid = currentUid(), fs = { mkdirSync, lstatSync, statSync, chmodSync } } = {}) {
+	if (!Number.isInteger(uid)) {
+		fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+		return;
+	}
+	const refuse = (why) => configError(`${root} ${why}: ${jobsDirOwnerFix(root, true)}`);
+	const look = () => {
+		try {
+			return fs.lstatSync(root);
+		} catch (err) {
+			if (err?.code === "ENOENT") return null;
+			throw refuse(`could not be read (${err?.code ?? err?.message})`);
+		}
+	};
+	let st = look();
+	if (st === null) {
+		try {
+			// The temp dir itself (a TMPDIR the operator named may not exist yet), then the root on its own.
+			fs.mkdirSync(posix.dirname(root), { recursive: true });
+			fs.mkdirSync(root, { mode: 0o700 });
+		} catch (err) {
+			if (err?.code !== "EEXIST") throw refuse(`could not be created (${err?.code ?? err?.message})`);
+		}
+		st = look();
+		if (st === null) throw refuse("vanished as it was created");
+	}
+	if (st.isSymbolicLink() || !st.isDirectory()) throw refuse("is not a directory (a symlink or a file there is refused, since any account can create a name under the temp dir)");
+	if (st.uid !== uid) throw refuse(`is owned by uid ${st.uid}, not by this account (uid ${uid})`);
+	if ((st.mode & 0o077) !== 0) fs.chmodSync(root, 0o700);
+}
+
+export function defaultSandboxDir(env = process.env, uid = currentUid()) {
 	// Beside the per-job dirs, because a retained directory IS a per-job dir -- `cleanup` renames it here
 	// rather than copying, which only stays atomic while both live on one filesystem. Created mode 0700 by
 	// the retention step, since the OS temp dir is 1777 on POSIX and a retained tree holds a repository
 	// clone plus the run's prompt.md/event.json. Exported so the admin extension resolves the same default
 	// without calling loadConfig, which throws on unrelated env problems.
-	return `${env.PI_JOBS_DIR ?? defaultJobsDir()}/sandboxes`.replace(/\\/g, "/");
+	//
+	// Under temp deliberately, and unmoved by issue #290: a retained workspace is bounded by
+	// PI_SANDBOX_RETENTION_HOURS and is disposable by design, so a swept temp dir costs nothing that the
+	// sweep was not already going to take.
+	return `${jobsDirPath(env, uid)}/sandboxes`.replace(/\\/g, "/");
+}
+
+/**
+ * The home directory, or "" when this host cannot name one.
+ *
+ * `homedir()` throws on a host with no passwd entry (a bare uid in a container) and returns "" when
+ * HOME is set but empty -- both measured. This takes `defaultWorkerName`'s posture below: a path is
+ * never worth refusing boot for, so an unanswerable home degrades to the temp fallback rather than
+ * throwing, and `underOsTempDir` is what makes that degradation VISIBLE instead of silent.
+ */
+export function safeHomeDir() {
+	try {
+		return homeOrEmpty(homedir());
+	} catch {
+		return "";
+	}
 }
 
-export function defaultLogsDir() {
-	// Under the OS temp dir by default. Holds durable per-run history/log artifacts written host-side;
-	// a worker-owned path that never enters the container env allowlist (no-broad-env-into-container).
-	return `${process.env.TMPDIR ?? process.env.TEMP ?? "/tmp"}/pi-dispatch/logs`.replace(/\\/g, "/");
+/**
+ * Normalise anything offered as a home directory to a usable string, or "".
+ *
+ * Split out of `safeHomeDir` because `home` is also a SEAM (doctor injects one to exercise the no-home
+ * case on a host that has one), and a seam that only the guarded path validates is a guard with a hole:
+ * `defaultLogsDir({}, null)` threw a TypeError before this existed. Blank-but-present is "" for the same
+ * reason `loadConfig` spells the durable paths with `||` -- an empty value can only mask a working
+ * default, never express one.
+ */
+function homeOrEmpty(home) {
+	return typeof home === "string" ? home.trim() : "";
+}
+
+/**
+ * The root of the two DURABLE stores: the run history and the settings overlay (issue #290).
+ *
+ * Under the home directory, NOT the OS temp dir. Linux leaves TMPDIR unset so the old default was
+ * literally `/tmp/pi-dispatch`, and on the distros where /tmp is tmpfs that is RAM: the run history
+ * REQ-DURABLE-RUN-HISTORY promises and every cap the operator tuned from the panel were gone on the
+ * next reboot, while the queue beside them survived on Valkey's AOF volume.
+ *
+ * `~/.pi-dispatch` rather than a per-platform state dir (XDG_STATE_HOME, ~/Library/Application
+ * Support, LOCALAPPDATA), for four reasons. This project has exactly ONE home-dir pattern and it is
+ * this shape (`PI_CODING_AGENT_DIR || ~/.pi/agent`). docs/sessions.md already teaches
+ * `~/.pi-dispatch/sessions` as the place to put the session store, so these two land beside a
+ * directory the docs already tell an operator to create, and docs/backup.md can name one target.
+ * `~/Library/Application Support` contains a space, and doctor prints copy-pasteable fix lines. And a
+ * per-platform trio would be three new ENV reads needing their own env-internal markers, where
+ * `homedir()` is a node:os call that the env-docs scan does not see at all.
+ *
+ * WITH NO HOME, this falls back to a temp path, and that is load-bearing rather than a leak: the fallback
+ * is exactly what `underOsTempDir` detects, so doctor prints one line naming the path that will not
+ * survive a reboot. Since issue #464 that fallback is the PER-ACCOUNT root (`accountTempRoot`,
+ * `<tmp>/pi-dispatch-<euid>`), secured by `ensureUnderAccountRoot` as the jobs dir is: the old shared
+ * `<tmp>/pi-dispatch` was created by whichever homeless account wrote first, and every other account's
+ * records then failed to write, or landed in a directory another account controls. `legacyTempStateDir`
+ * still names that OLD shared address, for doctor's migration hint, and is spelled out on its own.
+ *
+ * The temp fallback reads a BLANK `TMPDIR`/`TEMP` as absent rather than using it.
+ * The pre-#290 code spelled this `??`, so `TMPDIR=""` composed the bare `/pi-dispatch` -- a path at the
+ * filesystem root that a non-root worker cannot create, and one `underOsTempDir` cannot recognise either,
+ * because an empty root is not a prefix of anything. The detector would then have reported "survives a
+ * reboot" over a directory that does not even exist. `||` in both places is what keeps the fallback and
+ * the detector describing the same world; it is the same rule `loadConfig` applies to PI_LOGS_DIR itself.
+ */
+function defaultStateDir(env = process.env, home = safeHomeDir(), uid = currentUid()) {
+	// Strip the home dir's own trailing separator BEFORE composing, not after: stripping the composed
+	// string only reaches a slash at the END, and `${"/home/u/"}/.pi-dispatch` puts one in the MIDDLE.
+	const h = homeOrEmpty(home);
+	if (h !== "") return `${h.replace(/\\/g, "/").replace(/\/+$/, "")}/.pi-dispatch`;
+	return accountTempRoot(env, uid);
+}
+
+/**
+ * The OS temp dir as this project reads it, or "/tmp".
+ *
+ * TRIMMED and stripped of a trailing separator, which is not cosmetic on either count. A whitespace-only
+ * `TMPDIR` composed a RELATIVE path ("   /pi-dispatch/logs") that would resolve against whatever cwd the
+ * worker was started in, and macOS hands back a trailing slash that otherwise rides into the `//` doctor
+ * prints in its copy-pasteable fix lines. Blank reads as absent for the reason `defaultStateDir` explains.
+ */
+function tempRoot(env = process.env) {
+	for (const raw of [env.TMPDIR, env.TEMP]) {
+		const v = typeof raw === "string" ? raw.trim() : "";
+		if (v !== "") return v.replace(/\\/g, "/").replace(/(?!^)\/+$/, "");
+	}
+	return "/tmp";
+}
+
+/** The address the durable stores had before issue #290, so doctor's migration hint can name it. */
+export function legacyTempStateDir(env = process.env) {
+	// The SHARED address every account used before issues #290 and #464; not a path anything writes any more.
+	return `${tempRoot(env)}/pi-dispatch`;
+}
+
+export function defaultLogsDir(env = process.env, home = safeHomeDir(), uid = currentUid()) {
+	// Durable by default (issue #290, REQ-DURABLE-RUN-HISTORY): holds the per-run history sidecars and,
+	// when PI_CAPTURE_JOB_LOGS=1, the raw logs. A worker-owned path that never enters the container env
+	// allowlist (no-broad-env-into-container). Exported so the admin extension resolves the same default
+	// without calling loadConfig, which throws on unrelated env problems -- and the admin resolving the
+	// SAME answer is the whole point: a panel reading a different directory shows an empty history and
+	// says nothing about why.
+	return `${defaultStateDir(env, home, uid)}/logs`;
+}
+
+export function defaultSettingsFile(env = process.env, home = safeHomeDir(), uid = currentUid()) {
+	// Durable by default, beside the run history (issue #290). Holds the runtime-tunable settings overlay
+	// shared with the admin extension (INT-CONFIG-OVERLAY-CONTRACT); a worker-owned path that never
+	// enters the container env allowlist (no-broad-env-into-container).
+	//
+	// Losing this file is not neutral: readOverlay treats a missing file as an EMPTY overlay, so a swept
+	// settings.json silently restores the wider env cap. That is the same fail-open
+	// DES-RUNTIME-SETTINGS-FILE-OVERLAY already refuses on a bad parse, arriving through the filesystem
+	// instead of through the parser.
+	return `${defaultStateDir(env, home, uid)}/settings.json`;
+}
+
+/**
+ * The resolved run-history directory. ONE derivation, so loadConfig, the admin and doctor cannot drift.
+ *
+ * `home` is forwarded rather than resolved here: doctor injects a home seam (it has to, to exercise the
+ * no-home case on a host that has one), and a helper that read the real homedir behind that seam's back
+ * would answer a different question than the one doctor is asking. Passing `undefined` is what keeps the
+ * ordinary caller on `safeHomeDir()`, since an undefined argument activates a default parameter.
+ */
+/**
+ * The two boot files' paths, `??` and not `||`, EXPORTED so doctor asks the same question the worker does.
+ *
+ * The distinction is the whole reason these exist (issue #384). `??` keeps an empty string, so a blank
+ * `PI_PAUSE_WINDOWS_FILE=` survives into the config, `start.mjs` loads it unconditionally and the boot
+ * refuses; `logsDirPath` below uses `||` and falls back instead. Doctor had a copy of the `??` rule written
+ * out by hand, which is how it came to warn about a deployment its own sibling check failed.
+ */
+export function pauseWindowsFilePath(env = process.env) {
+	return env.PI_PAUSE_WINDOWS_FILE ?? null;
+}
+
+export function scopedLimitsFilePath(env = process.env) {
+	return env.PI_SCOPED_LIMITS_FILE ?? null;
+}
+
+export function logsDirPath(env = process.env, home) {
+	return env.PI_LOGS_DIR || defaultLogsDir(env, home);
+}
+
+/**
+ * The resolved settings-overlay path. Lives HERE, beside `logsDirPath`, so the pair of durable stores has
+ * one derivation each and `loadConfig` does not open-code either. `runtime-settings.mjs` re-exports it, so
+ * `@edgehero/pi-dispatch/runtime-settings` stays the import path the admin and the probe fixture already
+ * use; the alternative (config importing runtime-settings) would be a cycle, since that module reads
+ * `defaultSettingsFile` from here.
+ */
+export function settingsFilePath(env = process.env, home) {
+	return env.PI_SETTINGS_FILE || defaultSettingsFile(env, home);
+}
+
+/** One path in the slash alphabet these defaults are written in, with any trailing separators dropped. */
+function slashy(p) {
+	const s = posix.normalize(String(p).replace(/\\/g, "/")).replace(/\/+$/, "");
+	return s === "" ? "/" : s;
+}
+
+/** A root's spellings: as written, plus its realpath when one resolves. Both count, for a root. */
+function spellings(p, realpath) {
+	const out = new Set([slashy(p)]);
+	try {
+		out.add(slashy(realpath(p)));
+	} catch {
+		// ENOENT is the NORMAL case, not an error: doctor asks this question before these directories
+		// exist. The lexical spelling always remains, and the ROOT usually resolves even when the
+		// candidate does not, which is what still catches macOS's /var -> /private/var on a fresh host.
+	}
+	return out;
+}
+
+/**
+ * WHERE THE CANDIDATE'S BYTES ACTUALLY LAND, as one spelling.
+ *
+ * Deliberately not `spellings()`: unioning the written and resolved forms and accepting any match makes a
+ * symlink that points OUT of the temp dir a false positive, and this check's stated posture is that a
+ * false alarm on a durable path is the worse error. A resolved path is the honest answer to "will the OS
+ * sweep this", so it wins whenever it exists. The dirname retry covers the ordinary case where the leaf
+ * has not been created yet but its parent is a symlink; when neither resolves, the written form is all
+ * there is, which is doctor's situation on a fresh host.
+ */
+function landingSpelling(p, realpath) {
+	try {
+		return slashy(realpath(p));
+	} catch {
+		// fall through to the parent
+	}
+	const written = slashy(p);
+	const cut = written.lastIndexOf("/");
+	if (cut > 0) {
+		try {
+			return `${slashy(realpath(written.slice(0, cut)))}${written.slice(cut)}`;
+		} catch {
+			// fall through to the written form
+		}
+	}
+	return written;
+}
+
+/**
+ * Directories a POSIX host clears without being asked, beyond whatever TMPDIR names.
+ *
+ * `/tmp` is here because it is what the pre-#290 default resolved to on Linux, where TMPDIR is unset,
+ * and it is tmpfs on several distributions. The other three are the ones an operator most plausibly
+ * reaches for while looking for somewhere fast: `/dev/shm` and `/run` are tmpfs by definition, so they
+ * are RAM and do not survive a reboot at all (`/run` does not survive a service restart on some
+ * layouts), and `/var/tmp` is swept by systemd-tmpfiles on a 30 day timer, which is the same order as
+ * the run history's own retention window. Each of these would otherwise have been reported as durable.
+ */
+const POSIX_VOLATILE_ROOTS = Object.freeze(["/tmp", "/var/tmp", "/dev/shm", "/run"]);
+
+/**
+ * Does this path sit under a directory the OS is entitled to sweep (issue #290)?
+ *
+ * ADVISORY, and therefore FAILS OPEN -- the opposite posture from `withinRoots` in
+ * secret-profiles.mjs and `folderUnderRoots` in the admin's read-model, which are boundaries and fail
+ * closed. Nothing is gated on this answer; it decides whether doctor prints one warning. A false
+ * alarm on a durable path is the worse error, because a warning an operator learns to skim is a
+ * warning that stops working.
+ *
+ * It reuses `withinRoots`' ALGORITHM -- normalize, strip trailing separators, then `===` or
+ * `startsWith(base + separator)` so a sibling like `<tmp>-notmine` cannot match -- but deliberately
+ * does not call it. `withinRoots` compares in the NATIVE alphabet (path.sep), while every default in
+ * this file is stored slash-normalized, so its Windows branch would be untestable anywhere but
+ * Windows. Comparing in the alphabet the values are written in makes this checkable on every platform.
+ *
+ * Four cases it has to get right, all measured on this project's own hosts:
+ *   - macOS TMPDIR carries a TRAILING SLASH, so the old default composed `<tmp>//pi-dispatch/logs`;
+ *   - macOS /var/folders/... realpaths to /private/var/folders/..., so an operator's /private path
+ *     is a FALSE NEGATIVE unless both sides are expanded;
+ *   - `<tmp>-notmine/logs` is a FALSE POSITIVE for a bare prefix test;
+ *   - realpathSync THROWS on a path that does not exist yet, which is doctor's ordinary situation.
+ *
+ * os.tmpdir() is checked beside TMPDIR/TEMP because it consults TMP internally, which covers a third
+ * variable without naming one here. The literal "/tmp" is checked because it is what the pre-#290
+ * default resolved to on Linux, where TMPDIR is unset.
+ */
+export function underOsTempDir(candidate, env = process.env, { realpath = realpathSync, osTmpDir = tmpdir, platform = process.platform } = {}) {
+	if (typeof candidate !== "string" || candidate.trim() === "") return false;
+	let tmp = "";
+	try {
+		tmp = osTmpDir();
+	} catch {
+		// A host that cannot name its own temp dir is not one to throw over from an advisory check.
+	}
+	const target = landingSpelling(candidate, realpath);
+	// TEMP is consulted on WINDOWS ONLY. On POSIX it is not an OS temp variable, and plenty of shells
+	// export one for a ported toolchain -- honouring it there turns an ordinary durable subtree into a
+	// false "swept" verdict, which is the direction this check says it cares about most.
+	const win = platform === "win32";
+	for (const root of [env.TMPDIR, win ? env.TEMP : "", tmp, ...(win ? [] : POSIX_VOLATILE_ROOTS)]) {
+		if (typeof root !== "string" || root.trim() === "") continue;
+		for (const base of spellings(root, realpath)) {
+			// `base` is "/" only when the root IS the filesystem root, where `${base}/` would be "//" and
+			// match nothing. Everything absolute is under it, which is the honest answer for TMPDIR=/.
+			if (target === base || target.startsWith(base === "/" ? "/" : `${base}/`)) return true;
+		}
+	}
+	return false;
 }
 
 /**
@@ -596,23 +1061,18 @@ function workerName(env) {
 	return declared;
 }
 
-export function defaultGraphDir(env = process.env) {
+export function defaultGraphDir(env = process.env, uid = currentUid()) {
 	// Under the OS temp dir by default, beside logs/ and jobs/ -- the admin's graph HTML artifact
 	// (issue #54) is host-side display output on the defaultLogsDir doctrine, and deliberately NOT
 	// inside logsDir: INT-RUN-HISTORY-FILE-CONTRACT names that directory's filename shape, and a
 	// stray .html beside the sidecars would widen a contract for a file that is not a record.
 	// Overridable with PI_GRAPH_DIR; exported so the admin resolves the same default without
 	// loadConfig, like defaultSandboxDir above.
-	return `${env.TMPDIR ?? env.TEMP ?? "/tmp"}/pi-dispatch/graph`.replace(/\\/g, "/");
+	// Issue #464: under the per-account root, for the jobs dir's reason: another account's `<tmp>/pi-dispatch` made
+	// this one uncreatable.
+	return `${accountTempRoot(env, uid)}/graph`;
 }
 
-export function defaultSettingsFile() {
-	// Under the OS temp dir by default. Holds the runtime-tunable settings overlay shared with the admin
-	// extension (INT-CONFIG-OVERLAY-CONTRACT); a worker-owned path that never enters the container env
-	// allowlist (no-broad-env-into-container). Exported so the admin extension resolves the same default
-	// without calling loadConfig, which throws on unrelated env problems.
-	return `${process.env.TMPDIR ?? process.env.TEMP ?? "/tmp"}/pi-dispatch/settings.json`.replace(/\\/g, "/");
-}
 
 /**
  * The worker's Azure DevOps auth config, or `null` when none is configured -- same presence rule as the