@edgehero/pi-dispatch 1.3.0 → 1.4.0

package/deploy/docker-compose.yml

@@ -49,7 +49,11 @@ services:
       PI_TRIGGERS_FILE: /config/triggers.json
     # The repo-root triggers.json (`pi-dispatch init` scaffolds it -- run that first: mounting a path
     # that does not exist makes Docker create it as a DIRECTORY and the boot fails confusingly).
-    # Read-only: the receiver live-reloads this file on change; it never writes it.
+    # Read-only: the receiver live-reloads this file on change; it never writes it. One consequence of
+    # a single-FILE bind mount (issue #231): every write to this file is an atomic tmp+rename that
+    # SWAPS THE INODE, and the mount stays pinned to the old one -- so the worker's one-shot disarm is
+    # invisible in here until the container restarts, and the worker's own pre-spend check is what
+    # keeps a spent one-shot from running again in the meantime. A restart picks up the current file.
     volumes:
       - ../triggers.json:/config/triggers.json:ro
     # Loopback only, like Valkey's port above: the operator's reverse proxy or tunnel (TLS, public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
   "keywords": [
@@ -52,6 +52,7 @@
     "./job-id": "./src/job-id.mjs",
     "./forges": "./src/forges.mjs",
     "./triggers": "./src/triggers.mjs",
+    "./triggers-file": "./src/triggers-file.mjs",
     "./packages": "./src/packages.mjs",
     "./pause-windows": "./src/pause-windows.mjs",
     "./identity": "./src/identity.mjs",

package/src/doctor.mjs

@@ -264,7 +264,7 @@ export async function collectChecks(env, seams) {
 	// image checks just below, and `optingOut`/`requiring` colour the staged-packages lines further down.
 	// `optingOut` counts the only value that withholds the staged set; `requiring` counts an explicit
 	// run.packages: true, which arms nothing any more but is still an operator statement of intent.
-	const { requiring, optingOut, resuming, replicating, instructing, commands, secreting, secretProfiles, localSecretFolders, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
+	const { requiring, optingOut, resuming, replicating, instructing, commands, secreting, onceArmed, onceSpent, secretProfiles, localSecretFolders, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
 	// FIRST, and fail rather than warn: every check below this line reads counts that a parse failure
 	// zeroed, so a green run here would be reporting on a file nobody could read. The receiver loads this
 	// file unconditionally and refuses to start without it, which is the consequence worth naming.
@@ -1242,6 +1242,31 @@ export async function collectChecks(env, seams) {
 		});
 	}
 
+	// One-shot close triggers (issue #231, DES-ONE-SHOT-DISARM-IN-THE-FILE). Advisory only -- doctor
+	// never touches triggers -- and counted from the RAW file (readTriggerFacts says why). Two lines
+	// with different lives: the armed line names the count and, when PI_TRIGGERS_FILE is unset, warns
+	// that the disarm resolves ./triggers.json against the WORKER SERVICE's working directory -- a
+	// service unit whose WorkingDirectory differs from the receiver's would disarm a file nobody
+	// matches against, the split-file hazard no mechanism can detect. The spent line states the
+	// deliberate degradation: a spent entry counts toward NO parsed fact above (forges, flows,
+	// webhook-secret), mirroring what the receiver serves at its next boot.
+	if (onceArmed > 0) {
+		checks.push({
+			ok: true,
+			warn: env.PI_TRIGGERS_FILE === undefined,
+			label: `${onceArmed} one-shot trigger(s) armed (on.once) -- the worker disarms the entry in ${env.PI_TRIGGERS_FILE === undefined ? "./triggers.json resolved against the worker service's working directory; set PI_TRIGGERS_FILE so worker and receiver name the same file from anywhere" : "PI_TRIGGERS_FILE"} after the run record exists`,
+			fix: "set PI_TRIGGERS_FILE to an absolute path in both services' environments",
+		});
+	}
+	if (onceSpent > 0) {
+		checks.push({
+			ok: true,
+			warn: false,
+			label: `${onceSpent} one-shot trigger(s) already spent (on.disarmed) -- spent entries match nothing and count toward no credential or flow check; delete on.disarmed to re-arm, or delete the entry once its history no longer matters`,
+			fix: "",
+		});
+	}
+
 	// REQ-SCOPED-PAUSE-WINDOWS, the panel-writes-what-the-worker-ignores trap (issue #99). Three defaults
 	// that are individually defensible and together silent:
 	//
@@ -1472,15 +1497,25 @@ function parseSecretProfilesSafe(raw) {
 }
 
 function readTriggerFacts(env, fileExists, cwd) {
-	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, secretProfiles: [], localSecretFolders: [], images: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
+	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, onceArmed: 0, onceSpent: 0, secretProfiles: [], localSecretFolders: [], images: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
 	try {
 		// Unset falls back to ./triggers.json in cwd, MIRRORING the receiver's own default
 		// (receiver/src/config.mjs) -- the two must read the same file, or doctor preflights a deployment
 		// the receiver will not boot. An absent file still means "no triggers at all", exactly as before.
 		const path = env.PI_TRIGGERS_FILE ?? join(cwd, "triggers.json");
 		if (!fileExists(path)) return none;
-		const triggers = parseTriggers(readFileSync(path, "utf8"), path);
+		const text = readFileSync(path, "utf8");
+		const triggers = parseTriggers(text, path);
+		// The one-shot facts are counted from the RAW entries, not the parsed records, because the
+		// validator collapses a disarmed entry to a sentinel that carries neither `once` nor
+		// `disarmed` -- exactly so nothing can match it -- which also erases it from every parsed
+		// count above. Doctor is the surface that must still SEE the spent entry: "why did nothing
+		// fire" is answered by a spent row, and only the raw file still holds it. Safe unguarded:
+		// parseTriggers just accepted this same text, so JSON.parse cannot throw here.
+		const rawEntries = JSON.parse(text)?.triggers ?? [];
 		return {
+			onceArmed: rawEntries.filter((t) => t?.on?.once === true && t.on.disarmed === undefined).length,
+			onceSpent: rawEntries.filter((t) => t?.on?.disarmed !== undefined).length,
 			requiring: triggers.filter((t) => t.run.packages === true).length,
 			resuming: triggers.filter((t) => t.run.resume === true).length,
 			// REQ-PER-TRIGGER-INSTRUCTION. Counted beside `resuming` for the same reason: it is a per-trigger

package/src/get-token.mjs

@@ -104,10 +104,15 @@ export async function makeGitHubAuth(cfg, deps = {}) {
 				);
 			}
 			const repositoryNames = [repoNameOf(repo)]; // scope to the ONE repo; owner stripped
+			// An optional PERMISSIONS narrowing (issue #231): the receiver's closer-permission lookup asks
+			// for `{ metadata: "read" }`, so the token it holds for that one question cannot write anything
+			// even if leaked. Job mints never pass this and keep the installation's full grant -- narrowing
+			// is the caller's statement of intent, not a default this mint could guess.
+			const permissions = job?.permissions;
 			let minted;
 			try {
 				const appAuth = createAppAuth(auth);
-				minted = await appAuth({ type: "installation", repositoryNames });
+				minted = await appAuth({ type: "installation", repositoryNames, ...(permissions && { permissions }) });
 			} catch (error) {
 				throw classifyAppMintError(error);
 			}

package/src/index.mjs

@@ -125,6 +125,11 @@ export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, ap
 				// `queueJobId`, mirroring the collectChain injection above. Omitted when unwired so a bare
 				// processor keeps runJob's plain (job, token) call.
 				...(deps.prepareWorkspace ? { prepareWorkspace: (j, t) => deps.prepareWorkspace(j, t, { queueJobId: job.id }) } : {}),
+				// The one-shot pre-spend check (issue #231) needs the REAL BullMQ job's `.id` to excuse this
+				// delivery's own earlier attempt -- runJob's effectiveJob has no `.id`, prepareWorkspace's
+				// own injection above states why, and this one mirrors it. Omitted when unwired so a bare
+				// processor keeps runJob's admit-everything default.
+				...(deps.checkOnceSpent ? { checkOnceSpent: (j) => deps.checkOnceSpent(j, { queueJobId: job.id }) } : {}),
 			});
 			recordRun({ job, result, startedAt, endedAt: new Date().toISOString() });
 			return result;

package/src/processor.mjs

@@ -42,6 +42,11 @@ export async function runJob(job, deps) {
 		// this job names is on this host (image-preflight.mjs). Default admits everything, so a wiring that
 		// omits it behaves exactly as before -- the container's own failure stays the backstop.
 		imagePreflight = async () => ({ ok: true }),
+		// (job) => { ok } | { refused, at, jobId }. The one-shot pre-spend check (issue #231,
+		// DES-ONE-SHOT-DISARM-IN-THE-FILE). Default admits everything -- an unwired processor behaves
+		// exactly as before, and the gate below only calls it for a job whose matched rule was a
+		// one-shot, so the default is never a probe running on every delivery.
+		checkOnceSpent = async () => ({ ok: true }),
 		// REQ-EGRESS-ALLOWLIST. Default admits everything, so a wiring that omits it behaves exactly as a
 		// deployment with no egress policy does -- which is also what the real factory returns when unarmed.
 		egressPreflight = async () => ({ ok: true }),
@@ -121,6 +126,27 @@ export async function runJob(job, deps) {
 	let reserved = false;
 
 	try {
+		// The one-shot pre-spend check (issue #231), FIRST on the ladder: one file read, cheaper than
+		// the docker inspect below, free, determinate, credential-less. Only a FOREIGN positive
+		// disarmed mark refuses -- the check excuses this queue job's own id, so a retry of the
+		// delivery that spent the trigger still runs (attempts:2 stays attempts:2) -- and anything
+		// unreadable or changed means "run": fail-open, because the disarm writer owns the loud
+		// refusals, and a broken read must never wedge every once job. In the compose topology the
+		// receiver reads a dead inode until restart, so this check is the once-enforcement layer
+		// there, not optional hardening.
+		if (job.trigger?.matched?.once === true) {
+			const spent = await checkOnceSpent(job);
+			if (spent.refused) {
+				// Commented like every sibling policy refusal: explainability is this refusal's whole
+				// purpose, and only a DISTINCT re-close reaches it past the GUID dedup, so the noise
+				// bound is the operator's own reopen-close rate. `at`/`jobId` are harness-written
+				// provenance, never payload text.
+				await comment(job, `Refused: this one-shot trigger was already spent${spent.at ? ` at ${spent.at}` : ""}${spent.jobId ? ` by job ${spent.jobId}` : ""}. The close that armed it has already produced a run; delete on.disarmed from the trigger entry to re-arm it. Not run.`);
+				log("refused_once_already_spent", { triggerIndex: job.trigger?.matched?.index ?? null });
+				return { outcome: "policy", reason: "once-already-spent", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+		}
+
 		// The job image must exist on THIS host before anything else happens. Free, determinate and
 		// credential-less, so it precedes the mint, the clone and the reservation: a host that cannot run the
 		// image refuses without minting a credential it will not use, cloning a repo it will not read, or

package/src/queue.mjs

@@ -1,6 +1,11 @@
 import { Queue } from "bullmq";
 import { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId } from "./job-id.mjs";
 import { targetSeparator } from "./forges.mjs";
+import { PR_CLOSE_ACTIONS } from "./triggers.mjs";
+
+// The close words in every forge's spelling, derived from the one table (never re-typed here): a
+// matched PR action in this set marks a close job for the semantic-key discriminant below.
+const PR_CLOSE_WORDS = new Set(Object.values(PR_CLOSE_ACTIONS));
 
 export const QUEUE = "pi-jobs";
 export { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId };
@@ -180,6 +185,21 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		...(replica !== undefined && { replica }),
 		...(replicas !== undefined && { replicas }),
 	};
+	// A close-triggered job (issue #231) leads the semantic key's flow slot with `closed:`. Without it,
+	// a label/comment/PR job on the same target and flow inside the 10-minute window silently swallows
+	// the close job -- and because a swallowed close job writes no run record, the once trigger it was
+	// meant to spend never disarms: a permanently dead one-shot with nothing in the panel to say why.
+	// The discriminant is DERIVED from the matched rule (`issue` type, or a PR close action word) rather
+	// than carried as a job field: an execution detail of dedup is not a fact about the delivery, and
+	// `data`/`event.json` stay byte-identical. `:` is outside the skill-name charset -- enforced at load
+	// since #231 -- so no real flow can spell either prefixed form, and `closed:cmd:<name>` composes for
+	// close-dispatched commands (outermost discriminant first, then the entry-point prefix).
+	const matched = trigger?.matched;
+	// `type === "issue"` reads as "close" only while the issue vocabulary is close-only (it is; the
+	// tables say "one word each so far"). If that type ever grows a non-close action, this test must
+	// narrow to the matched action word, like the PR half already does.
+	const isCloseJob = matched?.type === "issue" || (matched?.type === "pull_request" && PR_CLOSE_WORDS.has(matched?.action));
+	const flowSlot = `${isCloseJob ? "closed:" : ""}${command !== undefined ? `cmd:${command}` : flow}`;
 	await queue.add(kind, data, {
 		jobId,
 		// A command job (issue #189) fills the semantic key's flow slot with `cmd:<command>`: a command
@@ -188,7 +208,7 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// `cmd:` prefix keeps a command named X from coalescing against a flow named X -- `:` is outside
 		// the skill-name charset, so no real flow can spell the prefixed form -- and a flow job's key
 		// stays byte-identical to before the feature.
-		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${command !== undefined ? `cmd:${command}` : flow}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
+		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${flowSlot}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
 		attempts: 2,
 		backoff: { type: "exponential", delay: 60_000 },
 		removeOnComplete: { age: 31 * 24 * 3600 }, // age in seconds -- do not cross units with the ms ttl above

package/src/run-history.mjs

@@ -34,13 +34,57 @@ export function sanitizeJobId(id) {
 	return s.replace(/[^A-Za-z0-9._-]/g, "_");
 }
 
+/**
+ * Parse one line of the buffered tail as a runner-emitted JSON line, or `null` for noise -- repairing
+ * the GLUED case (issue #224, OQ-003).
+ *
+ * The hazard: the runner's writes used to be newline-terminated but not newline-delimited, so a
+ * partial write from anything sharing the container's stdout (a subprocess that never flushed its
+ * trailing newline) lands as `<stray bytes><runner line>` in ONE line. A plain JSON.parse skips it,
+ * and because every parseExit* scan walks backwards past what does not parse, one un-newlined byte
+ * used to lose turns, tokens, usage, session and context at once -- or worse, hand the scan to a
+ * forged exit line placed earlier.
+ *
+ * The repair re-anchors on `{"event":"`, which is collision-free by construction: `event` is the
+ * first key both runner writers serialise, and JSON.stringify escapes every quote inside a string
+ * value, so these raw bytes cannot occur INSIDE a runner line -- only where one starts. Suffixes are
+ * tried left to right, so the leftmost complete object wins: a suffix beginning inside the stray
+ * bytes cannot parse to the line's end (nothing can close a JSON container after bytes the runner
+ * appended later, and the runner's own quotes terminate any string opened before them), so the first
+ * success is the glued runner object itself -- and this left-to-right scan, not just the quote
+ * escaping, is what keeps a would-be inner `{"event":"` from being chosen over the outer one.
+ * A line whose HEAD the capped tail sliced off is handled correctly either way: if the cut fell in a
+ * glued line's stray PREFIX the anchor survives and the genuine object is still repaired, and if it
+ * fell in or past the anchor no `{"event":"` survives and the line is skipped. A line truncated at the
+ * END (a mid-write death) has no complete object and is skipped too. A fragment is never MISREAD as a
+ * value: a broken one does not parse and an anchorless one is not repaired.
+ *
+ * NEVER throws, like the five scanners that call it.
+ */
+function parseTailLine(line) {
+	try {
+		return JSON.parse(line);
+	} catch {
+		// docker/agent noise, a truncated line, or a glued one -- try the repair before giving up.
+	}
+	let from = line.indexOf('{"event":"', 1);
+	while (from !== -1) {
+		try {
+			return JSON.parse(line.slice(from));
+		} catch {
+			from = line.indexOf('{"event":"', from + 1);
+		}
+	}
+	return null;
+}
+
 /**
  * Recover the agent's turn count from buffered container stdout, or `null` if it is not reported.
  *
  * The stream interleaves docker/agent noise and other JSON events (`pi_auto_retry`) with the runner's
  * own lines. Only the success exit line carries `turns` (`image/runner/run-job.mjs:263`); the
  * catch-path exit line (`:277`) omits it. Scan from the end and return the turns of the last `exit`
- * event that reports an integer count.
+ * event that reports an integer count, repairing a glued line on the way (`parseTailLine`).
  *
  * This is read-only telemetry: it MUST NEVER throw and MUST NOT feed exit-code or retry
  * classification -- that is the container exit code's job (INT-RUNNER-EXIT-CODE-PROTOCOL). Every parse
@@ -52,12 +96,7 @@ export function parseExitTurns(text) {
 	for (let i = lines.length - 1; i >= 0; i--) {
 		const line = lines[i].trim();
 		if (line === "") continue;
-		let parsed;
-		try {
-			parsed = JSON.parse(line);
-		} catch {
-			continue; // docker/agent noise or a truncated final line
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		return Number.isInteger(parsed?.turns) ? parsed.turns : null;
 	}
@@ -94,12 +133,7 @@ export function parseExitSession(text) {
 	for (let i = lines.length - 1; i >= 0; i--) {
 		const line = lines[i].trim();
 		if (line === "") continue;
-		let parsed;
-		try {
-			parsed = JSON.parse(line);
-		} catch {
-			continue; // docker/agent noise or a truncated final line
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		const sess = parsed?.session;
 		if (sess && typeof sess === "object" && !Array.isArray(sess) && typeof sess.resumed === "boolean") {
@@ -126,12 +160,7 @@ export function parseExitContext(text) {
 	for (let i = lines.length - 1; i >= 0; i--) {
 		const line = lines[i].trim();
 		if (line === "") continue;
-		let parsed;
-		try {
-			parsed = JSON.parse(line);
-		} catch {
-			continue; // docker/agent noise or a truncated final line
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		const c = parsed?.context;
 		// A window of 0 is not a denominator, and a negative count is not a measurement. SAFE integers
@@ -153,12 +182,7 @@ export function parseExitTokens(text) {
 	for (let i = lines.length - 1; i >= 0; i--) {
 		const line = lines[i].trim();
 		if (line === "") continue;
-		let parsed;
-		try {
-			parsed = JSON.parse(line);
-		} catch {
-			continue; // docker/agent noise or a truncated final line
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		const t = parsed?.tokens;
 		if (t && typeof t === "object" && !Array.isArray(t) && typeof t.total === "number") return t;
@@ -204,12 +228,7 @@ export function parseExitUsage(text) {
 	for (let i = lines.length - 1; i >= 0; i--) {
 		const line = lines[i].trim();
 		if (line === "") continue;
-		let parsed;
-		try {
-			parsed = JSON.parse(line);
-		} catch {
-			continue; // docker/agent noise or a truncated final line
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		return rebuildUsage(parsed?.usage);
 	}

package/src/start.mjs

@@ -1,6 +1,6 @@
 import { execFile } from "node:child_process";
 import { watch } from "node:fs";
-import { dirname, basename } from "node:path";
+import { dirname, basename, join } from "node:path";
 import { promisify } from "node:util";
 import { configError, loadConfig } from "./config.mjs";
 import { makeRedisClient, parseConnection } from "./connection.mjs";
@@ -22,6 +22,7 @@ import { makeCleanup, makeForgePreparers, makePrepareWorkspace } from "./prepare
 import { listRunningSandboxes } from "./sandbox.mjs";
 import { makeSandboxReaper } from "./sandbox-store.mjs";
 import { makeSessionStore } from "./session-store.mjs";
+import { makeCheckOnceSpent, makeDisarmOnce } from "./triggers-file.mjs";
 import { loadPauseWindows, pauseUntilMs } from "./pause-windows.mjs";
 import { makeQueue } from "./queue.mjs";
 import { makeRunContainer } from "./run-container.mjs";
@@ -313,8 +314,25 @@ export async function startWorker(
 	} catch (err) {
 		log("session_reaper_skipped", { reason: err?.message });
 	}
-	const recordRun = ({ job, result, error, startedAt, endedAt }) =>
+	// The one-shot file path (issue #231): PI_TRIGGERS_FILE, else ./triggers.json against this process's
+	// cwd -- doctor's own fallback, chosen for doctor's own reason ("the two must read the same file"),
+	// and deliberately NOT config.triggersFile, whose null means "cron disabled" and must keep meaning
+	// that: under that knob the DEFAULT single-host deployment would have a firing receiver and a worker
+	// that can neither disarm nor pre-spend-check.
+	const onceTriggersFile = env.PI_TRIGGERS_FILE ?? join(process.cwd(), "triggers.json");
+	const disarmOnce = makeDisarmOnce({ triggersPath: onceTriggersFile, log });
+	const recordRun = ({ job, result, error, startedAt, endedAt }) => {
 		writeRecord(buildRecord({ job, result, error, startedAt, endedAt }));
+		// Strictly AFTER the durable record: "fired" means "produced a run record", and the crash
+		// direction this ordering buys is the chosen one -- an armed one-shot with a record, never a
+		// disarm before writeRecord RETURNED. Returned, not succeeded: the record writer swallows fs
+		// errors by contract (run_record_failed), so a full disk still spends the one-shot -- the
+		// alternative, skipping the disarm on a failed record write, would re-fire it unbounded. Fire-and-forget: the hook never rejects, and the record path must not
+		// wait on a lock retry. An uncontended disarm completes synchronously inside this call; the
+		// one loss window is a drain's process.exit landing mid-lock-retry sleep, which loses only
+		// the disarm -- the same chosen direction, met at shutdown instead of a crash.
+		void disarmOnce({ job, endedAt });
+	};
 
 	// INT-CONFIG-OVERLAY-CONTRACT: the worker reads the runtime-settings overlay at EACH job start, so this
 	// closure -- not a value frozen at boot -- is what the processor calls per job. It resolves the eight
@@ -406,6 +424,11 @@ export async function startWorker(
 		pauseUntil: (job, now) => pauseUntilMs(pauseWindows.current, job, now),
 		deps: {
 			collectChain,
+			// The one-shot pre-spend check (issue #231): reads the same file the disarm writes, refuses
+			// only on a FOREIGN positive mark (index.mjs binds the real queue jobId so a retry of the
+			// spending delivery is excused). In the compose topology this check is the once-enforcement
+			// layer, because the receiver's single-file :ro mount pins a dead inode until restart.
+			checkOnceSpent: makeCheckOnceSpent({ triggersPath: onceTriggersFile }),
 			// One deployment default, two consumers, adjacent by construction: the preflight that refuses a missing
 			// image BEFORE the budget slot, and the factory that puts it in the argv. Both resolve a trigger's own
 			// `run.image` through the same resolveJobImage, so the image that was checked is the image that runs.

package/src/triggers-file.mjs

@@ -0,0 +1,403 @@
+/**
+ * The shared triggers-file WRITER (issue #231, DES-ONE-SHOT-DISARM-IN-THE-FILE, OQ-008).
+ *
+ * Moved here from the admin's read-model so BOTH authors of `triggers.json` serialize through one
+ * funnel: the operator's console (dialogs and confirm-gated tools, via the admin's re-export) and the
+ * worker's one-shot disarm. "REUSE, NEVER RE-DERIVE" -- the same rule that single-sources the parser
+ * and `loadGitHubAuth`. The file format is the admin's own: 2-space JSON plus a trailing newline,
+ * byte-for-byte what `writeTriggers` always wrote, and a test pins it.
+ *
+ * THE LOCK. Until #231 there was exactly one writer (one single-threaded pi process, tools declared
+ * sequential), so read-modify-write had nothing to race and `renameSync`'s last-writer-wins was moot.
+ * The worker's disarm is a second author -- and at PI_CONCURRENCY up to 3, a third and fourth -- so
+ * 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
+ * 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
+ * caller retries.
+ *
+ * Callers split by posture, deliberately:
+ *   - `writeTriggers` is SYNC and gives up IMMEDIATELY on contention (`{ invalid }` naming the lock).
+ *     Its callers sit on the pi TUI's event loop, where a bounded-retry sleep is a frozen panel; an
+ *     operator whose keypress lost the race gets a message and presses the key again.
+ *   - `disarmTrigger` is ASYNC and retries with jitter, because ITS caller is the worker's post-run
+ *     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.
+ *
+ * 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";
+
+/**
+ * A lock older than this is a crashed writer's, not a live one's: every write under it is a read,
+ * one mutate, one serialize and two syscalls, three orders of magnitude faster. Ten seconds rather
+ * than one so a laptop suspending mid-write on battery does not get its live lock stolen on resume.
+ */
+const LOCK_STALE_MS = 10_000;
+
+/** Bounded contention retry for the disarm path: ~5 attempts x 100-300ms jitter, well under a second of
+ * real contention, and the whole wait is smaller than the dedup window that bounds what a lost disarm
+ * costs. */
+const DISARM_LOCK_ATTEMPTS = 5;
+
+function lockPathFor(triggersPath) {
+	return `${triggersPath}.lock`;
+}
+
+/**
+ * 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.
+ */
+function takeLock(triggersPath, fs, log) {
+	const lock = lockPathFor(triggersPath);
+	let sweptAgeMs = null;
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try {
+			const fd = fs.openSync(lock, "wx"); // exclusive create IS the lock; no daemon, no lease
+			// Logged only AFTER the retake create succeeded: the unlink alone proves nothing (a rival
+			// sweeper may win the recreate race), and a takeover log for a lock we did not get would
+			// send an operator reading a history that never happened.
+			if (sweptAgeMs !== null) log("triggers_lock_stale_taken", { ageMs: sweptAgeMs });
+			return fd;
+		} catch (err) {
+			if (err?.code !== "EEXIST") throw err;
+			let mtimeMs;
+			try {
+				mtimeMs = fs.statSync(lock).mtimeMs;
+			} catch {
+				// 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
+			try {
+				fs.unlinkSync(lock);
+			} catch {
+				// Someone else swept it first; the retry create answers who won.
+			}
+			sweptAgeMs = Math.round(Date.now() - mtimeMs);
+		}
+	}
+	return null;
+}
+
+function releaseLock(fd, triggersPath, fs, log) {
+	fs.closeSync(fd);
+	try {
+		fs.unlinkSync(lockPathFor(triggersPath));
+	} catch {
+		// A leaked lock delays writers by LOCK_STALE_MS, then the takeover clears it. Logged, never
+		// thrown -- the session-store rule.
+		log("triggers_lock_stuck", {});
+	}
+}
+
+/** 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`;
+}
+
+/** tmp + rename with writeOverlay's single EPERM retry (a Windows AV/indexer briefly holding the
+ * destination); a second EPERM, and every other fs failure, propagates to the caller's contract. */
+function renameIntoPlace(fs, tmp, dest) {
+	try {
+		fs.renameSync(tmp, dest);
+	} catch (err) {
+		if (err?.code !== "EPERM") throw err;
+		fs.renameSync(tmp, dest); // single retry: the AV/indexer lock is transient
+	}
+}
+
+let tmpSeq = 0;
+
+/**
+ * A PER-WRITER tmp name, not the fixed `.tmp` the admin writer used to share. With one writer the
+ * fixed name was self-cleaning and harmless; with two authors it quietly voided the atomicity claim
+ * in the one window the lock concedes (the stale-takeover double-take): two writers sharing one tmp
+ * path means B can rename A's half-flushed tmp over the destination, and "a watcher never observes a
+ * half-written file" stops being true precisely when it matters. A pid+sequence name gives each
+ * write its own inode, so the rename is atomic no matter who else is mid-write. The cost is that a
+ * crash between write and rename leaves a uniquely-named straggler instead of one that the next
+ * write overwrites -- so both writers unlink their tmp on the failure path.
+ */
+function tmpPathFor(triggersPath) {
+	return `${triggersPath}.${process.pid}.${tmpSeq++}.tmp`;
+}
+
+/** Best-effort cleanup of this writer's own tmp after a failed write; the file either renamed away
+ * (unlink finds nothing, fine) or must not be left as litter. Never throws over the real failure. */
+function discardTmp(fs, tmp) {
+	try {
+		fs.unlinkSync(tmp);
+	} catch {
+		// Already renamed, or never written: either way there is nothing to clean.
+	}
+}
+
+/**
+ * Read-modify-write the triggers file under the lock. `mutate` receives the RAW entries (shallow
+ * copies) and returns the next raw array; the result is validated through the loaders' own
+ * `parseTriggers` -- never write a file they would reject -- and written atomically (tmp + rename) so
+ * a live-reload watcher never observes a half-written file.
+ *
+ * Human-approved writes only on the console path: reached from the operator-typed `/dispatch trigger
+ * ...` handlers and from the `dispatch_trigger_*` tools behind `confirmedWrite`'s dialog, so the
+ * 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.
+ */
+export function writeTriggers({ triggersPath, mutate, fs = nodeFs, log = () => {} }) {
+	const fd = takeLock(triggersPath, fs, log);
+	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.
+		return { invalid: `triggers file locked (another write in progress): ${lockPathFor(triggersPath)}` };
+	}
+	try {
+		let current = [];
+		try {
+			const raw = JSON.parse(fs.readFileSync(triggersPath, "utf8"));
+			if (Array.isArray(raw?.triggers)) current = raw.triggers;
+		} catch {
+			// Missing/invalid file: start from empty; the validated atomic write below repairs it.
+		}
+		const next = mutate(current.map((t) => ({ ...t })));
+		const text = serialize(next);
+		try {
+			parseTriggers(text, triggersPath); // 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 });
+			renameIntoPlace(fs, tmp, triggersPath);
+		} catch (err) {
+			discardTmp(fs, tmp);
+			throw err; // the writer's contract: fs failures throw
+		}
+		return { ok: true };
+	} finally {
+		releaseLock(fd, triggersPath, fs, log);
+	}
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Disarm ONE spent one-shot: add `on.disarmed = { at, jobId }` to the entry at `index`, and nothing
+ * else -- the worker's whole write authority over this file is this one added key, which is what lets
+ * OQ-008's "the file is the single write target" survive a second author (the worker can disarm what
+ * an operator armed; no machine path can ARM anything).
+ *
+ * The identity check compares EVERY field the job knows about the trigger it matched: `index` is
+ * positional and the file can change between enqueue and disarm, so the entry must still be an armed
+ * one-shot naming the exact item (`number`) and dispatching the exact `flow` or `command` the job
+ * carried. What the check confirms is therefore the matched ITEM and TARGET, not the trigger
+ * INSTANCE: an operator who deletes a spent-in-flight one-shot and re-arms an IDENTICAL one (same
+ * index, same number, same flow) inside the job's own run window has re-armed something this writer
+ * cannot tell from the original, and the earlier job's disarm will spend it. That residual is
+ * named rather than closed because a per-trigger id is the thing the design rejects -- the raw index
+ * IS the identity (`INT-TRIGGERS-FILE-CONTRACT`) -- and every DIFFERING re-arm (other flow, other
+ * number, other shape) refuses loudly here.
+ *
+ * Returns `{ ok }`, `{ already }` (a sibling replica/redelivery won the race -- idempotent success,
+ * 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 = () => {} }) {
+	for (let attempt = 0; attempt < DISARM_LOCK_ATTEMPTS; attempt++) {
+		let fd;
+		try {
+			fd = takeLock(triggersPath, fs, log);
+		} catch (err) {
+			return { invalid: `triggers file lock failed (${err?.code ?? "lock-error"}): ${triggersPath}` };
+		}
+		if (fd === null) {
+			await sleep(100 + Math.floor(Math.random() * 200));
+			continue;
+		}
+		try {
+			let raw;
+			try {
+				raw = JSON.parse(fs.readFileSync(triggersPath, "utf8"));
+			} 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}` };
+			}
+			const entries = Array.isArray(raw?.triggers) ? raw.triggers : null;
+			const entry = entries?.[index];
+			if (!entry || typeof entry !== "object") {
+				return { invalid: `no trigger at index ${index} -- the file changed since this job matched; not disarming a stranger` };
+			}
+			if (entry.on?.once !== true) {
+				return { invalid: `trigger at index ${index} is not an armed one-shot -- the file changed since this job matched; not disarming a stranger` };
+			}
+			if (entry.on?.number !== number) {
+				return { invalid: `trigger at index ${index} names item #${entry.on?.number}, this job matched #${number} -- a re-attributed index refuses rather than disarming a stranger` };
+			}
+			// Compared only when the caller supplied one, and BOTH lanes checked when it did: a job
+			// carries exactly one of flow/command, and the entry must agree on which lane as well as
+			// the name -- a flow job must not spend a command one-shot that took the same slot.
+			if (flow !== undefined && (entry.run?.flow !== flow || entry.run?.command !== undefined)) {
+				return { invalid: `trigger at index ${index} does not dispatch flow ${JSON.stringify(flow)} -- the entry changed since this job matched; not disarming a stranger` };
+			}
+			if (command !== undefined && (entry.run?.command !== command || entry.run?.flow !== undefined)) {
+				return { invalid: `trigger at index ${index} does not dispatch command ${JSON.stringify(command)} -- the entry changed since this job matched; not disarming a stranger` };
+			}
+			if (entry.on.disarmed !== undefined) {
+				return { already: true };
+			}
+			entry.on.disarmed = { at, ...(jobId !== undefined && { jobId }) };
+			const text = serialize(entries);
+			try {
+				parseTriggers(text, triggersPath); // the shared validator, same rule as every write
+			} catch (e) {
+				return { invalid: e?.message ?? String(e) };
+			}
+			const tmp = tmpPathFor(triggersPath);
+			try {
+				fs.writeFileSync(tmp, text, { mode: 0o644 });
+				renameIntoPlace(fs, tmp, triggersPath);
+			} catch (err) {
+				discardTmp(fs, tmp);
+				return { invalid: `triggers file write failed (${err?.code ?? "write-error"}): ${triggersPath}` };
+			}
+			return { ok: true };
+		} finally {
+			releaseLock(fd, triggersPath, fs, log);
+		}
+	}
+	return { invalid: `triggers file locked after ${DISARM_LOCK_ATTEMPTS} attempts: ${lockPathFor(triggersPath)}` };
+}
+
+/**
+ * The pre-spend read (worker slice of #231): what does the FILE currently say about the one-shot at
+ * `index`? Fail-open by design -- the caller refuses a job only on POSITIVE disarmed evidence, so
+ * "unknown" (unreadable file, index gone, entry no longer a one-shot) means "run": a broken read must
+ * never wedge every once job, and the identity mismatch cases are the disarm writer's to refuse.
+ */
+/**
+ * The post-record disarm hook (issue #231): wired around the worker's one recordRun funnel, called
+ * strictly AFTER writeRecord returns, for EVERY record -- completed, policy, and per-attempt failed
+ * alike, because "fired" means "produced a run record" (the issue's own definition) and the
+ * pre-spend check's own-jobId exception is what keeps BullMQ's second attempt of the same delivery
+ * runnable. NEVER throws and never rejects: a disarm failure is a loud log line, not a crashed
+ * record path.
+ *
+ * `triggersPath` may be null only when even the cwd fallback could not be formed; the caller
+ * resolves `PI_TRIGGERS_FILE ?? join(cwd, "triggers.json")` -- doctor's own precedent, NOT the
+ * worker config's `triggersFile` (whose null means "cron disabled" and must keep meaning that;
+ * under that knob the DEFAULT single-host deployment would have a firing receiver and a worker
+ * that can neither disarm nor pre-spend-check).
+ */
+export function makeDisarmOnce({ triggersPath, fs = nodeFs, log = () => {}, disarm = disarmTrigger }) {
+	return async function disarmOnce({ job, endedAt }) {
+		try {
+			const matched = job?.data?.trigger?.matched;
+			if (matched?.once !== true) return; // every unflagged job takes zero new code paths
+			const triggerIndex = matched.index ?? null;
+			if (typeof triggersPath !== "string" || triggersPath === "") {
+				log("trigger_disarm_unavailable", { jobId: job?.id ?? null, triggerIndex, reason: "triggers file unresolvable" });
+				return;
+			}
+			// The identity the writer re-checks: the item number (the issue shape carries it on matched,
+			// the PR shape on the target) and the dispatch lane the job actually carried.
+			const number = matched.number ?? job?.data?.target?.number;
+			const res = await disarm({
+				triggersPath,
+				index: matched.index,
+				number,
+				flow: job?.data?.flow,
+				command: job?.data?.command,
+				jobId: job?.id,
+				at: endedAt,
+				fs,
+				log,
+			});
+			if (res.ok) log("trigger_disarmed", { jobId: job?.id ?? null, triggerIndex });
+			else if (res.already) log("trigger_already_disarmed", { jobId: job?.id ?? null, triggerIndex });
+			else log("trigger_disarm_failed", { jobId: job?.id ?? null, triggerIndex, reason: res.invalid });
+		} catch (err) {
+			// Unreachable by construction (disarmTrigger never throws), kept because this hook sits on
+			// the record path and a record must never be lost to bookkeeping.
+			log("trigger_disarm_failed", { jobId: job?.id ?? null, triggerIndex: job?.data?.trigger?.matched?.index ?? null, reason: err?.code ?? "disarm-error" });
+		}
+	};
+}
+
+/**
+ * The pre-spend check's factory (issue #231): `(job, { queueJobId }) => { ok } | { refused, at, jobId }`.
+ * 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
+ * attempts:1 for every once job). A hand-written mark carries no jobId and reads as foreign, which
+ * is exactly what an operator disarming by hand intends. Everything else -- unreadable file, index
+ * 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.
+ */
+export function makeCheckOnceSpent({ triggersPath, fs = nodeFs }) {
+	return async function checkOnceSpent(job, { queueJobId } = {}) {
+		if (typeof triggersPath !== "string" || triggersPath === "") return { ok: true };
+		const matched = job?.trigger?.matched;
+		const state = readDisarmState({
+			triggersPath,
+			index: matched?.index,
+			number: matched?.number ?? job?.target?.number,
+			flow: job?.flow,
+			command: job?.command,
+			fs,
+		});
+		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 };
+	};
+}
+
+export function readDisarmState({ triggersPath, index, number, flow, command, fs = nodeFs }) {
+	let raw;
+	try {
+		raw = JSON.parse(fs.readFileSync(triggersPath, "utf8"));
+	} catch (err) {
+		return { state: "unknown", reason: err?.code ?? "parse-error" };
+	}
+	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" };
+	}
+	// The disarm writer's identity fields, folded to "unknown" rather than refused: a re-armed
+	// DIFFERENT one-shot at this index is not spent, so the fail-open answer -- run -- is the true one.
+	if (flow !== undefined && (entry.run?.flow !== flow || entry.run?.command !== undefined)) {
+		return { state: "unknown", reason: "entry-changed" };
+	}
+	if (command !== undefined && (entry.run?.command !== command || entry.run?.flow !== undefined)) {
+		return { state: "unknown", reason: "entry-changed" };
+	}
+	if (entry.on.disarmed !== undefined) {
+		const d = entry.on.disarmed;
+		return { state: "disarmed", at: typeof d?.at === "string" ? d.at : null, jobId: typeof d?.jobId === "string" ? d.jobId : null };
+	}
+	return { state: "armed" };
+}

package/src/triggers.mjs

@@ -1,7 +1,7 @@
 /**
  * Shared trigger-file schema + validator (issue #20). One `triggers.json` of `{ on, run }` entries is
  * the single reviewed source of standing triggers for BOTH services: the worker owns `on.type:"cron"`
- * (local jobs), the receiver owns the webhook types (`label|comment|pull_request` -> a forge job). Each
+ * (local jobs), the receiver owns the webhook types (`label|comment|pull_request|issue` -> a forge job). Each
  * service validates the WHOLE file, then selects the `on.type` it owns, so a malformed file fails both
  * identically and the two cannot drift.
  *
@@ -24,10 +24,25 @@
  */
 
 import { EGRESS_ENV_VARS, WORKER_ONLY_SECRET_VARS, configError } from "./config.mjs";
+// SKILL_NAME_RE is the single-sourced skill charset (flow-gate exports it for exactly this reason:
+// materialize.mjs and the admin already import it, and a keep-in-sync copy would drift where a
+// traversal guard cannot). flow-gate's module body is import-inert, so this keeps parseTriggers pure.
+import { SKILL_NAME_RE } from "./flow-gate.mjs";
 import { FORGE_HOST_VARS, FORGE_KINDS, MINTED_TOKEN_VARS, RUN_KINDS, forgeSpec, isForgeKind } from "./forges.mjs";
 import { CONTAINER_ENV_NAMES } from "./reserved-env.mjs";
 
-const ON_TYPES = new Set(["cron", "label", "comment", "pull_request"]);
+const ON_TYPES = new Set(["cron", "label", "comment", "pull_request", "issue"]);
+
+/**
+ * The `on.type` a DISARMED one-shot normalizes to (issue #231). Producible only by this validator:
+ * `ON_TYPES` excludes it, so an authored `on.type: "disarmed"` refuses like any unknown type. The
+ * sentinel keeps the entry's raw array position (deleting it would shift `triggerIndex` attribution
+ * for every later entry) while making it unmatchable BY CONSTRUCTION -- it carries no selectors, no
+ * actions, no run.kind and no flow, so no receiver group, no schedule and no flow allowlist can ever
+ * pick it up. A marker flag on the original type was rejected: one consumer forgetting to check it
+ * is a spent one-shot firing again, and this shape makes that bug unwritable.
+ */
+export const DISARMED_TYPE = "disarmed";
 
 // `RUN_KINDS` and `FORGE_KINDS` come from the forge table (forges.mjs) rather than being written out
 // here. They differ by exactly `local`, and that difference IS the on x run matrix below: a webhook
@@ -41,8 +56,17 @@ export { FORGE_KINDS };
  * what their forge's documentation says and can grep for it there.
  *
  * GitLab has no `labeled`: adding a label to a merge request arrives as `update` carrying a
- * `changes.labels` diff, and `open`/`reopen` are its spellings of `opened`/`reopened`. `merge` and
- * `close` are omitted on purpose: a job started by a merge or a close has nothing left to act on.
+ * `changes.labels` diff, and `open`/`reopen` are its spellings of `opened`/`reopened`.
+ *
+ * The close words (issue #231) carry a distinction the old "nothing left to act on" wording folded
+ * flat. A job ABOUT the closed thing still has nothing left to act on, and `run.replicas`' neighbour
+ * refusal still stands; what a close CAN do is release separately-armed work -- an operator wrote
+ * "when this closes, run that" into this file, and the close is the starting gun, not the subject.
+ * So `closed`/`close` are close-ONLY action lists (mixing them with other actions is refused below:
+ * the two families gate on different actors), while `merge` stays omitted everywhere -- GitHub and
+ * Forgejo emit `closed` for a merged PR so close rules cover merges there, and GitLab's `merge` is
+ * its own action no rule takes (an explicit close is what fires a GitLab close rule; the spec names
+ * the gap).
  *
  * `review_submitted` (issue #66) is github's fifth and the one compound word here. It names the
  * `pull_request_review` event's `submitted` action, so both halves are greppable in GitHub's own docs, the
@@ -53,23 +77,61 @@ export { FORGE_KINDS };
  * `author_association`, never the PR author's -- see filter.mjs and CONST-TRIGGER-AUTHOR-GATE.
  */
 const PR_ACTIONS = {
-	github: new Set(["labeled", "opened", "synchronize", "reopened", "review_submitted"]),
+	github: new Set(["labeled", "opened", "synchronize", "reopened", "review_submitted", "closed"]),
 	// GitLab's `approved` is its review gate (a member approved the MR). It is NOT github's
 	// `review_submitted` renamed: `approved` is one verdict, `review_submitted` is every verdict, which is
-	// what `on.reviewState` below exists to narrow.
-	gitlab: new Set(["open", "update", "reopen", "approved"]),
+	// what `on.reviewState` below exists to narrow. `close` is GitLab's own spelling of the close action.
+	gitlab: new Set(["open", "update", "reopen", "approved", "close"]),
 	// Forgejo's own spellings. `label_updated` is its `labeled` and `synchronized` its `synchronize` -- a
 	// one-letter difference that an operator would otherwise discover as a trigger that loads clean and
 	// never fires. `label_cleared` is deliberately ABSENT and always will be: REMOVING a label must never
 	// start a paid run, and it has no GitHub counterpart to inherit that rule from.
-	forgejo: new Set(["label_updated", "opened", "synchronized", "reopened"]),
+	forgejo: new Set(["label_updated", "opened", "synchronized", "reopened", "closed"]),
 	// Azure's Service Hook events reduced to the two that leave something to act on. `git.pullrequest.merged`
-	// is omitted for the same reason GitLab's `merge` and `close` are: a job started by a merge has nothing
-	// left to do. There is no label action at all -- Azure attaches tags to WORK ITEMS, never to pull
-	// requests -- which is why azure's `prLabelAction` is null and a predicated PR rule is refused below.
+	// is omitted for the reason the close words' own comment above records, and there is no close word here at
+	// all: an abandon arrives as `git.pullrequest.updated` with nothing in the projected subset to tell it from
+	// any other update, so an azure close rule could only ever fire on the wrong events or never. Widening
+	// INT-AZURE-PAYLOAD-SUBSET (a PR status field) is the gap to close before this set can grow. There is no
+	// label action either -- Azure attaches tags to WORK ITEMS, never to pull requests -- which is why azure's
+	// `prLabelAction` is null and a predicated PR rule is refused below.
 	azure: new Set(["created", "updated"]),
 };
 
+/**
+ * The one action per forge that closes a pull request, in that forge's own words (issue #231). Spelled
+ * once because three places turn on it: the close-only refusal in `normalizePullRequest` (a close rule
+ * gates on the CLOSER's write access, every other PR rule gates on the author's association or a
+ * collaborator's label, and one rule cannot gate on two different actors), the `capable` switch that
+ * admits `on.number`/`on.once` there, and the queue's semantic-key discriminant. Azure is absent for
+ * the subset reason the table above records, so `PR_ACTIONS.azure` simply never grows the word and the
+ * existing vocabulary refusal names azure on its own.
+ *
+ * EXPORTED for the two consumers that must never re-derive it: the receiver's grouping (a close-only
+ * rule routes through the close gate, every other PR rule through the author gate, and the split must
+ * be THIS table's) and the queue's semantic-key discriminant (a matched close action word is what
+ * marks a close job).
+ */
+export const PR_CLOSE_ACTIONS = { github: "closed", gitlab: "close", forgejo: "closed" };
+
+/**
+ * The `issue` action vocabulary, per forge, in each forge's own words (issue #231). One word each so
+ * far: the type exists for "when issue #40 closes, run deploy", and every other issue event already
+ * has a home (`label` for label predicates, `comment` for phrases). GitLab's word is `close` (its
+ * `object_attributes.action`), GitHub's and Forgejo's is `closed`.
+ *
+ * Azure is REFUSED rather than absent-and-unhandled, with its own message: a work item's close is a
+ * `System.State` transition whose terminal names vary by process template (Agile "Closed", Scrum
+ * "Done", plus "Resolved"), and the projected subset carries only `System.Tags` -- so matching a
+ * close needs both an INT-AZURE-PAYLOAD-SUBSET widening and a state vocabulary this version does not
+ * guess at. Not yet covered, not impossible -- validateResumeFlag's distinction, kept for the same
+ * reason.
+ */
+const ISSUE_ACTIONS = {
+	github: new Set(["closed"]),
+	gitlab: new Set(["close"]),
+	forgejo: new Set(["closed"]),
+};
+
 /**
  * The verdicts a submitted GitHub review can carry, in the webhook's own (lower-case) spelling, and the
  * vocabulary of the optional `on.reviewState` narrowing (issue #66).
@@ -175,8 +237,12 @@ function normalizeTrigger(entry, index, path, state) {
 	if (run === null || typeof run !== "object") {
 		throw configError(`${at}: "run" must be an object: ${path}`);
 	}
+	// Joined from the set for the joined-vocabulary rule stated over the run.kind check below -- a type
+	// added to the vocabulary can never be
+	// refused by a message that does not mention it. This is also what keeps `DISARMED_TYPE` refused
+	// when authored: it is deliberately not in ON_TYPES, so it reads here as any other unknown type.
 	if (!ON_TYPES.has(on.type)) {
-		throw configError(`${at}: on.type must be one of cron|label|comment|pull_request (got ${JSON.stringify(on.type)}): ${path}`);
+		throw configError(`${at}: on.type must be one of ${[...ON_TYPES].join("|")} (got ${JSON.stringify(on.type)}): ${path}`);
 	}
 	// The legal-values half of every message below is JOINED from the table rather than typed out, so a
 	// forge added to the table can never be refused by a message that does not mention it -- which reads
@@ -195,9 +261,18 @@ function normalizeTrigger(entry, index, path, state) {
 	if (!isForgeKind(run.kind)) {
 		throw configError(`${at}: a ${on.type} trigger is webhook-driven and produces a forge job; run.kind must be one of ${FORGE_KINDS.join("|")} (got ${JSON.stringify(run.kind)}): ${path}`);
 	}
-	if (on.type === "label") return normalizeLabel(on, run, index, path);
-	if (on.type === "comment") return normalizeComment(on, run, index, path, state);
-	return normalizePullRequest(on, run, index, path);
+	let normalized;
+	if (on.type === "label") normalized = normalizeLabel(on, run, index, path);
+	else if (on.type === "comment") normalized = normalizeComment(on, run, index, path, state);
+	else if (on.type === "issue") normalized = normalizeIssue(on, run, index, path);
+	else normalized = normalizePullRequest(on, run, index, path);
+
+	// A disarmed one-shot has validated IN FULL above (a disarmed entry with a malformed run still
+	// refuses the file -- writeTriggers' fail-closed contract needs the whole file valid, and the
+	// worker's disarm only ever ADDS one key to an entry that already passed). Only then does it
+	// normalize to the sentinel, so its raw index survives and nothing downstream can match it.
+	if (on.disarmed !== undefined) return { on: { type: DISARMED_TYPE }, run: {} };
+	return normalized;
 }
 
 function normalizeCron(on, run, index, path, state) {
@@ -264,6 +339,10 @@ function normalizeCron(on, run, index, path, state) {
 	// Called and DISCARDED: on a cron trigger this can only refuse, and the refusal is the point. The
 	// returned `run` below deliberately grows no `replicas` key -- a cron entry can never carry one.
 	validateReplicas(run, `cron trigger "${id}"`, path);
+	// Same posture for the close-trigger fields (issue #231): none has a legal value on cron.
+	validateNumber(on, `cron trigger "${id}"`, path, { onType: "cron" });
+	validateOnce(on, run, `cron trigger "${id}"`, path, { onType: "cron" });
+	validateDisarmed(on, `cron trigger "${id}"`, path, { onType: "cron" });
 	const secrets = validateSecrets(run, `cron trigger "${id}"`, path);
 	const secretsProfile = validateSecretsProfile(run, `cron trigger "${id}"`, path);
 
@@ -600,6 +679,122 @@ function validatePredicate(on, index, path, requirePositive) {
 	return { any: on.any, all: on.all, none: on.none };
 }
 
+/**
+ * `on.number` -- narrow a close-capable trigger to ONE item, by the number the forge itself assigns
+ * (issue #231). Legal with or without `on.once`: a standing "every close of #40" rule is coherent
+ * narrowing, exactly as `on.reviewState` narrows without changing what the rule is. Called from ALL
+ * normalizers, `validateReplicas`' posture -- where it cannot apply it refuses, never ignores.
+ * `capable` is passed only by the close-capable paths (the `issue` normalizer, and a `pull_request`
+ * rule whose only action is the forge's close word).
+ */
+function validateNumber(on, at, path, { capable = false, onType } = {}) {
+	const number = on.number;
+	if (number === undefined) return undefined;
+	if (!capable) {
+		if (onType === "cron") {
+			throw configError(`${at}: on.number is not available on a cron trigger -- a schedule fires on time, not on an item, so there is no delivery for a number to narrow: ${path}`);
+		}
+		throw configError(`${at}: on.number is not yet covered for ${onType} triggers here -- only the close routes read it, so on a rule they never serve it would sit in the file looking configured; narrowing labels, comments or non-close pull_request rules is a gap to close, not a limit: ${path}`);
+	}
+	if (!Number.isInteger(number) || number < 1) {
+		throw configError(`${at}: on.number must be an integer >= 1 when present -- the item number the forge itself assigns (on GitLab, the iid) (got ${JSON.stringify(number)}): ${path}`);
+	}
+	return number;
+}
+
+/**
+ * `on.once` -- a one-shot: the trigger fires, produces a run record, and the worker disarms it by
+ * adding `on.disarmed` to this entry (issue #231, DES-ONE-SHOT-DISARM-IN-THE-FILE). Strictly boolean
+ * and fail-loud, the house rule; `false` is legal and carried, validateResumeFlag's argument -- an
+ * operator who wrote down today's default must not be refused for stating present behaviour.
+ *
+ * `once: true` REQUIRES `on.number`, and the requirement is a race analysis, not taste: a numberless
+ * one-shot matched by two different items' closes inside one dedup window enqueues both before either
+ * disarm lands, and which item "spent" the trigger is a coin flip. With a number, concurrent
+ * duplicates are duplicates of the SAME item, which is what the delivery GUID and the semantic window
+ * actually bound -- and the number is the identity the disarm re-checks before it writes, so a file
+ * edited between enqueue and disarm refuses loudly instead of disarming a stranger.
+ *
+ * `once: true` is refused beside `run.replicas` (`false`, the written-down default, is not): "exactly
+ * one run" and "N sandboxes race" contradict on their face,
+ * and with N run records the disarm no longer says which one spent the trigger.
+ */
+function validateOnce(on, run, at, path, { capable = false, onType } = {}) {
+	const once = on.once;
+	if (once === undefined) return undefined;
+	if (!capable) {
+		if (onType === "cron") {
+			throw configError(`${at}: on.once is not available on a cron trigger -- a one-shot that can re-arm is a schedule, and a cron job carries no matched delivery for the disarm to name; delete the entry when the work is done: ${path}`);
+		}
+		// The close-word hint is JOINED from the table (the same rule the vocabulary messages follow), so a
+		// forge gaining a close word later can never be pointed away from it by a stale sentence here.
+		const closeWords = Object.entries(PR_CLOSE_ACTIONS).map(([k, w]) => `${k} has ${JSON.stringify(w)}`).join(", ");
+		throw configError(`${at}: on.once is not yet covered here -- the disarm writes back to the one entry a delivery matched, and only a close delivery names the single item that spends it; use on.type "issue", or a pull_request rule whose only action is the close word (${closeWords}; azure has no close trigger yet): ${path}`);
+	}
+	if (typeof once !== "boolean") {
+		throw configError(`${at}: on.once must be true or false when present -- a truthy string arming a one-shot is exactly the drift this validator exists to refuse (got ${JSON.stringify(once)}): ${path}`);
+	}
+	if (once === true && on.number === undefined) {
+		throw configError(`${at}: on.once requires on.number -- a one-shot without a named item is spent by whichever close arrives first, and two different items closing inside one dedup window would race for it; the number is also the identity the disarm re-checks before it writes: ${path}`);
+	}
+	if (once === true && run.replicas !== undefined) {
+		throw configError(`${at}: on.once and run.replicas cannot be combined -- "exactly one run" and "N sandboxes race" contradict, and with N run records the disarm no longer says which one spent the trigger: ${path}`);
+	}
+	return once;
+}
+
+/**
+ * `on.disarmed` -- the mark the worker writes when a one-shot fires: `{ at, jobId? }`, provenance an
+ * operator can read a year later when the run record is long reaped (issue #231). Hand-writable too
+ * (jobId optional), which is how an operator disarms deliberately; deleting the key is how they
+ * re-arm. The entry it sits on normalizes to the DISARMED_TYPE sentinel -- see normalizeTrigger --
+ * but only AFTER this shape check and the full entry validation pass, so a corrupted disarm mark is
+ * a load refusal, never a silently-still-armed rule.
+ */
+function validateDisarmed(on, at, path, { capable = false, onType } = {}) {
+	const disarmed = on.disarmed;
+	if (disarmed === undefined) return undefined;
+	if (!capable) {
+		throw configError(`${at}: on.disarmed marks a spent one-shot, and on.once is not ${onType === "cron" ? "available on a cron trigger" : "yet covered here"}, so there is nothing this entry could have spent: ${path}`);
+	}
+	if (disarmed === null || typeof disarmed !== "object" || Array.isArray(disarmed)) {
+		throw configError(`${at}: on.disarmed must be an object with a non-empty string "at" (and optionally a non-empty string "jobId") -- the worker writes it when the one-shot fires, and a hand-written one disarms the entry deliberately (got ${JSON.stringify(disarmed)}): ${path}`);
+	}
+	for (const key of Object.keys(disarmed)) {
+		if (key !== "at" && key !== "jobId") {
+			throw configError(`${at}: on.disarmed has an unsupported key ${JSON.stringify(key)} (expected at|jobId): ${path}`);
+		}
+	}
+	if (!isNonEmptyString(disarmed.at)) {
+		throw configError(`${at}: on.disarmed.at must be a non-empty string (the time the one-shot fired): ${path}`);
+	}
+	if (disarmed.jobId !== undefined && !isNonEmptyString(disarmed.jobId)) {
+		throw configError(`${at}: on.disarmed.jobId must be a non-empty string when present (the run record it joins to): ${path}`);
+	}
+	if (on.once !== true) {
+		throw configError(`${at}: on.disarmed is only meaningful beside on.once: true -- an entry that was never a one-shot has nothing to spend: ${path}`);
+	}
+	return disarmed;
+}
+
+/**
+ * `run.flow` charset for the WEBHOOK kinds (issue #231). materialize.mjs refuses a name outside
+ * SKILL_NAME_RE at job start, AFTER the budget slot is reserved -- so until now a charset-invalid
+ * forge flow loaded clean and could only ever fail in-container (graph-model already renders it as
+ * the `charset-invalid` defect). Refusing at load turns that paid failure into a free one, and it is
+ * also what keeps `:` out of the flow slot of the queue's semantic dedup key, where the command jobs'
+ * `cmd:` prefix lives and the close jobs' discriminant sits beside it once close routing lands.
+ * Deliberately NOT called on cron:
+ * a local flow resolves inside the operator's own folder by pi itself, and the semantic key does not
+ * apply to repeat jobs -- narrowing there would refuse deployments this hazard cannot reach.
+ */
+function validateFlowName(run, at, path) {
+	if (run.flow === undefined) return;
+	if (!SKILL_NAME_RE.test(run.flow)) {
+		throw configError(`${at}: run.flow ${JSON.stringify(run.flow)} fails the skill-name charset (lowercase letters, digits, dash and underscore, 1-64 chars, starting and ending alphanumeric) -- a name outside it can never materialise, so this trigger could only ever fail after the budget slot was reserved: ${path}`);
+	}
+}
+
 
 /**
  * `run.repository` -- WHICH repository a job clones, for a forge whose trigger subject does not name one.
@@ -792,11 +987,15 @@ function validateSecretsProfile(run, at, path) {
 function normalizeLabel(on, run, index, path) {
 	const at = `trigger at index ${index}`;
 	const predicate = validatePredicate(on, index, path, true);
+	validateNumber(on, at, path, { onType: "label" });
+	validateOnce(on, run, at, path, { onType: "label" });
+	validateDisarmed(on, at, path, { onType: "label" });
 	// First among the run checks, before the flow-required check -- validateCommand says why.
 	const command = validateCommand(run, at, path, { onType: "label" });
 	if (command === undefined && !isNonEmptyString(run.flow)) {
 		throw configError(`${at}: label trigger run.flow must be a non-empty string (or use run.command): ${path}`);
 	}
+	validateFlowName(run, at, path);
 	const packages = validatePackagesFlag(run, at, path);
 	const image = validateImageRef(run, at, path);
 	const skillsDir = validateSkillsDir(run, at, path);
@@ -817,6 +1016,9 @@ function normalizeComment(on, run, index, path, state) {
 	if (!isNonEmptyString(on.phrase)) {
 		throw configError(`${at}: comment trigger on.phrase must be a non-empty string: ${path}`);
 	}
+	validateNumber(on, at, path, { onType: "comment" });
+	validateOnce(on, run, at, path, { onType: "comment" });
+	validateDisarmed(on, at, path, { onType: "comment" });
 	// First among the run checks, before the flow-required check -- validateCommand says why. A command
 	// trigger has NO default flow for the `<phrase> <flow>` comment override to replace; making that
 	// token inert is the receiver filter's job, not a shape this validator can see.
@@ -824,6 +1026,7 @@ function normalizeComment(on, run, index, path, state) {
 	if (command === undefined && !isNonEmptyString(run.flow)) {
 		throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string (or use run.command): ${path}`);
 	}
+	validateFlowName(run, at, path);
 	// At most one comment trigger PER FORGE. The cap exists because the receiver holds one comment rule
 	// per forge and a second would be silently unreachable -- so it is a cap on ambiguity, not on count,
 	// and a deployment serving GitHub and GitLab is entitled to the same `@pi` phrase on each.
@@ -846,6 +1049,78 @@ function normalizeComment(on, run, index, path, state) {
 	};
 }
 
+/**
+ * `on.type: "issue"` (issue #231): fire when an ISSUE's lifecycle action happens -- one word so far,
+ * the close. The type exists because every other issue event already has a home (`label` for label
+ * predicates, `comment` for phrases) and neither of those shapes fits a close: there is no label diff
+ * to match and no phrase to read, only an action, an item number, and the actor who performed it.
+ * A PULL REQUEST's close is deliberately NOT this type -- it rides `on.type: "pull_request"` as an
+ * action, the #66 rule (one forge's PR lifecycle must not be a type while another's is an action),
+ * and because GitLab and Azure number issues and merge/pull requests from SEPARATE sequences, a
+ * both-kinds type narrowed by `on.number` would be ambiguous exactly where a one-shot spending
+ * itself on the wrong #5 hurts most. Under the split, the type IS the discriminator.
+ */
+function normalizeIssue(on, run, index, path) {
+	const at = `trigger at index ${index}`;
+
+	// Kind first: on azure the whole TYPE is unsupported, and hearing that beats hearing that one
+	// action word is. See ISSUE_ACTIONS for why, and validateResumeFlag for the "not yet covered"
+	// vocabulary this reuses.
+	if (run.kind === "azure") {
+		throw configError(`${at}: an issue trigger is not yet covered for azure -- a work item's close is a System.State transition whose terminal names vary by process template (Agile "Closed", Scrum "Done"), and the projected subset carries only System.Tags, so nothing in the delivery says the item closed; widening the payload subset is the gap to close, not a limit: ${path}`);
+	}
+
+	const actions = on.action;
+	if (!Array.isArray(actions) || actions.length === 0) {
+		throw configError(`${at}: issue on.action must be a non-empty array: ${path}`);
+	}
+	// Validated against THIS entry's forge, in that forge's own words -- normalizePullRequest's rule.
+	const allowed = ISSUE_ACTIONS[run.kind];
+	const expected = [...allowed].join("|");
+	for (const a of actions) {
+		if (!allowed.has(a)) {
+			throw configError(`${at}: issue on.action has an unsupported ${run.kind} action ${JSON.stringify(a)} (expected ${expected}): ${path}`);
+		}
+	}
+
+	// The close route matches action and number alone, so a predicate here would be accepted-and-
+	// ignored -- the exact thing validateRepository's posture forbids. Refused, not dropped.
+	if (on.any !== undefined || on.all !== undefined || on.none !== undefined) {
+		throw configError(`${at}: an issue trigger cannot carry a label predicate -- it fires on a lifecycle action, not a label diff, so any/all/none could never match; a label-predicated rule is on.type "label": ${path}`);
+	}
+
+	const number = validateNumber(on, at, path, { capable: true, onType: "issue" });
+	const once = validateOnce(on, run, at, path, { capable: true, onType: "issue" });
+	validateDisarmed(on, at, path, { capable: true, onType: "issue" });
+
+	// First among the run checks, before the flow-required check -- validateCommand says why.
+	const command = validateCommand(run, at, path, { onType: "issue" });
+	if (command === undefined && !isNonEmptyString(run.flow)) {
+		throw configError(`${at}: issue trigger run.flow must be a non-empty string (or use run.command): ${path}`);
+	}
+	validateFlowName(run, at, path);
+	const packages = validatePackagesFlag(run, at, path);
+	const image = validateImageRef(run, at, path);
+	const skillsDir = validateSkillsDir(run, at, path);
+	const instructions = validateInstructions(run, at, path);
+	const resume = validateResumeFlag(run, at, path);
+	validateRepository(run, "issue", at, path);
+	const replicas = validateReplicas(run, at, path);
+	const secrets = validateSecrets(run, at, path);
+	const secretsProfile = validateSecretsProfile(run, at, path);
+	return {
+		on: {
+			type: "issue",
+			action: [...actions],
+			// Absent rather than present-and-undefined, reviewState's rule below: an unnarrowed rule's
+			// normalized shape must not grow keys.
+			...(number !== undefined && { number }),
+			...(once !== undefined && { once }),
+		},
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
+	};
+}
+
 function normalizePullRequest(on, run, index, path) {
 	const at = `trigger at index ${index}`;
 
@@ -863,6 +1138,16 @@ function normalizePullRequest(on, run, index, path) {
 		}
 	}
 
+	// The close-only split (issue #231). A close rule gates on the CLOSER's write access; every other
+	// PR action gates on the author's association or a collaborator-applied label. One rule cannot
+	// gate on two different actors, so a list mixing the close word with anything else is refused --
+	// which is also what lets the receiver group close rules separately without re-deriving this.
+	const closeWord = PR_CLOSE_ACTIONS[run.kind];
+	const isClose = closeWord !== undefined && actions.includes(closeWord);
+	if (isClose && actions.some((a) => a !== closeWord)) {
+		throw configError(`${at}: pull_request on.action cannot mix ${JSON.stringify(closeWord)} with other actions -- a close rule is gated on the closer's write access and every other action on the author's, and one rule cannot gate on two different actors; split it into two entries: ${path}`);
+	}
+
 	const reviewState = validateReviewState(on, actions, run, at, path);
 
 	// A `labeled` PR trigger is gated by its label predicate (the collaborator-applied label is the
@@ -882,12 +1167,21 @@ function normalizePullRequest(on, run, index, path) {
 	if (run.kind === "azure" && (on.any !== undefined || on.all !== undefined || on.none !== undefined)) {
 		throw configError(`${at}: an azure pull_request trigger cannot carry a label predicate -- Azure DevOps attaches tags to work items, never to pull requests, so any/all/none could never match: ${path}`);
 	}
+	// A close-only rule reads no label diff either -- its route matches action and number alone -- so
+	// a predicate on it is normalizeIssue's refusal arriving on the PR side.
+	if (isClose && (on.any !== undefined || on.all !== undefined || on.none !== undefined)) {
+		throw configError(`${at}: a close pull_request rule cannot carry a label predicate -- the close route matches the action and on.number alone, so any/all/none would sit in the file looking configured and never match anything: ${path}`);
+	}
 	const predicate = validatePredicate(on, index, path, requirePositive);
+	const number = validateNumber(on, at, path, { capable: isClose, onType: "pull_request" });
+	const once = validateOnce(on, run, at, path, { capable: isClose, onType: "pull_request" });
+	validateDisarmed(on, at, path, { capable: isClose, onType: "pull_request" });
 	// First among the run checks, before the flow-required check -- validateCommand says why.
 	const command = validateCommand(run, at, path, { onType: "pull_request" });
 	if (command === undefined && !isNonEmptyString(run.flow)) {
 		throw configError(`${at}: pull_request trigger run.flow must be a non-empty string (or use run.command): ${path}`);
 	}
+	validateFlowName(run, at, path);
 	const packages = validatePackagesFlag(run, at, path);
 	const image = validateImageRef(run, at, path);
 	const skillsDir = validateSkillsDir(run, at, path);
@@ -907,6 +1201,9 @@ function normalizePullRequest(on, run, index, path) {
 			any: predicate.any,
 			all: predicate.all,
 			none: predicate.none,
+			// Same rule for the close-narrowing pair (issue #231): only a close-only rule can carry them.
+			...(number !== undefined && { number }),
+			...(once !== undefined && { once }),
 		},
 		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
 	};