@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/projects.mjs

@@ -25,10 +25,33 @@ import { hash16 } from "./fleet-lease.mjs";
 import { PROJECT_ID_RE, isProjectId } from "./project-id.mjs";
 import { parseScopeString, qualifiedScopeOf } from "./pause-windows.mjs";
 import { canonicalScope } from "./scoped-limits.mjs";
+import { neededVersion } from "./store-version.mjs";
 
 /** The highest schema version this build reads. A file declaring a higher one is refused loudly. */
 export const PROJECTS_VERSION = 1;
 
+/**
+ * Each project field whose ABSENCE an older build would misread, with the version that introduced it (issue #761,
+ * `DES-STORE-VERSION-WHEN-NEEDED`). A project entry is a closed shape its writers rebuild, so an older admin drops a
+ * field it does not know on its next write: a new field that changes which scope a project holds (and so which cap
+ * counts it) must declare its version here and raise `PROJECTS_VERSION` in the same commit. Empty until one does.
+ */
+export const PROJECTS_FIELD_VERSIONS = Object.freeze({});
+
+/**
+ * The version a file of `rows` (the projects as written, `{ id, name?, members }`) needs: the LOWEST that expresses
+ * them, 1 while no field needs more, and never above `PROJECTS_VERSION` (a table above this build's version is its own
+ * bug, held by the table test). `version` is required in this file, so the writer always writes the number this
+ * returns; it is a function rather than the constant so the file keeps the lowest version when the constant rises.
+ */
+export function projectsVersionFor(rows, { table = PROJECTS_FIELD_VERSIONS, supported = PROJECTS_VERSION } = {}) {
+	const fields = new Set();
+	for (const row of Array.isArray(rows) ? rows : []) {
+		if (row !== null && typeof row === "object" && !Array.isArray(row)) for (const key of Object.keys(row)) fields.add(key);
+	}
+	return Math.min(neededVersion(fields, table), supported);
+}
+
 // The id rule lives in an import-free module, so the run record can check an id without this module's graph.
 export { PROJECT_ID_RE, isProjectId };
 

package/src/prompt-fence.mjs

@@ -0,0 +1,18 @@
+/**
+ * The code fence every piece of untrusted text in a prompt is wrapped in (CONST-ISSUE-TEXT-IS-DATA's render barrier).
+ *
+ * Moved here from github-prompt.mjs (issue #646) so the steer framing (steer-framing.mjs) can fence a running job's
+ * message with the SAME rule the trigger's own text gets, without importing a prompt builder (and its branch and
+ * session imports) to reach one function. github-prompt.mjs imports it back, so there is still exactly one fence rule:
+ * two copies would drift, and the one that drifted would be the one a crafted body escapes.
+ *
+ * Wrap untrusted content in a code fence long enough that the content cannot close it early. A `##` heading or a
+ * shorter backtick run inside the payload then renders literally, inside the fence, rather than escaping the data
+ * region. The fence is defense in depth, not the boundary: placement as a user turn is (see github-prompt.mjs).
+ */
+export function fenceBlock(content) {
+	const runs = String(content).match(/`+/g) ?? [];
+	const longest = runs.reduce((max, run) => Math.max(max, run.length), 0);
+	const fence = "`".repeat(Math.max(3, longest + 1));
+	return `${fence}text\n${content}\n${fence}`;
+}

package/src/provider-key.mjs

@@ -40,6 +40,13 @@ export const OAUTH_KEY_RE = /_OAUTH_TOKEN$/;
 // bless the next provider's bearer variable. Pinned against pi in worker/test/provider-key.test.mjs.
 export const BEARER_KEY_RE = /_AUTH_TOKEN$/;
 
+// These browser setup routes require host authentication guidance even when pi exposes
+// a token-shaped environment slot. This policy does not change runtime credential loading.
+export const HOST_AUTH_PROVIDERS = Object.freeze(["amazon-bedrock", "github-copilot", "google-vertex", "openai-codex"]);
+export function needsHostAuthentication(provider) {
+	return HOST_AUTH_PROVIDERS.includes(provider);
+}
+
 /**
  * Why a variable pi reads is not an API key, or null when it is one. The two answers need different
  * advice, so the caller is told which: an OAuth token is a subscription login that expires, a bearer token

package/src/provider-steering.mjs

@@ -174,6 +174,7 @@ const PI_OWN_READS = [
 	"PI_PACKAGE_DIR",
 	"PI_PROGRAM_STATUS",
 	"PI_RADIUS_GATEWAY",
+	"PI_SELF_UPDATE_COMMAND",
 	"PI_SHARE_VIEWER_URL",
 	"PI_SKIP_VERSION_CHECK",
 	"PI_STARTUP_BENCHMARK",

package/src/question-context.mjs

@@ -0,0 +1,35 @@
+import * as nodeFs from "node:fs";
+
+/**
+ * Private final context for semantic grouping. An oversized final entry is not skipped to find an older convenient
+ * question. The reader follows no link, holds a descriptor identity, and never reads an entire unbounded transcript.
+ */
+export function readQuestionContext({ path, redact, fs = nodeFs, readBytes = 64 * 1024, excerptBytes = 16 * 1024 } = {}) {
+	if (typeof redact !== "function") return { status: "source-unavailable" };
+	let fd;
+	try {
+		const before = fs.lstatSync(path);
+		if (!before.isFile() || before.isSymbolicLink()) return { status: "source-unavailable" };
+		fd = fs.openSync(path, nodeFs.constants.O_RDONLY | (nodeFs.constants.O_NOFOLLOW ?? 0));
+		const stat = fs.fstatSync(fd);
+		if (!stat.isFile() || stat.dev !== before.dev || stat.ino !== before.ino) return { status: "source-unavailable" };
+		const offset = Math.max(0, stat.size - readBytes);
+		const buffer = Buffer.alloc(Math.min(stat.size, readBytes));
+		const bytes = fs.readSync(fd, buffer, 0, buffer.length, offset);
+		const after = fs.fstatSync(fd);
+		if (bytes !== buffer.length || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) return { status: "source-unavailable" };
+		const raw = buffer.toString("utf8");
+		const complete = offset > 0 ? raw.slice(raw.indexOf("\n") + 1) : raw;
+		if (offset > 0 && (!raw.includes("\n") || !complete.trim() && raw.trim())) return { status: "source-oversize" };
+		const clean = redact(complete);
+		if (typeof clean !== "string" || !clean.trim()) return { status: "source-unavailable" };
+		if (Buffer.byteLength(clean) <= excerptBytes) return { status: "ready", text: clean, truncated: offset > 0 };
+		let kept = "";
+		for (const line of clean.split("\n").reverse()) {
+			if (Buffer.byteLength(`${line}\n${kept}`) > excerptBytes) break;
+			kept = `${line}\n${kept}`;
+		}
+		return kept.trim() ? { status: "ready", text: kept, truncated: true } : { status: "source-oversize" };
+	} catch { return { status: "source-unavailable" }; }
+	finally { if (fd !== undefined) try { fs.closeSync(fd); } catch {} }
+}

package/src/question-group-runtime.mjs

@@ -0,0 +1,91 @@
+import * as nodeFs from "node:fs";
+import { join } from "node:path";
+import { parseTriggersDocument } from "./triggers.mjs";
+import { questionDigest, QUESTION_RUN_RE, QUESTION_GROUP_LIMITS } from "./question-groups.mjs";
+
+export const QUESTION_GROUP_REASONS = Object.freeze(["question-group-unavailable", "question-group-config-changed", "question-group-source-expired", "question-group-source-unavailable", "question-group-source-oversize", "question-group-candidates-expired", "question-group-limit", "question-group-stale", "question-group-refused", "question-group-unanswered", "question-group-output-invalid"]);
+const policy = (reason) => ({ outcome: "policy", reason, budgetReserved: false });
+const modelRef = (text) => { const slash = text.indexOf("/"); return { provider: text.slice(0, slash), id: text.slice(slash + 1) }; };
+export const questionGroupConfigDigest = (config) => questionDigest(config);
+
+/** Queue data is references only. Private context is non-enumerable because queue deferrals serialize job.data. */
+export function makeQuestionGroupRuntime({ store, triggersPath, getSettings = () => ({}), resolveClassifier = () => null, readFile = nodeFs.readFileSync, fs = nodeFs } = {}) {
+	const config = () => parseTriggersDocument(readFile(triggersPath, "utf8"), triggersPath).zeroTouch;
+	return {
+		async resolve(data, runId) {
+			const ref = data?.questionGrouping;
+			// Admission deferrals can persist the resolved, text-free local wrapper. Rebuild it from the same narrow
+			// reference on every pickup; no queued execution setting or lost private property is reused.
+			if (!(data?.kind === "question-grouping" || data?.kind === "local" && data?.purpose === "zero-touch-grouping") || !ref || Object.keys(ref).sort().join() !== "configDigest,digest,runId" || !QUESTION_RUN_RE.test(ref.runId ?? "") || !/^[a-f0-9]{64}$/.test(ref.digest ?? "") || !/^[a-f0-9]{64}$/.test(ref.configDigest ?? "")) return { result: policy("question-group-refused") };
+			// Issue #761: a file a newer pi-dispatch wrote is `{ newer: <the store> }`, never a refusal, and is answered
+			// BEFORE any status is set: the processor defers the job (`newer-release`), and the grouping, queued with one
+			// attempt, is neither refused nor lost. The settings are read here, once, for that reason; a broken overlay is
+			// still refused below, where it always was.
+			const settings = getSettings();
+			if (settings?.invalid && settings.newer === true) return { newer: "the settings file" };
+			let current;
+			try { current = config(); } catch (error) { if (error?.newer === true) return { newer: "the triggers file" }; return { result: policy("question-group-config-changed") }; }
+			if (!current?.capture || questionGroupConfigDigest(current) !== ref.configDigest) return { result: policy("question-group-config-changed") };
+			const source = await store.privateInput(ref.runId);
+			if (source.status !== "ready") {
+				await store.setStatus(ref.runId, source.status);
+				const reason = ({ "source-expired": "question-group-source-expired", "source-unavailable": "question-group-source-unavailable", "source-oversize": "question-group-source-oversize", "candidates-expired": "question-group-candidates-expired", "group-limit": "question-group-limit" })[source.status] ?? "question-group-refused";
+				return { result: policy(reason) };
+			}
+			if (source.meta.digest !== ref.digest) return { result: policy("question-group-stale") };
+			if (settings.invalid || typeof settings.provider !== "string" || typeof settings.model !== "string") return { result: policy("question-group-refused") };
+			const classifier = modelRef(current.model);
+			let selected;
+			try { selected = await resolveClassifier(classifier); } catch { return { result: policy("question-group-refused") }; }
+			// The full reviewed context window is a conservative input-only price ceiling, not a guessed tokenizer.
+			// The runner still checks the exact call at its dispatch boundary before it can reach the provider.
+			if (!selected || selected.type !== "classifier" || !Number.isFinite(selected.cost?.input) || selected.cost.input < 0 || selected.cost.output !== 0 || !Number.isSafeInteger(selected.contextWindow) || selected.contextWindow <= 0) return { result: policy("question-group-refused") };
+			const boundMicros = Math.ceil(selected.contextWindow * selected.cost.input);
+			if (!Number.isSafeInteger(boundMicros) || boundMicros > Math.round(Number(current.maxCostUsd) * 1000000)) return { result: policy("question-group-refused") };
+			const grouping = { ...ref };
+			Object.defineProperties(grouping, {
+				input: { value: { version: 1, model: classifier, source: source.excerpt, candidates: source.candidates.map((candidate, i) => ({ slot: `g${i}`, excerpt: candidate.excerpt })), confidence: current.confidence } },
+				candidateIds: { value: source.candidates.map((candidate) => candidate.id) },
+				revision: { value: source.revision }, project: { value: source.meta.project }, jobId: { value: runId },
+			});
+			await store.setStatus(ref.runId, "pending");
+			return { data: { kind: "local", purpose: "zero-touch-grouping", provider: settings.provider, model: settings.model, maxCostUsd: current.maxCostUsd, models: [...new Set([`${settings.provider}/${settings.model}`, current.model])], maxTurns: 1, packages: false, github: false, questionGroupModel: classifier, questionGrouping: grouping } };
+		},
+		/** Collection never throws: neither invalid output nor a store failure is permission to buy the call again. */
+		async collect({ job, prepared, completed }) {
+			if (!job?.questionGrouping || !prepared?.outboxDir) return null;
+			const ref = job.questionGrouping;
+			try {
+				if (!completed) { await store.setStatus(ref.runId, "failed"); return { status: "failed" }; }
+				const current = config();
+				if (!current?.capture || questionGroupConfigDigest(current) !== ref.configDigest) { await store.setStatus(ref.runId, "stale"); return { status: "stale" }; }
+				const path = join(prepared.outboxDir, "question-group.json");
+				const stat = fs.lstatSync(path);
+				if (!stat.isFile() || stat.isSymbolicLink?.() || stat.size > 1024) throw new Error("invalid output");
+				const bytes = fs.readFileSync(path);
+				if (Buffer.byteLength(bytes) > 1024) throw new Error("invalid output");
+				const output = JSON.parse(bytes);
+				const allowed = ["new", "unassigned", ...ref.candidateIds.map((_, i) => `g${i}`)];
+				if (!output || Object.keys(output).sort().join() !== "confidence,slot,version" || output.version !== 1 || !allowed.includes(output.slot) || typeof output.confidence !== "number" || !Number.isFinite(output.confidence) || output.confidence < current.confidence || output.confidence > 1) throw new Error("invalid output");
+				if (output.slot === "unassigned") { await store.setStatus(ref.runId, "unassigned"); return { status: "unassigned" }; }
+				const groupId = output.slot === "new" ? null : ref.candidateIds[Number(output.slot.slice(1))];
+				const result = await store.assign({ runId: ref.runId, digest: ref.digest, revision: ref.revision, groupId });
+				if (result.status !== "assigned" && result.status !== "existing") await store.setStatus(ref.runId, "stale");
+				return result;
+			} catch { try { await store.setStatus(ref.runId, "failed"); } catch {} return { status: "failed" }; }
+		},
+	};
+}
+
+/** A classifier needs no repository tree or credentials; the existing container's /job and /outbox suffice. */
+export function prepareQuestionGrouping(job, { jobDir, fs = nodeFs } = {}) {
+	const input = job?.questionGrouping?.input;
+	if (!input || Buffer.byteLength(JSON.stringify(input)) > QUESTION_GROUP_LIMITS.inputBytes) return policy("question-group-source-oversize");
+	const workspace = join(jobDir, "workspace");
+	const outboxDir = join(jobDir, "outbox");
+	fs.mkdirSync(workspace, { recursive: true }); fs.mkdirSync(outboxDir, { recursive: true });
+	fs.writeFileSync(join(jobDir, "prompt.md"), "", { mode: 0o444 });
+	fs.writeFileSync(join(jobDir, "event.json"), JSON.stringify({ source: "zero-touch-grouping" }), { mode: 0o444 });
+	fs.writeFileSync(join(jobDir, "question-grouping.json"), JSON.stringify(input), { mode: 0o444 });
+	return { workspace, jobDir, outboxDir, sha: null, materialised: [], workspaceReadOnly: true };
+}

package/src/question-groups.mjs

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+
+/** Private question context and public assignment metadata are separate stores. A public read never fetches text. */
+export const QUESTION_GROUP_LIMITS = Object.freeze({ excerptBytes: 16384, inputBytes: 262144, corpusEntries: 1000, metadataEntries: 5000, candidates: 14, retentionDays: 90, timeoutMs: 2000 });
+export const QUESTION_GROUP_STATUSES = Object.freeze(["unassigned", "pending", "assigned", "source-expired", "source-unavailable", "source-oversize", "candidates-expired", "group-limit", "stale", "refused", "failed"]);
+export const GROUP_ID_RE = /^[a-f0-9]{32}$/;
+export const QUESTION_SCOPE_RE = /^[a-f0-9]{64}$/;
+export const QUESTION_RUN_RE = /^[A-Za-z0-9._:-]{1,200}$/;
+const sha = (value) => createHash("sha256").update(value).digest("hex");
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+const own = (value, keys) => object(value) && Object.keys(value).every((key) => keys.includes(key));
+const safeWord = (value, max = 200) => typeof value === "string" && value.length <= max && /^[A-Za-z0-9._:/ @!#-]+$/.test(value);
+export const questionDigest = (value) => sha(JSON.stringify(value));
+
+/** No model-owned names or prompts live here. Names are operator-owned and never sent as classification criteria. */
+export function validateZeroTouchConfig(value) {
+	if (value === undefined || value === null) return null;
+	if (!own(value, ["capture", "model", "maxCostUsd", "confidence", "names"]) || typeof value.capture !== "boolean") throw new Error("zeroTouch requires capture and only declared grouping settings");
+	if (typeof value.model !== "string" || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_./:@~+-]{1,128}$/.test(value.model)) throw new Error("zeroTouch.model requires an explicit provider/model");
+	if (typeof value.maxCostUsd !== "string" || !/^(?:0|[1-9]\d*)(?:\.\d{1,6})?$/.test(value.maxCostUsd) || !Number.isSafeInteger(Number(value.maxCostUsd) * 1e6)) throw new Error("zeroTouch.maxCostUsd must be a bounded dollar string");
+	const confidence = value.confidence ?? 0.9;
+	if (typeof confidence !== "number" || confidence <= 0.5 || confidence > 1) throw new Error("zeroTouch.confidence must be above 0.5 and at most 1");
+	const names = value.names ?? {};
+	if (!object(names) || Object.keys(names).length > 1000) throw new Error("zeroTouch.names must hold at most 1000 human names");
+	for (const [id, name] of Object.entries(names)) if (!GROUP_ID_RE.test(id) || typeof name !== "string" || !name.trim() || [...name].length > 120 || /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/u.test(name)) throw new Error("zeroTouch group names must be human text of 1 to 120 characters without controls");
+	return { capture: value.capture, model: value.model, maxCostUsd: value.maxCostUsd, confidence, names: { ...names } };
+}
+
+/** Redact before bounding; silently cutting before redaction can expose the head of a secret. */
+export function privateQuestionExcerpt(text, redact) {
+	if (typeof redact !== "function" || typeof text !== "string" || text === "") return { status: "source-unavailable" };
+	let clean;
+	try { clean = redact(text); } catch { return { status: "source-unavailable" }; }
+	if (typeof clean !== "string" || !clean.trim()) return { status: "source-unavailable" };
+	// The caller supplies the run's final bounded context, not a model-generated summary. Overlong context is
+	// refused rather than pretending the omitted half of a question was understood.
+	if (Buffer.byteLength(clean) > QUESTION_GROUP_LIMITS.excerptBytes) return { status: "source-oversize" };
+	return { status: "unassigned", excerpt: clean };
+}
+
+export const QUESTION_CAPTURE_SCRIPT = `
+if redis.call("EXISTS", KEYS[2]) == 1 then return "existing" end
+redis.call("SET", KEYS[1], ARGV[1], "PX", ARGV[4])
+redis.call("SET", KEYS[2], ARGV[2], "PX", ARGV[5])
+redis.call("ZADD", KEYS[3], ARGV[3], ARGV[6])
+redis.call("ZADD", KEYS[4], ARGV[3], ARGV[6])
+local cut = redis.call("ZRANGE", KEYS[3], 0, -tonumber(ARGV[7])-1)
+for _, id in ipairs(cut) do redis.call("DEL", ARGV[9] .. id) end
+if #cut > 0 then redis.call("ZREM", KEYS[3], unpack(cut)) end
+redis.call("ZREMRANGEBYRANK", KEYS[4], 0, -tonumber(ARGV[8])-1)
+redis.call("PEXPIRE", KEYS[3], ARGV[4]); redis.call("PEXPIRE", KEYS[4], ARGV[5])
+return "captured"
+`;
+export const QUESTION_ASSIGN_SCRIPT = `
+local old = redis.call("GET", KEYS[2])
+if not old then return "source-expired" end
+local meta = cjson.decode(old)
+if meta.groupId then return "existing" end
+if meta.digest ~= ARGV[1] then return "stale" end
+local rev = tonumber(redis.call("HGET", KEYS[1], "revision") or "0")
+if rev ~= tonumber(ARGV[2]) then return "stale" end
+if ARGV[3] == "new" then
+ redis.call("HSET", KEYS[1], ARGV[4], ARGV[5], "revision", rev + 1)
+elseif redis.call("HEXISTS", KEYS[1], ARGV[4]) == 0 then return "stale" end
+meta.groupId = ARGV[4]; meta.status = "assigned"
+redis.call("SET", KEYS[2], cjson.encode(meta), "PX", ARGV[6])
+redis.call("PEXPIRE", KEYS[1], ARGV[6])
+return "assigned"
+`;
+
+function bounded(promise, ms) {
+	let timer;
+	return Promise.race([Promise.resolve(promise), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("question-store-timeout")), ms); })]).finally(() => clearTimeout(timer));
+}
+const json = (value) => { try { return JSON.parse(value); } catch { return null; } };
+const validMeta = (m) => own(m, ["v", "runId", "scopeId", "project", "repo", "at", "digest", "status", "groupId", "triggerIndex", "contextTruncated"]) && m.v === 1 && QUESTION_RUN_RE.test(m.runId) && QUESTION_SCOPE_RE.test(m.scopeId) && integer(m.at) && /^[a-f0-9]{64}$/.test(m.digest) && QUESTION_GROUP_STATUSES.includes(m.status) && (m.groupId === undefined || GROUP_ID_RE.test(m.groupId)) && (m.project === null || safeWord(m.project, 64)) && (m.repo === null || safeWord(m.repo)) && (m.triggerIndex === undefined || integer(m.triggerIndex)) && (m.contextTruncated === undefined || typeof m.contextTruncated === "boolean");
+
+export function makeQuestionGroupStore({ redis, now = Date.now, retentionDays = 30, prefix = "zero-touch:questions:", timeoutMs = QUESTION_GROUP_LIMITS.timeoutMs } = {}) {
+	const days = Number(retentionDays);
+	// Even keep-forever deployments have a finite private corpus. Its shorter availability is explicit.
+	const ttlMs = Math.min(Number.isFinite(days) && days > 0 ? days : QUESTION_GROUP_LIMITS.retentionDays, QUESTION_GROUP_LIMITS.retentionDays) * 86400000;
+	const metaTtlMs = Math.max(ttlMs, 86400000);
+	const token = (runId) => sha(runId);
+	const privateKey = (runId) => `${prefix}private:${token(runId)}`;
+	const metaKey = (runId) => `${prefix}meta:${token(runId)}`;
+	const command = (method, ...args) => bounded(redis[method](...args), timeoutMs);
+	async function readMeta(runId) {
+		if (!QUESTION_RUN_RE.test(runId ?? "")) return null;
+		const raw = await command("get", metaKey(runId));
+		if (typeof raw !== "string" || Buffer.byteLength(raw) > 2048) return null;
+		const meta = json(raw);
+		return validMeta(meta) ? meta : null;
+	}
+	return {
+		async capture({ runId, scopeId, project = null, repo = null, at = now(), text, redact, triggerIndex, sourceStatus = null, contextTruncated = false } = {}) {
+			if (!QUESTION_RUN_RE.test(runId ?? "") || !QUESTION_SCOPE_RE.test(scopeId ?? "") || !integer(at) || project !== null && !safeWord(project, 64) || repo !== null && !safeWord(repo) || triggerIndex !== undefined && !integer(triggerIndex)) return { ok: false, status: "source-unavailable" };
+			if (sourceStatus !== null && !["source-unavailable", "source-oversize"].includes(sourceStatus) || typeof contextTruncated !== "boolean") return { ok: false, status: "source-unavailable" };
+			const selected = sourceStatus === null ? privateQuestionExcerpt(text, redact) : { status: sourceStatus };
+			const digest = sha(selected.excerpt ?? `${runId}:${selected.status}`);
+			const meta = { v: 1, runId, scopeId, project, repo, at, digest, status: selected.status, ...(contextTruncated ? { contextTruncated: true } : {}), ...(triggerIndex !== undefined ? { triggerIndex } : {}) };
+			try {
+				if (selected.excerpt === undefined) {
+					await command("set", metaKey(runId), JSON.stringify(meta), "PX", metaTtlMs, "NX");
+					await command("zadd", `${prefix}index`, at, token(runId));
+					await command("pexpire", `${prefix}index`, metaTtlMs);
+					return { ok: true, status: selected.status };
+				}
+				await command("eval", QUESTION_CAPTURE_SCRIPT, 4, privateKey(runId), metaKey(runId), `${prefix}corpus`, `${prefix}index`, JSON.stringify({ v: 1, runId, scopeId, at, digest, excerpt: selected.excerpt }), JSON.stringify(meta), at, ttlMs, metaTtlMs, token(runId), QUESTION_GROUP_LIMITS.corpusEntries, QUESTION_GROUP_LIMITS.metadataEntries, `${prefix}private:`);
+				return { ok: true, status: "unassigned" };
+			} catch { return { ok: false, status: "source-unavailable" }; }
+		},
+		readMeta,
+		async publicSnapshot({ sinceMs = 0, names = {} } = {}) {
+			try {
+				const ids = await command("zrevrangebyscore", `${prefix}index`, "+inf", sinceMs, "LIMIT", 0, QUESTION_GROUP_LIMITS.metadataEntries);
+				if (!Array.isArray(ids) || ids.some((id) => !/^[a-f0-9]{64}$/.test(id))) throw new Error("invalid index");
+				const raw = ids.length ? await command("mget", ...ids.map((id) => `${prefix}meta:${id}`)) : [];
+				const rows = raw.map(json).filter(validMeta);
+				// Availability probes read only key existence. A public projection never loads private bytes.
+				for (let i = 0; i < rows.length; i += 100) {
+					await Promise.all(rows.slice(i, i + 100).map(async row => {
+						if (!row.groupId && ["unassigned", "pending", "failed", "stale"].includes(row.status) && !await command("exists", privateKey(row.runId))) row.status = "source-expired";
+					}));
+				}
+				const groups = new Map();
+				for (const row of rows) {
+					const id = row.groupId ?? `unassigned-${row.scopeId}`;
+					if (!groups.has(id)) groups.set(id, { id: row.groupId ?? null, name: row.groupId && typeof names[row.groupId] === "string" ? names[row.groupId] : null, scopeId: row.scopeId, repo: row.repo, project: row.project, count: 0, runIds: [], status: row.groupId ? "open" : "unassigned", sourceStatus: row.status, ...(row.triggerIndex !== undefined ? { triggerIndex: row.triggerIndex } : {}) });
+					const group = groups.get(id); group.count++; group.runIds.push(row.runId);
+				}
+				return { state: "ok", groups: [...groups.values()], rows, partial: rows.length !== raw.length || ids.length === QUESTION_GROUP_LIMITS.metadataEntries || rows.some(row => row.contextTruncated === true) };
+			} catch { return { state: "unavailable", groups: [], rows: [], partial: true }; }
+		},
+		async privateInput(runId) {
+			const meta = await readMeta(runId);
+			if (!meta || !["unassigned", "pending", "assigned", "failed", "stale", "refused"].includes(meta.status)) return { status: meta?.status ?? "source-expired" };
+			const raw = await command("get", privateKey(runId));
+			if (typeof raw !== "string" || Buffer.byteLength(raw) > QUESTION_GROUP_LIMITS.excerptBytes + 1024) return { status: "source-expired" };
+			const source = json(raw);
+			if (!object(source) || source.runId !== runId || source.scopeId !== meta.scopeId || source.digest !== meta.digest || typeof source.excerpt !== "string" || sha(source.excerpt) !== meta.digest) return { status: "source-unavailable" };
+			const groupRaw = await command("hgetall", `${prefix}groups:${meta.scopeId}`);
+			const revision = Number(groupRaw.revision ?? 0);
+			const candidates = [];
+			for (const [id, encoded] of Object.entries(groupRaw)) {
+				if (id === "revision") continue;
+				const candidate = json(encoded);
+				if (!GROUP_ID_RE.test(id) || !own(candidate, ["id", "runId", "at"]) || candidate.id !== id || !QUESTION_RUN_RE.test(candidate.runId) || !integer(candidate.at)) return { status: "source-unavailable" };
+				const exemplarRaw = await command("get", privateKey(candidate.runId));
+				const exemplar = typeof exemplarRaw === "string" && Buffer.byteLength(exemplarRaw) <= QUESTION_GROUP_LIMITS.excerptBytes + 1024 ? json(exemplarRaw) : null;
+				if (!exemplar || exemplar.scopeId !== meta.scopeId || typeof exemplar.excerpt !== "string" || sha(exemplar.excerpt) !== exemplar.digest) return { status: "candidates-expired" };
+				candidates.push({ id, runId: candidate.runId, excerpt: exemplar.excerpt });
+			}
+			if (candidates.length > QUESTION_GROUP_LIMITS.candidates) return { status: "group-limit" };
+			return { status: "ready", meta, revision, excerpt: source.excerpt, candidates: candidates.sort((a, b) => a.id.localeCompare(b.id)) };
+		},
+		async assign({ runId, digest, revision, groupId = null } = {}) {
+			const meta = await readMeta(runId);
+			if (!meta || meta.digest !== digest || !integer(revision) || groupId !== null && !GROUP_ID_RE.test(groupId)) return { status: "stale" };
+			const id = groupId ?? sha(`${meta.scopeId}\0${runId}`).slice(0, 32);
+			const status = await command("eval", QUESTION_ASSIGN_SCRIPT, 2, `${prefix}groups:${meta.scopeId}`, metaKey(runId), digest, revision, groupId === null ? "new" : "existing", id, JSON.stringify({ id, runId, at: meta.at }), metaTtlMs);
+			return { status, ...(status === "assigned" || status === "existing" ? { groupId: id } : {}) };
+		},
+		async setStatus(runId, status) {
+			if (!QUESTION_GROUP_STATUSES.includes(status)) return false;
+			if (!QUESTION_RUN_RE.test(runId ?? "")) return false;
+			const script = `local raw=redis.call("GET",KEYS[1]); if not raw then return 0 end; local meta=cjson.decode(raw); if meta.groupId then return 0 end; meta.status=ARGV[1]; redis.call("SET",KEYS[1],cjson.encode(meta),"PX",ARGV[2]); return 1`;
+			return await command("eval", script, 1, metaKey(runId), status, metaTtlMs) === 1;
+		},
+	};
+}