@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/src/runtime-observations.mjs

@@ -15,6 +15,7 @@
 
 import { realpathSync } from "node:fs";
 import { execDockerBounded } from "./backend-local.mjs";
+import { PODMAN_RESTART_HOLD_EXPIRED } from "./comment-tables.mjs";
 import { DAEMON_APPLIES_BOUNDS, DOCKER_ENDPOINT_LOCAL, PODMAN_CONF_WIDENS_JOB, PODMAN_ROOTFUL_WIDENING_KEYS, RUNTIME_ADDS_NO_MOUNTS } from "./backends.mjs";
 
 /**
@@ -1123,7 +1124,8 @@ export function rootfulConfResidual(unread) {
  */
 export const PODMAN_RESTART_HOLD_RECHECK_MS = 60_000;
 export const PODMAN_RESTART_HOLD_MAX_MS = 3_600_000;
-export const PODMAN_RESTART_HOLD_EXPIRED = "podman-service-restart-hold-expired";
+// The expiry's reason token lives in comment-tables.mjs beside its comment (issue #710); re-exported under its old name.
+export { PODMAN_RESTART_HOLD_EXPIRED };
 
 /** Whether a rootful finding holds jobs back only until something heals by itself (a retry), not a configuration fix. */
 export function rootfulConfRetries(found) {

package/src/runtime-settings.mjs

@@ -1,20 +1,32 @@
 import * as nodeFs from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname } from "node:path";
 import { ensureUnderAccountRoot } from "./config.mjs";
+import { expectRefusal } from "./file-expect.mjs";
 import { findDuplicateKey } from "./json-duplicates.mjs";
+import { modelIdProblem, providerIdProblem } from "./model-ref.mjs";
 import { checkDollarInvariant, parseUsdMicros } from "./money.mjs";
+import { BUNDLE_FORMATS } from "./secret-profiles.mjs";
+import { neededVersion, underDeclared, valueNeededVersion, valueUnderDeclared, versionProblem } from "./store-version.mjs";
 
 /**
  * Runtime-settings overlay: the shared, durable truth between the admin extension and the worker
- * (INT-CONFIG-OVERLAY-CONTRACT, DES-RUNTIME-SETTINGS-FILE-OVERLAY). A flat `settings.json` with fourteen
- * optional keys -- `model`, `provider` (non-empty strings), `maxTurns`, `dailyCap`, `weeklyCap`,
- * `monthlyCap`, `maxTokens`, `dailyTokenCap` (int >= 1), `concurrency` (int 1-10), `softHoldPct`
+ * (INT-CONFIG-OVERLAY-CONTRACT, DES-RUNTIME-SETTINGS-FILE-OVERLAY). A flat `settings.json` of optional keys:
+ * the fourteen settings in `KNOWN_KEYS` -- `model`, `provider` (non-empty strings), `maxTurns`, `dailyCap`,
+ * `weeklyCap`, `monthlyCap`, `maxTokens`, `dailyTokenCap` (int >= 1), `concurrency` (int 1-10), `softHoldPct`
  * (int 1-99), and the dollar keys `maxCostUsd`, `dailyCostUsd`, `weeklyCostUsd`, `monthlyCostUsd`
- * (a decimal string or number, `parseUsdMicros`) -- read by the worker at each job start and written
+ * (a decimal string or number, `parseUsdMicros`) -- the two operator-only resolver tables in
+ * `OPERATOR_ONLY_KEYS` (`secretProfiles`, `secretBundles`), and an optional `version` that describes the file
+ * rather than setting anything (issue #761, `SETTINGS_VERSION`). Read by the worker at each job start and written
  * atomically by the admin extension (tmp + rename). `maxTokens`/`dailyTokenCap` are the optional token
  * controls (issue #25); the dollar keys are issue #501's (a window needs `maxCostUsd`, checked on the merged
  * values by `resolveSettings`).
  *
+ * A key this build does not know is dropped from the overlay it hands out and logged, and a writer given the
+ * `carry` its read returned writes that key back exactly as it found it, in its place (issue #761): the file is shared
+ * by every console, panel and worker of a deployment, and a writer from an older release must not delete a key a newer
+ * one added just because it cannot read it.
+ *
  * `readOverlay` NEVER throws: a bad settings file returns a discriminated `{ invalid }` rather than an
  * exception, so the processor RETURNS a policy refusal (`settings-overlay-invalid`) instead of letting
  * its catch classify the file as retryable infra and pay to retry a job that can never succeed
@@ -45,8 +57,43 @@ export const KNOWN_KEYS = ["model", "provider", "maxTurns", "dailyCap", "weeklyC
  *
  * A profile is declared through the operator-typed `/dispatch` command instead, which pi reaches only from
  * its own user-input path, and every declared path is bounded by PI_SECRET_RESOLVER_ROOTS in the worker.
+ *
+ * `secretBundles` (issue #704) is the same capability for a bundle resolver, `{ [name]: { path, format } }`, and is
+ * operator-only for the same reason: its path is an exec, bounded by the same roots.
+ */
+export const OPERATOR_ONLY_KEYS = ["secretProfiles", "secretBundles"];
+
+/**
+ * The highest overlay version this build reads (issue #761, `DES-STORE-VERSION-WHEN-NEEDED`). A file without
+ * `version` is version 1, and a writer writes `version` only when the content needs more than 1, so every overlay of
+ * today's keys stays byte-identical.
+ *
+ * `version` is deliberately NOT in `KNOWN_KEYS`: it describes the file, never a setting, so no tool, command or dialog
+ * can set it, and it never reaches the overlay a reader hands out. The writer computes it from what it writes.
+ */
+export const SETTINGS_VERSION = 1;
+
+/**
+ * Each overlay key whose ABSENCE an older build would misread (one that narrows: a cap, a refusal, a list a job is
+ * held to), with the version that introduced it. A key that is harmless when absent declares nothing and is simply
+ * carried by older writers. Empty until a key needs one; raising `SETTINGS_VERSION` and adding the row is one commit.
  */
-export const OPERATOR_ONLY_KEYS = ["secretProfiles"];
+export const SETTINGS_KEY_VERSIONS = Object.freeze({});
+
+/**
+ * Each EXISTING key whose range a later release widens, as `key -> (value) => version`: the version a value needs.
+ * A key-name table cannot say this, and an older build meeting the wider value refuses the whole overlay (every job
+ * refused `settings-overlay-invalid`) with no stamp to say an upgrade is the fix. So a rule here makes the writer stamp
+ * the version for exactly the values that need it. The same holds for a new field inside a closed nested shape
+ * (a `secretBundles` entry refuses an unknown field). Empty until a value needs one.
+ */
+export const SETTINGS_VALUE_VERSIONS = Object.freeze({});
+
+/** The lowest version a VALIDATED overlay needs, from its keys and the value rules: 1 while nothing needs more. */
+export function settingsVersionFor(overlay, { table = SETTINGS_KEY_VERSIONS, valueTable = SETTINGS_VALUE_VERSIONS } = {}) {
+	if (overlay === null || typeof overlay !== "object") return 1;
+	return Math.max(neededVersion(Object.keys(overlay), table), valueNeededVersion(overlay, valueTable));
+}
 
 // The dollar keys' near-miss spellings (issue #501), already normalised (`overlayKeyShape`), each mapped to the key it
 // meant: the four keys, their env names (`PI_MAX_COST_USD` pasted into settings.json is the likeliest slip of all),
@@ -81,10 +128,6 @@ function overlayKeyShape(key) {
 	return out.replace(/[_\-. ]/g, "");
 }
 
-function isNonEmptyString(value) {
-	return typeof value === "string" && value.trim() !== "";
-}
-
 function isIntAtLeast(value, min) {
 	return Number.isInteger(value) && value >= min;
 }
@@ -105,24 +148,63 @@ function isIntInRange(value, min, max) {
 export { settingsFilePath } from "./config.mjs";
 
 /**
- * Validate a parsed overlay against the key contract, returning the sanitized overlay (known keys only)
- * or `{ invalid }`. Shared by `readOverlay` (post-parse) and `writeOverlay` (pre-write) so a single
- * definition governs both directions. Unknown keys are dropped and logged, leaving the overlay valid;
- * any invalid known key fails the WHOLE object.
+ * Validate a parsed overlay FILE against the key contract: `{ overlay, unknownKeys }` (the sanitized overlay of known
+ * keys only, and the names this build does not know, in file order), `{ invalid }`, or `{ invalid, newer: true }` for
+ * a file written by a newer pi-dispatch. Shared by `readOverlayDocument` (post-parse) and `writeOverlay`'s re-read of
+ * its own output, so a single definition governs both directions. Unknown keys are dropped from `overlay` and logged,
+ * leaving it valid; any invalid known key fails the WHOLE object.
+ *
+ * The VERSION IS JUDGED FIRST, before any key (issue #761). A newer file may hold a value this build's rules refuse (a
+ * range a later release widened), and judged key by key it would read as broken when the truth is "upgrade". A broken
+ * `version` (not an integer of 1 or more) is an ordinary `{ invalid }`. Then, after the keys, a known key or value
+ * that needs a higher version than the file declares is refused by name: such a file was written by hand or by a
+ * writer that dropped the stamp, and an older build would read it without the key.
  */
-function validateOverlay(candidate, log) {
+export function validateOverlay(parsed, log = () => {}, { supported = SETTINGS_VERSION, table = SETTINGS_KEY_VERSIONS, valueTable = SETTINGS_VALUE_VERSIONS } = {}) {
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return { invalid: "root must be a JSON object" };
+	}
+	const declared = Object.hasOwn(parsed, "version") ? parsed.version : undefined;
+	const problem = versionProblem(declared, { supported, what: "settings file" });
+	if (problem) return problem.newer ? { invalid: problem.message, newer: true } : { invalid: problem.message };
+	const result = validateKeys(parsed, log);
+	if (result.invalid) return result;
+	const short = underDeclared(Object.keys(result.overlay), table, declared);
+	if (short) return { invalid: `${short.field} needs settings version ${short.needs}, and the file declares ${declared ?? 1}` };
+	const shortValue = valueUnderDeclared(result.overlay, valueTable, declared);
+	if (shortValue) return { invalid: `${shortValue.field} holds a value that needs settings version ${shortValue.needs}, and the file declares ${declared ?? 1}` };
+	return result;
+}
+
+/**
+ * The per-key half of `validateOverlay`, and all of what `writeOverlay` asks of a CANDIDATE: `{ overlay, unknownKeys }`
+ * or `{ invalid }`. `version` is skipped here, never copied: the file's is judged by `validateOverlay`, and a
+ * candidate's is ignored because the writer computes the version from what it writes.
+ */
+function validateKeys(candidate, log) {
 	if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
 		return { invalid: "root must be a JSON object" };
 	}
 	const overlay = {};
+	const unknownKeys = [];
 	for (const key of Object.keys(candidate)) {
 		const value = candidate[key];
 		switch (key) {
+			case "version":
+				break;
 			case "model":
-			case "provider":
-				if (!isNonEmptyString(value)) return { invalid: `${key} must be a non-empty string` };
+			case "provider": {
+				// Issue #673: the one model-id and provider-id shape a trigger's run.model and run.provider, PI_MODEL and
+				// PI_PROVIDER are held to (model-ref.mjs), so a run on the overlay's model is one the console's runs
+				// filter can find. Here, not at one admin surface, because every write (dispatch_set, /dispatch set,
+				// the panel dialog, the console's setting-set) and every read goes through this function: a bad value
+				// is refused at write, and one already on disk makes the overlay invalid, the loud path jobs and doctor
+				// already take. The value is never echoed. Kept in its original case: only the check lowercases.
+				const problem = key === "model" ? modelIdProblem(value) : providerIdProblem(value);
+				if (problem !== null) return { invalid: `${key} ${problem}` };
 				overlay[key] = value;
 				break;
+			}
 			case "maxTurns":
 			case "dailyCap":
 			case "weeklyCap":
@@ -165,6 +247,37 @@ function validateOverlay(candidate, log) {
 				overlay[key] = { ...value };
 				break;
 			}
+			case "secretBundles": {
+				// Issue #704. `{ [name]: { path: "/abs/path", format: "dotenv" | "json" } }`, the panel-authored half of
+				// PI_SECRET_BUNDLES. `secretProfiles`' rules (shape here, the path bound in the worker, an invalid value
+				// fails the whole overlay), plus two of its own: the format is REQUIRED and never guessed (secret-profiles.mjs
+				// `parseSecretBundleProfiles` says why), and an unknown field refuses rather than drops, because a misspelt
+				// `fromat` would otherwise read as declared while the entry has no format at all.
+				if (value === null || typeof value !== "object" || Array.isArray(value)) {
+					return { invalid: "secretBundles must be an object mapping bundle profile names to { path, format }" };
+				}
+				const bundles = {};
+				for (const name of Object.keys(value)) {
+					if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+						return { invalid: "secretBundles names may use letters, digits, dot, dash and underscore only" };
+					}
+					const entry = value[name];
+					if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+						return { invalid: `secretBundles.${name} must be an object { path, format }` };
+					}
+					const extra = Object.keys(entry).find((k) => k !== "path" && k !== "format");
+					if (extra !== undefined) return { invalid: `secretBundles.${name} has an unknown field (only path and format are read)` };
+					if (typeof entry.path !== "string" || entry.path.trim() === "") {
+						return { invalid: `secretBundles.${name}.path must be a non-empty absolute path` };
+					}
+					if (!BUNDLE_FORMATS.includes(entry.format)) {
+						return { invalid: `secretBundles.${name}.format must be ${BUNDLE_FORMATS.join(" or ")}` };
+					}
+					Object.defineProperty(bundles, name, { value: { path: entry.path, format: entry.format }, enumerable: true, writable: true, configurable: true });
+				}
+				overlay[key] = bundles;
+				break;
+			}
 			case "maxCostUsd":
 			case "dailyCostUsd":
 			case "weeklyCostUsd":
@@ -196,29 +309,49 @@ function validateOverlay(candidate, log) {
 				const meant = Object.hasOwn(DOLLAR_NEAR_MISSES, overlayKeyShape(key)) ? DOLLAR_NEAR_MISSES[overlayKeyShape(key)] : undefined;
 				if (meant !== undefined) return { invalid: `${key} is not a settings key -- did you mean ${meant}? A dollar cap the worker drops would not apply while the file reads as set` };
 				log("settings_overlay_unknown_key", { key });
+				// Issue #761: the ONE place that decides a key is unknown, so the list a writer carries cannot drift from
+				// this switch. A near miss never gets here (refused above), so it is never carried either.
+				unknownKeys.push(key);
 			}
 		}
 	}
-	return { overlay };
+	return { overlay, unknownKeys };
 }
 
 /**
- * Read the overlay at `path`. Returns `{ overlay }` (known keys only) on success, or `{ invalid }` with
- * a key-only reason on failure. NEVER throws.
+ * Read the overlay at `path` for a writer (issue #761): `{ overlay, carry: { doc, unknownKeys }, text }` on success,
+ * `{ invalid }` with a key-only reason, or `{ invalid, newer: true }` for a file written by a newer pi-dispatch.
+ * NEVER throws. `carry` is what `writeOverlay` needs to write back every key this build does not know (the parsed
+ * document and the unknown names), and `text` is the file as read, for a writer's `expect` snapshot.
+ *
+ * A missing file (ENOENT) is the normal empty overlay, `{ overlay: {}, carry: null, text: null }` (`null` is
+ * `fileSnapshot`'s encoding of a missing file). Any OTHER read error (EACCES, EISDIR, ...) is `{ invalid }`: a
+ * present-but-unreadable file must fail closed, not silently become an empty overlay that restores env's higher
+ * `dailyCap`. Unparseable JSON, a duplicate key, a non-object root, a broken `version` or an invalid known key is
+ * `{ invalid }`.
  *
- * A missing file (ENOENT) is the normal empty overlay `{ overlay: {} }`. Any OTHER read error
- * (EACCES, EISDIR, ...) is `{ invalid }`: a present-but-unreadable file must fail closed, not silently
- * become an empty overlay that restores env's higher `dailyCap`. Unparseable JSON, a non-object root,
- * or an invalid known key is `{ invalid }`.
+ * `supported`, `table` and `valueTable` default to this build's and are injectable so a test can run the version
+ * machinery while the shipped tables are empty.
  */
-export function readOverlay(path, { fs = nodeFs, log = () => {} } = {}) {
+export function readOverlayDocument(path, { fs = nodeFs, log = () => {}, supported = SETTINGS_VERSION, table = SETTINGS_KEY_VERSIONS, valueTable = SETTINGS_VALUE_VERSIONS } = {}) {
 	let text;
 	try {
 		text = fs.readFileSync(path, "utf8");
 	} catch (err) {
-		if (err?.code === "ENOENT") return { overlay: {} }; // missing file is a normal empty overlay
+		if (err?.code === "ENOENT") return { overlay: {}, carry: null, text: null }; // missing file is a normal empty overlay
 		return { invalid: `settings file unreadable (${err?.code ?? "read-error"})` };
 	}
+	const read = judgeOverlayText(text, log, { supported, table, valueTable });
+	if (read.invalid) return read;
+	return { overlay: read.overlay, carry: { doc: read.doc, unknownKeys: read.unknownKeys }, text };
+}
+
+/**
+ * The settings file's TEXT judged as a reader judges it: `{ overlay, unknownKeys, doc }`, `{ invalid }` or
+ * `{ invalid, newer: true }`. Shared by the read and by `writeOverlay`'s re-read of its own output, so the writer can
+ * never produce a file the reader refuses.
+ */
+function judgeOverlayText(text, log, versions) {
 	let parsed;
 	try {
 		parsed = JSON.parse(text);
@@ -230,7 +363,24 @@ export function readOverlay(path, { fs = nodeFs, log = () => {} } = {}) {
 	// is named, never a value. `writeOverlay` serialises an object, so a file it wrote never has one.
 	const duplicate = findDuplicateKey(text);
 	if (duplicate) return { invalid: `settings file has a duplicate key ${JSON.stringify(duplicate.key)}: JSON keeps the last value, so the file that reads and the file that runs differ` };
-	return validateOverlay(parsed, log);
+	const result = validateOverlay(parsed, log, versions);
+	if (result.invalid) return result;
+	return { ...result, doc: parsed };
+}
+
+/**
+ * Read the overlay at `path`. Returns `{ overlay }` (known keys only) on success, or `{ invalid }` with
+ * a key-only reason on failure, plus `newer: true` when the file was written by a newer pi-dispatch (issue #761: the
+ * worker defers rather than refuses then). NEVER throws. `readOverlayDocument`'s rules, without the carry.
+ *
+ * A key this build does not know NEVER appears in `overlay`, and that is load-bearing beyond tidiness: the admin's
+ * `withoutOperatorOnly` keeps operator-only values out of model-visible views with a BLOCK list, so a future
+ * operator-only key, unknown to this build, is kept out only because it never enters the overlay.
+ */
+export function readOverlay(path, { fs = nodeFs, log = () => {} } = {}) {
+	const read = readOverlayDocument(path, { fs, log });
+	if (read.invalid) return read.newer === true ? { invalid: read.invalid, newer: true } : { invalid: read.invalid };
+	return { overlay: read.overlay };
 }
 
 /**
@@ -274,28 +424,97 @@ export function effectiveSettings(config, overlay) {
  * `secretProfiles` (REQ-TRIGGER-SECRETS) rides ALONGSIDE the effective keys rather than inside them:
  * `effectiveSettings` resolves `overlay > env` over a fixed literal whose tests pin its key set, and this key
  * deliberately has no such precedence (a name declared in both sources is refused per delivery, not silently
- * won by either).
+ * won by either). `secretBundles` (issue #704) rides beside it for the same reason, under the same rule.
+ *
+ * A file written by a newer pi-dispatch keeps its `newer: true` (issue #761), so the processor can defer the job for an
+ * upgrade instead of refusing it; every other invalid read is exactly `{ invalid }`, as it always was.
  */
 export function resolveSettings(config, read) {
-	if (read.invalid) return { invalid: read.invalid };
+	if (read.invalid) return read.newer === true ? { invalid: read.invalid, newer: true } : { invalid: read.invalid };
 	const settings = effectiveSettings(config, read.overlay);
 	const broken = checkDollarInvariant(settings);
 	if (broken) return broken;
-	return { ...settings, secretProfiles: read.overlay?.secretProfiles ?? {} };
+	return { ...settings, secretProfiles: read.overlay?.secretProfiles ?? {}, secretBundles: read.overlay?.secretBundles ?? {} };
+}
+
+/**
+ * The file text for a validated overlay (issue #761): 2-space JSON and a trailing newline.
+ *
+ * Without `carry` it is exactly `JSON.stringify(validated, null, 2)` plus the newline, the bytes this writer always
+ * wrote. With it, the text follows the FILE's key order: walking `carry.doc`, a key this build does not know is written
+ * with its value as read, a known key is written from `validated` only if it is still there (so an unset removes it),
+ * and `version` is skipped; then the keys `validated` sets that the file did not have are appended in the candidate's
+ * order. So a changed key keeps its line, a file of known keys is rewritten byte for byte, and a key from a later
+ * release survives a write by an older console. `version` leads, and only when the content needs more than 1: the
+ * writer owns it, so a hand-written `"version": 1` is dropped and a stamp whose key was unset goes with it.
+ *
+ * Built with `Object.defineProperty`, `secretBundles`' precedent above: an assignment to a carried key named
+ * `__proto__` would set the result's PROTOTYPE and drop the key from the text, while a defined property stays data.
+ * Known residual: JavaScript lists integer-like keys (`"1"`) first in any object, so such a carried key moves to the top.
+ */
+function overlayText(validated, carry, versions) {
+	const out = {};
+	const put = (key, value) => Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+	const version = settingsVersionFor(validated, versions);
+	if (version > 1) put("version", version);
+	const doc = carry?.doc;
+	if (doc !== null && typeof doc === "object" && !Array.isArray(doc)) {
+		const unknown = new Set(Array.isArray(carry.unknownKeys) ? carry.unknownKeys : []);
+		for (const key of Object.keys(doc)) {
+			if (key === "version") continue;
+			if (unknown.has(key)) put(key, doc[key]);
+			else if (Object.hasOwn(validated, key)) put(key, validated[key]);
+		}
+	}
+	for (const key of Object.keys(validated)) {
+		if (!Object.hasOwn(out, key)) put(key, validated[key]);
+	}
+	return `${JSON.stringify(out, null, 2)}\n`;
 }
 
 /**
  * Write `candidate` to `path` atomically. Validates with the same rules as `readOverlay` (an invalid
  * candidate returns `{ invalid }` and touches no file; an empty `{}` candidate is valid), serialises
- * the validated overlay with 2-space indent and a trailing newline, writes a same-directory
- * `<path>.tmp`, then renames it over `path`. NEVER throws.
+ * the validated overlay with 2-space indent and a trailing newline, writes a same-directory tmp file of
+ * its own, then renames it over `path`. NEVER throws.
+ *
+ * The tmp name is `<path>.<pid>.<random>.tmp`, created exclusively (`wx`), as `writePauseWindows` and the admin's
+ * `replaceFile` do (issue #642). It was a fixed `<path>.tmp`, harmless while one process wrote the overlay; the
+ * console and the pi extension are two, and a shared name lets one rename the other's bytes past its own re-check.
+ * A write that fails after the tmp exists removes it, so a unique name never becomes litter. A file already at the tmp
+ * name (another writer's, or one planted there) refuses the write rather than being overwritten, and is left alone:
+ * the exclusive create is what makes the name this writer's. `random` is injectable so a test can aim at that name.
+ *
+ * `expect` (issue #642): the `{ path, text }` snapshots the change was built from (the admin's `writeInputs`, taken
+ * before an operator's confirm). Right before the rename each file is re-read, and a difference refuses with nothing
+ * written (`file-expect.mjs`). Without it the write is what it always was.
  *
  * The rename is retried once on EPERM to ride out a Windows AV/indexer briefly locking the destination;
  * a second failure surfaces as `{ invalid }`, never a throw. Returns `{ ok: true }` on success.
+ *
+ * `carry` (issue #761): `readOverlayDocument`'s `carry` for the file the candidate was built from. With it, the text
+ * keeps the FILE's key order and every key this build does not know, exactly as read (`overlayText`); without it, the
+ * output is what it always was. Only what came from the file is carried: an unknown key on the candidate itself
+ * (anything a `mutate` added) is still dropped and logged, so no caller can write an arbitrary key through here. The
+ * output is then judged by the reader's own rules before the tmp file exists, so a write never leaves a file the
+ * worker would refuse. `table`, `valueTable` and `supported` are the version rules, injectable for tests.
  */
-export function writeOverlay(path, candidate, { fs = nodeFs, log = () => {} } = {}) {
-	const result = validateOverlay(candidate, log);
+export function writeOverlay(path, candidate, { fs = nodeFs, log = () => {}, expect = null, carry = null, random = randomBytes, supported = SETTINGS_VERSION, table = SETTINGS_KEY_VERSIONS, valueTable = SETTINGS_VALUE_VERSIONS } = {}) {
+	const result = validateKeys(candidate, log);
 	if (result.invalid) return { invalid: result.invalid };
+	// A carry is only ever a READABLE file's (`readOverlayDocument` refuses the rest), and this keeps it so for any
+	// caller: the text below drops the file's `version` and writes its own, so a newer file's carry would otherwise come
+	// out stamped as a version this build vouches for, under keys it cannot read.
+	const carried = carry?.doc;
+	if (carried !== null && typeof carried === "object" && Object.hasOwn(carried, "version")) {
+		const problem = versionProblem(carried.version, { supported, what: "settings file" });
+		if (problem) return problem.newer ? { invalid: problem.message, newer: true } : { invalid: problem.message };
+	}
+	const data = overlayText(result.overlay, carry, { table, valueTable });
+	// The reader's own judgement of the bytes about to be written (parse, duplicate keys, version, every key), silently:
+	// the candidate's unknown keys were logged above, and the carried ones were logged when the file was read.
+	const reread = judgeOverlayText(data, () => {}, { supported, table, valueTable });
+	if (reread.invalid) return { invalid: reread.invalid };
 
 	try {
 		// Issue #464: on an account with no home the overlay's default lives in the per-account temp root, which is made
@@ -306,21 +525,37 @@ export function writeOverlay(path, candidate, { fs = nodeFs, log = () => {} } =
 		return { invalid: err?.piDispatchConfig ? `settings dir refused: ${err.message}` : `settings dir unwritable (${err?.code ?? "mkdir-error"})` };
 	}
 
-	const tmp = `${path}.tmp`;
-	const data = `${JSON.stringify(result.overlay, null, 2)}\n`;
+	const tmp = `${path}.${process.pid}.${random(6).toString("hex")}.tmp`;
+	const drop = () => {
+		try {
+			fs.unlinkSync?.(tmp);
+		} catch {
+			// nothing to drop
+		}
+	};
 	try {
-		fs.writeFileSync(tmp, data);
+		fs.writeFileSync(tmp, data, { flag: "wx" });
 	} catch (err) {
 		return { invalid: `settings write failed (${err?.code ?? "write-error"})` };
 	}
 
+	const changed = expectRefusal(fs, expect);
+	if (changed) {
+		drop();
+		return { invalid: changed };
+	}
+
 	try {
 		fs.renameSync(tmp, path);
 	} catch (err) {
-		if (err?.code !== "EPERM") return { invalid: `settings rename failed (${err?.code ?? "rename-error"})` };
+		if (err?.code !== "EPERM") {
+			drop();
+			return { invalid: `settings rename failed (${err?.code ?? "rename-error"})` };
+		}
 		try {
 			fs.renameSync(tmp, path); // single retry: Windows AV/indexer lock is transient
 		} catch (retryErr) {
+			drop();
 			return { invalid: `settings rename failed (${retryErr?.code ?? "rename-error"})` };
 		}
 	}

package/src/sandbox-cli.mjs

@@ -2,8 +2,11 @@ import { spawn } from "node:child_process";
 import { parseArgs } from "node:util";
 import { loadConfig } from "./config.mjs";
 import { basename } from "node:path";
-import { SANDBOX_OPEN_GRACE_MS, launchSandbox, listRunningSandboxes, openSandbox, parsePublish, sandboxContainerName, sandboxLauncher, sandboxVenueOf, sandboxVenueRefusal, sandboxVenues } from "./sandbox.mjs";
+import { fileURLToPath } from "node:url";
+import { SANDBOX_OPEN_GRACE_MS, decideSandboxJobUser, launchSandbox, listRunningSandboxes, openSandbox, parsePublish, resolveSandbox, sandboxContainerName, sandboxLauncher, sandboxVenueOf, sandboxVenueRefusal, sandboxVenues } from "./sandbox.mjs";
 import { listSandboxes, pinSandbox, sandboxDeadline } from "./sandbox-store.mjs";
+import { ensureSandboxMonitor, inspectSandboxSession, makeSandboxMonitor } from "./sandbox-session-watch.mjs";
+import { SANDBOX_SESSION_ID_RE } from "./sandbox-sessions.mjs";
 
 /**
  * `pi-dispatch sandbox` -- re-open a finished run's sandbox as an interactive shell
@@ -43,13 +46,50 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 				list: { type: "boolean", default: false },
 				publish: { type: "string", multiple: true }, // repeatable; always bound to 127.0.0.1
 				pin: { type: "boolean", default: false },
+				attach: { type: "boolean", default: false },
+				new: { type: "string" },
+				ref: { type: "string" },
+				as: { type: "string" },
+				deployment: { type: "string" },
+				"expected-host": { type: "string" },
+				"opened-by": { type: "string" },
 			},
 		}));
 	} catch (error) {
 		return fail(err, error.message);
 	}
 
-	const config = loadConfig(env);
+	if (values.deployment) {
+		const { sandboxDeploymentEnv } = await import("./sandbox-deployment.mjs");
+		const loaded = await (deps.deploymentEnv ?? sandboxDeploymentEnv)({ dir: values.deployment, env, expectedHost: values["expected-host"] });
+		if (loaded.refused) return fail(err, loaded.message);
+		// Readers and runtime helpers use their process's environment. Re-exec in the clean environment so none
+		// can accidentally consult the SSH shell's DOCKER_HOST, egress or rootless store (#771).
+		const next = [];
+		for (let i = 0; i < argv.length; i++) {
+			if (argv[i] === "--deployment" || argv[i] === "--expected-host") { i++; continue; }
+			if (argv[i].startsWith("--deployment=") || argv[i].startsWith("--expected-host=")) continue;
+			next.push(argv[i]);
+		}
+		return (deps.runDeployment ?? runDeploymentSandbox)(next, loaded.env, values.deployment);
+	}
+	if (values["expected-host"]) return fail(err, "--expected-host requires --deployment");
+	let config;
+	try { config = loadConfig(env); } catch (error) { return fail(err, error.message); }
+	if (values.new !== undefined) {
+		if (positionals.length || values.list || values.attach || values.publish?.length || values.ref === undefined || values.as === undefined || !/^(0|[1-9][0-9]*)$/.test(values.as)) return fail(err, "--new takes --ref <branch|pr:N|sha> and --as <trigger index>, with no run id, --list, --attach or --publish");
+		try {
+			const { createSandboxPreparer } = await import("./sandbox-prepare.mjs");
+			const prepare = deps.prepare ?? createSandboxPreparer({ config, env });
+			const result = await prepare({ repo: values.new, ref: values.ref, triggerIndex: Number(values.as), host: config.workerName, pin: values.pin });
+			if (result.refused) return fail(err, result.message);
+			out(`prepared ${result.id}, kept until ${new Date(result.until).toISOString()}; no container started\n`);
+			out(`open it with: pi-dispatch sandbox ${result.id}\n`);
+			return 0;
+		} catch { return fail(err, "sandbox preparation failed; check the repository, forge access and deployment settings, then try again"); }
+	}
+	if (values.ref !== undefined || values.as !== undefined) return fail(err, "--ref and --as require --new");
+	if (positionals.length > 1 || (values.list && (positionals.length || values.attach || values.pin || values.publish?.length))) return fail(err, "choose one sandbox id, or --list");
 	// A docker that cannot be reached costs a column, never the command: `listRunningSandboxes` throws so
 	// the REAPER can tell "none" from "could not ask", and these callers only draw a marker. Asked only
 	// where it is used, and never before the arguments are known good -- a typo should not shell out.
@@ -75,6 +115,7 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 
 	const jobId = positionals[0];
 	if (!jobId) return fail(err, "a job id is required — `pi-dispatch sandbox --list` shows what is still re-openable");
+	if (!SANDBOX_SESSION_ID_RE.test(jobId)) return fail(err, "the sandbox id must contain only letters, digits, dot, underscore, colon and hyphen (at most 200 characters)");
 
 	// Refused BEFORE anything else that could half-succeed. `-t` against a pipe fails inside docker with
 	// "the input device is not a TTY", which names neither the cause nor the fix; a sandbox is an operator
@@ -82,6 +123,24 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 	if (!isTty) {
 		return fail(err, "`pi-dispatch sandbox` needs a terminal — it opens an interactive shell, so it cannot run from a pipe, a script without a TTY, or CI");
 	}
+	const monitorSession = deps.monitorSession ?? makeSandboxMonitor({ env, config, by: values["opened-by"], now });
+	if (values.attach) {
+		if (values.publish?.length || values.pin) return fail(err, "--attach does not take --publish or --pin; pin the kept workspace separately");
+		const resolved = resolveSandbox({ jobId, sandboxDir: config.sandboxDir, retentionHours: config.sandboxRetentionHours, blessed: config.backends, pin: true, now });
+		if (resolved.refused) return fail(err, resolved.message);
+		const { bin } = sandboxLauncher(resolved.venue);
+		const state = await (deps.inspectSession ?? inspectSandboxSession)({ bin, name: resolved.name });
+		if (state.unknown) return fail(err, "the runtime could not report this sandbox; check its host and try again");
+		if (!state.present || !state.running) return fail(err, "this sandbox is no longer running; open its kept workspace again");
+		if (!/^[a-f0-9]{32}$/.test(state.nonce ?? "")) return fail(err, `this shell predates session tracking; return with \`${bin} attach ${resolved.name}\`, or exit it and open it again to register it`);
+		const user = await (resolveJobUser ?? decideSandboxJobUser)({ manifest: resolved.manifest, venue: resolved.venue, backendFloor: config.backendFloor });
+		if (user?.refused) return fail(err, user.message);
+		try { await (deps.ensureMonitor ?? ensureSandboxMonitor)({ resolved, runtime: bin, state, config, env, admittedRuntime: user?.runtime ?? null, by: values["opened-by"], now }); }
+		catch { return fail(err, "sandbox tracking could not be recovered; check Valkey before attaching"); }
+		out(`attaching to ${resolved.name} (${bin}); exit the shell to end it\n`);
+		const attached = await (deps.attach ?? attachSandbox)({ bin, containerId: state.containerId });
+		return attached.code ?? 1;
+	}
 
 	let publish;
 	try {
@@ -121,6 +180,7 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 		// Issue #429: which venues open here, and what a podman sandbox's observations must show, as the worker reads them.
 		blessed: config.backends,
 		backendFloor: config.backendFloor,
+		monitorSession,
 		now,
 		// Pin BEFORE the shell, not after: the operator asked to keep this one, and a session that ends in a crashed
 		// terminal or a closed laptop lid must not be the reason the pin never landed. And since issue #446 before
@@ -149,6 +209,22 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 	return result.code ?? 0;
 }
 
+function runDeploymentSandbox(argv, env, dir) {
+	return new Promise((resolve) => {
+		const child = spawn(process.execPath, [fileURLToPath(new URL("./cli.mjs", import.meta.url)), "sandbox", ...argv], { env, ...(dir ? { cwd: dir } : {}), stdio: "inherit" });
+		child.once("error", () => resolve(1));
+		child.once("exit", (code) => resolve(code ?? 1));
+	});
+}
+
+export function attachSandbox({ bin, containerId, spawnFn = spawn }) {
+	return new Promise((resolve) => {
+		const child = spawnFn(bin, ["attach", containerId], { stdio: "inherit" });
+		child.once("error", () => resolve({ code: 1 }));
+		child.once("exit", (code) => resolve({ code: code ?? 1 }));
+	});
+}
+
 /**
  * What is still re-openable, newest first, plus what is running right now.
  *

package/src/sandbox-deployment.mjs

@@ -0,0 +1,51 @@
+/** An explicit deployment handoff is stronger than a generic deployment pointer: it loads sandbox authority only. */
+import * as nodeFs from "node:fs";
+import { isAbsolute, join, win32 } from "node:path";
+import { homedir } from "node:os";
+import { deploymentServiceEnv } from "./service-env.mjs";
+import { workerName } from "./config.mjs";
+
+export const SANDBOX_DEPLOYMENT_KEYS = Object.freeze([
+	"PI_WORKER_NAME", "PI_SANDBOX_DIR", "PI_JOBS_DIR", "PI_SANDBOX_RETENTION_HOURS", "PI_SANDBOX_PIN_DAYS", "PI_SANDBOX_IDLE_MINUTES",
+	"PI_BACKENDS", "PI_BACKEND_FLOOR", "PI_EGRESS", "PI_EGRESS_PROXY", "DOCKER_HOST", "DOCKER_CONTEXT", "DOCKER_CONFIG", "DOCKER_TLS_VERIFY", "DOCKER_CERT_PATH",
+	"VALKEY_URL", "VALKEY_PASSWORD", "PI_VALKEY_SHARED", "PATH", "XDG_DATA_HOME", "XDG_RUNTIME_DIR", "XDG_CONFIG_HOME", "CONTAINERS_STORAGE_CONF", "CONTAINERS_CONF", "CONTAINERS_CONF_OVERRIDE", "CONTAINERS_REGISTRIES_CONF", "CONTAINER_HOST", "CONTAINER_CONNECTION",
+]);
+const OS_KEYS = Object.freeze(["HOME", "USERPROFILE", "SystemRoot", "WINDIR", "TEMP", "TMP", "TMPDIR", "TERM", "LANG", "LC_ALL", "PATH"]);
+export function sandboxDeploymentEnv({ dir, env = process.env, expectedHost = null, fs = nodeFs, platform = process.platform, uid = process.geteuid?.(), home = homedir(), read = deploymentServiceEnv } = {}) {
+	const refuse = (message) => ({ refused: "sandbox-deployment", message });
+	if (typeof dir !== "string" || !isAbsolute(dir) || /[\x00-\x1f\x7f]/.test(dir)) return refuse("--deployment must name an absolute deployment directory");
+	// One descriptor-backed read. Ambient values are compared afterwards, never used as defaults for authority.
+	const resolved = read({ dir, env: {}, keys: SANDBOX_DEPLOYMENT_KEYS, platform, fs, uid });
+	if (resolved.unreadable || resolved.untrusted || resolved.hazard) return refuse("the deployment .env cannot be trusted or read as its service reads it; run pi-dispatch doctor");
+	if (!resolved.path || (resolved.fromFile && Object.keys(resolved.fromFile).length === 0 && resolved.env && !fs.existsSync(resolved.path))) return refuse("the deployment .env is missing; point --deployment at the installed deployment");
+	if (resolved.unread?.length || resolved.hazardSkipped?.length) return refuse("a sandbox setting cannot be read the way the deployment service reads it; run pi-dispatch doctor");
+	const clean = { ...resolved.env };
+	for (const key of SANDBOX_DEPLOYMENT_KEYS) {
+		if (typeof env[key] !== "string") continue;
+		// SSH's PATH routinely lacks the service's Docker/Podman directory. A reviewed deployment PATH wins;
+		// when absent, PATH alone keeps the ordinary OS fallback (it grants no sandbox policy or runtime endpoint).
+		if (key === "PATH") continue;
+		if (typeof clean[key] === "string") {
+			if (clean[key] !== env[key]) return refuse(`the shell disagrees with the deployment for ${key}; unset that variable before opening`);
+			continue;
+		}
+		// PAM supplies the account's standard runtime directory on an SSH login, as a user service does. Admit it
+		// only after identity/ownership validation; a non-default rootless store remains deployment authority.
+		if (key === "XDG_RUNTIME_DIR" && platform === "linux" && Number.isInteger(uid) && env[key] === `/run/user/${uid}`) {
+			try { const stat = fs.lstatSync(env[key]); if (stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === uid && !(stat.mode & 0o077)) { clean[key] = env[key]; continue; } } catch {}
+		}
+		if (key === "XDG_DATA_HOME" && env[key] === join(home, ".local", "share")) { clean[key] = env[key]; continue; }
+		if (key === "XDG_CONFIG_HOME" && env[key] === join(home, ".config")) { clean[key] = env[key]; continue; }
+		return refuse(`the shell sets sandbox authority absent from the deployment: ${key}; unset that variable before opening`);
+	}
+	const result = {};
+	for (const key of OS_KEYS) if (typeof env[key] === "string") result[key] = env[key];
+	// env-internal HOME: compare the launching account's home to the OS identity before opening a rootless store.
+	if (platform !== "win32" && env.HOME && env.HOME !== home) return refuse("HOME is not this account's home; open the sandbox as the worker's account");
+	for (const key of SANDBOX_DEPLOYMENT_KEYS) if (typeof clean[key] === "string") result[key] = clean[key];
+	if (typeof result.PATH === "string" && (/[\x00-\x1f\x7f]/.test(result.PATH) || result.PATH.split(platform === "win32" ? ";" : ":").some((part) => !part || !(platform === "win32" ? win32.isAbsolute(part) : isAbsolute(part))))) return refuse("the sandbox runtime PATH must contain only absolute tool directories; correct PATH in the deployment .env");
+	try {
+		if (expectedHost !== null && workerName(result) !== expectedHost) return refuse("the deployment worker name does not match the opener host; check Fleet and the local opener configuration");
+	} catch { return refuse("the deployment worker name is invalid; run pi-dispatch doctor"); }
+	return { env: result };
+}