@edgehero/pi-dispatch 1.10.3 → 2.1.0

package/src/subscriptions.mjs

@@ -1,8 +1,12 @@
 /**
  * Operator-declared subscription plans (issue #53): the one place a flat-rate plan's real price can be
- * stated. Subscription-backed providers ship all-zero rate tables (pi-ai's kimi-coding and zai-coding-cn
- * both do), so their runs record cost 0 and read as FREE when they are PREPAID -- and the env boundary
- * REFUSES OAuth/subscription logins on purpose (env-allowlist.mjs: an expiring token cannot power an
+ * stated. pi-ai's rate table for a subscription-backed provider does not state the plan's price: at 0.80.7
+ * kimi-coding and zai-coding-cn shipped all-zero tables, so their runs recorded cost 0 and read as FREE
+ * when they were PREPAID; at the 0.99.1 pin most of their models carry an implied API-equivalent rate
+ * instead (issue #509), so the same prepaid runs now record a POSITIVE cost and read as METERED spend.
+ * Either way the table is the wrong price, and a zero rate is no longer even a hint that a plan exists
+ * (the qwen-token-plan family is all-zero, and so are free models of metered providers). And the env
+ * boundary REFUSES OAuth/subscription logins on purpose (env-allowlist.mjs: an expiring token cannot power an
  * unattended service), so no credential ever reaches the worker that could name the plan. An operator-side
  * declaration is therefore the only honest price source, and `subscriptions.json` is that declaration.
  *

package/src/transient.mjs

@@ -0,0 +1,240 @@
+/**
+ * One stated rule for the question `CONST-RETRY-INFRA-ONLY` asks at every failure site: would the same
+ * job, with the same inputs, refuse identically an hour from now with nobody touching anything?
+ *
+ * Absence, a bad credential, a malformed file, a URL that will always redirect, a certificate the host
+ * will always distrust: yes, determinate, and the operator has to fix it. A rate limit, a busy or
+ * unreachable filesystem, a network timeout, a forge that answered 502: no.
+ *
+ * WHY THIS EXISTS AS A MODULE (issue #316). The distinction was drawn twice, differently, one file apart:
+ * `gitlab-host.mjs` and `forgejo-host.mjs` classify a fetch rejection, a non-ok status and an unparseable
+ * body as `InfraRetry`, while `gitlab-identity.mjs`, `forgejo-identity.mjs`, `azure-identity.mjs` and
+ * `identity.mjs` tagged those same three conditions `piDispatchConfig`. Two precedents and no rule, which
+ * is how `classifyAppMintError` came to send a GitHub primary rate limit to the determinate side. #310
+ * made that expensive: the tag now means never retried, budget refunded, and a PUBLIC comment telling the
+ * issue author that the operator's deployment is misconfigured.
+ *
+ * IMPORT-FREE, and it has to stay that way. The identity modules are re-exported to the receiver through
+ * `worker/package.json`'s export map, and the receiver has no business importing `processor.mjs` to reach
+ * `InfraRetry`. So the rule is a set of predicates over a status, an errno and a rejection, and each
+ * caller pairs it with the throw its own layer can afford: `InfraRetry` where the processor will retry, an
+ * UNTAGGED throw at boot, where `entryExitCode` maps untagged to 1 (the supervisor restarts) and tagged to
+ * `EXIT_POLICY` (2), which `RestartPreventExitStatus=2` and `AppExit 2 Exit` deliberately leave stopped.
+ */
+
+/**
+ * Filesystem and spawn errnos that mean the thing is not there, or can never be reached by that name.
+ *
+ * An ALLOW-LIST, not a deny-list, which is the shape `env-allowlist.mjs`'s `credentialFromPiAuth` already
+ * argues for and the reason the two agree: the expensive direction is the false determinate, so a code
+ * nobody has thought about lands on the retryable side. `EACCES` is transient on purpose and it is the
+ * case that motivates the whole set: a not-yet-mounted autofs path, a directory whose permissions a
+ * deploy is mid-way through changing, and a genuinely wrong chmod are indistinguishable from one stat,
+ * and only the last one is the operator's to fix.
+ *
+ * `ENOTDIR` joins `ENOENT` because a path component that is a file is the same answer as absence. `ELOOP`
+ * and `ENAMETOOLONG` are properties of the PATH rather than of the filesystem's mood: a symlink cycle and
+ * an over-long name resolve identically forever, and retrying either is paying to be told so twice.
+ */
+export const DETERMINATE_FS_CODES = new Set(["ENOENT", "ENOTDIR", "ELOOP", "ENAMETOOLONG"]);
+
+/** True when this errno means the thing is absent or unreachable by that name, rather than out of reach now. */
+export function isDeterminateFsCode(code) {
+	return DETERMINATE_FS_CODES.has(code);
+}
+
+/**
+ * HTTP statuses that are transient on their own, regardless of headers.
+ *
+ * 429 is the obvious one. 408 (request timeout) and 425 (too early) are the two the old catch-all in
+ * `classifyAppMintError` swallowed alongside it, both of them by definition about timing.
+ */
+export const TRANSIENT_STATUSES = new Set([408, 425, 429]);
+
+/**
+ * The two 5xx that are NOT about load. "This server does not implement that method" and "it does not
+ * speak that HTTP version" answer identically forever, and both are what a misconfigured reverse proxy in
+ * front of a self-hosted forge actually returns.
+ */
+export const DETERMINATE_5XX = new Set([501, 505]);
+
+/**
+ * Classify an HTTP status, with the headers available where they change the answer.
+ *
+ * `getHeader` is a FUNCTION rather than a headers object because the two callers hold two different
+ * shapes: octokit exposes `error.response.headers` as a lowercase-keyed plain object, and `fetch` exposes
+ * `res.headers.get(name)`. A shared helper that took one of them would make the other call site adapt at
+ * the point where a mistake is silent.
+ *
+ * The 403 arm is the defect this module was written for. GitHub answers a PRIMARY rate limit with 403 and
+ * `x-ratelimit-remaining: 0`, sending `x-ratelimit-reset` and NO `retry-after`; only the secondary limit
+ * usually sends `retry-after`. The old code tested `retry-after` alone, so the primary limit -- the one an
+ * ordinary busy deployment actually hits, and which clears within the hour -- fell through to the
+ * catch-all and was reported to the issue author as a misconfiguration.
+ *
+ * **A SECONDARY limit can arrive with NEITHER header**, which is why GitHub's own guidance is a three-rung
+ * ladder ending in "otherwise wait at least a minute", and why octokit's throttling plugin detects it by
+ * matching the response BODY rather than the headers. Headers alone are therefore not enough, and the
+ * callers that hold a message pass it here; see `saysRateLimited`.
+ *
+ * A status that is absent or is not a positive integer is INDETERMINATE and therefore transient. That is
+ * not hypothetical: `@octokit/request-error` sets `status = 0` when the status will not parse, and `0` is
+ * a number, so the old `status !== undefined` catch-all turned "we could not tell what happened" into a
+ * permanent refusal. The same split `makeImagePreflight` draws with `docker info`: a determinate negative
+ * is a policy answer, an unanswered probe is not.
+ */
+export function isTransientStatus(status, getHeader = () => undefined, message = undefined) {
+	if (!Number.isInteger(status) || status <= 0) return true;
+	if (DETERMINATE_5XX.has(status)) return false;
+	if (status >= 500) return true;
+	if (TRANSIENT_STATUSES.has(status)) return true;
+	if (status === 403) {
+		// Secondary rate limit by header, then primary by quota, then the secondary limit that announces
+		// itself only in its body. Anything else answering 403 is a scope or credential problem, which is
+		// determinate.
+		const retryAfter = getHeader("retry-after");
+		if (retryAfter !== undefined && retryAfter !== null) return true;
+		if (String(getHeader("x-ratelimit-remaining") ?? "") === "0") return true;
+		if (saysRateLimited(message)) return true;
+		// A 403 whose body is not JSON did not come from the forge's API at all: it is a WAF or proxy
+		// interstitial in front of it, which is indeterminate rather than a refusal we can read.
+		if (getHeader("content-type") !== undefined && !isJsonContentType(getHeader)) return true;
+	}
+	return false;
+}
+
+/**
+ * Whether a response claims to carry JSON.
+ *
+ * The discriminator for an unparseable body, which is otherwise ambiguous in the expensive direction. A
+ * TRUNCATED JSON body is transient. An HTML page is not: it is a Cloudflare Access or OIDC portal
+ * answering instead of the forge, or Azure DevOps answering an expired PAT with **203 and a sign-in
+ * page** -- 203 is `ok`, so it reaches the parse rather than the status check, and an expired PAT is
+ * about as determinate as a fault gets.
+ */
+export function isJsonContentType(getHeader) {
+	const type = String(getHeader("content-type") ?? "").toLowerCase();
+	return type.includes("application/json") || type.includes("+json");
+}
+
+/**
+ * Whether an error body says it is a rate limit, for the 403s where the headers do not.
+ *
+ * The vocabulary is GitHub's own and matches what octokit's throttling plugin looks for. Kept as a
+ * message test rather than a status rule because that is the only channel this case has.
+ */
+export function saysRateLimited(message) {
+	return typeof message === "string" && /secondary rate limit|abuse detection|rate limit exceeded/i.test(message);
+}
+
+/**
+ * TLS and protocol faults that are determinate, and therefore the one family of connection failure that
+ * stays tagged.
+ *
+ * A CONNECTION is transient by default: refused, reset, timed out, DNS that did not answer. A TRUST
+ * failure is not. An instance behind a private CA fails the handshake identically forever until the
+ * operator sets `NODE_EXTRA_CA_CERTS`, which is the single commonest self-hosted GitLab misconfiguration
+ * and the reason `fetchFailureReason` unwraps the cause chain at all: the whole point of that unwrapping
+ * is to put "unable to verify the first certificate" in front of an operator so they can act on it, and
+ * reclassifying it as transient would answer that with a restart loop instead.
+ */
+export const DETERMINATE_TLS_CODES = new Set([
+	"UNABLE_TO_GET_ISSUER_CERT",
+	"UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+	"UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+	"SELF_SIGNED_CERT_IN_CHAIN",
+	"DEPTH_ZERO_SELF_SIGNED_CERT",
+	"CERT_UNTRUSTED",
+	"CERT_HAS_EXPIRED",
+	"CERT_NOT_YET_VALID",
+	"ERR_TLS_CERT_ALTNAME_INVALID",
+	// `ERR_SSL_*` is matched by PREFIX beside this set (see `isDeterminateFetchFailure`); this one is
+	// named as the worked example of why, and because it is the commonest of them.
+	"ERR_SSL_WRONG_VERSION_NUMBER",
+]);
+
+/**
+ * True when a rejection names a fault an operator has to fix, rather than one that may clear on its own.
+ *
+ * Walks the cause chain the way `fetchFailureReason` does, and `AggregateError.errors` beside it, because
+ * `fetch` reports a multi-address connect failure as an aggregate and a cause walk alone would step past
+ * the only frame carrying a code.
+ *
+ * TWO SIGNALS, and the second is deliberately narrow. The CODE is the real one, and every TLS failure
+ * Node actually produces carries it. The message is only consulted when a frame has NO code at all, for
+ * two cases where Node gives nothing else: a cause that lost its code on the way through a wrapper, and
+ * `redirect: "error"`, which every client here passes and which rejects with the bare string "unexpected
+ * redirect". A redirect is a URL-shaped fault wearing a connection failure's clothes: an `http://` URL for
+ * an https instance, or a host that 302s to an SSO portal, redirects identically forever.
+ *
+ * The code guard on the message test is not decoration. Node's DNS errors embed the HOSTNAME
+ * (`getaddrinfo ENOTFOUND certificates.corp`), so an unguarded `/certificate/i` over the whole chain makes
+ * every DNS failure at a host whose name contains that word look like a trust problem, which is the
+ * expensive direction.
+ *
+ * Deliberately NOT determinate: `ENOTFOUND` and `ECONNREFUSED`. A typo'd hostname and a wrong port are
+ * permanent, and are indistinguishable from a DNS outage or a forge that is down. They stay on the
+ * retryable side under this module's own allow-list rule, and that residual is named here rather than
+ * hidden.
+ */
+export function isDeterminateFetchFailure(err) {
+	const seen = new Set();
+	const walk = (e, depth) => {
+		if (!e || depth > 6 || seen.has(e)) return false;
+		seen.add(e);
+		if (DETERMINATE_TLS_CODES.has(e.code)) return true;
+		// Every OpenSSL protocol alert, not just the two spelled out above. An appliance that only speaks
+		// TLS 1.0 answers `ERR_SSL_TLSV1_ALERT_PROTOCOL_VERSION`, which is as determinate as a distrusted
+		// certificate and was missed by a name list; the prefix is the derivable version of that list.
+		if (typeof e.code === "string" && e.code.startsWith("ERR_SSL_")) return true;
+		if (e.code === undefined && typeof e.message === "string") {
+			if (/certificate/i.test(e.message)) return true;
+			if (e.message === "unexpected redirect") return true;
+		}
+		if (Array.isArray(e.errors) && e.errors.some((inner) => walk(inner, depth + 1))) return true;
+		return walk(e.cause, depth + 1);
+	};
+	return walk(err, 0);
+}
+
+/**
+ * A transient failure, reported UNTAGGED.
+ *
+ * The absence of the tag is the whole payload: `cli.mjs` and `receiver/src/cli.mjs` both map a tagged
+ * throw to `EXIT_POLICY` (2), which `RestartPreventExitStatus=2` and nssm's `AppExit 2 Exit` deliberately
+ * leave stopped, and map everything else to 1, which restarts. A boot-path caller therefore cannot use
+ * `InfraRetry` (it lives in `processor.mjs`, which the receiver must not import) and does not need to:
+ * plain is exactly right, and naming the constructor keeps that a decision rather than an omission.
+ */
+export function transientError(message, cause) {
+	return new Error(message, cause ? { cause } : undefined);
+}
+
+/**
+ * Read one header out of whatever shape the caller happens to hold.
+ *
+ * Both readers accept a plain object, a `Headers` and a `Map`, and the reason is that failing to read a
+ * header falls to the DETERMINATE side, which is the expensive one: a genuine rate limit read through the
+ * wrong accessor becomes a public accusation. `@octokit/request` v7 builds a plain object today, and
+ * `fetch` gives a `Headers`, but neither is guaranteed by anything in this repo, and a silent `undefined`
+ * is not a failure mode worth keeping for the sake of two fewer branches.
+ *
+ * `Object.hasOwn` matters: a bare `headers[name]` reads through `Object.prototype`, so a lookup for a
+ * header called `constructor` would answer with a function.
+ */
+function headerReaderFor(headers) {
+	if (!headers) return () => undefined;
+	if (typeof headers.get === "function") return (name) => headers.get(name) ?? undefined;
+	if (typeof headers === "object") return (name) => (Object.hasOwn(headers, name) ? headers[name] : undefined);
+	return () => undefined;
+}
+
+/** Read a header off an octokit rejection's `error.response.headers` bag. */
+export function octokitHeaderReader(error) {
+	return headerReaderFor(error?.response?.headers);
+}
+
+/** Read a header off a WHATWG `Response`. `redirect: "error"` responses still carry one. */
+export function responseHeaderReader(res) {
+	return headerReaderFor(res?.headers);
+}

package/src/triggers-file.mjs

@@ -13,11 +13,15 @@
  * every write now takes `<path>.lock` via exclusive create (`wx`), the session-store's idiom with its
  * two doctrines kept verbatim: EEXIST is the ONLY failure that means locked (anything else failed to
  * create the lock for its own reason and is reported as that reason), and a leaked lock is logged,
- * never thrown. What is NEW here, with no in-repo precedent, is the STALE TAKEOVER: a lock whose
- * mtime is older than LOCK_STALE_MS is unlinked and retaken once. The session store can afford to
- * discard on contention and let its reaper sweep a leak; this file cannot -- a crashed writer's lock
- * would otherwise wedge every trigger add, edit, delete and disarm on the deployment forever, and
- * there is no reaper whose beat covers it. The residual is the classic one: unlink-then-create is not
+ * never thrown. The STALE TAKEOVER started here and no longer has to argue for itself: a lock whose
+ * mtime is older than LOCK_STALE_MS is unlinked and retaken once, and the session store took the same
+ * idiom under issue #336, which refuted the premise this comment used to rest on -- that the store could
+ * afford to discard on contention and let its reaper sweep a leak. It could not: its reaper keys on a
+ * transcript, so a key whose first promotion died before one landed was never swept at all. The reason
+ * this file needed it FIRST still stands: a crashed writer's lock would wedge every trigger add, edit,
+ * delete and disarm on the deployment forever, and there is no reaper whose beat covers it. The two
+ * thresholds differ by 360 times because the work under the two locks does (see the session store's own
+ * constant). The residual is the classic one: unlink-then-create is not
  * atomic, so two writers racing a stale takeover can interleave in a window of milliseconds. That
  * window replaces today's always-open one, and the loser's write still validated through the shared
  * parser, so the file stays loadable; the lost update is one disarm or one edit, and the disarm
@@ -42,6 +46,7 @@
 
 import nodeFs from "node:fs";
 import { parseTriggers } from "./triggers.mjs";
+import { findDuplicateKey } from "./json-duplicates.mjs";
 
 /**
  * A lock older than this is a crashed writer's, not a live one's: every write under it is a read,
@@ -63,8 +68,31 @@ function lockPathFor(triggersPath) {
  * Take the lock, with one stale takeover. Returns an fd, or null when a LIVE writer holds it.
  * Throws only for non-EEXIST failures -- the session-store doctrine: reporting a read-only dir or a
  * full disk as "locked" sends an operator hunting for a stuck lock file that does not exist.
+ *
+ * `now` is INJECTED and defaults to the real clock, so every production path is byte-identical. It
+ * exists for two reasons and the test is only the second of them.
+ *
+ * The staleness threshold had NO test, because pinning it meant a ten-second sleep; with a clock it is
+ * a two-line assertion, and a bound nothing exercises is a bound that drifts.
+ *
+ * And the comparison it feeds is between TWO DIFFERENT CLOCKS. `Date.now()` is this process's;
+ * `mtimeMs` is the FILESYSTEM's, which on a network mount is a server's. `OQ-031` already records two
+ * hosts sharing one working tree as a live hazard, and `triggers.json` is exactly the file such a
+ * deployment shares. BOTH signs of the skew are bad, and differently:
+ *
+ *   - A server more than LOCK_STALE_MS BEHIND makes every LIVE lock read as stale, so the takeover fires
+ *     on every attempt and the millisecond-wide double-take window this module concedes stops being a
+ *     rare race and becomes the normal case. Worse than it sounds, because `releaseLock` unlinks by PATH
+ *     rather than by fd: once A's lock is stolen, A's release deletes B's, so under sustained skew the
+ *     lock is not merely racy, it is functionally absent.
+ *   - A server AHEAD makes the difference negative, so the comparison is always true and a genuinely
+ *     crashed writer's lock is NEVER swept. `writeTriggers` then refuses forever and `disarmTrigger`
+ *     exhausts its retries, which means a spent one-shot never records its disarm and can fire again.
+ *
+ * Nothing here closes either; the seam is what let a test demonstrate the skew, and issue #293's
+ * clock-shifted CI run is what found it.
  */
-function takeLock(triggersPath, fs, log) {
+function takeLock(triggersPath, fs, log, now = () => Date.now()) {
 	const lock = lockPathFor(triggersPath);
 	let sweptAgeMs = null;
 	for (let attempt = 0; attempt < 2; attempt++) {
@@ -84,13 +112,13 @@ function takeLock(triggersPath, fs, log) {
 				// The holder released between our open and our stat: the next loop iteration takes it.
 				continue;
 			}
-			if (Date.now() - mtimeMs <= LOCK_STALE_MS) return null; // live writer; caller decides
+			if (now() - mtimeMs <= LOCK_STALE_MS) return null; // live writer; caller decides
 			try {
 				fs.unlinkSync(lock);
 			} catch {
 				// Someone else swept it first; the retry create answers who won.
 			}
-			sweptAgeMs = Math.round(Date.now() - mtimeMs);
+			sweptAgeMs = Math.round(now() - mtimeMs);
 		}
 	}
 	return null;
@@ -165,8 +193,8 @@ function discardTmp(fs, tmp) {
  * Returns `{ ok: true }`, or `{ invalid }` for a validation failure OR a held lock; fs failures throw,
  * the contract this function has always had.
  */
-export function writeTriggers({ triggersPath, mutate, fs = nodeFs, log = () => {} }) {
-	const fd = takeLock(triggersPath, fs, log);
+export function writeTriggers({ triggersPath, mutate, fs = nodeFs, log = () => {}, now = () => Date.now() }) {
+	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
 		// that finishes in milliseconds. The operator re-presses; the file was never touched.
@@ -174,12 +202,30 @@ export function writeTriggers({ triggersPath, mutate, fs = nodeFs, log = () => {
 	}
 	try {
 		let current = [];
+		// 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;
 		try {
-			const raw = JSON.parse(fs.readFileSync(triggersPath, "utf8"));
-			if (Array.isArray(raw?.triggers)) current = raw.triggers;
+			const raw = fs.readFileSync(triggersPath, "utf8");
+			const value = JSON.parse(raw);
+			parsedText = raw;
+			if (Array.isArray(value?.triggers)) current = value.triggers;
 		} catch {
 			// Missing/invalid file: start from empty; the validated atomic write below repairs it.
 		}
+		// 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.
+		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 next = mutate(current.map((t) => ({ ...t })));
 		const text = serialize(next);
 		try {
@@ -224,11 +270,11 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * not failure), or `{ invalid }` with an operator-actionable reason. NEVER throws, and NEVER repairs:
  * an unreadable file is `{ invalid }` with the bytes untouched.
  */
-export async function disarmTrigger({ triggersPath, index, number, flow, command, jobId, at, fs = nodeFs, log = () => {} }) {
+export async function disarmTrigger({ triggersPath, index, number, flow, command, jobId, at, fs = nodeFs, log = () => {}, now = () => Date.now() }) {
 	for (let attempt = 0; attempt < DISARM_LOCK_ATTEMPTS; attempt++) {
 		let fd;
 		try {
-			fd = takeLock(triggersPath, fs, log);
+			fd = takeLock(triggersPath, fs, log, now);
 		} catch (err) {
 			return { invalid: `triggers file lock failed (${err?.code ?? "lock-error"}): ${triggersPath}` };
 		}
@@ -238,14 +284,24 @@ export async function disarmTrigger({ triggersPath, index, number, flow, command
 		}
 		try {
 			let raw;
+			let currentText;
 			try {
-				raw = JSON.parse(fs.readFileSync(triggersPath, "utf8"));
+				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".
 				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
+			// path parses, collapses the duplicate to its last value, and then rewrites the WHOLE file from
+			// the parsed array -- so the shadowed key is gone from disk, permanently, to record one disarm.
+			// A file that says two things is not a file to rewrite from one of them.
+			const duplicate = findDuplicateKey(currentText);
+			if (duplicate) {
+				return { invalid: `triggers file has a duplicate key ${JSON.stringify(duplicate.key)} at ${duplicate.at}, disarm not written: ${triggersPath}` };
+			}
 			const entries = Array.isArray(raw?.triggers) ? raw.triggers : null;
 			const entry = entries?.[index];
 			if (!entry || typeof entry !== "object") {