@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/valkey-auth.mjs

@@ -13,10 +13,11 @@
  * says only whether it is set. An operator's own VALKEY_URL with its own userinfo (a managed Valkey, TLS) is left as it
  * is, and its password wins over this key (`connection.mjs`).
  *
- * HOW THE VALKEY LEARNS IT, measured on Podman 5.8.1 (Fedora 44) and 4.9.3 (Ubuntu 24.04) with valkey/valkey:8
- * (Valkey 8.1.10): the image runs `tini -- docker-entrypoint.sh <command>`, and tini keeps its whole argv as PID 1 for
- * the life of the container, so `valkey-server --requirepass X` put the password in a /proc/<pid>/cmdline that another
- * account read, on the host, for as long as the Valkey ran (the pid namespace hides nothing: /proc of the host lists
+ * HOW THE VALKEY LEARNS IT, measured on Podman 5.8.1 (Fedora 44) and 4.9.3 (Ubuntu 24.04) with Valkey 8.1.10 (pulled
+ * as valkey/valkey:8 then, the minor `VALKEY_IMAGE` pins since issue #761): the image runs
+ * `tini -- docker-entrypoint.sh <command>`, and tini keeps its whole argv as PID 1 for the life of the container, so
+ * `valkey-server --requirepass X` put the password in a /proc/<pid>/cmdline that another account read, on the host,
+ * for as long as the Valkey ran (the pid namespace hides nothing: /proc of the host lists
  * the container's processes, and cmdline is world-readable). The image's VALKEY_EXTRA_FLAGS only appends to that same
  * argv. So the password travels in the container's ENVIRONMENT (a Quadlet `EnvironmentFile=` of a 0600 file, compose's
  * `environment:`, `docker run -e VALKEY_PASSWORD` with the value in the CLI's own environment), which /proc shows only
@@ -38,6 +39,25 @@ import { basename, join } from "node:path";
 /** The `.env` key (issue #468). */
 export const VALKEY_PASSWORD_KEY = "VALKEY_PASSWORD";
 
+/**
+ * The image of every Valkey this project starts or ships (issue #761): `up`'s `docker run` and the owner check below,
+ * `deploy/docker-compose.yml`, the Quadlet unit (as `docker.io/` and this), CI's services and its smoke script, each
+ * held to this value by `worker/test/valkey-image.test.mjs`. A minor, where an older release shipped the floating
+ * major `:8` on the reasoning that a bad pull breaks loudly and spends nothing. That is not enough:
+ *   - the specs state measured facts about this Valkey (`HEXPIRE` answers `ERR unknown command`, `/bin/sh` is dash),
+ *     and a floating tag makes each a claim about whatever was pulled last;
+ *   - the hosts of one fleet must not cross a minor at different times, each on its own next pull;
+ *   - a newer minor's data files need not load in an older one, so a pull nobody chose could rule out a rollback;
+ *   - an upgrade guide needs a known starting point.
+ * Not a patch or a digest: `8.1` still takes 8.1's patch releases, security fixes among them, which a patch pin would
+ * hold back until someone moved it (the egress proxy, which IS the allowlist, stays digest-pinned). When pinned
+ * it was the image `:8` pulled (both resolved to Valkey 8.1.11, and no `:8.2` existed), so neither a fresh pull nor a
+ * host that pulled `:8` moved, and a volume written by 8.0.2 or by 8.1.11 loaded in the other, measured both ways.
+ * Moving it: change this value, add the old one to `OLDER_VALKEY_IMAGES` (older-state.mjs), re-measure the claims above
+ * and the load in both directions, and add a row to docs/upgrading.md.
+ */
+export const VALKEY_IMAGE = "valkey/valkey:8.1";
+
 /**
  * A new password: 32 random bytes as 64 lowercase hex characters. Hex because every loader of `.env` reads it back
  * byte for byte (systemd, the shells, the cmd wrapper split on `=`), nothing in it is special to a Valkey config line,
@@ -115,7 +135,7 @@ export function valkeyDockerRunArgs({ port = 6379, deployment = null } = {}) {
 		"3s",
 		"--health-retries",
 		"5",
-		"valkey/valkey:8",
+		VALKEY_IMAGE,
 		"sh",
 		"-c",
 		VALKEY_START_SCRIPT,
@@ -319,8 +339,10 @@ function ownerShown(info) {
 }
 
 /**
- * One container by name: `{ absent }`, `{ ours, owner }`, or `{ unknown }` when docker did not answer (which is never
- * taken as ours). `query(cmd, args)` resolves `{ code, stdout, stderr }`.
+ * One container by name: `{ absent }`, `{ ours, owner, image? }`, or `{ unknown }` when docker did not answer (which is
+ * never taken as ours). `query(cmd, args)` resolves `{ code, stdout, stderr }`. `image` is the record's `Config.Image`,
+ * the reference the container was created from as given (measured on docker 27.4: `valkey/valkey:8` and
+ * `docker.io/valkey/valkey:8` each come back unchanged), which `up` holds against the older images (issue #761).
  */
 export async function valkeyContainerOwner(name, { dirs, port, query }) {
 	const res = await query("docker", ["container", "inspect", name]);
@@ -331,7 +353,8 @@ export async function valkeyContainerOwner(name, { dirs, port, query }) {
 	} catch {
 		return { unknown: `docker container inspect ${name} printed no record` };
 	}
-	return { ours: valkeyContainerIsOurs(info, { dirs, port }), owner: ownerShown(info) };
+	const image = info?.Config?.Image;
+	return { ours: valkeyContainerIsOurs(info, { dirs, port }), owner: ownerShown(info), ...(typeof image === "string" ? { image } : {}) };
 }
 
 /**
@@ -511,7 +534,7 @@ export const OWNER_CHECK_CONTAINER = "pi-dispatch-valkey-ownercheck";
  * AOF on, as always, so it loads the queue as the real one will; it is stopped (SIGTERM), never killed.
  */
 export function valkeyOwnerCheckArgs(deployment) {
-	return ["run", "-d", "--name", OWNER_CHECK_CONTAINER, "--label", `${DEPLOYMENT_LABEL}=${deployment}`, "--network", "none", "-v", `${VALKEY_VOLUME}:/data`, "valkey/valkey:8", "valkey-server", "--appendonly", "yes"];
+	return ["run", "-d", "--name", OWNER_CHECK_CONTAINER, "--label", `${DEPLOYMENT_LABEL}=${deployment}`, "--network", "none", "-v", `${VALKEY_VOLUME}:/data`, VALKEY_IMAGE, "valkey-server", "--appendonly", "yes"];
 }
 
 /** `docker exec` reading the marker inside the owner check's Valkey. */

package/src/valkey-endpoint.mjs

@@ -29,7 +29,7 @@ import { lookup as dnsLookup } from "node:dns/promises";
 import { readFileSync } from "node:fs";
 import { networkInterfaces, userInfo } from "node:os";
 import { join } from "node:path";
-import { venuesOf } from "./backends.mjs";
+import { openshellSetupOf, venuesOf } from "./backends.mjs";
 import { DEFAULT_VALKEY_URL } from "./config.mjs";
 import { VALKEY_SHARED_KEY, judgeValkeyListeners, passwdNameFrom, pinnedValkeyUrl, probeTcpAddress, readStackKeys, readSubuidRanges, readValkeyKeys, valkeySharedOn, valkeySchemeOf } from "./podman-stack.mjs";
 import { VALKEY_PASSWORD_KEY, isLoopbackHost } from "./valkey-auth.mjs";
@@ -95,7 +95,11 @@ export function valkeyClientContext({ env = process.env, cwd = process.cwd(), pl
 	if (content !== null) {
 		const stack = readStackKeys(content, { loader: "systemd", path: envPath });
 		if (stack.error) error = stack.error;
-		else if (typeof stack.keys.PI_BACKENDS === "string") fileKeys.PI_BACKENDS = stack.keys.PI_BACKENDS;
+		else {
+			if (typeof stack.keys.PI_BACKENDS === "string") fileKeys.PI_BACKENDS = stack.keys.PI_BACKENDS;
+			// Issue #707: the engine decides whether the queue is this account's Quadlet Valkey (`openshellSetupOf`).
+			if (typeof stack.keys.PI_OPENSHELL_ENGINE === "string") fileKeys.PI_OPENSHELL_ENGINE = stack.keys.PI_OPENSHELL_ENGINE;
+		}
 		const keys = readValkeyKeys(content, { loader: "systemd", path: envPath });
 		if (keys.error) error ??= keys.error;
 		else for (const k of [VALKEY_SHARED_KEY, VALKEY_PASSWORD_KEY, "VALKEY_URL"]) if (typeof keys.keys[k] === "string") fileKeys[k] = keys.keys[k];
@@ -119,12 +123,16 @@ export function valkeyContextFromResolution({ service, envPath = null, shared, p
 		if (typeof fileValue(key) === "string") fileKeys[key] = fileValue(key);
 	}
 	if (typeof service?.env?.PI_BACKENDS === "string") env.PI_BACKENDS = service.env.PI_BACKENDS;
+	// Issue #707 (review round 2 of #715): the engine beside the list, which decides whether an openshell venue's queue is
+	// this account's Quadlet Valkey (`openshellSetupOf`).
+	if (typeof service?.env?.PI_OPENSHELL_ENGINE === "string") env.PI_OPENSHELL_ENGINE = service.env.PI_OPENSHELL_ENGINE;
 	if (typeof shared === "string") fileKeys[VALKEY_SHARED_KEY] = shared;
 	return valkeyContextFromKeys({ env, envPath, fileKeys, platform });
 }
 
 /** The keys a client's context takes from a deployment `.env` (`valkeyContextFromKeys`). */
-export const VALKEY_CONTEXT_KEYS = Object.freeze(["VALKEY_URL", VALKEY_PASSWORD_KEY, VALKEY_SHARED_KEY, "PI_BACKENDS"]);
+// Issue #707 (review round 2 of #715): and PI_OPENSHELL_ENGINE, which `valkeyContextFromKeys` reads beside PI_BACKENDS.
+export const VALKEY_CONTEXT_KEYS = Object.freeze(["VALKEY_URL", VALKEY_PASSWORD_KEY, VALKEY_SHARED_KEY, "PI_BACKENDS", "PI_OPENSHELL_ENGINE"]);
 
 /**
  * A context from keys a caller has already read out of the deployment's `.env` (`fileKeys`, the `VALKEY_CONTEXT_KEYS`
@@ -144,7 +152,9 @@ export function valkeyContextFromKeys({ env = process.env, envPath = null, fileK
 	} catch {
 		// An unparseable list: the default venue, as doctor reads it; the worker refuses to boot on it anyway.
 	}
-	const derived = platform === "linux" && venues.podmanUsed && !venues.localUsed;
+	// Issue #707 (review round 1 of #715): and an openshell venue on Podman that is the queue's engine, as the worker judges it.
+	const engine = typeof env.PI_OPENSHELL_ENGINE === "string" ? env.PI_OPENSHELL_ENGINE : fileKeys.PI_OPENSHELL_ENGINE;
+	const derived = platform === "linux" && ((venues.podmanUsed && !venues.localUsed) || openshellSetupOf(venues, { PI_OPENSHELL_ENGINE: engine }).valkeyEngine === "podman");
 	const envUrl = typeof env.VALKEY_URL === "string" ? env.VALKEY_URL : null;
 	return { envPath, shared, rootRefused: typeof rootRefused === "boolean" ? rootRefused : derived, error, password: { environment: envPassword, file: filePassword }, url: { environment: envUrl, file: fileUrl } };
 }

package/src/wait-for.mjs

@@ -38,7 +38,7 @@ function configError(message) {
  * condition it asked for is structural now, and `scoped-limits.json` covers the wider per-scope case.
  * Accepting-and-ignoring it would be the silent no-op this project refuses.
  */
-export const WAIT_CONDITION_KEYS = ["after", "profile"];
+export const WAIT_CONDITION_KEYS = Object.freeze(["after", "profile"]);
 
 /**
  * Every reason the wait gate refuses a job with (index.mjs `refuseWait`), each before the job holds a slot. A test

package/src/wait-state.mjs

@@ -18,6 +18,12 @@
  *      the worker rather than projected out of a delayed job's `.data`, which holds the issue title and
  *      body.
  *
+ * Two fields say more of the same to an operator, for the same reason (issue #737): `after`, the job's own
+ * `after` instant, and `a:<profile>`, what each check last answered and when (`<go|hold|fault|refuse|unclear>:<ms>`).
+ * A console reads both from here, never from the job's data. `after` is not the hold's lease horizon: on the
+ * polled path that is the next check, and on a throttled wake it is the maximum wait, so a console showing it
+ * as the hold's end would draw a time nobody chose. The next wake is the defer record's (`defer-reasons.mjs`).
+ *
  * WHY THIS IS NOT THE REDIS STATE `OQ-008` AND #242 REFUSED. That refusal is about a claim that would
  * survive a crash WRONGLY -- an in-flight count asserting a container the boot reaper had just killed.
  * This describes DELAYED JOBS, which are themselves Redis-persisted, so it is the same source of truth
@@ -29,7 +35,8 @@
  *
  * The keys, all under one prefix so an operator can see the whole feature with one `KEYS wait:*`:
  *   wait:held                 SET of held job ids -- an index the READER prunes, never a source of truth
- *   wait:job:<jobId>          HASH { since, faults, throttles, target, label, dedupId }, TTL sized to the hold
+ *   wait:job:<jobId>          HASH { since, faults, throttles, checks, target, label, dedupId, after, a:<profile> },
+ *                             TTL sized to the hold
  *   wait:done:<dedupId>       STRING jobId -- this target's wait was satisfied, briefly remembered
  *   wait:key:<dedupId>        STRING jobId -- the supersede lease, TTL sized to the expected hold
  */
@@ -61,6 +68,37 @@ export const satisfiedKey = (dedupId) => `wait:done:${dedupId}`;
 // longest two jobs that cleared together can wake apart.
 const SATISFIED_MS = 15 * 60 * 1000;
 
+/** The hold hash's field prefix for a check's last answer: `a:<profile>`. */
+export const WAIT_ANSWER_PREFIX = "a:";
+
+/** The answers a check's field may hold, the gate's own vocabulary for what it was told (`answerOf`). */
+export const WAIT_ANSWERS = Object.freeze(["go", "hold", "fault", "refuse", "unclear"]);
+
+/**
+ * A profile name that may become a field. The wait loader's charset with a length bound, so a field name stays a
+ * short token whatever a newer loader admits; a longer name keeps its hold and simply records no answer.
+ */
+export const WAIT_PROFILE_FIELD_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+/**
+ * What a check's verdict says, as the hold hash records it, or null when it says nothing about the condition: an
+ * aborted check (a restart or a cancel stopped it), a profile this worker does not declare, and a target no check
+ * can be handed are each decided by the gate without an answer. `hold` with a fault is `fault` (the check could not
+ * tell); anything the gate does not understand is `unclear`, the same shape it holds rather than runs.
+ *
+ * In the gate's own order of tests (index.mjs, after the check loop), so a verdict carrying two signals is recorded
+ * as what the gate did with it: a `refuse` that also says aborted is refused there, and recorded so here.
+ */
+export function answerOf(verdict) {
+	const v = verdict !== null && typeof verdict === "object" ? verdict : {};
+	if (v.unusableTarget || v.profileUnknown) return null;
+	if (v.verdict === "refuse") return "refuse";
+	if (v.aborted) return null;
+	if (v.verdict === "hold") return v.fault === true ? "fault" : "hold";
+	if (v.verdict === "go") return "go";
+	return "unclear";
+}
+
 /**
  * Build the state accessor. `redis` is the same client the budget uses; nothing here is on the paid path,
  * so every method is written to FAIL OPEN: a redis blip must never refuse a job or wedge a hold, it may
@@ -74,13 +112,16 @@ export function makeWaitState({ redis, now = () => Date.now(), counterTtlMs = 25
 		 * Record (or refresh) a hold. `since` is written ONCE with HSETNX so a re-pick does not restart the
 		 * clock -- that is the whole point of not using `job.timestamp`, and a plain HSET here would
 		 * reintroduce the bug from the other side by resetting the wait on every wake.
+		 *
+		 * `afterMs` is the job's own `after` instant (`afterMs(job.data)`), written as `after` beside the label in
+		 * the same HSET when it is a whole number of milliseconds; the hold's lease horizon `untilMs` never is.
 		 */
-		async hold(jobId, { dedupId, target, label, untilMs }) {
+		async hold(jobId, { dedupId, target, label, untilMs, afterMs = null }) {
 			try {
 				const key = jobKey(jobId);
 				const ttl = leaseMs(untilMs);
 				await redis.hsetnx(key, "since", String(now()));
-				await redis.hset(key, "target", target ?? "", "label", label ?? "", "dedupId", dedupId ?? "");
+				await redis.hset(key, "target", target ?? "", "label", label ?? "", "dedupId", dedupId ?? "", ...(Number.isSafeInteger(afterMs) ? ["after", String(afterMs)] : []));
 				await redis.pexpire(key, ttl);
 				await redis.sadd(HELD_SET, jobId);
 				// Refresh OUR lease only, and re-read to find out whether it IS ours: `hold` is no longer
@@ -245,6 +286,24 @@ export function makeWaitState({ redis, now = () => Date.now(), counterTtlMs = 25
 			}
 		},
 
+		/**
+		 * Record what one profile's check last answered, `a:<profile>` = `<answer>:<ms>`, for a console to show
+		 * beside the hold. One field per profile, overwritten by its next answer, so the hash grows with the job's
+		 * conditions and never with its wakes. Like a counter it may create the hash, so it carries the counters'
+		 * TTL for their reason. A profile or an answer outside its rule is not written, silently: the answers are
+		 * the gate's own vocabulary, and a profile name past the field rule keeps its hold without the detail.
+		 * Fail open.
+		 */
+		async noteAnswer(jobId, { profile, answer } = {}) {
+			if (typeof profile !== "string" || !WAIT_PROFILE_FIELD_RE.test(profile) || !WAIT_ANSWERS.includes(answer)) return;
+			try {
+				await redis.hset(jobKey(jobId), `${WAIT_ANSWER_PREFIX}${profile}`, `${answer}:${now()}`);
+				await redis.pexpire(jobKey(jobId), counterTtlMs);
+			} catch {
+				// Fail open: a lost answer costs a console its detail, never the gate its decision.
+			}
+		},
+
 		/** How long this job has been held, in ms, or null when nothing was recorded. */
 		async heldForMs(jobId) {
 			try {

package/src/watch-board.mjs

@@ -0,0 +1,38 @@
+/** A board is inert data with provenance, never agent-authored markup or executable query config. */
+export const WATCH_BOARD_MAX_BYTES = 16384;
+export const WATCH_BOARD_TYPES = Object.freeze(["number", "line", "table", "note", "hypotheses", "timeline"]);
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const text = (value) => typeof value === "string" && value.length <= 2048 && !/[\u0000-\u0008\u000b-\u001f\u007f]/.test(value);
+const scalar = (value) => value === null || text(value) || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value));
+const id = (value) => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(value) && !["__proto__", "constructor", "prototype"].includes(value);
+const keys = (value, allowed) => Object.keys(value).every((key) => allowed.includes(key));
+export function validateWatchBoard(input, { traceIds } = {}) {
+	const refuse = (reason) => ({ ok: false, reason });
+	let raw;
+	try { raw = typeof input === "string" ? input : JSON.stringify(input); } catch { return refuse("watch-board-invalid"); }
+	if (typeof raw !== "string") return refuse("watch-board-invalid");
+	if (Buffer.byteLength(raw) > WATCH_BOARD_MAX_BYTES) return refuse("watch-board-oversize");
+	let board;
+	try { board = JSON.parse(raw); } catch { return refuse("watch-board-invalid"); }
+	if (!record(board) || !keys(board, ["version", "blocks"]) || board.version !== 1 || !Array.isArray(board.blocks) || board.blocks.length > 64) return refuse("watch-board-invalid");
+	const ids = new Set();
+	for (const block of board.blocks) {
+		if (!record(block) || !id(block.id) || ids.has(block.id) || !WATCH_BOARD_TYPES.includes(block.type) || !id(block.traceId) || (traceIds !== undefined && !traceIds.has(block.traceId)) || !text(block.title ?? "")) return refuse("watch-board-invalid");
+		ids.add(block.id);
+		const common = ["id", "type", "traceId", "title"];
+		if (block.type === "number") {
+			if (!keys(block, [...common, "value", "unit"]) || typeof block.value !== "number" || !Number.isFinite(block.value) || !text(block.unit ?? "")) return refuse("watch-board-invalid");
+		} else if (block.type === "note") {
+			if (!keys(block, [...common, "text"]) || !text(block.text)) return refuse("watch-board-invalid");
+		} else if (block.type === "line") {
+			if (!keys(block, [...common, "points"]) || !Array.isArray(block.points) || block.points.length > 256 || !block.points.every((p) => record(p) && keys(p, ["x", "y"]) && (text(p.x) || typeof p.x === "number" && Number.isFinite(p.x)) && typeof p.y === "number" && Number.isFinite(p.y))) return refuse("watch-board-invalid");
+		} else if (block.type === "table") {
+			if (!keys(block, [...common, "columns", "rows"]) || !Array.isArray(block.columns) || !block.columns.length || block.columns.length > 16 || !block.columns.every(text) || !Array.isArray(block.rows) || block.rows.length > 128 || !block.rows.every((row) => Array.isArray(row) && row.length === block.columns.length && row.every(scalar))) return refuse("watch-board-invalid");
+		} else if (block.type === "hypotheses") {
+			if (!keys(block, [...common, "items"]) || !Array.isArray(block.items) || block.items.length > 32 || !block.items.every(text)) return refuse("watch-board-invalid");
+		} else if (block.type === "timeline") {
+			if (!keys(block, [...common, "items"]) || !Array.isArray(block.items) || block.items.length > 64 || !block.items.every((item) => record(item) && keys(item, ["at", "text"]) && text(item.at) && Number.isFinite(Date.parse(item.at)) && text(item.text))) return refuse("watch-board-invalid");
+		}
+	}
+	return { ok: true, board };
+}

package/src/watch-closer.mjs

@@ -86,7 +86,7 @@ export function makeWatchCloser(handles, log) {
  * The debounce every live-edit watch in this project uses, in one place (issue #386).
  *
  * The literal 150 was written four times -- the receiver's triggers watch and the worker's triggers,
- * pause-windows and scoped-limits watches -- and four copies of a number is the shape `CLAUDE.md` warns
+ * pause-windows and scoped-limits watches -- and four copies of a number is the shape `AGENTS.md` warns
  * about: they agree until one of them does not. It rides this module because this module is already what
  * both composition roots import for the same four watches.
  *

package/src/watch-contract.mjs

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { isProjectId } from "./project-id.mjs";
+
+export const WATCH_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+export const WATCH_SEVERITIES = Object.freeze(["debug", "info", "warning", "error", "critical"]);
+const FIELD_RE = /^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/;
+const forbidden = new Set(["__proto__", "prototype", "constructor"]);
+function fail(message) { const error = new Error(`watch: ${message}`); error.piDispatchConfig = true; throw error; }
+function object(value, name) { if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${name} must be an object`); }
+function keys(value, allowed, name) { for (const key of Object.keys(value)) if (!allowed.includes(key)) fail(`${name} has an unknown field`); }
+function integer(value, min, max, name) { if (!Number.isSafeInteger(value) || value < min || value > max) fail(`${name} is out of bounds`); return value; }
+function id(value, name) { if (typeof value !== "string" || !WATCH_ID_RE.test(value)) fail(`${name} must be a bounded identifier`); return value; }
+function field(value) { if (typeof value !== "string" || !FIELD_RE.test(value) || value.split(".").some(x => forbidden.has(x))) fail("invalid structured field name"); return value; }
+export function watchDurationMs(value) {
+	if (typeof value !== "string" || !/^[1-9][0-9]{0,4}[smhd]$/.test(value)) fail("duration must be a bounded s, m, h or d value");
+	const ms = Number(value.slice(0, -1)) * ({ s: 1000, m: 60000, h: 3600000, d: 86400000 })[value.at(-1)];
+	if (ms > 30 * 86400000) fail("duration exceeds 30 days");
+	return ms;
+}
+export function normalizeWatchSources(value = {}) {
+	object(value, "watchSources");
+	if (Object.keys(value).length > 64) fail("too many sources");
+	const sources = {};
+	for (const [name, source] of Object.entries(value)) {
+		id(name, "source"); object(source, "source"); keys(source, ["verify", "secretEnv", "maxBodyBytes", "project", "maxPerDay", "pull"], "source");
+		if (source.verify !== "hmac-sha256") fail("source requires hmac-sha256");
+		if (typeof source.secretEnv !== "string" || !/^[A-Z][A-Z0-9_]{0,127}$/.test(source.secretEnv)) fail("invalid source secretEnv");
+		if (source.project !== undefined && !isProjectId(source.project)) fail("invalid source project id");
+		sources[name] = { verify: source.verify, secretEnv: source.secretEnv, maxBodyBytes: integer(source.maxBodyBytes ?? 65536, 1, 65536, "maxBodyBytes"), maxPerDay: integer(source.maxPerDay ?? 1000, 1, 100000, "source maxPerDay"), ...(source.project !== undefined ? { project: source.project } : {}), ...(source.pull !== undefined ? { pull: normalizeWatchPullConfig(source.pull) } : {}) };
+	}
+	return sources;
+}
+export function normalizeWatchOn(on, sources) {
+	object(on, "on"); keys(on, ["type", "id", "source", "match", "fingerprint", "minCount", "window", "cooldown", "maxPerDay", "maxFingerprints"], "on");
+	if (on.type !== "watch") fail("on.type must be watch");
+	id(on.id, "trigger id"); id(on.source, "source");
+	if (sources && !Object.hasOwn(sources, on.source)) fail("source is not declared");
+	if (!Array.isArray(on.fingerprint) || !on.fingerprint.length || on.fingerprint.length > 8 || new Set(on.fingerprint).size !== on.fingerprint.length) fail("fingerprint requires 1 to 8 unique fields");
+	on.fingerprint.forEach(field);
+	const match = on.match ?? {};
+	object(match, "match"); keys(match, ["severity", "labels"], "match");
+	// Unique members bound it at WATCH_SEVERITIES.length; a count written as a number would refuse a rule naming every
+	// severity once the list grew past it.
+	if (match.severity !== undefined && (!Array.isArray(match.severity) || !match.severity.length || new Set(match.severity).size !== match.severity.length || match.severity.some(x => !WATCH_SEVERITIES.includes(x)))) fail("invalid match severity");
+	const labels = match.labels ?? {}; object(labels, "match labels");
+	if (Object.keys(labels).length > 16) fail("too many match labels");
+	for (const [key, values] of Object.entries(labels)) { field(key); if (!Array.isArray(values) || !values.length || values.length > 16 || values.some(x => typeof x !== "string" || Buffer.byteLength(x) > 256)) fail("invalid match label values"); }
+	if (watchDurationMs(on.window) > 86400000) fail("digest window exceeds one day"); if (watchDurationMs(on.window) + watchDurationMs(on.cooldown) > 7 * 86400000) fail("digest window plus cooldown exceeds seven-day finding retention");
+	return { type: "watch", id: on.id, source: on.source, match: structuredClone(match), fingerprint: [...on.fingerprint], minCount: integer(on.minCount ?? 1, 1, 1000000, "minCount"), window: on.window, cooldown: on.cooldown, maxPerDay: integer(on.maxPerDay, 1, 10000, "maxPerDay"), maxFingerprints: integer(on.maxFingerprints ?? 256, 1, 4096, "maxFingerprints") };
+}
+export function parseWatchFinding(value) {
+	object(value, "finding"); keys(value, ["source", "fields", "labels", "severity", "count", "firstSeen", "lastSeen", "samples"], "finding");
+	if (value.source !== undefined) id(value.source, "source");
+	if (!WATCH_SEVERITIES.includes(value.severity)) fail("invalid severity");
+	const fields = value.fields ?? value.labels ?? {}; object(fields, "fields");
+	if (Object.keys(fields).length > 32) fail("too many structured fields");
+	for (const [key, val] of Object.entries(fields)) { field(key); if (typeof val !== "string" || Buffer.byteLength(val) > 256 || /[\u0000-\u001f]/.test(val)) fail("invalid structured field value"); }
+	for (const key of ["firstSeen", "lastSeen"]) if (typeof value[key] !== "string" || value[key].length > 32 || !Number.isFinite(Date.parse(value[key]))) fail("invalid finding time");
+	if (Date.parse(value.firstSeen) > Date.parse(value.lastSeen)) fail("finding times are reversed");
+	const samples = value.samples ?? [];
+	if (!Array.isArray(samples) || samples.length > 8 || samples.some(x => typeof x !== "string" || Buffer.byteLength(x) > 2048)) fail("samples exceed bounds");
+	return { ...(value.source !== undefined ? { source: value.source } : {}), fields: { ...fields }, severity: value.severity, count: integer(value.count ?? 1, 1, 1000000, "count"), firstSeen: new Date(value.firstSeen).toISOString(), lastSeen: new Date(value.lastSeen).toISOString(), samples: [...samples] };
+}
+// A length-delimited JSON tuple prevents separators inside field values aliasing another identity.
+// Cardinality still needs a source/rule cap in the atomic store: structured values are attacker data.
+export function watchFingerprint(source, on, finding) {
+	id(source, "source"); id(on.id, "trigger id");
+	const values = on.fingerprint.map(key => { if (!Object.hasOwn(finding.fields, key)) fail("missing fingerprint field"); return [key, finding.fields[key]]; });
+	return createHash("sha256").update(JSON.stringify([source, on.id, values])).digest("hex");
+}
+export function matchesWatchFinding(on, finding) {
+	return (!on.match?.severity || on.match.severity.includes(finding.severity)) && Object.entries(on.match?.labels ?? {}).every(([key, values]) => values.includes(finding.fields[key]));
+}
+
+export function normalizeWatchRule(on, sources) {
+	const rule = normalizeWatchOn(on, sources);
+	return { ...rule, windowMs: watchDurationMs(rule.window), cooldownMs: watchDurationMs(rule.cooldown) };
+}
+
+export function normalizeWatchPullConfig(value) {
+	object(value, "pull");
+	const common = ["kind", "fields", "severity", "contains", "intervalSeconds"];
+	const kinds = { file: ["path"], journald: ["unit"], loki: ["url", "query", "secretEnv"] };
+	// An own key, of a string: a plain index finds `constructor` or `__proto__` on the prototype (a bare TypeError a line
+	// later), and ["file"] coerces to "file" and skips the path check below, as ["loki"] skips the HTTPS one.
+	const extra = typeof value.kind === "string" && Object.hasOwn(kinds, value.kind) ? kinds[value.kind] : null;
+	if (!extra) fail("pull kind must be file, journald or loki");
+	keys(value, [...common, ...extra], "pull");
+	object(value.fields, "pull fields");
+	if (!Object.keys(value.fields).length || Object.keys(value.fields).length > 32) fail("pull requires 1 to 32 reviewed fields");
+	for (const [key, val] of Object.entries(value.fields)) { field(key); if (typeof val !== "string" || Buffer.byteLength(val) > 256 || /[\u0000-\u001f]/.test(val)) fail("invalid pull field value"); }
+	if (value.severity !== undefined && !WATCH_SEVERITIES.includes(value.severity)) fail("invalid pull severity");
+	if (value.contains !== undefined && (typeof value.contains !== "string" || value.contains.length > 256)) fail("invalid pull match");
+	if (value.kind === "file" && (typeof value.path !== "string" || !value.path.startsWith("/") || value.path.length > 4096 || /[\u0000-\u001f]/.test(value.path))) fail("pull file path must be absolute");
+	if (value.kind === "journald" && (typeof value.unit !== "string" || !/^[A-Za-z0-9_.@-]{1,128}$/.test(value.unit))) fail("invalid pull journal unit");
+	if (value.kind === "loki") {
+		let url; try { url = new URL(value.url); } catch { fail("invalid pull Loki URL"); }
+		if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || typeof value.query !== "string" || !value.query.length || value.query.length > 4096) fail("invalid pull Loki query endpoint");
+		if (value.secretEnv !== undefined && (typeof value.secretEnv !== "string" || !/^[A-Z][A-Z0-9_]{0,127}$/.test(value.secretEnv))) fail("invalid pull Loki secretEnv");
+	}
+	return { ...structuredClone(value), intervalSeconds: integer(value.intervalSeconds ?? 30, 5, 3600, "pull intervalSeconds") };
+}

package/src/watch-decision.mjs

@@ -0,0 +1,78 @@
+/** Pure watch admission policy. Provider calls and dollar reservations belong to the caller. */
+const ACTIONS = new Set(["investigate", "file_issue", "ignore"]);
+const NAME = /^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/;
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const fail = () => ({ ok: false, reason: "decide-refused" });
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+const safeName = (value) => typeof value === "string" && NAME.test(value) && !["constructor", "prototype", "__proto__", "samples", "message", "text"].includes(value);
+
+export function validateWatchDecision(value, { resolveModel = () => null } = {}) {
+	if (!record(value) || Object.keys(value).some((key) => !["model", "maxCostUsd", "questions", "act", "fields"].includes(key))) return fail();
+	if (typeof value.model !== "string" || value.model.length > 256 || !value.model.includes("/")) return fail();
+	if (typeof value.maxCostUsd !== "string" || !/^(?:0|[1-9]\d*)(?:\.\d{1,6})?$/.test(value.maxCostUsd)) return fail();
+	const capMicros = Math.round(Number(value.maxCostUsd) * 1e6);
+	if (!Number.isSafeInteger(capMicros)) return fail();
+	let model;
+	try { model = resolveModel(value.model); } catch { return fail(); }
+	if (!model || model.type !== "classifier" || !record(model.cost) || !finite(model.cost.input) || model.cost.input < 0 || model.cost.output !== 0) return fail();
+	if (!record(value.questions) || !Object.keys(value.questions).length || Object.keys(value.questions).length > 16) return fail();
+	for (const [name, question] of Object.entries(value.questions)) {
+		if (!safeName(name) || !record(question) || Object.keys(question).some((key) => !["type", "criteria", "instructions"].includes(key))) return fail();
+		if (!["choice", "bool", "noul", "score"].includes(question.type) || !record(question.criteria) || !Object.keys(question.criteria).length || Object.keys(question.criteria).length > 16) return fail();
+		if (question.instructions !== undefined && (typeof question.instructions !== "string" || question.instructions.length > 2048)) return fail();
+		for (const [option, criteria] of Object.entries(question.criteria)) if (!safeName(option) || typeof criteria !== "string" || criteria.length > 2048) return fail();
+		if (["bool", "noul"].includes(question.type) && Object.keys(question.criteria).sort().join() !== "false,true") return fail();
+	}
+	if (value.questions.act?.type !== "choice" || Object.keys(value.questions.act.criteria).some((option) => !ACTIONS.has(option))) return fail();
+	if (!record(value.act) || Object.keys(value.act).some((key) => !ACTIONS.has(key) && key !== "otherwise")) return fail();
+	if (value.act.otherwise !== undefined && value.act.otherwise !== "file_issue") return fail();
+	for (const [action, threshold] of Object.entries(value.act)) {
+		if (action === "otherwise") continue;
+		if (!Object.hasOwn(value.questions.act.criteria, action) || !finite(threshold) || threshold <= 0.5 || threshold > 1) return fail();
+	}
+	if (value.fields !== undefined && (!Array.isArray(value.fields) || value.fields.length > 32 || new Set(value.fields).size !== value.fields.length || !value.fields.every(safeName))) return fail();
+	if (Buffer.byteLength(JSON.stringify(value)) > 16384) return fail();
+	return { ok: true, config: JSON.parse(JSON.stringify(value)), capMicros };
+}
+
+/** Arbitrary fingerprint values and sample text are deliberately excluded from the default state. */
+export function projectWatchDecisionState(finding, fields = []) {
+	const state = {};
+	if (!record(finding)) return state;
+	for (const key of ["severity", "count", "firstSeen", "lastSeen", "window", ...fields]) {
+		if (!safeName(key)) continue;
+		const value = Object.hasOwn(finding, key) ? finding[key] : fields.includes(key) && record(finding.fields) && Object.hasOwn(finding.fields, key) ? finding.fields[key] : undefined;
+		if ((typeof value === "string" && Buffer.byteLength(value) <= 256 && !/[\u0000-\u001f\u007f]/.test(value)) || (finite(value) && value >= 0) || typeof value === "boolean") state[key] = value;
+	}
+	return state;
+}
+
+/** A trusted pinned-runtime bound is required; input-only pricing alone is no token bound. */
+export function prepareWatchDecision(config, finding, { resolveModel, boundCostMicros } = {}) {
+	const checked = validateWatchDecision(config, { resolveModel });
+	if (!checked.ok || typeof boundCostMicros !== "function") return fail();
+	const state = projectWatchDecisionState(finding, checked.config.fields);
+	let boundMicros;
+	try { boundMicros = boundCostMicros({ model: checked.config.model, state, questions: checked.config.questions }); } catch { return fail(); }
+	if (!Number.isSafeInteger(boundMicros) || boundMicros < 0 || boundMicros > checked.capMicros) return fail();
+	return { ...checked, state, boundMicros };
+}
+
+export function selectWatchDecision(config, result) {
+	const fallback = { action: "file_issue", reason: "decide-unanswered" };
+	if (!record(result) || result.stopReason !== "stop" || !record(result.answers)) return fallback;
+	const answer = result.answers.act;
+	if (!record(answer) || answer.type !== "choice" || !ACTIONS.has(answer.choice) || !record(answer.probabilities) || !finite(answer.confidence) || answer.confidence < 0 || answer.confidence > 1) return fallback;
+	const allowed = config?.questions?.act?.criteria;
+	if (!record(allowed) || !Object.hasOwn(allowed, answer.choice) || Object.keys(answer.probabilities).sort().join() !== Object.keys(allowed).sort().join()) return fallback;
+	let sum = 0;
+	for (const probability of Object.values(answer.probabilities)) {
+		if (!finite(probability) || probability < 0 || probability > 1) return fallback;
+		sum += probability;
+	}
+	if (Math.abs(sum - 1) > 0.000001) return fallback;
+	const probability = answer.probabilities[answer.choice];
+	const threshold = config.act?.[answer.choice];
+	if (!finite(threshold) || probability < threshold || Object.values(answer.probabilities).some((p) => p > probability)) return { ...fallback, probabilities: { ...answer.probabilities }, confidence: answer.confidence };
+	return { action: answer.choice, ...(answer.choice === "ignore" && { reason: "watch-ignored" }), probabilities: { ...answer.probabilities }, confidence: answer.confidence };
+}

package/src/watch-drainer.mjs

@@ -0,0 +1,14 @@
+/** The timer survives an initially empty registry: sources can be added by reviewed live configuration. */
+export function makeWatchDrainer({ runtime, intervalMs = 5000, setInterval: start = globalThis.setInterval, clearInterval: stop = globalThis.clearInterval, log = () => {} }) {
+	let closed = false;
+	let active = false;
+	const timer = start(() => {
+		if (closed || active) return;
+		active = true;
+		void Promise.resolve().then(() => { if (!closed) return runtime.drain(); }).catch(() => {
+			if (!closed) log("watch-handoff-unavailable", {});
+		}).finally(() => { active = false; });
+	}, intervalMs);
+	timer?.unref?.();
+	return { close() { if (closed) return; closed = true; stop(timer); } };
+}

package/src/watch-issue-adapter.mjs

@@ -0,0 +1,44 @@
+/** Reviewed forge context supplies endpoint and credential; findings supply neither. */
+export function makeWatchIssueAdapter({ getContext, fetchFn = fetch, maxPages = 10, timeoutMs = 10000 }) {
+	if (typeof getContext !== "function" || !Number.isSafeInteger(maxPages) || maxPages < 1 || maxPages > 20) throw new Error("invalid watch issue adapter configuration");
+	async function context(target) {
+		if (!["github", "gitlab", "forgejo"].includes(target?.kind)) throw new Error("watch issue forge unsupported");
+		if (typeof target.repo !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(target.repo) || target.repo.split("/").some(x => [".", ".."].includes(x))) throw new Error("invalid watch issue repository");
+		const config = await getContext(target); const url = new URL(config.apiUrl);
+		if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || typeof config.token !== "string" || !config.token) throw new Error("invalid watch issue API context");
+		const base = url.href.replace(/\/$/, "");
+		const repo = target.repo.split("/").map(encodeURIComponent).join("/");
+		const root = target.kind === "gitlab" ? `${base}${url.pathname.replace(/\/$/, "").endsWith("/api/v4") ? "" : "/api/v4"}/projects/${encodeURIComponent(target.repo)}/issues` : target.kind === "forgejo" ? `${base}${url.pathname.replace(/\/$/, "").endsWith("/api/v1") ? "" : "/api/v1"}/repos/${repo}/issues` : `${base}/repos/${repo}/issues`;
+		return { root, headers: target.kind === "gitlab" ? { "private-token": config.token } : { authorization: `Bearer ${config.token}` } };
+	}
+	async function request(ctx, suffix, method = "GET", data) {
+		let res;
+		try { res = await fetchFn(ctx.root + suffix, { method, redirect: "error", signal: AbortSignal.timeout(timeoutMs), headers: { ...ctx.headers, accept: "application/json", ...(data ? { "content-type": "application/json" } : {}) }, ...(data ? { body: JSON.stringify(data) } : {}) }); } catch { throw new Error("watch issue API unavailable"); }
+		if (!res.ok) { await res.body?.cancel?.(); throw new Error("watch issue API refused request"); }
+		if (Number(res.headers?.get?.("content-length")) > 1048576) { await res.body?.cancel?.(); throw new Error("watch issue response exceeds limit"); }
+		const chunks = []; let bytes = 0;
+		if (!res.body?.getReader) throw new Error("watch issue API response missing");
+		const reader = res.body.getReader();
+		try { while (true) { const { done, value } = await reader.read(); if (done) break; bytes += value.byteLength; if (bytes > 1048576) throw new Error("watch issue response exceeds limit"); chunks.push(Buffer.from(value)); } } catch { await reader.cancel().catch(() => {}); throw new Error("watch issue response unavailable"); } finally { reader.releaseLock(); }
+		try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { throw new Error("watch issue API response invalid"); }
+	}
+	function issueId(value, kind) { const id = kind === "gitlab" ? value?.iid : value?.number; if (!Number.isSafeInteger(id) || id < 1) throw new Error("watch issue API response invalid"); return { id }; }
+	return {
+		async createIssue({ target, title, body }) { const ctx = await context(target); const data = target.kind === "gitlab" ? { title, description: body } : { title, body }; return issueId(await request(ctx, "", "POST", data), target.kind); },
+		async updateIssue({ target, id, title, body, state }) { if (!/^[1-9][0-9]{0,14}$/.test(String(id))) throw new Error("invalid watch issue id"); const ctx = await context(target); const data = { ...(title !== undefined ? { title } : {}), ...(body !== undefined ? target.kind === "gitlab" ? { description: body } : { body } : {}), ...(state === "open" ? target.kind === "gitlab" ? { state_event: "reopen" } : { state: "open" } : {}) }; await request(ctx, `/${id}`, target.kind === "gitlab" ? "PUT" : "PATCH", data); },
+		async closeIssue({ target, id }) { if (!/^[1-9][0-9]{0,14}$/.test(String(id))) throw new Error("invalid watch issue id"); const ctx = await context(target); await request(ctx, `/${id}`, target.kind === "gitlab" ? "PUT" : "PATCH", target.kind === "gitlab" ? { state_event: "close" } : { state: "closed" }); },
+		async findIssue({ target, marker }) {
+			if (typeof marker !== "string" || !/^pi-dispatch-watch:[a-f0-9]{64}$/.test(marker)) throw new Error("invalid watch issue marker");
+			const ctx = await context(target);
+			for (let page = 1; page <= maxPages; page++) {
+				const rows = await request(ctx, `?state=all&${target.kind === "forgejo" ? "limit" : "per_page"}=100&page=${page}`);
+				if (!Array.isArray(rows) || rows.length > 100) throw new Error("watch issue API response invalid");
+				const found = rows.filter(row => !row.pull_request && String(target.kind === "gitlab" ? row.description ?? "" : row.body ?? "").includes(`<!-- ${marker} -->`));
+				if (found.length > 1) throw new Error("watch issue marker ambiguous");
+				if (found.length === 1) return issueId(found[0], target.kind);
+				if (rows.length < 100) return null;
+			}
+			throw new Error("watch issue reconciliation page limit reached");
+		},
+	};
+}