@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/triggers-file.mjs

@@ -35,18 +35,20 @@
  *     hook with nobody at the keyboard, and the thing it races (an operator edit, a sibling job's
  *     disarm) clears in milliseconds.
  *
- * `disarmTrigger` is also deliberately NARROWER than `writeTriggers`: it refuses an unreadable file
- * outright rather than repairing from empty. The repair posture is right for the operator CRUD path
- * (a missing file plus "add trigger" should scaffold) and catastrophic here -- overwriting a file the
- * worker could not read, to record one disarm, would destroy the operator's trigger set.
+ * `disarmTrigger` is also deliberately NARROWER than `writeTriggers`: it refuses a MISSING file too, where the operator
+ * CRUD path scaffolds one (a missing file plus "add trigger" is a first trigger), since a disarm has nothing to add to
+ * nothing. A file neither can READ or PARSE, both refuse: not being able to see or understand a file is no reason to
+ * think it empty, and overwriting it would destroy the operator's trigger set.
  *
  * Custom: exclusive-create lockfile per session-store.mjs precedent; no proper-lockfile dependency
  * (repo keeps runtime deps minimal, and the two-writer case needs no lease/renewal machinery)
  */
 
 import nodeFs from "node:fs";
-import { parseTriggers } from "./triggers.mjs";
+import { parseTriggers, parseTriggersDocument, triggersFileNewer, triggersFileVersionFor, triggersFileVersionProblem } from "./triggers.mjs";
+import { heldDocument } from "./held-document.mjs";
 import { findDuplicateKey } from "./json-duplicates.mjs";
+import { expectRefusal } from "./file-expect.mjs";
 
 /**
  * A lock older than this is a crashed writer's, not a live one's: every write under it is a read,
@@ -136,9 +138,42 @@ function releaseLock(fd, triggersPath, fs, log) {
 }
 
 /** The one serializer: 2-space plus trailing newline, byte-identical to what the admin always wrote --
- * both live-reload watchers and the operator's own diff read this file, so its shape is a contract. */
-function serialize(triggersArray) {
-	return `${JSON.stringify({ triggers: triggersArray }, null, 2)}\n`;
+ * both live-reload watchers and the operator's own diff read this file, so its shape is a contract.
+ *
+ * `doc` is the parsed document the write started from, and every top-level key it carries besides
+ * `triggers` is written back unchanged, in its original order (issue #704). The file is a shared
+ * document, not a triggers-only one: the project secret bundles live beside the array, and a writer
+ * that rebuilt the file as `{ triggers }` deleted them on every console edit and every one-shot disarm,
+ * silently. `triggers` keeps its position when the document had it, and leads when it did not (a file
+ * started from nothing, which is the historical file). A file whose only key is `triggers` comes
+ * out byte-identical to what this function always wrote.
+ *
+ * `version` (issue #761): when given, the writer OWNS the file's `version` and sets it to this value, in place when
+ * the document had one and first when it is added, and deletes it at 1 (version 1 is written as nothing). When not
+ * given (the disarm, whose whole write authority is one added key), `version` rides along like any other key. */
+function serialize(triggersArray, doc = null, { version = null } = {}) {
+	const rest = doc !== null && typeof doc === "object" && !Array.isArray(doc) ? doc : {};
+	let next = Object.hasOwn(rest, "triggers") ? { ...rest, triggers: triggersArray } : { triggers: triggersArray, ...rest };
+	if (version !== null) {
+		const { version: _owned, ...without } = next;
+		if (version <= 1) next = without;
+		else if (Object.hasOwn(next, "version")) next = { ...next, version };
+		else next = { version, ...without };
+	}
+	return `${JSON.stringify(next, null, 2)}\n`;
+}
+
+/**
+ * The exact text `writeTriggers` writes for the entries `next` over the document `nextDocument`: `serialize`, with the
+ * `version` the result needs under `versions` (the five tables of `triggersFileVersionFor`; `supported` is ignored).
+ * Exported for the console's pre-checks (issue #823), which preview a change and parse it before the operator confirms
+ * it: a document they serialized themselves carries no stamp, so under a version rule it reads as a version 1 file
+ * holding a version 2 value and is refused although this writer would write it correctly, and its preview keeps a
+ * hand-written `"version": 1` that this writer drops. One function for both, so the preview cannot drift from the write.
+ */
+export function triggersFileText(next, nextDocument, versions = {}) {
+	const rest = nextDocument !== null && typeof nextDocument === "object" && !Array.isArray(nextDocument) ? nextDocument : {};
+	return serialize(next, nextDocument, { version: triggersFileVersionFor({ ...rest, triggers: next }, versions) });
 }
 
 /** tmp + rename with writeOverlay's single EPERM retry (a Windows AV/indexer briefly holding the
@@ -189,11 +224,31 @@ function discardTmp(fs, tmp) {
  * human keypress is the approval and CONST-TRIGGER-AUTHOR-GATE's principle holds. The worker's disarm
  * does NOT come through here -- `disarmTrigger` below is its own, narrower entry.
  *
- * A missing or unparseable existing file starts from an empty set; the validated write repairs it.
- * Returns `{ ok: true }`, or `{ invalid }` for a validation failure OR a held lock; fs failures throw,
- * the contract this function has always had.
+ * Only a file that holds nothing starts from an empty set: a missing one, or one of nothing but whitespace or a
+ * byte-order mark. A file that is there and cannot be read (EIO, EACCES, EISDIR) refuses with
+ * `{ invalid, unreadable: true }`, and one that holds something this writer cannot keep (`heldDocument`) with
+ * `{ invalid, malformed: true }`, both before `mutate` runs and with the file untouched.
+ * Returns `{ ok: true }`, or `{ invalid }` for a validation failure, a held lock or that read. A failure of the lock,
+ * the tmp file or the rename throws, the contract this function has always had: all three happen beside the file, so
+ * the old file is whole after any of them.
+ *
+ * `expect` (issue #642): the `{ path, text }` snapshots the change was built from (the admin's `writeInputs`, taken
+ * before an operator's confirm, e.g. the console's preview). Re-read INSIDE the lock, right before the rename, so the
+ * re-check and the rename are one critical section against every other writer of this file (the disarm included): a
+ * difference refuses with nothing written. Without it the write is byte-identical to what it always was; the lock
+ * already serialises a single read-modify-write, and `expect` widens that to the whole preview-to-confirm dialog.
+ *
+ * A file written by a newer pi-dispatch (issue #761) is refused BEFORE `mutate` and `mutateDocument` run, with
+ * `{ invalid, newer: true }` and the file untouched: this build cannot know what the newer one's fields mean, and the
+ * writer's own stamp (the lowest version the content needs) would otherwise LOWER the version under content it does
+ * not understand, after which the final validation would pass. Judged on the RAW `version` only, never the full
+ * parser, so a file with one bad entry can still be fixed; a broken `version` is overwritten by the writer's own. Then
+ * the writer owns `version`: it writes `triggersFileVersionFor` of the result (`triggersFileText`). `supported`,
+ * `runTable`, `blockTable`, `entryValueTable`, `runValueTable` and `blockValueTable` are the version rules, injectable
+ * for tests.
  */
-export function writeTriggers({ triggersPath, mutate, fs = nodeFs, log = () => {}, now = () => Date.now() }) {
+export function writeTriggers({ triggersPath, mutate, mutateDocument = null, expect = null, fs = nodeFs, log = () => {}, now = () => Date.now(), supported = undefined, runTable = undefined, blockTable = undefined, entryValueTable = undefined, runValueTable = undefined, blockValueTable = undefined }) {
+	const versions = { supported, runTable, blockTable, entryValueTable, runValueTable, blockValueTable };
 	const fd = takeLock(triggersPath, fs, log, now);
 	if (fd === null) {
 		// Immediate, not retried: the callers sit on the pi TUI event loop, and the holder is a write
@@ -202,40 +257,63 @@ export function writeTriggers({ triggersPath, mutate, fs = nodeFs, log = () => {
 	}
 	try {
 		let current = [];
+		// The whole parsed document, so the write keeps every top-level key it does not own (issue #704).
+		let doc = null;
 		// The text ONLY IF THE PARSE ACCEPTED IT, which is the scanner's whole contract: it never has to
 		// decide whether malformed input is malformed, so it is not asked. Assigning it before the parse
 		// would hand it a truncated file and get back a confident answer about a key, when what happened is
 		// that the file was cut in half.
 		let parsedText = null;
+		// Only a file that holds nothing may start from nothing. A file that is there and could not be read is not an empty one: folded
+		// into "missing", one failed read made `current` empty, the `expect` re-read below then saw the file as it was and
+		// passed, and the rename replaced every trigger with what `mutate` made of nothing, on an `{ ok: true }`. Returned, not
+		// thrown, so every caller says it in the words it says any refusal in, and before `mutate`, which is owed a real list.
+		let raw = null;
 		try {
-			const raw = fs.readFileSync(triggersPath, "utf8");
-			const value = JSON.parse(raw);
+			raw = fs.readFileSync(triggersPath, "utf8");
+		} catch (err) {
+			if (err?.code !== "ENOENT") return { invalid: `the triggers file ${triggersPath} could not be read (${typeof err?.code === "string" ? err.code : "read-error"}), so its triggers cannot be kept; nothing was written`, unreadable: true };
+		}
+		if (raw !== null && raw.trim() !== "") {
+			// This used to start from empty for anything that did not parse, so one stray comma and the next add replaced every
+			// trigger with one, on an `{ ok: true }`, under a preview whose sentences never said so, only its diff. What the file holds is the
+			// operator's to fix; a refusal costs them the add and nothing else.
+			const { value, problem } = heldDocument(raw, "triggers");
+			// A newer release may mean something by that shape, and the answer to that is upgrading, below.
+			const newerFirst = value !== undefined && triggersFileVersionProblem(value, { supported: versions.supported })?.newer;
+			if (problem && !newerFirst) return { invalid: `the triggers file ${triggersPath} ${problem}, so its triggers cannot be kept; nothing was written. Fix the file, or move it aside to start from an empty one`, malformed: true };
 			parsedText = raw;
-			if (Array.isArray(value?.triggers)) current = value.triggers;
-		} catch {
-			// Missing/invalid file: start from empty; the validated atomic write below repairs it.
+			doc = value;
+			if (Array.isArray(value.triggers)) current = value.triggers;
 		}
-		// The repair posture above cannot extend to a duplicate key (issue #313), and the two are exactly
-		// separated by the parse. A file that does not parse is repairable and stays repairable. A file that
-		// PARSES is not missing, so "start from empty" would not repair it, it would delete the operator's
-		// trigger set; and rebuilding from `current` writes back the winning value with the shadowed one
-		// silently gone, which turns a divergence a reviewer could still find into one nobody ever can.
+		// A duplicate key (issue #313) gets its own refusal: rebuilding from `current` writes back the winning value with the
+		// shadowed one silently gone, which turns a divergence a reviewer could still find into one nobody ever can.
 		if (parsedText !== null) {
 			const duplicate = findDuplicateKey(parsedText);
 			if (duplicate) {
 				return { invalid: `triggers file has a duplicate key ${JSON.stringify(duplicate.key)} at ${duplicate.at}; refusing to rewrite a file whose reviewed value and running value differ: ${triggersPath}` };
 			}
 		}
+		const newer = triggersFileVersionProblem(doc, { supported: versions.supported });
+		if (newer?.newer) return { invalid: `${newer.message}, so nothing was written and nothing in it was lost; change it with that release: ${triggersPath}`, newer: true };
 		const next = mutate(current.map((t) => ({ ...t })));
-		const text = serialize(next);
+		const nextDocument = typeof mutateDocument === "function" ? mutateDocument(JSON.parse(JSON.stringify(doc ?? { triggers: current }))) : doc;
+		const text = triggersFileText(next, nextDocument, versions);
 		try {
-			parseTriggers(text, triggersPath); // the loaders' own validator -- never write a file they would reject
+			parseTriggers(text, triggersPath, versions); // the loaders' own validator -- never write a file they would reject
 		} catch (e) {
 			return { invalid: e?.message ?? String(e) };
 		}
 		const tmp = tmpPathFor(triggersPath);
 		try {
 			fs.writeFileSync(tmp, text, { mode: 0o644 });
+			// After the tmp is written and before the rename, under the lock: nothing between this read and the rename
+			// can change the file except a writer that broke the lock (the stale-takeover residual in the header).
+			const changed = expectRefusal(fs, expect);
+			if (changed) {
+				discardTmp(fs, tmp);
+				return { invalid: changed };
+			}
 			renameIntoPlace(fs, tmp, triggersPath);
 		} catch (err) {
 			discardTmp(fs, tmp);
@@ -289,9 +367,9 @@ export async function disarmTrigger({ triggersPath, index, number, flow, command
 				currentText = fs.readFileSync(triggersPath, "utf8");
 				raw = JSON.parse(currentText);
 			} catch (err) {
-				// NEVER repair-from-empty here: overwriting a file we could not read, to record one
-				// disarm, would destroy the operator's trigger set. writeTriggers' repair posture is for
-				// the operator CRUD path, where "missing" means "first trigger".
+				// NEVER start from empty here: overwriting a file we could not read, to record one disarm,
+				// would destroy the operator's trigger set. writeTriggers starts from empty only for a file
+				// that holds nothing, on the operator CRUD path, where "missing" means "first trigger".
 				return { invalid: `triggers file unreadable (${err?.code ?? "parse-error"}), disarm not written: ${triggersPath}` };
 			}
 			// And a duplicate key is the destruction that comment thought it had closed (issue #313). This
@@ -326,11 +404,20 @@ export async function disarmTrigger({ triggersPath, index, number, flow, command
 				return { already: true };
 			}
 			entry.on.disarmed = { at, ...(jobId !== undefined && { jobId }) };
-			const text = serialize(entries);
+			// Every other top-level key rides along unchanged (issue #704), `version` included (issue #761): the disarm adds
+			// one key to one entry and owns nothing else. `serialize` over the RAW document keeps every top-level block,
+			// every key inside an entry and inside its `run`, and `version`, as they were read.
+			const text = serialize(entries, raw);
 			try {
 				parseTriggers(text, triggersPath); // the shared validator, same rule as every write
 			} catch (e) {
-				return { invalid: e?.message ?? String(e) };
+				// A file written by a newer pi-dispatch is the one refusal the disarm does NOT take (issue #761): the validator
+				// stops at its `version` and judges nothing below it, and the identity checks above have already found an armed
+				// one-shot at this index for this job. Refused, the one-shot would stay armed, and an upgraded worker or
+				// receiver would fire it again: a second paid run. Writing the one key this writer owns, with everything else
+				// as it was read, loses nothing the newer release wrote, which is the whole of why other writers refuse such a
+				// file. Any other refusal (a malformed file) is the validator's, as before.
+				if (e?.newer !== true) return { invalid: e?.message ?? String(e) };
 			}
 			const tmp = tmpPathFor(triggersPath);
 			try {
@@ -404,7 +491,7 @@ export function makeDisarmOnce({ triggersPath, fs = nodeFs, log = () => {}, disa
 }
 
 /**
- * The pre-spend check's factory (issue #231): `(job, { queueJobId }) => { ok } | { refused, at, jobId }`.
+ * The pre-spend check's factory (issue #231): `(job, { queueJobId }) => { ok } | { refused, at, jobId } | { newer }`.
  * Refuses ONLY on positive FOREIGN disarmed evidence -- a mark whose jobId is this very queue job
  * means BullMQ's second attempt of the delivery that spent the trigger, which must still run
  * (without the exception, a disarm on attempt one's failure record silently turns attempts:2 into
@@ -413,6 +500,7 @@ export function makeDisarmOnce({ triggersPath, fs = nodeFs, log = () => {}, disa
  * gone, entry changed -- is "run": fail-open, the disarm writer owns the loud refusals, and in the
  * compose topology (single-file :ro bind mount pinned to a dead inode, so the receiver never sees
  * the disarm until restart) this check IS the once-enforcement layer, which is why it exists at all.
+ * The one exception to fail-open is a file written by a newer pi-dispatch (issue #761): `{ newer: true }`, below.
  */
 export function makeCheckOnceSpent({ triggersPath, fs = nodeFs }) {
 	return async function checkOnceSpent(job, { queueJobId } = {}) {
@@ -426,6 +514,10 @@ export function makeCheckOnceSpent({ triggersPath, fs = nodeFs }) {
 			command: job?.command,
 			fs,
 		});
+		// Issue #761: NOT fail-open. A file written by a newer pi-dispatch may hold this one-shot's disarm in a shape this
+		// build cannot read (a renamed key, a mark this build would not see as one), so "run" could fire a spent one-shot
+		// again. The caller defers the job until a build that reads it.
+		if (state.state === "newer") return { newer: true };
 		if (state.state !== "disarmed") return { ok: true };
 		if (state.jobId !== null && state.jobId === queueJobId) return { ok: true }; // our own earlier attempt
 		return { refused: true, at: state.at, jobId: state.jobId };
@@ -454,7 +546,8 @@ export function makeCheckOnceSpent({ triggersPath, fs = nodeFs }) {
  *
  * FAIL-OPEN throughout, `readDisarmState`'s posture and for its reason: an unreadable or changed file means
  * "run", because a broken read must never wedge every job. Only a positive, identity-confirmed mismatch --
- * this entry authored conditions, this job carries none -- refuses.
+ * this entry authored conditions, this job carries none -- refuses. The one answer that is neither is a file written by
+ * a newer pi-dispatch (issue #761): `{ newer: true }`, which the caller turns into a deferral, never a refusal.
  */
 /**
  * The authored NARROWING fields the skew check covers besides `waitFor` (issues #502, #501): a `run` key whose absence
@@ -471,6 +564,8 @@ export function makeCheckOnceSpent({ triggersPath, fs = nodeFs }) {
  */
 export const AUTHORED_NARROWING_FIELDS = Object.freeze([
 	Object.freeze({ key: "models", authored: (v) => Array.isArray(v) && v.length > 0 }),
+	// A stale receiver dropping the reviewed retry order must not silently disable failover.
+	Object.freeze({ key: "fallbackModels", authored: (v) => Array.isArray(v) && v.length > 0 }),
 	// Issue #501: a trigger's per-job dollar cap. Dropped by a receiver from before #501 (which tolerated the key as
 	// unknown), the job would run under the deployment's wider cap, or with none, on a clean record. Any present
 	// value counts as authored; whether it is a valid amount is the loader's question, not this one.
@@ -482,6 +577,25 @@ export const AUTHORED_NARROWING_FIELDS = Object.freeze([
 	// the key as unknown), the job runs without it: the agent cannot ask, and the record reads like a clean run. Only
 	// `true` arms it, and the job data carries it only then, so `false` is nothing authored.
 	Object.freeze({ key: "awaitInput", authored: (v) => v === true }),
+	// Issue #644: the progress tool and the status comment. Dropped by a receiver from before #644 (which tolerates the
+	// keys as unknown), the job runs without the tool or without the comment the trigger promised, on a clean record.
+	// Only `true` arms either, and the job data carries each only then, so `false` is nothing authored.
+	Object.freeze({ key: "progress", authored: (v) => v === true }),
+	Object.freeze({ key: "statusComment", authored: (v) => v === true }),
+	// Issue #645: durable runs. Dropped by a receiver from before #645 (which tolerates the key as unknown), a run the
+	// worker loses fails instead of continuing from its checkpoint, the opposite of what the trigger promised. Only
+	// `true` arms it, and the job data carries it only then, so `false` is nothing authored.
+	Object.freeze({ key: "recover", authored: (v) => v === true }),
+	// Issue #646: steering a running job. Dropped by a receiver from before #646 (which tolerates the key as unknown), the
+	// run starts with no inbox, so an operator's steering message is refused as for an unarmed job while the trigger
+	// promised it would be heard. Only `true` arms it, and the job data carries it only then, so `false` is nothing
+	// authored.
+	Object.freeze({ key: "steer", authored: (v) => v === true }),
+	// Issue #800: what a trigger's jobs do not load and which tools they lose. Dropped by a service below the version floor, or a
+	// current one reading a dead inode through compose's single-file mount, the job loads what the file takes away and keeps the
+	// tool, on a clean record.
+	Object.freeze({ key: "excludeExtensions", authored: (v) => Array.isArray(v) && v.length > 0 }),
+	Object.freeze({ key: "excludeExtensionTools", authored: (v) => Array.isArray(v) && v.length > 0 }),
 ]);
 
 export function makeCheckWaitSkew({ triggersPath, fs = nodeFs }) {
@@ -492,18 +606,23 @@ export function makeCheckWaitSkew({ triggersPath, fs = nodeFs }) {
 	// stat replaces a read-and-parse on the hot path. The residual is millisecond mtime granularity: two
 	// writes inside one millisecond would serve a stale parse for one job, which fails OPEN like every other
 	// uncertainty here.
-	let cache = null; // { mtimeMs, size, triggers }
+	let cache = null; // { mtimeMs, size, triggers, newer }
+	// `{ triggers, newer }`: the raw entries (null when unreadable), and whether the file was written by a newer
+	// pi-dispatch (issue #761), judged by the loader's one rule (`triggersFileNewer`).
 	const read = () => {
 		try {
 			const st = fs.statSync?.(triggersPath);
-			if (cache && st && cache.mtimeMs === st.mtimeMs && cache.size === st.size) return cache.triggers;
-			const raw = JSON.parse(fs.readFileSync(triggersPath, "utf8"));
+			if (cache && st && cache.mtimeMs === st.mtimeMs && cache.size === st.size) return cache;
+			const text = fs.readFileSync(triggersPath, "utf8");
+			const raw = JSON.parse(text);
 			const triggers = Array.isArray(raw?.triggers) ? raw.triggers : null;
-			if (st) cache = { mtimeMs: st.mtimeMs, size: st.size, triggers };
-			return triggers;
+			// The TEXT, so a duplicate `version` is broken here as it is to the loader, never newer.
+			const newer = triggersFileNewer(text);
+			if (st) cache = { mtimeMs: st.mtimeMs, size: st.size, triggers, newer };
+			return { triggers, newer };
 		} catch {
 			cache = null;
-			return null;
+			return { triggers: null, newer: false };
 		}
 	};
 
@@ -517,12 +636,17 @@ export function makeCheckWaitSkew({ triggersPath, fs = nodeFs }) {
 		// Cron and CLI jobs carry no matched index, and cannot carry `waitFor` at all.
 		const index = job?.trigger?.matched?.index;
 		if (!Number.isInteger(index)) return { ok: true };
+		// Issue #761: read BEFORE the arrived-everything shortcut below, because a file written by a newer pi-dispatch may
+		// author a narrowing field this build has no row for, which no job field can show missing. Not fail-open: the
+		// caller defers the job (`{ newer: true }`) until a build that reads the file. The read is the cached stat.
+		const file = read();
+		if (file.newer) return { newer: true };
 		// The field arrived. Whether its conditions are SATISFIED is the gate's business, not this check's.
 		const waitArrived = Array.isArray(job?.waitFor) && job.waitFor.length > 0;
 		const missing = AUTHORED_NARROWING_FIELDS.filter((row) => job?.[row.key] === undefined || job[row.key] === null);
 		if (waitArrived && missing.length === 0) return { ok: true };
 
-		const triggers = read();
+		const triggers = file.triggers;
 		if (triggers === null) return { ok: true };
 		const entry = triggers[index];
 		const authored = entry?.run?.waitFor;
@@ -577,13 +701,149 @@ export function makeCheckPortfolioFlag({ triggersPath, fs = nodeFs }) {
 	};
 }
 
+/**
+ * The worker's read of the project secret bundles (issue #704, INT-TRIGGERS-FILE-CONTRACT `secretBundles`):
+ * `(job, { project }) => answer`, from the SAME file the one-shot, skew and portfolio checks read
+ * (`PI_TRIGGERS_FILE`, else `./triggers.json` in the worker's working directory).
+ *
+ * THE WORKER READS THE BINDING ITSELF, never the receiver, and that is the design rather than a shortcut. A
+ * bundle is not a field of a trigger: it applies to every job of a project, cron and forge alike, so there is no
+ * job field a receiver could carry it in. And a field the receiver carried would be droppable by a receiver
+ * older than it (the `AUTHORED_NARROWING_FIELDS` class), while a binding the worker reads cannot be dropped or
+ * forged by any receiver. `run.secretBundle: false` is read here for the same reason, from the entry the job came
+ * from, so the opt-out needs no receiver floor either.
+ *
+ * Answers, and why each is its own:
+ *   - `{ none: true }`: no bundle names this project, or the job has no project. Every other job of the deployment.
+ *   - `{ id, bundle, optedOut, entry }`: the project's bundle, and whether the job's trigger opted out.
+ *     `entry` is `"cron"`, `"forge"` or null (a job with no trigger: the processor skips it as `manual` anyway).
+ *   - `{ id, bundle, triggerChanged: true }`: the job came from a trigger, and no entry in the file is that
+ *     trigger any more, so whether it opted out is UNKNOWN. The processor refuses rather than guessing: granting
+ *     would widen a job whose trigger may have said `false`, and running without would be a job missing the
+ *     environment its project grants. The refusal says to re-run it, the skew check's posture.
+ *   - `{ unreadable }`: the file has never been read and validated in this process, and cannot be now, and the job
+ *     HAS a project. The processor retries such a job (never refuses it, never runs it without its bundle).
+ *
+ * THE LAST GOOD READ (issue #704 review round 1), the receiver's posture toward its own triggers. A file that cannot be
+ * read or does not validate NOW is answered from the last version that did, logged once per failure reason
+ * (`secret_bundles_last_good`), so an operator's broken save neither drops a bundle silently (a host that declares no
+ * bundle profile used to run a bundled job without it and say nothing) nor refuses jobs that can never be repaired by
+ * a retry (a host that declares one used to refuse every trigger job, project-less ones included, and a refused
+ * webhook delivery is gone). Only a process that has NEVER had a good read retries, and only a job with a project:
+ * which bundle it would hold is then unknowable, while a job in no project can hold none.
+ *
+ * A MISSING file (ENOENT) depends on the host (review round 2). On a host that declares a bundle profile
+ * (`bundlesDeclared()`), it is a failure like any other: such a host means to serve bundles, and a missing file there
+ * is a misconfiguration (a wrong `PI_TRIGGERS_FILE`, a file not copied to this host) that must not run a bundled
+ * project's jobs without their environment, so it falls back to the last good read, else retries. On a host that
+ * declares NONE it is a good read of no bundles, the overlay's rule for a missing settings file: such a host could
+ * serve no bundle anyway, and every host without a triggers file would otherwise retry every project job forever.
+ * The residual is named (DES-PROJECT-SECRET-BUNDLES): a host with neither a bundle profile nor the file runs a
+ * bundled project's job without the bundle, and doctor warns on a multi-host worker with projects and no file.
+ *
+ * Parsed with the shared validator (`parseTriggersDocument`), so a file the receiver would refuse is one this
+ * refuses too, and cached by mtime and size, `makeCheckWaitSkew`'s hot-path rule: this runs for every job.
+ *
+ * The identity of the job's entry is checked on the RAW entries, never the normalized ones, because the loader
+ * collapses a DISARMED one-shot to a sentinel and a retry of the very job that spent it would otherwise read as a
+ * changed trigger. A cron job is found by its id and must agree on folder, flow, command and task
+ * (`makeCheckPortfolioFlag`'s rule); a forge job by its matched index, agreeing on kind, `on.type`, command, and
+ * flow except on a comment trigger, whose phrase may name another flow (`<phrase> <flow>`) without changing
+ * which entry authorized it.
+ */
+export function makeFindSecretBundle({ triggersPath, fs = nodeFs, log = () => {}, bundlesDeclared = () => false }) {
+	let cache = null; // { mtimeMs, size } of the text `lastGood` came from
+	let lastGood = null; // { entries, bundles }
+	let failing = null; // the failure reason last logged, so a broken file logs once, not once per job
+	const fail = (why) => {
+		cache = null;
+		if (failing !== why) {
+			failing = why;
+			log("secret_bundles_last_good", { why, kept: lastGood !== null });
+		}
+		return lastGood ?? { unreadable: why };
+	};
+	const good = (doc, st) => {
+		lastGood = doc;
+		failing = null;
+		cache = st ? { mtimeMs: st.mtimeMs, size: st.size } : null;
+		return doc;
+	};
+	// No file: no bundles on a host that declares none, a failure on one that declares any (see above).
+	const missing = () => {
+		let declared = false;
+		try {
+			declared = bundlesDeclared() === true;
+		} catch {
+			declared = false;
+		}
+		return declared ? fail("absent") : good({ entries: [], bundles: {} }, null);
+	};
+	const read = () => {
+		if (typeof triggersPath !== "string" || triggersPath === "") return missing();
+		let st = null;
+		try {
+			st = fs.statSync?.(triggersPath) ?? null;
+		} catch (err) {
+			if (err?.code === "ENOENT") return missing();
+			return fail(typeof err?.code === "string" ? err.code : "read-error");
+		}
+		if (cache && lastGood && st && cache.mtimeMs === st.mtimeMs && cache.size === st.size) return lastGood;
+		let text;
+		try {
+			text = fs.readFileSync(triggersPath, "utf8");
+		} catch (err) {
+			if (err?.code === "ENOENT") return missing();
+			return fail(typeof err?.code === "string" ? err.code : "read-error");
+		}
+		try {
+			const { secretBundles } = parseTriggersDocument(text, triggersPath);
+			return good({ entries: JSON.parse(text).triggers, bundles: secretBundles }, st);
+		} catch {
+			return fail("invalid");
+		}
+	};
+
+	return function findSecretBundle(job, { project = null } = {}) {
+		if (typeof project !== "string" || project === "") return { none: true };
+		const doc = read();
+		if (doc.unreadable !== undefined) return doc;
+		const id = Object.keys(doc.bundles).find((key) => doc.bundles[key].project === project);
+		if (id === undefined) return { none: true };
+		const bundle = doc.bundles[id];
+		const trigger = job?.trigger;
+		if (trigger === undefined || trigger === null) return { id, bundle, optedOut: false, entry: null };
+		const entries = Array.isArray(doc.entries) ? doc.entries : [];
+		const matched = trigger.matched;
+		let raw;
+		let entry;
+		if (Number.isInteger(matched?.index)) {
+			entry = "forge";
+			const candidate = entries[matched.index];
+			const sameType = typeof matched.type !== "string" || candidate?.on?.type === matched.type;
+			const sameFlow = matched.type === "comment" || candidate?.run?.flow === job.flow;
+			if (candidate?.run?.kind === job.kind && sameType && sameFlow && candidate?.run?.command === job.command) raw = candidate;
+		} else if (typeof trigger.id === "string") {
+			entry = "cron";
+			raw = entries.find((t) => t?.on?.type === "cron" && t.on.id === trigger.id && ["folder", "flow", "command", "task"].every((k) => t.run?.[k] === job[k]));
+		}
+		if (raw === undefined) return { id, bundle, triggerChanged: true };
+		return { id, bundle, optedOut: raw.run?.secretBundle === false, entry };
+	};
+}
+
 export function readDisarmState({ triggersPath, index, number, flow, command, fs = nodeFs }) {
 	let raw;
+	let text;
 	try {
-		raw = JSON.parse(fs.readFileSync(triggersPath, "utf8"));
+		text = fs.readFileSync(triggersPath, "utf8");
+		raw = JSON.parse(text);
 	} catch (err) {
 		return { state: "unknown", reason: err?.code ?? "parse-error" };
 	}
+	// Before any entry is read (issue #761): a newer file's entries may mean something else, so nothing in it is evidence.
+	// Judged on the TEXT, so a duplicate `version` reads as the loader reads it: broken, not newer.
+	if (triggersFileNewer(text)) return { state: "newer" };
 	const entry = Array.isArray(raw?.triggers) ? raw.triggers[index] : undefined;
 	if (!entry || typeof entry !== "object" || entry.on?.once !== true || entry.on?.number !== number) {
 		return { state: "unknown", reason: "entry-changed" };