@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/src/watch-issue.mjs

@@ -0,0 +1,111 @@
+import { createHash, randomUUID } from "node:crypto";
+import { watchDurationMs } from "./watch-contract.mjs";
+
+export const WATCH_ISSUES_PER_SOURCE_MAX = 4096;
+export function issueIdentity(target, source, ruleId, fingerprint) {
+	if (!/^[A-Za-z0-9_-]{1,64}$/.test(source) || !/^[A-Za-z0-9_-]{1,64}$/.test(ruleId) || !/^[a-f0-9]{64}$/.test(fingerprint) || !["github", "gitlab", "forgejo"].includes(target?.kind) || 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 identity");
+	// Quiet policy is mutable reviewed config, never part of the remote issue's permanent identity.
+	return createHash("sha256").update(JSON.stringify([{ kind: target.kind, repo: target.repo }, source, ruleId, fingerprint])).digest("hex");
+}
+export const WATCH_ISSUE_ACTIVITY_SCRIPT = `-- watch-issue-activity
+if not redis.call('GET',KEYS[2]) then return cjson.encode({at=tonumber(ARGV[1]),version=0}) end
+local raw=redis.call('GET',KEYS[1]); local activity=raw and cjson.decode(raw) or {at=0,version=0}
+activity.at=math.max(activity.at,tonumber(ARGV[1])); activity.version=activity.version+1
+redis.call('SET',KEYS[1],cjson.encode(activity),'PX',2678400000)
+local mapped=redis.call('GET',KEYS[2]); if mapped then local m=cjson.decode(mapped); if m.closeAfterMs and m.state=='mapped' then redis.call('ZADD',KEYS[3],activity.at+m.closeAfterMs,ARGV[2]) end end
+return cjson.encode(activity)`;
+export async function noteWatchIssueActivity(redis, { target, source, ruleId, fingerprint }, { prefix = "watch:issue", now = () => Date.now() } = {}) {
+	const identity = issueIdentity(target, source, ruleId, fingerprint);
+	return JSON.parse(await redis.eval(WATCH_ISSUE_ACTIVITY_SCRIPT, 3, `${prefix}:activity:${identity}`, `${prefix}:${identity}`, `${prefix}:quiet`, now(), identity));
+}
+const RESERVE = `-- watch-issue-reserve
+local existing=redis.call('GET',KEYS[1]); if existing then return cjson.encode({owner=false,mapping=cjson.decode(existing)}) end
+if redis.call('ZCARD',KEYS[2])>=tonumber(ARGV[1]) then return cjson.encode({capped=true}) end
+redis.call('ZADD',KEYS[2],ARGV[2],ARGV[3]); redis.call('SET',KEYS[1],ARGV[4]); return cjson.encode({owner=true,mapping=cjson.decode(ARGV[4])})`;
+const CLAIM = `-- watch-issue-close-claim
+if redis.call('GET',KEYS[1])~=ARGV[1] then return 0 end
+if redis.call('GET',KEYS[2])~=ARGV[2] then return 0 end
+return redis.call('SET',KEYS[3],ARGV[3],'NX','PX',30000) and 1 or 0`;
+const COMMIT = `-- watch-issue-close-commit
+if redis.call('GET',KEYS[3])~=ARGV[1] then return 0 end
+if redis.call('GET',KEYS[1])~=ARGV[2] then return 0 end
+if redis.call('GET',KEYS[2])~=ARGV[3] then return 0 end
+redis.call('SET',KEYS[1],ARGV[4]); redis.call('ZREM',KEYS[4],ARGV[5]); return 1`;
+const UNLOCK = `-- watch-issue-unlock
+if redis.call('GET',KEYS[1])==ARGV[1] then return redis.call('DEL',KEYS[1]) end return 0`;
+
+/** Forge adapters own transport. Pending writes reconcile by marker, never blind-create again. */
+export function makeWatchIssuePublisher({ redis, adapter, prefix = "watch:issue", now = () => Date.now(), maxPerSource = WATCH_ISSUES_PER_SOURCE_MAX, canClose = async () => false, reportClose = async () => {} }) {
+	for (const method of ["findIssue", "createIssue", "updateIssue"]) if (typeof adapter?.[method] !== "function") throw new Error("watch issue adapter is incomplete");
+	if (!Number.isSafeInteger(maxPerSource) || maxPerSource < 1 || maxPerSource > WATCH_ISSUES_PER_SOURCE_MAX) throw new Error("invalid watch issue index bound");
+	const activityKey = id => `${prefix}:activity:${id}`;
+	const noteActivity = args => noteWatchIssueActivity(redis, args, { prefix, now });
+	const schedule = async (identity, mapping) => { if (mapping.closeAfterMs) { const activity = JSON.parse(await redis.get(activityKey(identity))); await redis.zadd(`${prefix}:quiet`, activity.at + mapping.closeAfterMs, identity); } };
+	const publish = async function publishWatchIssue({ source, ruleId, fingerprint, finding, target }) {
+		const identity = issueIdentity(target, source, ruleId, fingerprint);
+		const closeAfterMs = target.closeAfter === undefined ? undefined : watchDurationMs(target.closeAfter);
+		if (closeAfterMs && typeof adapter.closeIssue !== "function") throw new Error("watch issue quiet closure unsupported");
+		const key = `${prefix}:${identity}`; const marker = `pi-dispatch-watch:${identity}`;
+		const pending = { state: "pending", marker, source, ruleId, fingerprint, target: { kind: target.kind, repo: target.repo }, ...(closeAfterMs ? { closeAfterMs } : {}) };
+		const reserved = JSON.parse(await redis.eval(RESERVE, 2, key, `${prefix}:source:${source}`, maxPerSource, now(), identity, JSON.stringify(pending)));
+		if (reserved.capped) return { status: "capped", reason: "watch-issue-cap" };
+		await noteActivity({ source, ruleId, fingerprint, target });
+		let mapping = reserved.mapping;
+		const title = `[watch] ${ruleId} ${fingerprint.slice(0, 12)}`;
+		const count = Number.isSafeInteger(finding.count) && finding.count >= 0 ? finding.count : 0;
+		const severity = ["debug", "info", "warning", "error", "critical"].includes(finding.severity) ? finding.severity : "unknown";
+		const body = `<!-- ${marker} -->\nWatch rule: ${ruleId}\nSource: ${source}\nFingerprint: ${fingerprint}\nSeverity: ${severity}\nEvents: ${count}\n\nA person with repository write access must apply the configured label before code work starts.`;
+		if (!reserved.owner && mapping.state === "pending") {
+			let found; try { found = await adapter.findIssue({ target, marker }); } catch { throw new Error("watch issue reconciliation unavailable"); }
+			if (!found) return { status: "uncertain", reason: "watch-issue-uncertain" };
+			mapping = { ...pending, state: "mapped", issueId: String(found.id) };
+			await redis.set(key, JSON.stringify(mapping));
+		}
+		if (mapping.issueId !== undefined) {
+			try { await adapter.updateIssue({ target, id: mapping.issueId, title, body, state: "open" }); } catch { throw new Error("watch issue update unavailable"); }
+			mapping = { ...pending, state: "mapped", issueId: mapping.issueId };
+			await redis.set(key, JSON.stringify(mapping)); await schedule(identity, mapping);
+			if (!closeAfterMs) await redis.zrem(`${prefix}:quiet`, identity);
+			return { status: "updated", issueId: mapping.issueId };
+		}
+		let issue; try { issue = await adapter.createIssue({ target, title, body, marker }); } catch { throw new Error("watch issue create outcome unknown"); }
+		if (!issue || issue.id === undefined) throw new Error("watch issue create outcome unknown");
+		mapping = { ...pending, state: "mapped", issueId: String(issue.id) };
+		await redis.set(key, JSON.stringify(mapping)); await schedule(identity, mapping);
+		return { status: "created", issueId: mapping.issueId };
+	};
+	publish.noteActivity = noteActivity;
+	publish.sweep = async function sweep() {
+		const outcomes = [];
+		const report = async (outcome, mapping) => { outcomes.push(outcome); try { await reportClose(outcome, mapping); } catch {} };
+		for (const identity of await redis.zrangebyscore(`${prefix}:quiet`, "-inf", now(), "LIMIT", 0, 128)) {
+			if (!/^[a-f0-9]{64}$/.test(identity)) continue;
+			const key = `${prefix}:${identity}`; const lock = `${prefix}:closing:${identity}`;
+			const raw = await redis.get(key); const activityRaw = await redis.get(activityKey(identity));
+			let mapping; let activity;
+			try { mapping = JSON.parse(raw); activity = JSON.parse(activityRaw); } catch { await report({ identity, status: "uncertain", reason: "watch-issue-close-uncertain" }, null); continue; }
+			if (!mapping?.closeAfterMs || mapping.state !== "mapped") { await redis.zrem(`${prefix}:quiet`, identity); continue; }
+			if (!activity || activity.at + mapping.closeAfterMs > now()) { if (activity) await redis.zadd(`${prefix}:quiet`, activity.at + mapping.closeAfterMs, identity); continue; }
+			let allowed = false; try { allowed = await canClose(mapping); } catch {}
+			if (!allowed) { await redis.zrem(`${prefix}:quiet`, identity); await report({ identity, status: "suppressed", reason: "watch-issue-close-policy-changed" }, mapping); continue; }
+			const token = randomUUID();
+			if (!await redis.eval(CLAIM, 3, key, activityKey(identity), lock, raw, activityRaw, token)) continue;
+			try {
+				await adapter.closeIssue({ target: mapping.target, id: mapping.issueId });
+				const closed = { ...mapping, state: "closed" };
+				const committed = await redis.eval(COMMIT, 4, key, activityKey(identity), lock, `${prefix}:quiet`, token, raw, activityRaw, JSON.stringify(closed), identity);
+				if (!committed) {
+					// A collector advanced activity during the remote close. Reopen rather than hide that race.
+					await adapter.updateIssue({ target: mapping.target, id: mapping.issueId, state: "open" });
+					const current = JSON.parse(await redis.get(key));
+					if (current?.state === "closed") await redis.set(key, JSON.stringify({ ...current, state: "mapped" }));
+					await schedule(identity, mapping);
+					await report({ identity, status: "active", reason: "watch-issue-close-raced" }, mapping);
+				} else await report({ identity, status: "closed" }, mapping);
+			} catch { await report({ identity, status: "uncertain", reason: "watch-issue-close-uncertain" }, mapping); }
+			finally { await redis.eval(UNLOCK, 1, lock, token); }
+		}
+		return outcomes;
+	};
+	return publish;
+}

package/src/watch-record.mjs

@@ -0,0 +1,10 @@
+/** Only reviewed names and numeric answers may enter a durable run record. */
+export function recordedWatchDecision(value) {
+	if (!value || typeof value !== "object" || !["investigate", "file_issue", "ignore"].includes(value.action) || typeof value.model !== "string" || !/^[A-Za-z0-9_.:/@~-]{1,128}$/.test(value.model)) return null;
+	const out = { model: value.model, action: value.action, shadow: value.shadow === true };
+	if (Array.isArray(value.questions) && value.questions.length <= 16 && value.questions.every(n => /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(n))) out.questions = [...value.questions];
+	if (value.probabilities && Object.keys(value.probabilities).every(k => ["investigate", "file_issue", "ignore"].includes(k)) && Object.values(value.probabilities).every(p => Number.isFinite(p) && p >= 0 && p <= 1)) out.probabilities = { ...value.probabilities };
+	if (Number.isFinite(value.confidence) && value.confidence >= 0 && value.confidence <= 1) out.confidence = value.confidence;
+	if (Number.isFinite(value.costUsd) && value.costUsd >= 0) out.costUsd = value.costUsd;
+	return out;
+}

package/src/watch-runtime.mjs

@@ -0,0 +1,167 @@
+import { collectedWatchTrace } from "./watch-trace.mjs";
+import { makeRedactor } from "./redact-secrets.mjs";
+import { recordedWatchDecision } from "./watch-record.mjs";
+import * as nodeFs from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { parseTriggersDocument } from "./triggers.mjs";
+import { selectWatchDecision, projectWatchDecisionState } from "./watch-decision.mjs";
+import { validateWatchBoard } from "./watch-board.mjs";
+
+const digest = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const refusal = reason => ({ outcome: "policy", reason, budgetReserved: false });
+const modelRef = ref => { const at = ref.indexOf("/"); return { provider: ref.slice(0, at), id: ref.slice(at + 1) }; };
+
+/** Open the inode once: an agent may replace an outbox path, including with a FIFO or symlink. */
+export function readWatchOutput(path, maxBytes, fs = nodeFs) {
+	let fd;
+	try {
+		fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+		const stat = fs.fstatSync(fd);
+		if (!stat.isFile() || stat.size > maxBytes) return null;
+		const bytes = Buffer.alloc(maxBytes + 1);
+		let used = 0;
+		while (used < bytes.length) { const n = fs.readSync(fd, bytes, used, bytes.length - used, null); if (!n) break; used += n; }
+		return used > maxBytes ? null : bytes.subarray(0, used).toString("utf8");
+	} catch { return null; } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
+
+function refusedOutput(path, maxBytes, fs) {
+	try { const stat = fs.lstatSync(path); return stat.size > maxBytes ? "watch-board-oversize" : "watch-board-invalid"; }
+	catch (error) { return error?.code === "ENOENT" ? null : "watch-board-invalid"; }
+}
+
+/** Producer references are resolved again at pickup; queue bytes never select execution settings. */
+export function makeWatchRuntime({ store, triggersPath, readFile = nodeFs.readFileSync, enqueue, publishIssue, getSettings = () => ({}), pauseUntil = () => null, now = Date.now, fs = nodeFs, log = () => {} }) {
+	const document = () => parseTriggersDocument(readFile(triggersPath, "utf8"), triggersPath);
+	const currentRule = (doc, id) => doc.triggers.find(t => t.on.type === "watch" && t.on.id === id);
+	let draining = false;
+	return {
+		async started(job) {
+			if (job.watch?.stage !== "decision") return;
+			await store.updateFinding(job.watch.findingId, { status: "deciding", runId: job.watch.runId });
+			await store.scheduleAction(job.watch.findingId, job.watch.ruleId, now() + 35 * 60 * 1000);
+		},
+		async drain() {
+			if (draining) return;
+			draining = true;
+			try {
+			if (publishIssue?.sweep) for (const outcome of await publishIssue.sweep()) log("watch_issue_close", { identity: outcome.identity, status: outcome.status, ...(outcome.reason ? { reason: outcome.reason } : {}) });
+			for (const fields of await store.pendingActions()) {
+				if (!await store.readFinding(fields.id)) { await store.acknowledgeAction(fields.id); continue; }
+				await enqueue(fields, { phase: "action" });
+			}
+			} finally { draining = false; }
+		},
+		async resolve(data, runId) {
+			if (data?.kind !== "watch" && !data?.watch) return { data };
+			const ref = data.watch;
+			if (!ref || !/^[a-f0-9]{64}$/.test(ref.findingId) || !["dispatch", "action"].includes(ref.phase)) return { result: refusal("watch-reference-invalid") };
+			// Issue #761: a read of a file a newer pi-dispatch wrote is `{ newer: <the store> }`, never `watch-config-changed`,
+			// and is answered BEFORE the finding is taken (a take cannot be undone): the processor defers the job
+			// (`newer-release`) and this build neither misreads the rule nor spends the finding.
+			let doc;
+			try { doc = document(); } catch (error) { if (error?.newer === true) return { newer: "the triggers file" }; if (error?.piDispatchConfig || error?.code === "ENOENT") return { result: refusal("watch-config-changed") }; throw error; }
+			const rule = currentRule(doc, ref.ruleId);
+			if (!rule || !doc.watchSources?.[rule.on.source]) return { result: refusal("watch-config-changed") };
+			const target = rule.run.mode === "issue" ? { kind: rule.run.issue.kind, repo: rule.run.issue.repo } : { kind: "local", folder: rule.run.folder };
+			const until = pauseUntil(target, now());
+			if (Number.isFinite(until) && until > now()) return { deferUntil: until };
+			// The settings a decision reads, read ONCE and before the take (issue #761), so a newer overlay defers the job
+			// with the finding still in place. Only a deciding rule's dispatch can become a decision, so only it reads them.
+			const settings = rule.decide && ref.phase === "dispatch" ? getSettings() : null;
+			if (settings?.invalid && settings.newer === true) return { newer: "the settings file" };
+			const taken = await store.takeFinding(ref.findingId);
+			if (taken.status !== "ready") return { result: refusal(taken.status === "below-threshold" ? "watch-threshold" : taken.status === "held" ? "watch-window-pending" : "watch-evidence-expired") };
+			const finding = taken.finding;
+			if (finding.ruleId !== ref.ruleId || finding.source !== rule.on.source) return { result: refusal("watch-reference-invalid") };
+			if (finding.policyDigest && finding.policyDigest !== digest(rule)) return { result: refusal("watch-config-changed") };
+			const latest = await store.readFinding(ref.findingId, { private: true });
+			if (ref.phase === "action") await store.acknowledgeAction(ref.findingId);
+			const decision = recordedWatchDecision(latest?.decision);
+			let phase = "investigate";
+			let action = rule.run.mode === "issue" ? "file_issue" : "investigate";
+			if (rule.decide) {
+				if (ref.phase === "dispatch" && !decision && latest?.status !== "deciding") phase = "decision";
+				else action = decision ? (rule.decide.shadow ? "investigate" : decision.action) : "file_issue";
+			}
+			if (phase !== "decision" && action === "ignore") { await store.updateFinding(ref.findingId, { status: "ignored", reason: "watch-ignored" }); return { result: { outcome: "completed", reason: "watch-ignored", budgetReserved: false, ...(decision ? { decision } : {}) } }; }
+			if (phase !== "decision" && action === "file_issue") {
+				if (!rule.run.issue || typeof publishIssue !== "function") return { result: refusal("watch-issue-target-missing") };
+				const published = await publishIssue({ source: finding.source, ruleId: ref.ruleId, fingerprint: finding.fingerprint, finding, target: rule.run.issue });
+				await store.updateFinding(ref.findingId, { status: published.status === "uncertain" ? "issue-uncertain" : published.status === "capped" ? "capped" : "issue", ...(published.reason ? { reason: published.reason } : {}) });
+				return { result: { outcome: ["uncertain", "capped"].includes(published.status) ? "policy" : "completed", budgetReserved: false, ...(published.reason ? { reason: published.reason } : {}), ...(decision ? { decision } : {}) } };
+			}
+			const board = await store.readBoard(ref.ruleId);
+			const execution = { ...rule.run };
+			delete execution.mode; delete execution.issue; delete execution.queryLogs;
+			const watch = { findingId: ref.findingId, ruleId: ref.ruleId, phase: ref.phase, configDigest: digest(rule), ...(decision ? { decision } : {}) };
+			// BullMQ deferrals may persist job.data. Private evidence must survive in memory without
+			// becoming queue data when an unrelated admission gate persists its data.
+			Object.defineProperties(watch, { stage: { value: phase }, project: { value: doc.watchSources[rule.on.source].project ?? null }, runId: { value: runId }, finding: { value: finding }, board: { value: { version: 1, blocks: board.blocks } }, queries: { value: rule.run.queryLogs ?? {} } });
+			if (phase === "decision") {
+				Object.defineProperty(watch, "gate", { value: { version: 1, model: modelRef(rule.decide.model), state: projectWatchDecisionState({ ...finding, window: rule.on.window }, rule.decide.fields), questions: rule.decide.questions } });
+				execution.maxCostUsd = rule.decide.maxCostUsd;
+				// The read from before the take: a broken overlay is still refused here, as it always was.
+				if (settings.invalid) return { result: refusal("watch-config-changed") };
+				const primary = `${execution.provider ?? settings.provider}/${execution.model ?? settings.model}`;
+				execution.models = [...new Set([...(execution.models ?? []), primary, rule.decide.model])];
+				await store.updateFinding(ref.findingId, { status: "decision-pending", runId });
+			} else await store.updateFinding(ref.findingId, { status: "running", runId });
+			await store.appendTrace(ref.findingId, { id: `${runId}:admit`, kind: "rule", status: phase, ruleId: ref.ruleId, count: finding.count });
+			return { data: { ...execution, kind: "local", github: false, packages: false, watch, ...(rule.decide ? { watchDecisionModel: modelRef(rule.decide.model) } : {}) } };
+		},
+		/** A completed paid attempt is never retried because collecting its output failed. */
+		async collect({ job, prepared, completed, policyRefused = false, usage }) {
+			if (!job.watch || !prepared?.outboxDir) return;
+			const watch = job.watch;
+			const redact = prepared.watchRedact ?? makeRedactor();
+			const privateEntry = entry => JSON.parse(redact(JSON.stringify(entry)));
+			try {
+				const raw = readWatchOutput(join(prepared.outboxDir, "watch-trace.jsonl"), 262144, fs);
+				const traceIds = new Set();
+				let traceUnavailable = false;
+				if (raw === null && refusedOutput(join(prepared.outboxDir, "watch-trace.jsonl"), 262144, fs)) traceUnavailable = true;
+				if (raw !== null) for (const line of raw.split("\n").filter(Boolean).slice(0, 128)) {
+					let entry; try { entry = JSON.parse(line); } catch { traceUnavailable = true; continue; }
+					const projected = collectedWatchTrace(entry, { model: job.watchDecisionModel ? `${job.watchDecisionModel.provider}/${job.watchDecisionModel.id}` : null, ruleId: watch.ruleId, runId: watch.runId });
+					if (!projected) { traceUnavailable = true; continue; }
+					if (["query", "decide"].includes(entry.kind) && entry.status === "completed") traceIds.add(entry.id);
+					try { await store.appendTrace(watch.findingId, privateEntry(projected)); } catch { traceUnavailable = true; }
+				}
+				let rule;
+				try { rule = currentRule(document(), watch.ruleId); } catch {}
+				if (!rule || digest(rule) !== watch.configDigest) { await store.updateFinding(watch.findingId, { status: "refused", reason: "watch-config-changed" }); return; }
+				if (watch.stage === "decision") {
+					let output; try { output = JSON.parse(readWatchOutput(join(prepared.outboxDir, "decision.json"), 16384, fs)); } catch {}
+					const selected = completed ? selectWatchDecision(rule.decide, output) : { action: "file_issue", reason: policyRefused ? "decide-refused" : "decide-unanswered" };
+					const summary = recordedWatchDecision({ ...selected, model: rule.decide.model, questions: Object.keys(rule.decide.questions), shadow: rule.decide.shadow, costUsd: usage?.costUsd });
+					watch.decision = summary;
+					try { await store.appendTrace(watch.findingId, privateEntry({ id: "decision", kind: "decide", state: watch.gate.state, questions: rule.decide.questions, ...summary, modelReviewed: true, status: selected.reason ?? "answered" })); } catch { traceUnavailable = true; }
+					await store.updateFinding(watch.findingId, { status: "decided", decision: summary, ...(selected.reason ? { reason: selected.reason } : {}) });
+					await store.scheduleAction(watch.findingId, watch.ruleId);
+					await enqueue({ id: watch.findingId, ruleId: watch.ruleId, dueAt: now() }, { phase: "action" });
+				} else {
+					const boardRaw = completed ? readWatchOutput(join(prepared.outboxDir, "board.json"), 16384, fs) : null;
+					const boardProblem = completed && boardRaw === null ? refusedOutput(join(prepared.outboxDir, "board.json"), 16384, fs) : null;
+					if (boardProblem) await store.appendTrace(watch.findingId, { id: "board-refused", kind: "board", status: boardProblem });
+					if (boardRaw !== null && !traceUnavailable) {
+						const checked = validateWatchBoard(redact(boardRaw), { traceIds });
+						if (checked.ok) {
+							for (const block of checked.board.blocks) block.traceId = `${watch.runId}:${block.traceId}`;
+							const remapped = validateWatchBoard(checked.board);
+							if (remapped.ok) await store.proposeBoard(watch.ruleId, checked.board, watch.findingId);
+							else await store.appendTrace(watch.findingId, { id: "board-refused", kind: "board", status: remapped.reason });
+						}
+						else await store.appendTrace(watch.findingId, { id: "board-refused", kind: "board", status: checked.reason });
+					}
+					await store.updateFinding(watch.findingId, { status: completed ? "completed" : "failed" });
+				}
+				if (traceUnavailable) await store.updateFinding(watch.findingId, { reason: "watch-trace-unavailable" });
+			} catch {
+				log("watch-output-unavailable", { ruleId: watch.ruleId });
+				try { await store.updateFinding(watch.findingId, { status: "unavailable", reason: "watch-output-unavailable" }); } catch {}
+			}
+		},
+	};
+}

package/src/watch-store.mjs

@@ -0,0 +1,183 @@
+import { publicWatchTrace } from "./watch-trace.mjs";
+import { recordedWatchDecision } from "./watch-record.mjs";
+import { noteWatchIssueActivity } from "./watch-issue.mjs";
+import { createHash } from "node:crypto";
+import { validateWatchBoard as checkBoard } from "./watch-board.mjs";
+import { watchFingerprint, matchesWatchFinding, watchDurationMs } from "./watch-contract.mjs";
+
+const TTL_MS = 7 * 86400000;
+// One script owns replay, digest and caps: a receiver crash between separate writes must never
+// consume a delivery without leaving the same enqueueable finding for its retry.
+export const WATCH_INGEST_SCRIPT = `
+local now = tonumber(ARGV[1])
+local ttl = tonumber(ARGV[2])
+local replay = redis.call('GET', KEYS[1])
+if replay then return replay end
+local sourceCount = tonumber(redis.call('GET', KEYS[2]) or '0')
+if sourceCount >= tonumber(ARGV[3]) then return cjson.encode({status='capped',reason='watch-cap'}) end
+redis.call('INCR', KEYS[2]); redis.call('PEXPIRE', KEYS[2], 172800000)
+redis.call('ZREMRANGEBYSCORE', KEYS[4], '-inf', now)
+local active = redis.call('GET', KEYS[3])
+local result
+if active then
+ local a = cjson.decode(active)
+ if now > a.dueAt + tonumber(ARGV[7]) then redis.call('DEL', KEYS[3]); active=nil end
+end
+if active then
+ local a = cjson.decode(active)
+ if now <= a.dueAt then
+  local existing = redis.call('GET', ARGV[12] .. ':finding:' .. a.id)
+  if existing then
+   local f = cjson.decode(existing)
+   if not f.claimed then
+   local incoming = cjson.decode(ARGV[8])
+   f.count = math.min(1000000, f.count + incoming.count)
+   if incoming.firstSeen < f.firstSeen then f.firstSeen = incoming.firstSeen end
+   if incoming.lastSeen > f.lastSeen then f.lastSeen = incoming.lastSeen end
+   for _, sample in ipairs(incoming.samples) do if #f.samples < 8 then table.insert(f.samples, sample) end end
+   redis.call('SET', ARGV[12] .. ':finding:' .. a.id, cjson.encode(f), 'PX', ttl)
+   result = cjson.encode({status='held',id=a.id,fingerprint=ARGV[9],dueAt=a.dueAt})
+   end
+  end
+ end
+ if not result then result = cjson.encode({status='suppressed',id=a.id,fingerprint=ARGV[9],dueAt=a.dueAt,reason='watch-cooldown'}) end
+elseif redis.call('ZCARD', KEYS[4]) >= tonumber(ARGV[4]) or tonumber(redis.call('GET', KEYS[5]) or '0') >= tonumber(ARGV[5]) then
+ result = cjson.encode({status='capped',reason='watch-cap',fingerprint=ARGV[9]})
+else
+ local due = now + tonumber(ARGV[6])
+ local a = {id=ARGV[10],dueAt=due}
+ local f = cjson.decode(ARGV[8]); f.id=ARGV[10]; f.fingerprint=ARGV[9]; f.dueAt=due; f.createdAt=now
+ f.source=ARGV[11]; f.ruleId=ARGV[13]; f.status='held'; f.minCount=tonumber(ARGV[15])
+ redis.call('SET', KEYS[3], cjson.encode(a), 'PX', tonumber(ARGV[6])+tonumber(ARGV[7]))
+ redis.call('ZADD', KEYS[4], due+tonumber(ARGV[7]), ARGV[9]); redis.call('PEXPIRE', KEYS[4], ttl+tonumber(ARGV[7]))
+ redis.call('INCR', KEYS[5]); redis.call('PEXPIRE', KEYS[5], 172800000)
+ redis.call('SET', ARGV[12] .. ':finding:' .. ARGV[10], cjson.encode(f), 'PX', ttl)
+ redis.call('ZADD', KEYS[6], now, ARGV[10]); redis.call('ZREMRANGEBYSCORE', KEYS[6], '-inf', now-ttl); redis.call('PEXPIRE', KEYS[6], ttl)
+ redis.call('HSET', KEYS[7], ARGV[13], ARGV[14]); redis.call('PEXPIRE', KEYS[7], ttl)
+ result = cjson.encode({status='held',id=ARGV[10],fingerprint=ARGV[9],dueAt=due})
+end
+redis.call('SET', KEYS[1], result, 'PX', ttl)
+return result
+`;
+const BOARD_SCRIPT = `
+local raw=redis.call('GET',KEYS[1]); local b
+if raw then b=cjson.decode(raw) else b=cjson.decode(ARGV[1]) end
+if b.version ~= tonumber(ARGV[2]) then return cjson.encode({ok=false,reason='board-conflict',board=b}) end
+local change=cjson.decode(ARGV[3])
+if change.action=='freeze' then b.frozen=change.frozen
+elseif change.action=='clear' then b.blocks={}; b.proposals={}
+elseif change.action=='adopt' then
+ if b.frozen then return cjson.encode({ok=false,reason='board-frozen',board=b}) end
+ local found=false
+ for _,p in ipairs(b.proposals or {}) do if p.id==change.proposalId then b.blocks=p.blocks; found=true end end
+ if not found then return cjson.encode({ok=false,reason='board-proposal-missing',board=b}) end
+elseif change.action=='revert' then
+ local found=false
+ for _,v in ipairs(b.versions) do if v.version==change.version then b.blocks=v.blocks; found=true end end
+ if not found then return cjson.encode({ok=false,reason='board-version-missing',board=b}) end
+else return cjson.encode({ok=false,reason='board-action-invalid',board=b}) end
+b.version=b.version+1
+table.insert(b.versions,{version=b.version,blocks=b.blocks})
+while #b.versions>20 do table.remove(b.versions,1) end
+redis.call('SET',KEYS[1],cjson.encode(b),'PX',ARGV[4])
+return cjson.encode({ok=true,board=b})
+`;
+function validId(value) { if (typeof value !== "string" || !/^[a-zA-Z0-9_-]{1,128}$/.test(value)) throw new Error("invalid watch identifier"); return value; }
+const hash = value => createHash("sha256").update(value).digest("hex");
+const parse = raw => raw ? JSON.parse(raw) : null;
+function boardArrays(board) { if (!Array.isArray(board.blocks)) board.blocks = []; if (!Array.isArray(board.versions)) board.versions = []; if (!Array.isArray(board.proposals)) board.proposals = []; for (const proposal of board.proposals) if (!Array.isArray(proposal.blocks)) proposal.blocks = []; for (const version of board.versions) if (!Array.isArray(version.blocks)) version.blocks = []; return board; }
+const publicFinding = f => f && { ...Object.fromEntries(["id", "source", "ruleId", "fingerprint", "severity", "count", "firstSeen", "lastSeen", "dueAt", "createdAt", "status", "reason", "runId"].filter(k => f[k] !== undefined).map(k => [k, f[k]])), ...(recordedWatchDecision(f.decision) ? { decision: recordedWatchDecision(f.decision) } : {}) };
+export function makeWatchStore(redis, { now = () => Date.now(), prefix = "watch", sourceCaps = {} } = {}) {
+	const key = suffix => `${prefix}:${suffix}`;
+	const emptyBoard = ruleId => ({ ruleId, version: 0, frozen: false, blocks: [], versions: [], proposals: [] });
+	return {
+		async noteIssueActivity(args) { return noteWatchIssueActivity(redis, args, { now }); },
+		async recordIssueOutcome(ruleId, outcome) {
+			validId(ruleId);
+			if (!["closed", "active", "uncertain", "suppressed"].includes(outcome.status) || (outcome.reason !== undefined && !["watch-issue-close-uncertain", "watch-issue-close-raced", "watch-issue-close-policy-changed"].includes(outcome.reason))) throw new Error("invalid watch issue outcome");
+			await redis.multi().hset(key(`summary:${ruleId}`), "lastIssueStatus", outcome.status, "lastIssueReason", outcome.reason ?? "").pexpire(key(`summary:${ruleId}`), TTL_MS).exec();
+		},
+		async scheduleAction(id, ruleId, dueAt = now()) {
+			validId(id); validId(ruleId);
+			await redis.multi().hset(key("pending-action-rules"), id, ruleId).zadd(key("pending-actions"), dueAt, id).exec();
+		},
+		async pendingActions() {
+			const ids = await redis.zrangebyscore(key("pending-actions"), "-inf", now(), "LIMIT", 0, 100);
+			return (await Promise.all(ids.map(async id => ({ id, ruleId: await redis.hget(key("pending-action-rules"), id), dueAt: now() })))).filter(row => row.ruleId);
+		},
+		async acknowledgeAction(id) { validId(id); await redis.multi().zrem(key("pending-actions"), id).hdel(key("pending-action-rules"), id).exec(); },
+		async ingest({ source, rule, finding, delivery, sourceMaxPerDay }) {
+			validId(source); validId(rule.id); validId(delivery);
+			if (!matchesWatchFinding(rule, finding)) return { status: "unmatched", reason: "watch-unmatched" };
+			const fingerprint = watchFingerprint(source, rule, finding);
+			const clock = now(); const day = new Date(clock).toISOString().slice(0, 10);
+			const id = hash(JSON.stringify([source, rule.id, fingerprint, delivery, clock]));
+			const ruleKey = `${source}:${rule.id}`;
+			const result = await redis.eval(WATCH_INGEST_SCRIPT, 7,
+				key(`delivery:${source}:${rule.id}:${delivery}`), key(`source-day:${source}:${day}`), key(`active:${ruleKey}:${fingerprint}`), key(`fingerprints:${ruleKey}`), key(`rule-day:${ruleKey}:${day}`), key(`findings:${rule.id}`), key("rules"),
+				clock, TTL_MS, sourceMaxPerDay ?? sourceCaps[source] ?? 1000, rule.maxFingerprints ?? 256, rule.maxPerDay, rule.windowMs ?? watchDurationMs(rule.window), rule.cooldownMs ?? watchDurationMs(rule.cooldown), JSON.stringify(finding), fingerprint, id, source, prefix, rule.id, JSON.stringify({ id: rule.id, source, maxPerDay: rule.maxPerDay }), rule.minCount ?? 1);
+			return parse(result);
+		},
+		async takeFinding(id) {
+			validId(id);
+			const script = `local raw=redis.call('GET',KEYS[1]); if not raw then return cjson.encode({status='missing'}) end
+local f=cjson.decode(raw)
+if tonumber(ARGV[1]) < f.dueAt then return cjson.encode({status='held',dueAt=f.dueAt}) end
+if not f.claimed then f.claimed=true; f.status=f.count>=f.minCount and 'ready' or 'below-threshold'; redis.call('SET',KEYS[1],cjson.encode(f),'KEEPTTL') end
+return cjson.encode({status=f.count>=f.minCount and 'ready' or 'below-threshold',finding=f,source=f.source,ruleId=f.ruleId,fingerprint=f.fingerprint})`;
+			const result = parse(await redis.eval(script, 1, key(`finding:${id}`), now()));
+			if (result.finding && !Array.isArray(result.finding.samples)) result.finding.samples = [];
+			return result;
+		},
+		async proposeBoard(ruleId, board, runId) {
+			validId(ruleId); validId(runId); validateWatchBoard(board);
+			const proposal = { id: hash(JSON.stringify([ruleId, runId, board])), runId, blocks: board.blocks, createdAt: now() };
+			const script = `local raw=redis.call('GET',KEYS[1]); local b=raw and cjson.decode(raw) or cjson.decode(ARGV[1]); b.proposals=b.proposals or {}; local p=cjson.decode(ARGV[2]); for _,old in ipairs(b.proposals) do if old.id==p.id then return cjson.encode(old) end end; table.insert(b.proposals,p); while #b.proposals>20 do table.remove(b.proposals,1) end; redis.call('SET',KEYS[1],cjson.encode(b),'PX',ARGV[3]); return cjson.encode(p)`;
+			return parse(await redis.eval(script, 1, key(`board:${ruleId}`), JSON.stringify(emptyBoard(ruleId)), JSON.stringify(proposal), TTL_MS));
+		},
+		async recordVerdict(ruleId, source, status) {
+			validId(ruleId); validId(source);
+			if (!["held", "suppressed", "capped", "unmatched"].includes(status)) throw new Error("invalid watch verdict");
+			await redis.multi().hset(key("rules"), ruleId, JSON.stringify({ id: ruleId, source })).hincrby(key(`summary:${ruleId}`), status, 1).hset(key(`summary:${ruleId}`), "lastDeliveryAt", String(now())).pexpire(key(`summary:${ruleId}`), TTL_MS).pexpire(key("rules"), TTL_MS).exec();
+		},
+		async listRules() { return Promise.all(Object.values(await redis.hgetall(key("rules"))).map(parse).map(async rule => ({ ...rule, summary: await redis.hgetall(key(`summary:${rule.id}`)) }))); },
+		async listFindings(ruleId, { limit = 1000 } = {}) {
+			validId(ruleId); if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) throw new Error("invalid watch findings limit");
+			const ids = await redis.zrevrange(key(`findings:${ruleId}`), 0, limit - 1);
+			return (await Promise.all(ids.map(id => this.readFinding(id)))).filter(Boolean);
+		},
+		async readFinding(id, { private: privateRead = false } = {}) { validId(id); const f = parse(await redis.get(key(`finding:${id}`))); return privateRead ? f : publicFinding(f); },
+		async readTrace(id, { private: privateRead = false } = {}) {
+			validId(id); const entries = (await redis.lrange(key(`trace:${id}`), 0, 999)).map(parse);
+			const dropped = Number(await redis.get(key(`trace-dropped:${id}`)) ?? 0);
+			if (dropped > 0) entries.unshift({ id: "trace-trimmed", kind: "rule", status: "trace-trimmed", count: dropped });
+			return privateRead ? entries : entries.map(publicWatchTrace);
+		},
+		async appendTrace(id, entry) {
+			validId(id); const text = JSON.stringify({ ...entry, at: now() });
+			if (Buffer.byteLength(text) > 32768) throw new Error("watch trace entry exceeds limit");
+			const script = `local n=redis.call('RPUSH',KEYS[1],ARGV[1]); if n>1000 then redis.call('INCRBY',KEYS[2],n-1000); redis.call('LTRIM',KEYS[1],-1000,-1); redis.call('PEXPIRE',KEYS[2],ARGV[2]) end; redis.call('PEXPIRE',KEYS[1],ARGV[2]); return n`;
+			await redis.eval(script, 2, key(`trace:${id}`), key(`trace-dropped:${id}`), text, TTL_MS);
+		},
+		async updateFinding(id, patch) {
+			validId(id); const allowed = ["status", "decision", "reason", "runId"];
+			if (Object.keys(patch).some(k => !allowed.includes(k))) throw new Error("invalid watch finding update");
+			const script = `local raw=redis.call('GET',KEYS[1]); if not raw then return 0 end; local f=cjson.decode(raw); local p=cjson.decode(ARGV[1]); for k,v in pairs(p) do f[k]=v end; redis.call('SET',KEYS[1],cjson.encode(f),'KEEPTTL'); return 1`;
+			return Boolean(await redis.eval(script, 1, key(`finding:${id}`), JSON.stringify(patch)));
+		},
+		async readBoard(ruleId) { validId(ruleId); return boardArrays(parse(await redis.get(key(`board:${ruleId}`))) ?? emptyBoard(ruleId)); },
+		async mutateBoard(ruleId, change, expectedVersion) {
+			validId(ruleId);
+			if (!Number.isSafeInteger(expectedVersion) || expectedVersion < 0) throw new Error("invalid board version");
+			if (!["freeze", "clear", "revert", "adopt"].includes(change.action) || (change.action === "freeze" && typeof change.frozen !== "boolean")) throw new Error("invalid board change");
+			if (change.action === "adopt") validId(change.proposalId);
+			const result = parse(await redis.eval(BOARD_SCRIPT, 1, key(`board:${ruleId}`), JSON.stringify(emptyBoard(ruleId)), expectedVersion, JSON.stringify(change), TTL_MS));
+			result.board = boardArrays(result.board); return result;
+		},
+	};
+}
+export function validateWatchBoard(board) {
+	const result = checkBoard({ version: 1, ...board });
+	if (!result.ok) throw new Error(result.reason);
+	return board;
+}

package/src/watch-trace.mjs

@@ -0,0 +1,34 @@
+const ACTIONS = ["investigate", "file_issue", "ignore"];
+const STATUSES = ["started", "completed", "failed", "proposed", "held", "suppressed", "capped", "unmatched", "decision", "investigate", "answered", "decide-unanswered", "decide-refused", "watch-ignored", "watch-board-invalid", "watch-board-oversize", "trace-trimmed"];
+const token = value => typeof value === "string" && /^[A-Za-z0-9_.:-]{1,128}$/.test(value);
+const integer = value => Number.isSafeInteger(value) && value >= 0 && value <= 1000000;
+
+/** Public trace values have types and closed vocabularies, not merely familiar key names. */
+export function publicWatchTrace(entry) {
+	const out = {};
+	if (token(entry.id)) out.id = entry.id;
+	if (["stream", "rule", "decide", "query", "turn", "board"].includes(entry.kind)) out.kind = entry.kind;
+	if (Number.isSafeInteger(entry.at) && entry.at >= 0) out.at = entry.at;
+	if (STATUSES.includes(entry.status)) out.status = entry.status;
+	for (const key of ["count", "rows"]) if (integer(entry[key])) out[key] = entry[key];
+	if (typeof entry.fingerprint === "string" && /^[a-f0-9]{64}$/.test(entry.fingerprint)) out.fingerprint = entry.fingerprint;
+	for (const key of ["ruleId", "source"]) if (token(entry[key])) out[key] = entry[key];
+	if (["verified", "pull"].includes(entry.signature)) out.signature = entry.signature;
+	if (ACTIONS.includes(entry.action ?? entry.option)) out.action = entry.action ?? entry.option;
+	if (entry.modelReviewed === true && typeof entry.model === "string" && /^[A-Za-z0-9_./:@~-]{1,128}$/.test(entry.model)) { out.model = entry.model; out.modelReviewed = true; }
+	if (Number.isFinite(entry.confidence) && entry.confidence >= 0 && entry.confidence <= 1) out.confidence = entry.confidence;
+	if (Number.isFinite(entry.costUsd) && entry.costUsd >= 0) out.costUsd = entry.costUsd;
+	if (entry.probabilities && !Array.isArray(entry.probabilities) && Object.keys(entry.probabilities).every(k => ACTIONS.includes(k)) && Object.values(entry.probabilities).every(p => Number.isFinite(p) && p >= 0 && p <= 1)) out.probabilities = { ...entry.probabilities };
+	if (entry.checks && Object.keys(entry.checks).every(k => ["match", "threshold", "cooldown", "cap"].includes(k)) && Object.values(entry.checks).every(v => ["passed", "refused", "active", "at-window-end"].includes(v))) out.checks = { ...entry.checks };
+	return out;
+}
+
+export function collectedWatchTrace(entry, { model, ruleId, runId }) {
+	if (!entry || !["query", "decide", "board"].includes(entry.kind) || !/^watch-\d{1,4}$/.test(entry.id) || !STATUSES.includes(entry.status)) return null;
+	const out = { id: `${runId}:${entry.id}`, kind: entry.kind, status: entry.status, ruleId };
+	if (entry.kind === "decide" && model) Object.assign(out, { model, modelReviewed: true });
+	for (const key of ["rows", "blocks"]) if (integer(entry[key])) out[key] = entry[key];
+	// Query text, agent-chosen questions and state remain in the operator projection alone.
+	for (const key of ["state", "questions", "answers", "usage", "query", "callId"]) if (entry[key] !== undefined && Buffer.byteLength(JSON.stringify(entry[key])) <= 16384) out[key] = entry[key];
+	return out;
+}