@edgehero/pi-dispatch 1.2.0 → 1.4.0

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.
  *
@@ -23,10 +23,26 @@
  * Custom: triggers validated inline per config.mjs/schedules.mjs precedent; zod not in deps
  */
 
-import { configError } from "./config.mjs";
-import { FORGE_KINDS, RUN_KINDS, forgeSpec, isForgeKind } from "./forges.mjs";
+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
@@ -40,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
@@ -52,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).
@@ -100,6 +163,41 @@ const ID_CHARSET = /^[A-Za-z0-9._-]+$/;
  */
 const REPLICAS_MAX = 3;
 
+/**
+ * The ceiling on how many references one trigger may name (issue #225). Not tidiness: the worker resolves
+ * them SEQUENTIALLY, before the container, each with its own timeout, so N references hold a
+ * `PI_CONCURRENCY` slot for up to N x PI_SECRET_RESOLVE_TIMEOUT_MS inside the job's own 30-minute kill
+ * timer. A cap at load turns an unbounded slot occupancy into a bounded one for free, before anything
+ * runs. It bounds the host argv too: every resolved value is pushed as `-e NAME=VALUE` (docker-run.mjs).
+ *
+ * Sixteen rather than three: unlike `REPLICAS_MAX` this multiplies no spend, and a deploy job legitimately
+ * wants a handful of credentials. A literal for REPLICAS_MAX's reason -- this validator is pure and fs-free.
+ */
+const SECRETS_MAX = 16;
+
+/**
+ * A POSIX environment variable name. Nothing in this repo validated one before `run.secrets` (checked), so
+ * this is the definition rather than a copy of one. Deliberately stricter than what `execve` would accept:
+ * a name is `-e NAME=VALUE` in the docker argv, so `=` would split in the wrong place, and the leading
+ * digit is excluded because a shell cannot expand `$1FOO` as that variable.
+ */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * The env variable names a trigger may NOT bind, and why each set is here.
+ *
+ * These are the STATICALLY KNOWABLE half. `parseTriggers` is pure, fs-free and env-free, so it cannot see
+ * the resolved provider's credential variable names (they come from `findEnvKeys(provider, hostEnv)`) or
+ * the deployment's `PI_FORWARD_ENV` list. Those two are refused PRE-SPEND in the processor, where both are
+ * in hand -- the same load-time / deployment-state split `run.resume` already makes against
+ * `PI_SESSIONS_DIR`. Refusing here what can be answered here keeps the file's own mistakes in the file's
+ * own error.
+ *
+ * Every set is IMPORTED, never retyped, which is the rule `sandbox.test.mjs` keeps for the same reason: a
+ * forge added to the table later must not need a second edit here to stay covered.
+ */
+const RESERVED_ENV_NAMES = new Set([...MINTED_TOKEN_VARS, ...FORGE_HOST_VARS, ...WORKER_ONLY_SECRET_VARS, ...EGRESS_ENV_VARS, ...CONTAINER_ENV_NAMES]);
+
 function isNonEmptyString(value) {
 	return typeof value === "string" && value.trim() !== "";
 }
@@ -139,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
@@ -159,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) {
@@ -228,6 +339,12 @@ 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);
 
 	// provider/model/maxTurns stay absent when omitted so the value resolves at job start against the
 	// settings overlay/env, not a default frozen here (INT-CONFIG-OVERLAY-CONTRACT). github/packages/image stay
@@ -236,7 +353,7 @@ function normalizeCron(on, run, index, path, state) {
 	// freeze today's default into every stored repeatable.
 	return {
 		on: { type: "cron", id, pattern },
-		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }) },
+		run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
 	};
 }
 
@@ -562,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.
@@ -635,14 +868,134 @@ function validateReplicas(run, at, path) {
 	return replicas;
 }
 
+/**
+ * `run.secrets` -- the env variables this trigger's job receives, and the opaque references an operator's
+ * own resolver turns into values (REQ-TRIGGER-SECRETS, issue #225).
+ *
+ * THE GRAMMAR OF THE VALUES IS NOT OURS. `op://vault/item/field`, `secret/data/ci#stripe` and a bare name
+ * are all valid here, because what parses them is a script the operator wrote and named in
+ * `PI_SECRET_PROFILES`. This file validates the SHAPE of the map and never the meaning of a reference --
+ * the posture #206 and #209 already set ("the seam is a command"), and the same one
+ * `DES-SERVICE-ENV-SETUP-SEAM` implements one layer up. A regex over `op://` here would bless a vendor.
+ *
+ * WHY EACH REFUSAL:
+ *   - not a plain object, or a value that is not a non-empty string. An array or a nested object is an
+ *     operator writing a different feature than the one that exists.
+ *   - more than SECRETS_MAX entries -- see that constant: it bounds a worker slot, not a preference.
+ *   - a key that is not an environment variable name. There is no downstream check: `-e NAME=VALUE` goes
+ *     into the docker argv as written, so a key with an `=` in it silently binds a different variable.
+ *   - a key in RESERVED_ENV_NAMES. The mint, the egress policy and the closed map all write AFTER this
+ *     feature does, so such a key would be accepted, overwritten, and the job would run without the value
+ *     it named on a clean exit 0. Ordering is the backstop; this is the refusal, which is the same
+ *     division of labour `PI_FORWARD_ENV` already keeps (config.mjs refuses the names, env-allowlist.mjs
+ *     orders the assignments so a slip cannot matter).
+ *   - a reference starting with `-`. It is passed as `argv[1]` of the resolver, where a leading dash
+ *     parses as a flag -- exactly `validateImageRef`'s reason for the same refusal on `run.image`. We do
+ *     NOT pass `--` before it instead: that would be a claim about the resolver's option parser, and the
+ *     option parser is the operator's.
+ *   - `run.resume: true`. `assertResumeAllowedOnGhSource` (get-token.mjs) already refuses the `gh` token
+ *     source for a resumed job, and states the argument this inherits whole: every property
+ *     CONST-TOKEN-SCOPED-PER-JOB relies on assumes the credential is an ENV VALUE that dies with the
+ *     container, while a persisted transcript is a FILE on host disk, replayed into the next job on that
+ *     key. A resolved vault value is an env value the agent can echo, and nothing here redacts a
+ *     transcript. Refused with NO escape hatch, unlike that one's PI_SESSIONS_ALLOW_GH_SOURCE: a pure
+ *     validator cannot read an env var to find one, and the reason is stronger anyway, since that refusal
+ *     complains a `gh` login is "full-scope and NON-EXPIRING" and a vault password does not expire either.
+ *
+ * Called from ALL FOUR normalizers, cron included. Unlike `run.replicas` this is NOT refused on a local
+ * job: nothing about resolving a secret is forge-specific, and a nightly deploy is the obvious user. The
+ * replica refusal turns on a local `/workspace` being the operator's own folder with no clone, which is a
+ * fact about two agents sharing a working tree, not about a credential. That folder does bring its own
+ * hazard (an agent that writes a credential into `.env` writes it into the operator's real repository),
+ * and `doctor` warns about exactly that rather than this validator refusing the use case outright.
+ *
+ * Returns the map, undefined when absent, so an unflagged trigger normalizes byte-identically.
+ */
+function validateSecrets(run, at, path) {
+	const secrets = run.secrets;
+	if (secrets === undefined) return undefined;
+	if (secrets === null || typeof secrets !== "object" || Array.isArray(secrets)) {
+		throw configError(`${at}: run.secrets must be an object mapping environment variable names to references when present (got ${JSON.stringify(secrets)}): ${path}`);
+	}
+	const names = Object.keys(secrets);
+	if (names.length === 0) {
+		throw configError(`${at}: run.secrets is empty -- an empty map is a field that does nothing, and this trigger reads as though it binds a secret: ${path}`);
+	}
+	if (names.length > SECRETS_MAX) {
+		throw configError(`${at}: run.secrets names ${names.length} variables, over the ${SECRETS_MAX} cap -- each one is resolved before the container starts, holding a concurrency slot while it runs: ${path}`);
+	}
+	for (const name of names) {
+		if (!ENV_NAME.test(name)) {
+			throw configError(`${at}: run.secrets key ${JSON.stringify(name)} is not an environment variable name (letters, digits and underscore, not starting with a digit): ${path}`);
+		}
+		if (RESERVED_ENV_NAMES.has(name)) {
+			throw configError(`${at}: run.secrets key ${JSON.stringify(name)} is a variable the worker sets itself -- the job container would receive the worker's value, not this trigger's, and the trigger would look like it worked: ${path}`);
+		}
+		const reference = secrets[name];
+		if (!isNonEmptyString(reference)) {
+			throw configError(`${at}: run.secrets.${name} must be a non-empty string reference for your resolver to read (got ${JSON.stringify(reference)}): ${path}`);
+		}
+		if (reference !== reference.trim()) {
+			throw configError(`${at}: run.secrets.${name} must not have leading or trailing whitespace -- the file is the reviewed artifact and silently trimming it would make the file disagree with what the resolver is asked for: ${path}`);
+		}
+		if (reference.startsWith("-")) {
+			throw configError(`${at}: run.secrets.${name} must not start with "-" -- it is passed as the resolver's first argument, where a leading dash parses as a flag: ${path}`);
+		}
+	}
+	if (run.resume === true) {
+		throw configError(`${at}: run.secrets and run.resume cannot be combined -- a resumed job replays a transcript kept on host disk, and any command the agent ran that echoed a resolved value wrote it into that transcript, which is then prefilled into every later job on the same key: ${path}`);
+	}
+	return { ...secrets };
+}
+
+/**
+ * `run.secretsProfile` -- WHICH of the operator's declared resolvers reads this trigger's references.
+ *
+ * A NAME, never a path, and that distinction is the whole reason this field is allowed to exist.
+ * `DES-SERVICE-ENV-SETUP-SEAM` rejected "making this reachable from configuration, which would turn a
+ * boot-time root-adjacent exec into something a trigger file could name". A profile name selects among
+ * execs the operator already declared in `PI_SECRET_PROFILES`; it cannot introduce one, cannot name a
+ * path, and cannot reach a script nobody wired. The rejected thing is a trigger file NAMING an exec.
+ *
+ * The charset is `ID_CHARSET`, shared with cron ids, for two reasons that both bite: the name is echoed in
+ * a refusal that `comment` posts PUBLICLY on the issue, and `PI_SECRET_PROFILES` is a `,`-separated list
+ * of `name:path` pairs, so a name containing either separator could not round-trip through the very
+ * variable that declares it.
+ *
+ * WHETHER the named profile exists is NOT checked here and cannot be: which profiles a deployment declares
+ * is env and overlay state, and this validator is pure and fs-free. That is refused pre-spend, per
+ * delivery, as `secret-profile-unknown` -- the same split `run.resume` makes against `PI_SESSIONS_DIR`,
+ * where the file answers what the file knows and `doctor` plus a per-delivery refusal carry the rest.
+ *
+ * Absent selects the profile named `default`, so a single-manager deployment never writes the field.
+ */
+function validateSecretsProfile(run, at, path) {
+	const profile = run.secretsProfile;
+	if (profile === undefined) return undefined;
+	if (!isNonEmptyString(profile)) {
+		throw configError(`${at}: run.secretsProfile must be a non-empty string naming one of the resolver profiles this deployment declares (got ${JSON.stringify(profile)}): ${path}`);
+	}
+	if (!ID_CHARSET.test(profile)) {
+		throw configError(`${at}: run.secretsProfile ${JSON.stringify(profile)} may use letters, digits, dot, dash and underscore only -- PI_SECRET_PROFILES is a comma-separated list of name:path pairs, so a name carrying either separator cannot be declared: ${path}`);
+	}
+	if (run.secrets === undefined) {
+		throw configError(`${at}: run.secretsProfile is set but run.secrets names nothing -- a profile that resolves no references is a field that does nothing: ${path}`);
+	}
+	return profile;
+}
+
 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);
@@ -650,9 +1003,11 @@ function normalizeLabel(on, run, index, path) {
 	const resume = validateResumeFlag(run, at, path);
 	const repository = validateRepository(run, "label", at, path);
 	const replicas = validateReplicas(run, at, path);
+	const secrets = validateSecrets(run, at, path);
+	const secretsProfile = validateSecretsProfile(run, at, path);
 	return {
 		on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
 	};
 }
 
@@ -661,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.
@@ -668,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.
@@ -682,9 +1041,83 @@ function normalizeComment(on, run, index, path, state) {
 	const resume = validateResumeFlag(run, at, path);
 	const repository = validateRepository(run, "comment", at, path);
 	const replicas = validateReplicas(run, at, path);
+	const secrets = validateSecrets(run, at, path);
+	const secretsProfile = validateSecretsProfile(run, at, path);
 	return {
 		on: { type: "comment", phrase: on.phrase },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
+	};
+}
+
+/**
+ * `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 }) },
 	};
 }
 
@@ -705,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
@@ -724,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);
@@ -737,6 +1189,8 @@ function normalizePullRequest(on, run, index, path) {
 	const resume = validateResumeFlag(run, at, path);
 	validateRepository(run, "pull_request", at, path);
 	const replicas = validateReplicas(run, at, path);
+	const secrets = validateSecrets(run, at, path);
+	const secretsProfile = validateSecretsProfile(run, at, path);
 	return {
 		on: {
 			type: "pull_request",
@@ -747,8 +1201,11 @@ 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 }) },
+		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 }) },
 	};
 }