@edgehero/pi-dispatch 1.5.0 → 1.6.1

package/.env.example

@@ -102,6 +102,25 @@ PI_JOB_IMAGE=pi-job:latest          # the DEFAULT job image. Any trigger may nam
 #                                     Default empty = fail-closed: `/dispatch secrets add` can declare nothing, and only PI_SECRET_PROFILES above is honoured.
 # PI_SECRET_RESOLVE_TIMEOUT_MS=     # default 10000, per reference. Sits before a paid container and is multiplied by the reference count, so tighter than doctor's 30s.
 
+# --- Holding a job until something else happens (docs/wait-for.md, issue #230) ---
+# A trigger may carry "waitFor": [{ "after": "2026-09-01T09:00:00Z" }, { "profile": "jira" }]. The job is
+# enqueued as usual and then HELD: it reserves no budget slot, arms no kill timer, consumes no retry attempt,
+# survives a restart, and runs exactly once when every condition clears. An `after` is answered from the
+# clock and costs nothing. A `profile` names one of YOUR scripts, which the worker runs on the HOST with the
+# job's id-only target as its first argument.
+# PI_WAIT_PROFILES=                 # name:/absolute/path pairs, comma separated (each entry splits on its FIRST colon, so a Windows C:\ path parses). Unset = feature off.
+#                                     Map the codes yourself, because a bare pipeline cannot: `s=$(jira issue view "$1" --plain) || exit 1` then
+#                                     `case "$s" in *"Status: Done"*) exit 0;; *) exit 3;; esac`. `grep -q` alone exits 1 for "no match", which is a counted FAULT, not "not yet".
+#                                     Exit 0 to go, 3 for not yet, 2 if it will NEVER clear (terminal), 1 if you could not tell (held, and counted).
+# PI_WAIT_CHECK_TIMEOUT_MS=         # default 10000, per check. Sits before a paid container and holds a concurrency slot while it runs.
+# PI_WAIT_INTERVAL_MS=              # default 60000, floored at 30000: a positive value BELOW the floor is raised to it, while 0, a negative, a fraction or junk still refuses at boot.
+#                                     The base cadence; it backs off toward 15 minutes, or toward YOUR value if you set a longer one.
+# PI_WAIT_CHECK_SLOTS=              # default 1. How many checks may run at once. Will be held below PI_CONCURRENCY at the gate, so a check can never take the last slot from a paid job.
+# PI_WAIT_MAX_MS=                   # default 86400000 (24h). A profile hold terminates here with a named reason: a dependency, unlike a pause window, does not end on its own.
+# PI_WAIT_AFTER_MAX_MS=             # default 2592000000 (30d). The separate, larger ceiling on an `after` instant, which polls nothing while it waits.
+# PI_WAIT_MAX_CHECKS=               # default 96, per job. Nothing in the spend caps sees a check, so this is the bound that does.
+# PI_WAIT_MAX_FAULTS=               # default 5 consecutive "could not tell" answers. What makes a broken check loud in minutes instead of silent for a day.
+
 PI_SCHEDULER_STALL_MAX=2            # tear down a scheduler after N consecutive stalls (money backstop)
 
 # --- Egress policy: what a job container may reach on the network (docs/egress.md) ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "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": [
@@ -56,6 +56,8 @@
     "./packages": "./src/packages.mjs",
     "./pause-windows": "./src/pause-windows.mjs",
     "./scoped-limits": "./src/scoped-limits.mjs",
+    "./wait-for": "./src/wait-for.mjs",
+    "./wait-state": "./src/wait-state.mjs",
     "./identity": "./src/identity.mjs",
     "./gitlab-identity": "./src/gitlab-identity.mjs",
     "./forgejo-identity": "./src/forgejo-identity.mjs",

package/src/config.mjs

@@ -10,6 +10,7 @@ import { delimiter } from "node:path";
 import { DEFAULT_EGRESS_PROXY, egressArmed } from "./egress.mjs";
 import { MINTED_TOKEN_VARS } from "./forges.mjs";
 import { parseSecretProfiles } from "./secret-profiles.mjs";
+import { WAIT_AFTER_MAX_DEFAULT_MS, WAIT_INTERVAL_FLOOR_MS, parseWaitProfiles } from "./wait-for.mjs";
 
 export function configError(message) {
 	const error = new Error(message);
@@ -296,6 +297,39 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// Per-reference ceiling. Tighter than doctor's 30s on purpose: this runs before a paid container, is
 		// multiplied by the reference count, and holds a PI_CONCURRENCY slot while it waits.
 		secretResolveTimeoutMs: positiveInt(env, "PI_SECRET_RESOLVE_TIMEOUT_MS", 10000),
+		// Issue #230, `run.waitFor`. The operator's declared wait checks, same `name:absolute-path` grammar as
+		// the resolvers above and deliberately a SEPARATE variable: the two answer different questions (one
+		// fetches a value, one says whether to go), they will grow different bounds, and one list would make a
+		// resolver reachable as a gate and a gate reachable as a resolver. Unset = the feature is off and any
+		// trigger naming a profile refuses pre-spend. There is no `PI_WAIT_RESOLVER_ROOTS` twin because there
+		// is no overlay half to bound: the wait gate runs ABOVE the per-job settings read, so a wait profile
+		// can only ever be declared here, beside the forge tokens.
+		waitProfiles: parseWaitProfiles(env.PI_WAIT_PROFILES),
+		// Per-check ceiling, `secretResolveTimeoutMs`' twin and for its reason: this runs before a paid
+		// container and holds a PI_CONCURRENCY slot while it waits.
+		waitCheckTimeoutMs: positiveInt(env, "PI_WAIT_CHECK_TIMEOUT_MS", 10000),
+		// The base re-check cadence, clamped UP to the floor rather than refused (wait-for.mjs states why, and
+		// what the clamp does not cover). The backoff derives from elapsed time, so this is a base, not a period.
+		waitIntervalMs: Math.max(WAIT_INTERVAL_FLOOR_MS, positiveInt(env, "PI_WAIT_INTERVAL_MS", 60_000)),
+		// How long a PROFILE hold may last before it terminates with a named reason. A dependency, unlike a
+		// pause window, is not self-terminating by construction, so this is the bound that makes it one.
+		waitMaxMs: positiveInt(env, "PI_WAIT_MAX_MS", 24 * 3600 * 1000),
+		// The separate, far larger ceiling on an `after` instant. Deliberately NOT waitMaxMs: an `after` is a
+		// scheduled instant, not a poll -- one exact moveToDelayed, self-terminating, costing nothing while it
+		// waits -- so bounding it by the polling budget would refuse "hold this until the maintenance window
+		// next month" for a reason that is about subprocesses it never runs.
+		waitAfterMaxMs: positiveInt(env, "PI_WAIT_AFTER_MAX_MS", WAIT_AFTER_MAX_DEFAULT_MS),
+		// How many wait checks may run AT ONCE in this worker process. One by default, and the ceiling it
+		// really pins is duty cycle: slots x timeout is the most wall-clock a worker can spend answering
+		// questions instead of running paid jobs. Clamped below PI_CONCURRENCY at the gate so a check can
+		// never take the last free slot.
+		waitCheckSlots: positiveInt(env, "PI_WAIT_CHECK_SLOTS", 1),
+		// Two bounds on ONE job's checks, both logged on overflow. The count bound is SECRETS_MAX's argument
+		// applied over time rather than over a map, and it matters because nothing in the money system sees a
+		// check at all: CONST-BUDGET-BEFORE-TOKENS counts container starts. The fault bound is what makes a
+		// broken check loud in minutes instead of silent for a day (OQ-027: most CLIs exit 1 for everything).
+		waitMaxChecks: positiveInt(env, "PI_WAIT_MAX_CHECKS", 96),
+		waitMaxFaults: positiveInt(env, "PI_WAIT_MAX_FAULTS", 5),
 		github: { ...loadGitHubAuth(env, fileExists), allowGhResume: env.PI_SESSIONS_ALLOW_GH_SOURCE === "1" },
 		gitlab: loadGitLabAuth(env),
 		forgejo: loadForgejoAuth(env),

package/src/doctor.mjs

@@ -44,13 +44,14 @@
  * about severity: a --fix run still exits by the same failed/ok logic, warns stay warns, and the fix pass
  * happens at most once (check, fix, re-check -- never a loop).
  */
-import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, readSync, realpathSync, rmSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn as nodeSpawn } from "node:child_process";
 import { defaultSandboxDir, globalExtensionsEnabled } from "./config.mjs";
 import { canonicalScope, parseScopedLimits } from "./scoped-limits.mjs";
+import { WAIT_AFTER_MAX_DEFAULT_MS, afterInstantMs, parseWaitProfiles } from "./wait-for.mjs";
 import { isForgeKind } from "./forges.mjs";
 import { findLiteralSecret, ADMIN_RE } from "./import-pi.mjs";
 import { agentDirFrom, readHostPi } from "./host-pi.mjs";
@@ -265,7 +266,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, onceArmed, onceSpent, secretProfiles, localSecretFolders, folders, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
+	const { requiring, waiting, waitProfiles, waitAfters, optingOut, resuming, replicating, instructing, commands, secreting, onceArmed, onceSpent, secretProfiles, localSecretFolders, folders, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
 	const scopedLimitFacts = readScopedLimitFacts(env, fileExists);
 	// 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
@@ -1099,14 +1100,84 @@ export async function collectChecks(env, seams) {
 		});
 	}
 
+	// Issue #230, `run.waitFor`. The PARSE is asked unconditionally, and the rest only when something waits.
+	// That split is not the usual "only report what this deployment uses": `loadConfig` calls
+	// `parseWaitProfiles` on every boot whether or not a trigger holds anything, so a garbled variable is a
+	// worker that will not START, and gating that behind `waiting > 0` would have hidden it from precisely
+	// the operator this check exists for. The ordinary sequence produces that state: declare the variable,
+	// restart, then write the trigger -- doctor is run in the middle, and would have said nothing at all.
+	const { profiles: declaredWaits, error: waitParseFailure } = parseWaitProfilesSafe(env.PI_WAIT_PROFILES);
+	if (waitParseFailure) {
+		checks.push({ ok: false, label: "PI_WAIT_PROFILES does not parse", fix: `${waitParseFailure} -- the worker refuses to BOOT until this is fixed, rather than dropping the entry and leaving you a check you believe is wired` });
+	}
+	// Everything below is about triggers, so it is asked only when a trigger holds something: a deployment
+	// that waits on nothing must not carry a line about a feature it does not use, which is the always-on
+	// advisory this file avoids everywhere else.
+	if (waiting > 0 && !waitParseFailure) {
+		// A HARD FAIL, `secretProfiles`' twin and for its reason: these jobs refuse pre-spend until the
+		// profile is declared, deliberately, rather than starting without ever asking the question.
+		const missing = waitProfiles.filter((name) => !(name in declaredWaits));
+		checks.push({
+			ok: missing.length === 0,
+			label: missing.length === 0 ? `${waiting} trigger(s) hold their jobs, and every wait profile they name is declared` : `${waiting} trigger(s) hold their jobs, but ${missing.length} named wait profile(s) are not declared: ${missing.join(", ")}`,
+			fix: `declare them in PI_WAIT_PROFILES as name:/absolute/path pairs (a check is one line, and its exit code is the answer: 0 go, 3 not yet, 2 never, 1 could not tell) -- these jobs refuse pre-spend until you do`,
+		});
+		// Each declared check is stat'd, exactly as a resolver is: absent, a directory, or not executable is a
+		// check that can never answer. NAMED profiles fail; declared-but-unnamed ones only warn, because no
+		// job looks them up -- a retired entry left in `.env` is untidy, not a deployment that refuses
+		// deliveries, and failing the whole command on it is the same over-reporting the `waiting > 0` gate
+		// exists to prevent. The probe is `wait-check.mjs`'s own, symlinks and all, so doctor and the gate
+		// cannot disagree about what will run.
+		const named = new Set(waitProfiles);
+		for (const name of Object.keys(declaredWaits).sort()) {
+			const path = declaredWaits[name];
+			const st = statPath(path);
+			const used = named.has(name);
+			checks.push({
+				ok: st.ok || !used,
+				...(st.ok ? { label: `Wait profile ${name} -> ${path}${used ? "" : " (declared, named by no trigger)"}` } : {}),
+				...(st.ok
+					? {}
+					: used
+						? { label: `Wait profile ${name} -> ${path} ${st.why}`, fix: "every job naming this profile refuses pre-spend as wait-profile-unknown until the path resolves to an executable file" }
+						: { warn: true, label: `Wait profile ${name} -> ${path} ${st.why}, and no trigger names it`, fix: "no job looks this up, so nothing refuses today -- fix the path or drop the entry before a trigger starts naming it" }),
+			});
+		}
+		// An `after` further out than the ceiling refuses EVERY delivery at first pickup, and doctor holds
+		// both halves of that arithmetic, so it is the same class of finding as an undeclared profile: a
+		// trigger that cannot deliver, knowable before anything is enqueued. Measured from now, exactly as
+		// the gate measures it.
+		const afterMax = Number(env.PI_WAIT_AFTER_MAX_MS ?? "") > 0 ? Number(env.PI_WAIT_AFTER_MAX_MS) : WAIT_AFTER_MAX_DEFAULT_MS;
+		const beyond = waitAfters.filter((iso) => {
+			const ms = afterInstantMs(iso);
+			return ms !== null && ms - Date.now() > afterMax;
+		});
+		if (beyond.length > 0) {
+			checks.push({
+				ok: false,
+				label: `${beyond.length} wait condition(s) name an instant beyond PI_WAIT_AFTER_MAX_MS: ${beyond.join(", ")}`,
+				fix: "every delivery refuses pre-spend as wait-after-beyond-max at first pickup -- bring the instant inside the ceiling or raise PI_WAIT_AFTER_MAX_MS",
+			});
+		}
+		// The version-floor disclosure. Stated ONCE, as a fact rather than a warning, because it is not a
+		// defect: it is the one thing about this feature an operator cannot check from here. `doctor` runs
+		// on the worker host and cannot see the receiver's installed version, so an unconditional warning
+		// would be the always-on amber the panel's own design rejects -- and the worker's own skew check
+		// already refuses a job that arrives without conditions it should have had.
+		checks.push({
+			ok: true,
+			label: `run.waitFor needs worker >= 1.6.0, receiver >= 1.4.0 and admin >= 1.6.0 (a service below the floor drops the field silently; the worker refuses such a job as wait-skew rather than running it unheld)`,
+		});
+	}
+
 	// REQ-TRIGGER-SECRETS. Only reported when a trigger actually binds one, on the run.resume block's
 	// reasoning below: a deployment that uses no secrets should not be told about a variable it has no
 	// reason to set.
 	if (secreting > 0) {
-		const declared = parseSecretProfilesSafe(env.PI_SECRET_PROFILES);
+		const { profiles: declared, error: parseFailure } = parseSecretProfilesSafe(env.PI_SECRET_PROFILES);
 		const names = Object.keys(declared).sort();
-		if (declared.error) {
-			checks.push({ ok: false, label: "PI_SECRET_PROFILES does not parse", fix: `${declared.error} -- the worker refuses to boot until this is fixed, rather than dropping the entry and leaving you a profile you believe is wired` });
+		if (parseFailure) {
+			checks.push({ ok: false, label: "PI_SECRET_PROFILES does not parse", fix: `${parseFailure} -- the worker refuses to boot until this is fixed, rather than dropping the entry and leaving you a profile you believe is wired` });
 		} else {
 			// A HARD FAIL, not a warning, and worded like the run.resume/PI_SESSIONS_DIR check below for the
 			// same reason: these jobs refuse pre-spend until it is set, deliberately, rather than running
@@ -1537,16 +1608,46 @@ async function repoFlowAtHead(spawn, folder, flow) {
 }
 
 /**
- * `parseSecretProfiles`, but doctor never throws. A malformed PI_SECRET_PROFILES is a finding to REPORT,
- * not a reason for the diagnostic tool to die: the operator running doctor is very likely running it
- * BECAUSE the worker refused to boot on that exact line, and a stack trace instead of a check is the least
- * useful possible answer. Returns the table, or `{ error }` carrying the parser's own message.
+ * `parseWaitProfiles`, but doctor never throws: a malformed variable is a finding to REPORT, not a reason
+ * for the diagnostic tool to die, since the operator running doctor is very likely running it BECAUSE the
+ * worker refused to boot on that exact line.
+ *
+ * Returns an ENVELOPE, `{ profiles, error }`, rather than the table with an `error` key beside the profiles.
+ * The flat shape reads better and is wrong: `error` is a legal profile name, so `PI_WAIT_PROFILES=error:/x.sh`
+ * declares a profile whose PATH then reads as a parse failure -- doctor reports the variable as unparseable,
+ * quoting the path as the message, and skips every check below it on a deployment that is perfectly fine.
+ */
+function parseWaitProfilesSafe(raw) {
+	try {
+		return { profiles: parseWaitProfiles(raw), error: null };
+	} catch (err) {
+		return { profiles: Object.create(null), error: err?.message ?? String(err) };
+	}
+}
+
+/** Is this path something the worker could actually execute? The resolver's probe, reused verbatim. */
+function statPath(path) {
+	try {
+		const real = realpathSync(path);
+		const st = statSync(real);
+		if (!st.isFile()) return { ok: false, why: "(not a regular file)" };
+		if ((st.mode & 0o111) === 0) return { ok: false, why: "(not executable)" };
+		return { ok: true };
+	} catch (err) {
+		return { ok: false, why: `(${err?.code ?? "unreadable"})` };
+	}
+}
+
+/**
+ * `parseSecretProfiles`, but doctor never throws, for `parseWaitProfilesSafe`'s reason and returning the
+ * same envelope. The `error`-is-a-legal-profile-name defect was found in the wait copy and fixed in both:
+ * the flat shape let one declared profile's PATH read as a parse failure and hide every check below it.
  */
 function parseSecretProfilesSafe(raw) {
 	try {
-		return parseSecretProfiles(raw);
+		return { profiles: parseSecretProfiles(raw), error: null };
 	} catch (err) {
-		return { error: err?.message ?? "unparseable" };
+		return { profiles: Object.create(null), error: err?.message ?? "unparseable" };
 	}
 }
 
@@ -1573,7 +1674,7 @@ function readScopedLimitFacts(env, fileExists) {
 }
 
 function readTriggerFacts(env, fileExists, cwd) {
-	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, onceArmed: 0, onceSpent: 0, secretProfiles: [], localSecretFolders: [], folders: [], images: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
+	const none = { requiring: 0, waiting: 0, waitProfiles: [], waitAfters: [], optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, onceArmed: 0, onceSpent: 0, secretProfiles: [], localSecretFolders: [], folders: [], 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
@@ -1619,6 +1720,21 @@ function readTriggerFacts(env, fileExists, cwd) {
 			// canonicalizes a job's folder (one derivation -- canonicalScope, never re-spelled here), so
 			// the unreferenced-scope advisory compares like with like across spelling variants.
 			folders: [...new Set(triggers.filter((t) => t.run.kind === "local" && typeof t.run.folder === "string").map((t) => canonicalScope({ kind: "local", folder: t.run.folder })))].sort(),
+			// Issue #230. How many triggers hold their jobs, and the distinct profile NAMES they select --
+			// deduped like `secretProfiles` and for its reason: each name costs a lookup, and two triggers
+			// waiting on one profile are one question.
+			waiting: triggers.filter((t) => Array.isArray(t.run.waitFor) && t.run.waitFor.length > 0).length,
+			// The `after` instants as WRITTEN, deduped. Not parsed here: `readTriggerFacts` is a fact reader and
+			// the ceiling it is measured against is env, which belongs at the check. Two triggers naming one
+			// instant are one finding, and the raw string is what the operator has to go and edit.
+			waitAfters: [...new Set(triggers.flatMap((t) => (Array.isArray(t.run.waitFor) ? t.run.waitFor : [])).map((c) => c?.after).filter((v) => typeof v === "string"))].sort(),
+			waitProfiles: [
+				...new Set(
+					triggers
+						.filter((t) => Array.isArray(t.run.waitFor))
+						.flatMap((t) => t.run.waitFor.map((c) => c?.profile).filter((n) => typeof n === "string")),
+				),
+			].sort(),
 			optingOut: triggers.filter((t) => t.run.packages === false).length,
 			images: [...new Set(triggers.map((t) => t.run.image).filter((i) => typeof i === "string"))].sort(),
 			// REQ-PER-TRIGGER-SKILLS. The distinct host directories the file names, deduped like `images`,

package/src/exit-code.mjs

@@ -9,6 +9,21 @@ export const EXIT_COMPLETED = 0; // agent ran, INCLUDING "I cannot fix this" --
 export const EXIT_INFRA = 1; // container died, network, provider 5xx/429 -- the only retryable class
 export const EXIT_POLICY = 2; // budget/turn cap/config -- a determinate refusal, never retried
 
+/**
+ * "Not yet, ask again later" (issue #230). Emitted by the WAIT PARTICIPANT ONLY.
+ *
+ * The protocol's third queue behaviour, and the only code in it that no container and no secret resolver
+ * may emit: a container exiting 3 is still an unrecognised code and still infra-retries through
+ * `processor.mjs`'s own switch, a resolver exiting 3 is still `unreachable`, and both are pinned. This is
+ * therefore a per-participant widening rather than a new meaning for a code anyone else already speaks.
+ *
+ * Minting a code rather than riding `reason` on an exit log line -- which is what
+ * `INT-RUNNER-EXIT-CODE-PROTOCOL` asks of the CONTAINER's new vocabulary -- is possible here for the
+ * reason that rule does not reach: a wait participant has no exit log line to ride. It produces no run
+ * record and no log line of its own while a job is held, so `reason` is not a channel it has.
+ */
+export const EXIT_HOLD = 3;
+
 /**
  * Decide whether the processor should RETURN (BullMQ records success, no retry) or THROW (BullMQ
  * retries per `attempts`). Returns `{ retry }`; the caller returns on false and throws on true.
@@ -30,3 +45,44 @@ export function decideRetry(exitCode) {
 			return { retry: true, outcome: `unknown-exit-${exitCode}` };
 	}
 }
+
+/**
+ * Classify a WAIT PROFILE's exit code (issue #230). Returns `{ verdict, fault }`, where `verdict` is
+ * `"go"` (run the job), `"hold"` (defer and ask again) or `"refuse"` (terminal, never retried).
+ *
+ * The four codes and why each lands where it does:
+ *
+ *   0  the condition has cleared            -> go
+ *   3  not yet                              -> hold, NOT a fault: this is the normal answer
+ *   1  I could not tell                     -> hold, AND a fault
+ *   2  this will never clear                -> refuse, terminal
+ *   *  anything else                        -> hold, AND a fault
+ *
+ * `1` HOLDS RATHER THAN REFUSING because a check that cannot answer has not answered "no": treating an
+ * unreachable Jira as "this will never clear" would drop a paid delivery over a transient outage, which is
+ * `CONST-RETRY-INFRA-ONLY` in the expensive direction and the same call `secrets.mjs` makes for a resolver
+ * that cannot reach its manager.
+ *
+ * `fault` is what keeps `1` and `3` from being the same code wearing two hats, and it exists because of
+ * `OQ-027`: most CLIs exit 1 for everything, so without it a permanently broken check -- a typo'd `curl`
+ * exits 6, a false `jq -e` exits 1 -- would hold for the entire maximum wait, spawn a process every
+ * interval, and finally terminate with a reason that blames the CONDITION rather than the script. Counting
+ * consecutive faults lets that terminate loudly in minutes, naming the check. A `3` resets the count: a
+ * check that answered is a check that works.
+ *
+ * The unrecognised arm folds into `1` deliberately, which is this protocol's own rule for an unrecognised
+ * code, and it is why the naive one-liner an operator writes first (`grep -q ... ` , exit 1 when the
+ * pattern is absent) behaves correctly by accident: it holds, and the fault counter bounds it.
+ */
+export function decideWait(exitCode) {
+	switch (exitCode) {
+		case EXIT_COMPLETED:
+			return { verdict: "go", fault: false };
+		case EXIT_HOLD:
+			return { verdict: "hold", fault: false };
+		case EXIT_POLICY:
+			return { verdict: "refuse", fault: false };
+		default:
+			return { verdict: "hold", fault: true }; // EXIT_INFRA and every unrecognised code
+	}
+}