@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/approval-runtime.mjs

@@ -0,0 +1,188 @@
+import { cleanTouch, touchScopeOf } from "./touch-state.mjs";
+/** Host orchestration of durable approvals. No queue field can manufacture a system expiry decision: it must match
+ * the private store and the one deterministic expiry job. All refusals happen before the caller's spend gates. */
+import { approvalActor, approvalAudit, approvalReply, approvalRequestId, validateApprovalConfig } from "./approval-policy.mjs";
+
+export const APPROVAL_EXPIRED_COMMENT = "The approval request expired and was declined. The run will continue with that decision.";
+export const APPROVAL_REVOKED_COMMENT = "The approval request was withdrawn because its trigger policy changed. No continuation was started.";
+export const approvalExpiryJobId = (requestId) => `approval-expiry-${requestId}`;
+const failed = (out) => out?.error ? { error: out.error } : { refused: typeof out?.refused === "string" && out.refused.startsWith("approval-") ? out.refused : "approval-state-conflict" };
+
+/** checkPolicy(job) returns {ok:true,digest}; enqueueExpiry(request) must use approvalExpiryJobId(request.requestId).
+ * The comment hook receives (request, fixedText); it owns forge delivery/idempotence, never a model summary. */
+export function makeApprovalRuntime({ store, checkPolicy, now = () => Date.now(), host, hostQueue = null, requireSessionDigest = false, enqueueExpiry, comment = async () => {}, touchStore = null, touchOutbox = null } = {}) {
+	if (!store || typeof checkPolicy !== "function" || typeof host !== "string" || !host) throw new TypeError("approval runtime needs store, checkPolicy and host");
+	// `{ newer: true }` (issue #761) passes through untouched: the triggers file was written by a newer pi-dispatch, so
+	// this build cannot judge the declaration either way. It is neither a refusal nor a changed policy, so no request is
+	// cancelled, declined, decided or claimed on it; the processor defers the job (`newer-release`) and the sweep skips it.
+	const policy = async (job, request = null) => {
+		let out;
+		try { out = await checkPolicy(job); } catch { return { refused: "approval-policy-unavailable" }; }
+		if (out?.newer === true) return { newer: true };
+		if (!out?.ok) return failed(out);
+		if (request && (out.digest !== request.configDigest || !job?.gates?.includes(request.action))) return { refused: "approval-policy-changed" };
+		return out;
+	};
+	const waitWriter = touchOutbox ?? (touchStore ? { begin: typeof touchStore.begin === "function" ? (event) => touchStore.begin(event) : async (event) => ({ event }), applied: (intent) => touchStore.write(intent.event), abort: (intent) => touchStore.abort?.(intent.event) } : null);
+	const waitEvent = (request, reason, at = now()) => {
+		if (reason === "approval-expired") {
+			if (request.decision?.actor?.kind !== "system" || request.decision.actor.id !== "expiry") return null;
+			at = Number.isSafeInteger(request.expiresAt) ? Math.min(request.expiresAt, request.decision.at) : request.decision.at;
+		} else if (Number.isSafeInteger(request.decision?.at)) {
+			at = request.decision.actor?.kind === "system" && request.decision.actor.id === "expiry" && Number.isSafeInteger(request.expiresAt) ? Math.min(request.expiresAt, request.decision.at) : request.decision.at;
+		}
+		return cleanTouch({ type: "wait-end", reason, runId: request.runId, at, parkedAt: request.createdAt, scopeId: touchScopeOf(request.resumeJob, host), nonce: request.requestId });
+	};
+	const beginWait = async (event) => {
+		if (!waitWriter || !event) return null;
+		try { return await waitWriter.begin(event); } catch { return { event, error: "touch-index-unavailable" }; }
+	};
+	const publishWait = async (request, reason, intent = null, at = now()) => {
+		const event = waitEvent(request, reason, at);
+		if (!waitWriter || !event) return null;
+		try {
+			intent ??= await beginWait(event);
+			const sent = await waitWriter.applied({ ...intent, event });
+			return sent?.ok ? null : "touch-tracking-incomplete";
+		} catch { return "touch-tracking-incomplete"; }
+	};
+	const terminalMove = async (request, reason, move) => {
+		const at = now();
+		// Persist intent before the approval transition. A later publication fault repairs only this fact,
+		// never repeats the cancellation, decline or paid continuation that already happened.
+		const intent = await beginWait(cleanTouch({ type: "wait-end", reason, runId: request.runId, at, parkedAt: request.createdAt, scopeId: touchScopeOf(request.resumeJob, host), nonce: request.requestId }));
+		const result = await move();
+		if (!result.ok) { try { if (intent) await waitWriter.abort(intent); } catch {} return result; }
+		const touchWarning = await publishWait(result.request, reason, intent, at);
+		return touchWarning ? { ...result, touchWarning } : result;
+	};
+	return {
+		finish: ({ requestId, jobId } = {}) => store.finish({ requestId, jobId }),
+		async before(job) {
+			let configInvalid = false;
+			if (job.gates !== undefined || job.gateTimeout !== undefined || job.gateBudgetRaiseUsd !== undefined) {
+				try { validateApprovalConfig(job); } catch { configInvalid = true; }
+			}
+			const found = await store.find(job);
+			if (!found.ok) return failed(found);
+			let request = found.request;
+			if (!request) {
+				if (job.approvalRequestId) return { refused: "approval-request-stale" };
+				if (configInvalid) return { refused: "approval-config-invalid" };
+				return job.gates !== undefined ? policy(job) : { ok: true };
+			}
+			if (request.host !== host) return { refused: "approval-host-mismatch" };
+			if (requireSessionDigest && !/^[a-f0-9]{64}$/.test(request.sessionDigest ?? "")) return { refused: "approval-session-unavailable" };
+			if (job.approvalRequestId && job.approvalRequestId !== request.requestId) return { refused: "approval-request-stale" };
+			if (typeof job.id !== "string" || !job.id) return { refused: "approval-job-id-missing" };
+			if (job.approvalRequestId !== request.requestId) return { refused: job.trigger?.comment ? "approval-request-unbound" : "approval-pending" };
+			// The reply and the initiating trigger are independent declarations. Keeping the comment rule must
+			// not preserve an approval whose original label/PR rule was revoked, including requests without a deadline.
+			const initiating = await policy(request.resumeJob, request);
+			const checked = initiating.ok ? await policy(job, request) : initiating;
+			if (!checked.ok) {
+				if (checked.refused !== "approval-policy-changed") return checked;
+				const cancelled = await terminalMove(request, "approval-policy-changed", () => store.cancel({ requestId: request.requestId, jobId: job.id }));
+				return cancelled.ok ? { refused: "approval-policy-changed", request: cancelled.request, audit: approvalAudit(cancelled.request), ...(cancelled.touchWarning ? { touchWarning: cancelled.touchWarning } : {}) } : failed(cancelled);
+			}
+			if (configInvalid) return { refused: "approval-config-invalid" };
+			const expiryJob = job.id === approvalExpiryJobId(request.requestId) && job.approvalRequestId === request.requestId && job.trigger?.deliveryId === `expiry-${request.requestId}`;
+			if (expiryJob) {
+				if (request.decision?.actor?.kind !== "system" || request.decision?.actor?.id !== "expiry" || request.decision?.decision !== "declined") return { refused: "approval-expiry-invalid" };
+				await publishWait(request, "approval-expired");
+			} else {
+				if (request.decision?.actor?.kind === "system") { const touchWarning = await publishWait(request, "approval-expired"); return { refused: "approval-expired", ...(touchWarning ? { touchWarning } : {}) }; }
+				if (!job.trigger?.comment || typeof job.trigger.comment.body !== "string") return { refused: "approval-pending" };
+				if (job.approvalRequestId !== request.requestId) return { refused: "approval-request-unbound" };
+				const actor = approvalActor(job);
+				if (!actor) return { refused: "approval-author-missing" };
+				const touch = { runId: request.runId, cause: "approval-decision", at: now(), parkedAt: request.createdAt, scopeId: touchScopeOf(request.resumeJob, host), nonce: job.id };
+				const writer = touchOutbox ?? (touchStore?.begin ? { begin: (event) => touchStore.begin(event), applied: (intent) => touchStore.write(intent.event), abort: (intent) => touchStore.abort(intent.event) } : null);
+				const intent = writer ? await writer.begin(touch) : null;
+				const decided = await store.decide({ requestId: request.requestId, decisionId: job.id, ...approvalReply(job.trigger.comment.body, { phrase: job.trigger?.matched?.phrase }), actor });
+				if (!decided.ok) { if (intent) await writer.abort(intent); return failed(decided); }
+				request = decided.request;
+				// A human racing the exact deadline may cause the store to persist an expiry decline. Only its own
+				// synthetic job may consume it; otherwise both the human job and the sweep could start containers.
+				if (request.decision.actor.kind === "system") { if (intent) await writer.abort(intent); const touchWarning = await publishWait(request, "approval-expired"); return { refused: "approval-expired", ...(touchWarning ? { touchWarning } : {}) }; }
+				const event = cleanTouch({ ...touch, at: request.decision.at, nonce: request.decision.decisionId });
+				if (intent) await writer.applied({ ...intent, event });
+				else if (touchStore) await touchStore.write(event);
+
+			}
+			const claimed = await store.claim({ requestId: request.requestId, jobId: job.id });
+			if (!claimed.ok) return failed(claimed);
+			request = claimed.request;
+			return {
+				ok: true,
+				decision: { requestId: request.requestId, action: request.action, toolCallId: request.toolCallId, decision: request.decision.decision, text: request.decision.text },
+				request,
+				audit: approvalAudit(request),
+				...(request.action === "budget-raise" && request.decision.decision === "approved" ? { budgetCapUsd: job.gateBudgetRaiseUsd } : {}),
+			};
+		},
+		async afterPark({ job, session, metadata, rawJob = job } = {}) {
+			if (!metadata || !job?.gates?.includes(metadata.action) || typeof metadata.toolCallId !== "string" || !session?.key || typeof job.id !== "string") return { refused: "approval-park-invalid" };
+			if (requireSessionDigest && !/^[a-f0-9]{64}$/.test(session.digest ?? "")) return { refused: "approval-session-unavailable" };
+			const checked = await policy(job);
+			if (!checked.ok) return checked;
+			const requestId = approvalRequestId(job.id, metadata.toolCallId);
+			const prior = await store.read(requestId);
+			if (!prior.ok) return failed(prior);
+			if (prior.request) {
+				if (prior.request.runId !== job.id || prior.request.action !== metadata.action || prior.request.configDigest !== checked.digest || prior.request.sessionKey !== session.key || prior.request.host !== host || prior.request.sessionDigest !== session.digest) return { refused: "approval-request-conflict" };
+				return { ...prior, audit: approvalAudit(prior.request) };
+			}
+			const createdAt = now();
+			const resumeJob = { ...rawJob };
+			for (const field of ["id", "maxCostMicros", "approvalDecision", "approvalRequestId"]) delete resumeJob[field];
+			const out = await store.publish({
+				requestId, runId: job.id, kind: job.kind, repo: job.repo,
+				target: job.target, action: metadata.action, toolCallId: metadata.toolCallId,
+				configDigest: checked.digest, sessionKey: session.key, host, ...(hostQueue !== null ? { hostQueue } : {}), createdAt,
+				...(session.digest !== undefined ? { sessionDigest: session.digest } : {}),
+				...(job.gateTimeout !== undefined ? { expiresAt: createdAt + job.gateTimeout * 86400_000 } : {}),
+				resumeJob,
+			});
+			return out.ok ? { ...out, audit: approvalAudit(out.request) } : failed(out);
+		},
+		async sweep(limit = 100) {
+			const due = await store.due(limit, host);
+			if (!due.ok) return failed(due);
+			let enqueued = 0;
+			const failures = [];
+			for (const id of due.requestIds) {
+				const read = await store.read(id);
+				if (!read.ok) { failures.push({ requestId: id, ...failed(read) }); continue; }
+				if (!read.request || read.request.host !== host) continue;
+				const checked = await policy(read.request.resumeJob, read.request);
+				// A newer triggers file (issue #761): neither expired nor revoked here. Left due, so the next sweep asks again,
+				// and the build that reads the file decides it.
+				if (checked.newer) continue;
+				if (!checked.ok) {
+					if (checked.refused === "approval-policy-changed") {
+						const cancelled = await terminalMove(read.request, "approval-policy-changed", () => store.cancel({ requestId: id, jobId: approvalExpiryJobId(id) }));
+						if (!cancelled.ok) failures.push({ requestId: id, ...failed(cancelled) });
+						else {
+							try { await comment(cancelled.request, APPROVAL_REVOKED_COMMENT); } catch { failures.push({ requestId: id, error: "approval-expiry-comment-failed" }); }
+						}
+					} else failures.push({ requestId: id, ...checked });
+					continue;
+				}
+				const expired = await terminalMove(read.request, "approval-expired", () => store.expire(id));
+				if (!expired.ok) {
+					if (expired.refused !== "already-decided" && expired.refused !== "request-stale") failures.push({ requestId: id, ...failed(expired) });
+					continue;
+				}
+				try {
+					if (typeof enqueueExpiry !== "function") { failures.push({ requestId: id, refused: "approval-expiry-queue-unavailable" }); continue; }
+					const queued = await enqueueExpiry(expired.request);
+					if (queued?.error || queued?.refused || queued?.ok === false) { failures.push({ requestId: id, ...failed(queued) }); continue; }
+					enqueued++;
+					await comment(expired.request, APPROVAL_EXPIRED_COMMENT);
+				} catch { failures.push({ requestId: id, error: "approval-expiry-enqueue-failed" }); }
+			}
+			return { ok: failures.length === 0, enqueued, failures };
+		},
+	};
+}

package/src/approval-session.mjs

@@ -0,0 +1,137 @@
+/**
+ * Free, fail-closed approval transcript preflight (issue #649). An approval cannot cold-start: before credentials,
+ * clone or reservation, its canonical session must still end on the exact unanswered request. This intentionally
+ * validates only a narrow raw shape, not pi's projection algorithm. The runner checks the pinned SDK's projection
+ * again on the staged file. Descriptor reads and path identity rechecks prevent a swapped name deciding this gate.
+ */
+import * as nodeFs from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { SESSION_KEY_PATTERN } from "./session-key.mjs";
+import { hasEmptyCompaction } from "./session-store.mjs";
+import { MODEL_REF_PATTERN } from "./model-ref.mjs";
+
+const REFUSED = Object.freeze({ refused: "approval-session-unavailable" });
+const dirIdentity = (stat) => `${stat.dev}:${stat.ino}`;
+const fileIdentity = (stat) => `${dirIdentity(stat)}:${stat.size}:${stat.mtimeMs}`;
+
+/** Pure raw-branch check. Fail closed on ambiguity; the SDK's projected context remains a separate later check. */
+export function approvalTranscriptMatches(text, request, { maxAgeDays = 0, now = () => Date.now() } = {}) {
+	try {
+		const entries = text.split("\n").filter((line) => line.trim() !== "").map((line) => JSON.parse(line));
+		const header = entries.shift();
+		if (header?.type !== "session" || typeof header.id !== "string" || entries.length === 0 || hasEmptyCompaction(text)) return false;
+		if (maxAgeDays > 0) {
+			const created = typeof header.timestamp === "string" ? Date.parse(header.timestamp) : NaN;
+			if (!Number.isFinite(created) || now() - created > maxAgeDays * 86400_000) return false;
+		}
+		const byId = new Map();
+		for (const entry of entries) {
+			if (!entry || typeof entry.id !== "string" || !entry.id || byId.has(entry.id) || !(entry.parentId === null || typeof entry.parentId === "string")) return false;
+			byId.set(entry.id, entry);
+		}
+		const branch = [];
+		let leaf = entries.at(-1);
+		const seen = new Set();
+		while (leaf) {
+			if (seen.has(leaf.id)) return false;
+			seen.add(leaf.id);
+			branch.unshift(leaf);
+			if (leaf.parentId === null) break;
+			leaf = byId.get(leaf.parentId);
+			if (!leaf) return false;
+		}
+		const messages = branch.filter((entry) => entry.type === "message");
+		const target = messages.at(-1);
+		const result = target?.message;
+		const caller = messages.at(-2)?.message;
+		if (result?.role !== "toolResult" || result.toolName !== "request_approval" || result.toolCallId !== request.toolCallId || result.isError === true || result.details?.approval?.action !== request.action || result.details?.approval?.toolCallId !== request.toolCallId) return false;
+		if (caller?.role !== "assistant" || !Array.isArray(caller.content) || !caller.content.some((part) => part?.type === "toolCall" && part.name === "request_approval" && part.id === request.toolCallId && part.arguments?.action === request.action)) return false;
+		const at = branch.indexOf(target);
+		if (branch.some((entry, index) => entry.type === "context_edit" && entry.targetId === target.id || index > at && ["compaction", "branch_summary", "custom_message"].includes(entry.type))) return false;
+		return true;
+	} catch { return false; }
+}
+
+export function makeApprovalSessionCheck({ sessionsDir, maxBytes = 8 * 1024 * 1024, ttlDays = 0, maxAgeDays = 0, maxResumeChain = 0, maxContextPct = null, now = () => Date.now(), fs = nodeFs } = {}) {
+	const boundedRead = (path, bound) => {
+		const before = fs.lstatSync(path);
+		if (!before.isFile() || before.size <= 0 || !Number.isSafeInteger(before.size) || bound > 0 && before.size > bound) throw new Error("unavailable");
+		let fd;
+		try {
+			fd = fs.openSync(path, nodeFs.constants.O_RDONLY | nodeFs.constants.O_NOFOLLOW);
+			const opened = fs.fstatSync(fd);
+			if (!opened.isFile() || fileIdentity(before) !== fileIdentity(opened)) throw new Error("unavailable");
+			const bytes = Buffer.alloc(before.size + 1);
+			let count = 0;
+			while (count < bytes.length) {
+				const read = fs.readSync(fd, bytes, count, bytes.length - count, count);
+				if (read === 0) break;
+				count += read;
+			}
+			if (count !== before.size || fileIdentity(fs.fstatSync(fd)) !== fileIdentity(before) || fileIdentity(fs.lstatSync(path)) !== fileIdentity(before)) throw new Error("unavailable");
+			const snapshot = bytes.subarray(0, count);
+			return { text: snapshot.toString("utf8"), digest: createHash("sha256").update(snapshot).digest("hex"), stat: before };
+		} finally { if (fd !== undefined) fs.closeSync(fd); }
+	};
+	const validate = (request, expected = {}) => {
+		try {
+			if (typeof sessionsDir !== "string" || !sessionsDir || !SESSION_KEY_PATTERN.test(request?.sessionKey ?? "") || typeof request.action !== "string" || typeof request.toolCallId !== "string") return REFUSED;
+			// The configured root may be a link, as in the existing session store. Only a derived key directory
+			// must itself be real; the operator's chosen store location is not an attacker-derived pathname.
+			const root = fs.statSync(sessionsDir);
+			const directory = join(sessionsDir, request.sessionKey);
+			const dir = fs.lstatSync(directory);
+			if (!root.isDirectory() || !dir.isDirectory()) return REFUSED;
+			const read = boundedRead(join(directory, "current.jsonl"), maxBytes);
+			if (request.sessionDigest !== undefined && request.sessionDigest !== read.digest) return REFUSED;
+			if (ttlDays > 0 && now() - read.stat.mtimeMs > ttlDays * 86400_000) return REFUSED;
+			const sidecar = (name) => {
+				try { return boundedRead(join(directory, name), 4096).text.trim(); } catch { return null; }
+			};
+			if (Object.hasOwn(expected, "piVersion") && (typeof expected.piVersion !== "string" || !expected.piVersion || sidecar("pi-version") !== expected.piVersion)) return REFUSED;
+			if (Object.hasOwn(expected, "venue")) {
+				let stored;
+				try { fs.lstatSync(join(directory, "venue")); stored = sidecar("venue"); } catch (error) { stored = error?.code === "ENOENT" ? "local" : null; }
+				if (typeof expected.venue !== "string" || !expected.venue || stored !== expected.venue) return REFUSED;
+			}
+			// Early preflight has no image/model selection yet. Defer this model-sensitive gate until the caller
+			// supplies the current pickup's model, preserving the store's deliberate foreign-model exemption.
+			if (maxContextPct !== null && (Object.hasOwn(expected, "modelId") || Object.hasOwn(expected, "provider"))) {
+				const raw = sidecar("context");
+				if (raw !== null) {
+					const [rawTokens, rawWindow, stampedModel] = raw.split(/\s+/);
+					const tokens = Number.parseInt(rawTokens, 10);
+					const window = Number.parseInt(rawWindow, 10);
+					let currentModel = typeof expected.modelId === "string" ? expected.modelId.toLowerCase() : null;
+					if (Object.hasOwn(expected, "provider")) {
+						const provider = typeof expected.provider === "string" ? expected.provider.toLowerCase() : "";
+						currentModel = provider && currentModel && MODEL_REF_PATTERN.test(provider) && MODEL_REF_PATTERN.test(currentModel) ? `${provider}/${currentModel}` : null;
+					}
+					const foreign = stampedModel !== undefined && currentModel !== null && stampedModel !== currentModel;
+					if (Number.isInteger(tokens) && tokens >= 0 && String(tokens) === rawTokens && Number.isInteger(window) && window > 0 && String(window) === rawWindow && !foreign && tokens * 100 / window >= maxContextPct) return REFUSED;
+				}
+			}
+			if (maxResumeChain > 0) {
+				let chain = 0;
+				try {
+					const raw = boundedRead(join(directory, "resume-chain"), 4096).text.trim();
+					const value = Number.parseInt(raw, 10);
+					if (Number.isInteger(value) && value > 0 && String(value) === raw) chain = value;
+				} catch { /* The session store treats an absent or unreadable counter as zero, too. */ }
+				if (chain >= maxResumeChain) return REFUSED;
+			}
+			if (!approvalTranscriptMatches(read.text, request, { maxAgeDays, now })) return REFUSED;
+			const rootAfter = fs.statSync(sessionsDir);
+			const dirAfter = fs.lstatSync(directory);
+			if (!rootAfter.isDirectory() || !dirAfter.isDirectory() || dirIdentity(rootAfter) !== dirIdentity(root) || dirIdentity(dirAfter) !== dirIdentity(dir)) return REFUSED;
+			return { ok: true, digest: read.digest };
+		} catch { return REFUSED; }
+	};
+	const check = (request, expected = {}) => {
+		const out = validate(request, expected);
+		return out.ok ? { ok: true } : out;
+	};
+	check.fingerprint = validate;
+	return check;
+}

package/src/approval-state.mjs

@@ -0,0 +1,170 @@
+/**
+ * Durable approval requests (issue #649). Every transition is a Valkey compare-and-set: a label, queue payload or
+ * a second reply cannot replace the first accepted decision. Pending requests never expire as keys: the deadline
+ * produces a durable decline instead. Callers authorize the actor before decide and keep this private store's text
+ * out of run records and logs. Claiming again with the same job id supports infrastructure retry after queue.add.
+ */
+import { createHash } from "node:crypto";
+import { ANSWER_TEXT_MAX_BYTES, scrubAnswerText } from "./console-answer.mjs";
+import { FORGE_JOB_RETENTION_MS } from "./retention.mjs";
+
+/**
+ * How long a finished or cancelled request is kept, in MILLISECONDS (the `PEXPIRE` below, and the expiry comment's NX
+ * mark in start.mjs): a day past a forge job's retention, so the evidence of a decision outlives every queued job that
+ * could still carry its request id, the expiry job (a forge-kind job built from the request's `resumeJob`) included.
+ * Derived, so lengthening the forge retention cannot leave it shorter than the jobs it answers for. Interpolated into
+ * the script as a plain integer, so its text is what it was when this was the literal 32 days.
+ */
+export const APPROVAL_FINISHED_TTL_MS = FORGE_JOB_RETENTION_MS + 86_400_000;
+export const APPROVAL_PREFIX = "run:approval:";
+export const APPROVAL_DUE_KEY = `${APPROVAL_PREFIX}due`;
+const ID = /^[A-Za-z0-9._:-]{1,200}$/;
+const word = (v, max = 256) => typeof v === "string" && v.length > 0 && v.length <= max && !/[\u0000-\u001f\u007f]/u.test(v);
+const instant = (v) => Number.isSafeInteger(v) && v >= 0;
+const key = (id) => `${APPROVAL_PREFIX}request:${id}`;
+export const approvalDueKey = (host) => `${APPROVAL_DUE_KEY}:${createHash("sha256").update(host).digest("hex")}`;
+
+/** A derived target key, shared by publish and find; no attacker text is put in a Valkey key. */
+export function approvalTargetKey(job) {
+	if (!word(job?.kind) || !word(job?.repo) || !["issue", "pull_request"].includes(job?.target?.type) || !Number.isSafeInteger(job.target.number) || job.target.number <= 0) return null;
+	return `${APPROVAL_PREFIX}target:${createHash("sha256").update(JSON.stringify([job.kind, job.repo, job.target.type, job.target.number])).digest("hex")}`;
+}
+
+function normalized(request) {
+	if (request?.version !== undefined && request.version !== 1) return null;
+	if (request?.sessionDigest !== undefined && (typeof request.sessionDigest !== "string" || !/^[a-f0-9]{64}$/.test(request.sessionDigest))) return null;
+	if (!request || !ID.test(request.requestId ?? "") || !ID.test(request.runId ?? "") || !approvalTargetKey(request) || !word(request.action, 128) || !word(request.toolCallId) || !word(request.configDigest) || !word(request.sessionKey) || !word(request.host) || !instant(request.createdAt)) return null;
+	if (request.hostQueue !== undefined && request.hostQueue !== null && (typeof request.hostQueue !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(request.host) || request.hostQueue !== `pi-jobs@${request.host}`)) return null;
+	if (request.expiresAt !== undefined && (!instant(request.expiresAt) || request.expiresAt <= request.createdAt)) return null;
+	const out = { version: 1, requestId: request.requestId, runId: request.runId, kind: request.kind, repo: request.repo, target: { type: request.target.type, number: request.target.number }, action: request.action, toolCallId: request.toolCallId, configDigest: request.configDigest, sessionKey: request.sessionKey, host: request.host, createdAt: request.createdAt };
+	if (request.expiresAt !== undefined) out.expiresAt = request.expiresAt;
+	if (request.sessionDigest !== undefined) out.sessionDigest = request.sessionDigest;
+	if (request.hostQueue !== undefined && request.hostQueue !== null) out.hostQueue = request.hostQueue;
+	// Routing data is worker-authored and private; its JSON must remain bounded before it reaches Valkey.
+	if (request.resumeJob !== undefined) {
+		if (!request.resumeJob || typeof request.resumeJob !== "object" || Array.isArray(request.resumeJob)) return null;
+		out.resumeJob = request.resumeJob;
+	}
+	if (Buffer.byteLength(JSON.stringify(out)) > 128 * 1024) return null;
+	return out;
+}
+
+const PUBLISH = `local prior = redis.call('GET', KEYS[1])
+if prior then
+ local valid, r = pcall(cjson.decode, prior)
+ if not valid or type(r) ~= 'table' or r.version ~= 1 then return {'refused', 'state-invalid'} end
+ if r.identity ~= ARGV[1] then return {'refused', 'request-conflict'} end
+ return {'ok', prior}
+end
+if redis.call('EXISTS', KEYS[2]) == 1 then return {'refused', 'target-pending'} end
+local r = cjson.decode(ARGV[1]); r.state = 'pending'; r.identity = ARGV[1]
+local raw = cjson.encode(r)
+redis.call('SET', KEYS[1], raw); redis.call('SET', KEYS[2], r.requestId)
+if r.expiresAt then redis.call('ZADD', KEYS[3], r.expiresAt, r.requestId); redis.call('ZADD', KEYS[4], r.expiresAt, r.requestId) end
+return {'ok', raw}`;
+
+const MOVE = `local raw = redis.call('GET', KEYS[1])
+if not raw then return {'refused', 'request-missing'} end
+local valid, r = pcall(cjson.decode, raw)
+if not valid or type(r) ~= 'table' or r.version ~= 1 then return {'refused', 'state-invalid'} end
+if (ARGV[1] == 'finish' or ARGV[1] == 'cancel') and r.state == 'finished' and r.jobId == ARGV[3] then return {'ok', raw} end
+if redis.call('GET', KEYS[2]) ~= r.requestId then return {'refused', 'request-stale'} end
+local op = ARGV[1]; local at = tonumber(ARGV[2])
+if op == 'decide' or op == 'expire' then
+ if r.state ~= 'pending' then
+  if op == 'decide' and r.decision and r.decision.decisionId == ARGV[3] then return {'ok', raw} end
+  if op == 'expire' and r.decision and r.decision.actor.kind == 'system' then return {'ok', raw} end
+  return {'refused', 'already-decided'}
+ end
+ if op == 'expire' and (not r.expiresAt or at < r.expiresAt) then return {'refused', 'not-expired'} end
+ if r.expiresAt and at >= r.expiresAt then
+  r.decision = {decisionId = 'expiry-' .. r.requestId, decision = 'declined', actor = {kind = 'system', id = 'expiry'}, text = '', at = at}
+ else
+  r.decision = cjson.decode(ARGV[4]); r.decision.at = at
+ end
+ r.state = 'decided'
+ if r.decision.actor.kind ~= 'system' then redis.call('ZREM', KEYS[3], r.requestId); redis.call('ZREM', KEYS[4], r.requestId) end
+elseif op == 'claim' then
+ if r.state == 'claimed' and r.jobId == ARGV[3] then return {'ok', raw} end
+ if r.state ~= 'decided' then return {'refused', 'not-decided'} end
+ r.state = 'claimed'; r.jobId = ARGV[3]; redis.call('ZREM', KEYS[3], r.requestId); redis.call('ZREM', KEYS[4], r.requestId)
+elseif op == 'finish' then
+ if r.state ~= 'claimed' or r.jobId ~= ARGV[3] then return {'refused', 'not-claimed'} end
+ r.state = 'finished'; redis.call('DEL', KEYS[2]); redis.call('ZREM', KEYS[3], r.requestId); redis.call('ZREM', KEYS[4], r.requestId)
+elseif op == 'cancel' then
+ if r.state == 'claimed' and r.jobId ~= ARGV[3] then return {'refused', 'not-claimed'} end
+ if r.state ~= 'pending' and r.state ~= 'decided' and r.state ~= 'claimed' then return {'refused', 'request-stale'} end
+ if not r.decision then r.decision = {decisionId = 'revocation-' .. r.requestId, decision = 'declined', actor = {kind = 'system', id = 'revocation'}, text = '', at = at} end
+ r.state = 'finished'; r.jobId = ARGV[3]; redis.call('DEL', KEYS[2]); redis.call('ZREM', KEYS[3], r.requestId); redis.call('ZREM', KEYS[4], r.requestId)
+else return {'refused', 'operation-invalid'} end
+raw = cjson.encode(r); redis.call('SET', KEYS[1], raw)
+if op == 'finish' or op == 'cancel' then redis.call('PEXPIRE', KEYS[1], ${APPROVAL_FINISHED_TTL_MS}) end
+return {'ok', raw}`;
+
+const exposed = (raw) => {
+	try {
+		const request = JSON.parse(raw);
+		if (request?.version !== 1 || !normalized(request) || !["pending", "decided", "claimed", "finished"].includes(request.state)) return null;
+		if (request.state !== "pending" && (!request.decision || !["approved", "declined", "question"].includes(request.decision.decision) || !["forge", "operator", "panel", "system"].includes(request.decision.actor?.kind) || !word(request.decision.actor.id, 200) || !instant(request.decision.at) || typeof request.decision.text !== "string")) return null;
+		delete request.identity;
+		return request;
+	} catch { return null; }
+};
+
+/** Methods return {ok, request}, {refused}, or {error}; missing read/find returns request:null. */
+export function makeApprovalStore({ redis, now = () => Date.now() } = {}) {
+	if (!redis || typeof redis.eval !== "function") throw new TypeError("makeApprovalStore needs redis.eval");
+	const safe = async (fn) => {
+		try { return await fn(); } catch (error) { return { error: typeof error?.code === "string" && /^[A-Z0-9_]{1,40}$/.test(error.code) ? error.code : "approval-store-error" }; }
+	};
+	const read = (id) => safe(async () => {
+		if (!ID.test(id ?? "")) return { refused: "request-invalid" };
+		const raw = await redis.get(key(id));
+		if (raw === null) return { ok: true, request: null };
+		const request = exposed(raw);
+		return request ? { ok: true, request } : { refused: "state-invalid" };
+	});
+	const decode = (result) => {
+		if (result[0] !== "ok") return { refused: result[1] };
+		const request = exposed(result[1]);
+		return request ? { ok: true, request } : { refused: "state-invalid" };
+	};
+	const move = (op, id, marker = "", decision = null) => safe(async () => {
+		const got = await read(id);
+		if (!got.ok) return got;
+		if (!got.request) return { refused: "request-missing" };
+		const at = now();
+		if (!instant(at)) return { refused: "clock-invalid" };
+		return decode(await redis.eval(MOVE, 4, key(id), approvalTargetKey(got.request), APPROVAL_DUE_KEY, approvalDueKey(got.request.host), op, String(at), marker, JSON.stringify(decision)));
+	});
+	return {
+		publish: (request) => safe(async () => {
+			const r = normalized(request);
+			if (!r) return { refused: "request-invalid" };
+			return decode(await redis.eval(PUBLISH, 4, key(r.requestId), approvalTargetKey(r), APPROVAL_DUE_KEY, approvalDueKey(r.host), JSON.stringify(r)));
+		}),
+		read,
+		find: (job) => safe(async () => {
+			const target = approvalTargetKey(job);
+			if (!target) return { refused: "target-invalid" };
+			const id = await redis.get(target);
+			return id === null ? { ok: true, request: null } : read(id);
+		}),
+		decide: ({ requestId, decisionId, decision, actor, text = "" } = {}) => {
+			if (!ID.test(decisionId ?? "") || !["approved", "declined", "question"].includes(decision) || !["forge", "operator", "panel"].includes(actor?.kind) || !word(actor?.id, 200) || typeof text !== "string" || Buffer.byteLength(text) > ANSWER_TEXT_MAX_BYTES || (typeof text.isWellFormed === "function" && !text.isWellFormed())) return Promise.resolve({ refused: "decision-invalid" });
+			return move("decide", requestId, decisionId, { decisionId, decision, actor: { kind: actor.kind, id: actor.id }, text: scrubAnswerText(text) });
+		},
+		claim: ({ requestId, jobId } = {}) => ID.test(jobId ?? "") ? move("claim", requestId, jobId) : Promise.resolve({ refused: "job-invalid" }),
+		finish: ({ requestId, jobId } = {}) => ID.test(jobId ?? "") ? move("finish", requestId, jobId) : Promise.resolve({ refused: "job-invalid" }),
+		cancel: ({ requestId, jobId } = {}) => ID.test(jobId ?? "") ? move("cancel", requestId, jobId) : Promise.resolve({ refused: "job-invalid" }),
+		expire: (id) => move("expire", id),
+		hasPending: (host) => safe(async () => {
+			if (!word(host)) return { refused: "host-invalid" };
+			return { ok: true, pending: (await redis.zcard(approvalDueKey(host))) > 0 };
+		}),
+		due: (limit = 100, host = null) => safe(async () => {
+			if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000 || !instant(now()) || host !== null && !word(host)) return { refused: "limit-invalid" };
+			return { ok: true, requestIds: await redis.zrangebyscore(host === null ? APPROVAL_DUE_KEY : approvalDueKey(host), "-inf", String(now()), "LIMIT", 0, limit) };
+		}),
+	};
+}

package/src/auth-cli.mjs

@@ -0,0 +1,86 @@
+import { createInterface } from "node:readline/promises";
+import { loadConfig } from "./config.mjs";
+import { configuredSubscriptions } from "./subscription-config.mjs";
+import { subscriptionIdentity } from "./subscription-runtime.mjs";
+import { makeRedisClient } from "./connection.mjs";
+import { openBrowser } from "./open-browser.mjs";
+import { authError } from "./auth-store.mjs";
+import { OPENAI_LOGIN_INSTRUCTIONS } from "./oauth-openai.mjs";
+
+/** Native pi selects use `id`; older community callbacks use `value`. Only an offered choice can leave the prompt. */
+export function authSelectAnswer(question, answer) {
+	const options = Array.isArray(question?.options) ? question.options : [];
+	const values = options.map((option) => option?.value ?? option?.id);
+	if (!values.length || values.some((value) => typeof value !== "string" || !value)) throw authError("auth-selection-invalid");
+	const input = typeof answer === "string" ? answer.trim() : "";
+	if (/^\d+$/.test(input)) {
+		const index = Number(input) - 1;
+		if (!Number.isSafeInteger(index) || index < 0 || index >= values.length) throw authError("auth-selection-invalid");
+		return values[index];
+	}
+	if (!values.includes(input)) throw authError("auth-selection-invalid");
+	return input;
+}
+
+export async function runAuth(args, { env = process.env, write = (value) => process.stdout.write(value), writeErr = (value) => process.stderr.write(value), configure = configuredSubscriptions, configFn = loadConfig, redisFn = makeRedisClient, interaction = null, now = Date.now, terminalInput = process.stdin, terminalOutput = process.stdout, createPrompt = createInterface, openBrowserFn = openBrowser } = {}) {
+	const [command = "status", id, ...rest] = args;
+	if (!["status", "login", "logout", "usage", "trial"].includes(command) || rest.length > 0 || (command === "status" ? id !== undefined : !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id ?? ""))) {
+		writeErr("usage: pi-dispatch auth status | login CONNECTION | logout CONNECTION | usage CONNECTION | trial CONNECTION\n");
+		return 2;
+	}
+	let redis;
+	let prompt;
+	try {
+		const config = configFn(env);
+		if (!config.authConnectionsFile) { writeErr("Set PI_AUTH_CONNECTIONS_FILE to an operator-reviewed subscription connection policy.\n"); return 2; }
+		redis = redisFn(config.valkeyUrl);
+		const service = configure({ config, redis, now });
+		if (!interaction) interaction = {
+			async notify(event) {
+				if (event?.type === "auth_url" && typeof event.url === "string" && event.url.startsWith("https://")) {
+					write(`Open the authorization page on this host: ${event.url}\n`);
+					if (URL.canParse(event.url) && new URL(event.url).origin === "https://auth.openai.com") write(`${OPENAI_LOGIN_INSTRUCTIONS}\n`);
+					openBrowserFn(event.url);
+				}
+				if (event?.type === "device_code") write(`Authorization code: ${event.code ?? event.userCode ?? "shown in browser"}\n`);
+			},
+			async prompt(question) {
+				if (!terminalInput.isTTY) throw Object.assign(new Error("interactive terminal required"), { code: "auth-terminal-required" });
+				prompt ??= createPrompt({ input: terminalInput, output: terminalOutput });
+				if (question.type === "select" && Array.isArray(question.options)) write(`${question.options.map((option, i) => `${i + 1}. ${option.label ?? option.value ?? option.id}`).join("\n")}\n`);
+				const answer = await prompt.question(`${question.message ?? "Authorization response"}: `, question.signal ? { signal: question.signal } : {});
+				if (question.type === "select") return authSelectAnswer(question, answer);
+				return answer;
+			},
+		};
+		let result;
+		if (command === "login") result = await service.auth.login(id, { interaction, signal: AbortSignal.timeout(10 * 60_000) });
+		else if (command === "logout") result = await service.auth.logout(id);
+		else if (command === "usage") result = await service.runtime.usage(id);
+		else if (command === "trial") {
+			const row = (await service.auth.status()).find((entry) => entry.id === id && entry.active && entry.ownerHost === config.workerName);
+			if (!row) throw Object.assign(new Error("connection inactive"), { code: "auth-connection-inactive" });
+			const identity = subscriptionIdentity(row);
+			const current = await service.quota.read(identity);
+			result = await service.quota.grantOneTrial(identity, { expectedVersion: current.version, actorKind: "person" });
+		} else result = await service.runtime.status();
+		// A login may return private credentials from an adapter. Print only the host service's safe status after it.
+		if (command === "login") result = await service.runtime.status();
+		if (command === "logout") {
+			const logout = { id, state: "disconnected", remoteRevocationConfirmed: result?.remoteRevocationConfirmed === true };
+			let status;
+			try { status = await service.runtime.status(); }
+			catch { status = { state: "unavailable", partial: true, connections: [] }; }
+			result = { ...status, logout };
+		}
+		write(`${JSON.stringify(result, (key, value) => ["accountGroup", "generation", "accountDigest", "credential", "registration"].includes(key) ? undefined : value, 2)}\n`);
+		return result?.ok === false || result?.kind === "unavailable" ? 2 : 0;
+	} catch (error) {
+		const code = typeof error?.code === "string" && /^(?:auth|subscription)-[a-z-]+$/.test(error.code) ? error.code : "auth-unavailable";
+		writeErr(`Subscription authentication: ${code}. Run auth status on the connection owner host.\n`);
+		return error?.transient === true ? 1 : 2;
+	} finally {
+		prompt?.close();
+		try { await redis?.quit(); } catch { redis?.disconnect?.(); }
+	}
+}