@staix/agent-hub 0.20.0 → 0.21.0

package/src/hub/schedules.ts

@@ -0,0 +1,266 @@
+import { Database } from "bun:sqlite";
+import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { corpusPathProblem } from "./corpus-config.ts";
+
+// agent-hub #512 (hub task #330): machine-local schedules. Spec: "Schedules and folder triggers (#512)".
+
+export const MIN_EVERY_MS = 15 * 60_000;
+export const MAX_EVERY_MS = 365 * 86_400_000;
+export const MAX_SCHEDULES = 64;
+export const MAX_SCHEDULE_SOURCES = 16;
+/** Under the board's 8000-character detail cap with the fixed lines and 16 source lines around it, so the marker line is never cut off. */
+export const MAX_SCHEDULE_DETAIL = 7000;
+/** The first line of a scheduled task's detail: how the board finds the task a schedule made, whatever hub.db remembers. */
+export const SCHEDULE_MARKER = "Schedule key: ";
+
+export interface ScheduleEntry {
+  id: string;
+  every: string;
+  class: string;
+  title: string;
+  detail?: string;
+  sources?: string[];
+  owner?: string;
+  queue: "backlog" | "ready";
+}
+
+/** The source id form of `src/hub/sources.ts` (`validSourceId`), repeated here because that module reaches the file system and the converters and this one is bundled into the Claude channel server through the config schema; `test/schedules.test.ts` pins that the two agree. */
+export const SOURCE_ID = /^src:[0-9a-f]{16}$/;
+const ID = /^[a-z0-9][a-z0-9_-]{0,47}$/, PEER = /^[a-z][a-z0-9-]{0,31}$/, CLASS = /^[a-z][a-z0-9_]{0,47}$/, KEYS = new Set(["id", "every", "cron", "class", "title", "detail", "sources", "owner", "queue"]);
+const control = /[\x00-\x1f\x7f]/;
+
+/** `<n>m|h|d` to milliseconds; a thrown reason otherwise. The 15-minute floor keeps a typo from flooding the board. */
+export function parseEvery(value: unknown): number {
+  const match = typeof value === "string" ? /^([1-9][0-9]{0,5})([mhd])$/.exec(value) : null;
+  if (!match) throw new Error("every must be <n>m, <n>h or <n>d, such as 90m, 6h or 1d");
+  const ms = Number(match[1]) * { m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2] as "m" | "h" | "d"];
+  if (ms < MIN_EVERY_MS) throw new Error("every must be at least 15m");
+  if (ms > MAX_EVERY_MS) throw new Error("every must be at most 365d");
+  return ms;
+}
+
+/** The checked `schedules` list. Every refusal names the entry; nothing here reads the board, a clock or a file. */
+export function schedulesConfig(input: unknown): ScheduleEntry[] {
+  if (input === undefined) return [];
+  if (!Array.isArray(input)) throw new Error("schedules must be a list");
+  if (input.length > MAX_SCHEDULES) throw new Error(`schedules holds at most ${MAX_SCHEDULES} entries`);
+  const seen = new Set<string>(), out: ScheduleEntry[] = [];
+  input.forEach((raw, index) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`schedules[${index}] must be an object`);
+    const row = raw as Record<string, unknown>;
+    const name = typeof row.id === "string" && ID.test(row.id) ? `schedules.${row.id}` : `schedules[${index}]`;
+    const bad = (reason: string): never => { throw new Error(`${name}: ${reason}`); };
+    for (const key of Object.keys(row)) if (!KEYS.has(key)) bad(`unknown key ${key}`);
+    if (typeof row.id !== "string" || !ID.test(row.id)) bad("id is 1 to 48 lower-case letters, digits, - or _");
+    if (seen.has(row.id as string)) bad("duplicate id");
+    seen.add(row.id as string);
+    if (row.cron !== undefined) bad("cron not supported yet; use every");
+    try { parseEvery(row.every); } catch (error) { bad((error as Error).message); }
+    if (typeof row.class !== "string" || !CLASS.test(row.class)) bad("class is required");
+    if (typeof row.title !== "string" || !row.title.trim() || row.title.length > 300 || control.test(row.title)) bad("title is 1 to 300 printable characters on one line");
+    if (row.detail !== undefined && (typeof row.detail !== "string" || row.detail.length > MAX_SCHEDULE_DETAIL || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(row.detail))) bad(`detail is text of at most ${MAX_SCHEDULE_DETAIL} characters`);
+    if (row.owner !== undefined && (typeof row.owner !== "string" || !PEER.test(row.owner))) bad("owner is a peer id");
+    if (row.queue !== undefined && row.queue !== "backlog" && row.queue !== "ready") bad('queue is "backlog" or "ready"');
+    if (row.sources !== undefined) {
+      if (!Array.isArray(row.sources) || row.sources.length > MAX_SCHEDULE_SOURCES || !row.sources.every(id => typeof id === "string" && SOURCE_ID.test(id))) bad(`sources is a list of at most ${MAX_SCHEDULE_SOURCES} source ids (src:<16 hex>)`);
+    }
+    out.push({
+      id: row.id as string, every: row.every as string, class: row.class as string, title: (row.title as string).replace(/\s+/g, " ").trim(),
+      ...(row.detail !== undefined ? { detail: row.detail as string } : {}), ...(row.sources !== undefined ? { sources: [...(row.sources as string[])] } : {}),
+      ...(row.owner !== undefined ? { owner: row.owner as string } : {}), queue: (row.queue as "backlog" | "ready" | undefined) ?? "backlog",
+    });
+  });
+  return out;
+}
+
+// agent-hub #512c (hub task #336): machine-local folder triggers. The pure config only; the scan, the store and the registration are in `folder-trigger.ts`, which reaches the disk.
+export const MAX_FOLDER_TRIGGERS = 16;
+export const MAX_FOLDER_GLOB = 100;
+/** The first line of a folder-triggered task's detail: which trigger made it. A task per file, so unlike a schedule's marker it blocks nothing. */
+export const FOLDER_MARKER = "Folder trigger: ";
+
+export interface FolderEntry {
+  id: string;
+  folder: string;
+  glob?: string;
+  class: string;
+  title: string;
+  detail?: string;
+  owner?: string;
+  queue: "backlog" | "ready";
+}
+const FOLDER_KEYS = new Set(["id", "folder", "glob", "class", "title", "detail", "owner", "queue"]);
+
+/** A file-name pattern: letters, digits, `.`, `_`, `-`, space, `*` and `?`. Never a path, so it cannot reach outside the folder. */
+export const folderGlobProblem = (value: unknown): string | undefined =>
+  typeof value !== "string" || !value || value.length > MAX_FOLDER_GLOB || !/^[A-Za-z0-9._ *?-]+$/.test(value) || value === "." || value === ".."
+    ? `glob is a file-name pattern of at most ${MAX_FOLDER_GLOB} characters (letters, digits, . _ - space, * and ?), never a path` : undefined;
+
+/** Whether a file name matches a trigger's glob. Dot files never match: a hidden file is not something a person dropped in. */
+export function folderGlobMatches(glob: string | undefined, name: string): boolean {
+  if (name.startsWith(".")) return false;
+  if (glob === undefined) return true;
+  return new RegExp(`^${glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`).test(name);
+}
+
+/** The checked `folder_triggers` list. Every refusal names the entry; nothing here reads the disk (the folder check does, at each poll). */
+export function foldersConfig(input: unknown): FolderEntry[] {
+  if (input === undefined) return [];
+  if (!Array.isArray(input)) throw new Error("folder_triggers must be a list");
+  if (input.length > MAX_FOLDER_TRIGGERS) throw new Error(`folder_triggers holds at most ${MAX_FOLDER_TRIGGERS} entries`);
+  const seen = new Set<string>(), out: FolderEntry[] = [];
+  input.forEach((raw, index) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`folder_triggers[${index}] must be an object`);
+    const row = raw as Record<string, unknown>;
+    const name = typeof row.id === "string" && ID.test(row.id) ? `folder_triggers.${row.id}` : `folder_triggers[${index}]`;
+    const bad = (reason: string): never => { throw new Error(`${name}: ${reason}`); };
+    for (const key of Object.keys(row)) if (!FOLDER_KEYS.has(key)) bad(`unknown key ${key}`);
+    if (typeof row.id !== "string" || !ID.test(row.id)) bad("id is 1 to 48 lower-case letters, digits, - or _");
+    if (seen.has(row.id as string)) bad("duplicate id");
+    seen.add(row.id as string);
+    const folderProblem = corpusPathProblem(row.folder);
+    if (folderProblem) bad(folderProblem.replace("a corpus path", "folder"));
+    if (row.glob !== undefined) { const problem = folderGlobProblem(row.glob); if (problem) bad(problem); }
+    if (typeof row.class !== "string" || !CLASS.test(row.class)) bad("class is required");
+    if (typeof row.title !== "string" || !row.title.trim() || row.title.length > 300 || control.test(row.title)) bad("title is 1 to 300 printable characters on one line");
+    if (row.detail !== undefined && (typeof row.detail !== "string" || row.detail.length > MAX_SCHEDULE_DETAIL || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(row.detail))) bad(`detail is text of at most ${MAX_SCHEDULE_DETAIL} characters`);
+    if (row.owner !== undefined && (typeof row.owner !== "string" || !PEER.test(row.owner))) bad("owner is a peer id");
+    if (row.queue !== undefined && row.queue !== "backlog" && row.queue !== "ready") bad('queue is "backlog" or "ready"');
+    out.push({
+      id: row.id as string, folder: row.folder as string, ...(row.glob !== undefined ? { glob: row.glob as string } : {}), class: row.class as string,
+      title: (row.title as string).replace(/\s+/g, " ").trim(), ...(row.detail !== undefined ? { detail: row.detail as string } : {}),
+      ...(row.owner !== undefined ? { owner: row.owner as string } : {}), queue: (row.queue as "backlog" | "ready" | undefined) ?? "backlog",
+    });
+  });
+  return out;
+}
+
+/** What one poll of a trigger did: `baseline` (first poll, recorded only), `ran`, `none`, `held`, `refused` (the folder may not be read, with the reason) or `failed`. */
+export interface FolderRunResult { id: string; outcome: "baseline" | "ran" | "none" | "held" | "refused" | "failed"; tasks: number[]; files: number; reason?: string; more?: true }
+/**
+ * One file a poll found: its real path, name, size, mtime and SHA-256, and never its bytes (a scan of a big inbox would hold them all). `seen` marks a file the trigger
+ * already recorded at this path, size and mtime: its hash is the recorded one and the file was not read again.
+ */
+export interface ScannedFile { real: string; name: string; size: number; mtime: number; sha256: string; seen?: true }
+/** What a read of a trigger's folder gave. `refused` is the reason the folder may not be read; `truncated` says the hash budget ran out and some files wait for the next poll. */
+export interface FolderScan { folder?: string; files: ScannedFile[]; skipped: { name: string; reason: string }[]; refused?: string; truncated: boolean }
+/** The part of the folder state `Tasks` needs. The scan, the disk and the table are in `folder-trigger.ts`, which the Claude channel bundle must not reach. */
+export interface FolderStorePort {
+  baselined(trigger: string): boolean;
+  begin(trigger: string, now: number): void;
+  markBaselined(trigger: string, now: number): void;
+  polled(trigger: string, now: number, error?: string): void;
+  isNew(trigger: string, sha256: string): boolean;
+  record(trigger: string, file: Pick<ScannedFile, "real" | "size" | "mtime" | "sha256">, task: number | null, now: number): void;
+  observe(trigger: string, file: Pick<ScannedFile, "real" | "size" | "mtime" | "sha256">, now: number): void;
+  prune(keep: readonly string[]): void;
+}
+/** New files one poll registers per trigger: a drop of a whole archive becomes a handful of tasks per tick, never a burst. */
+export const MAX_NEW_PER_POLL = 20;
+
+/** The detail of a folder-triggered task: the marker first, then the person's text, then the one source it names. Never the file's name or path: both can be private. */
+export function folderDetail(entry: FolderEntry, source: string): string {
+  return [`${FOLDER_MARKER}${entry.id}`, `Made by the machine-local folder trigger "${entry.id}" for a new file, registered as the source below.`, ...(entry.detail ? ["", entry.detail] : []), "", `Source: ${source}`].join("\n");
+}
+
+export interface ScheduleRow {
+  id: string;
+  /** The start of the current period: the first time the schedule was seen, then the last run. The next run is this plus `every`. */
+  anchor: number;
+  last_run: number | null;
+  last_task: number | null;
+  /** Ticks that were due and skipped (held, or the previous task still open) since the last run: coalesced into the one run that follows. */
+  coalesced: number;
+  last_error: string | null;
+  /** #335: 1 while a person has paused it. */
+  paused?: number;
+}
+
+/** `schedule_runs` in hub.db: when each schedule last ran and what it made. The board stays the record of the tasks themselves. */
+export class ScheduleStore {
+  private readonly db: Database;
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
+    this.db.run("CREATE TABLE IF NOT EXISTS schedule_runs (id TEXT PRIMARY KEY, anchor INTEGER NOT NULL, last_run INTEGER, last_task INTEGER, coalesced INTEGER NOT NULL DEFAULT 0, last_error TEXT)");
+    // #335: a person's pause. A column on the existing table, so an older database gains it and every older row reads as not paused.
+    if (!(this.db.query("PRAGMA table_info(schedule_runs)").all() as { name: string }[]).some(column => column.name === "paused")) this.db.run("ALTER TABLE schedule_runs ADD COLUMN paused INTEGER NOT NULL DEFAULT 0");
+  }
+  get(id: string): ScheduleRow | undefined { return (this.db.query("SELECT * FROM schedule_runs WHERE id = ?").get(id) as ScheduleRow | null) ?? undefined; }
+  rows(): ScheduleRow[] { return this.db.query("SELECT * FROM schedule_runs ORDER BY id").all() as ScheduleRow[]; }
+  /** A schedule seen for the first time starts its period now: it never runs at once, and a restart never replays a missed one. */
+  ensure(id: string, now: number): ScheduleRow {
+    this.db.query("INSERT OR IGNORE INTO schedule_runs(id, anchor) VALUES(?, ?)").run(id, now);
+    return this.get(id)!;
+  }
+  /**
+   * A schedule's pause generation, in memory: `setPaused` bumps it. A run captures it when it is admitted and its write fence asks again, so a pause or a resume that
+   * lands while the run awaits its PII screen cancels that run instead of being overtaken by it. A restart ends every run in flight, so memory is enough.
+   */
+  private readonly epochs = new Map<string, number>();
+  epoch(id: string): number { return this.epochs.get(id) ?? 0; }
+  /**
+   * #335: pause or resume one schedule. A pause stops the timer from proposing it and counts no skipped tick. Resuming starts a fresh period at `now`, so a long
+   * pause is never replayed as a run the moment it ends, as a restart is never replayed either.
+   */
+  setPaused(id: string, paused: boolean, now: number): void {
+    this.epochs.set(id, this.epoch(id) + 1);
+    this.db.query("INSERT OR IGNORE INTO schedule_runs(id, anchor) VALUES(?, ?)").run(id, now);
+    if (paused) this.db.query("UPDATE schedule_runs SET paused = 1 WHERE id = ?").run(id);
+    else this.db.query("UPDATE schedule_runs SET paused = 0, anchor = ?, coalesced = 0 WHERE id = ?").run(now, id);
+  }
+  skipped(id: string): void { this.db.query("UPDATE schedule_runs SET coalesced = coalesced + 1 WHERE id = ?").run(id); }
+  ran(id: string, now: number, task: number): void {
+    // The anchor never moves back: a resume that landed after the task was written already started a later period, and an older pass timestamp must not shorten it.
+    this.db.query("UPDATE schedule_runs SET anchor = MAX(anchor, ?), last_run = ?, last_task = ?, coalesced = 0, last_error = NULL WHERE id = ?").run(now, now, task, id);
+  }
+  failed(id: string, reason: string): void { this.db.query("UPDATE schedule_runs SET last_error = ? WHERE id = ?").run(reason.slice(0, 200), id); }
+  /** A schedule removed from the config keeps no row. */
+  prune(keep: readonly string[]): void {
+    for (const row of this.rows()) if (!keep.includes(row.id)) this.db.query("DELETE FROM schedule_runs WHERE id = ?").run(row.id);
+  }
+  close(): void { try { this.db.close(); } catch { /* already closed */ } }
+}
+
+/** What one run of a schedule did. `changed`: the person paused or resumed it after the run was admitted, so it wrote nothing (#335). */
+export type ScheduleOutcome = "ran" | "held" | "waiting" | "failed" | "changed";
+export interface ScheduleRunResult { id: string; outcome: ScheduleOutcome; task?: number }
+
+export type ScheduleState = "scheduled" | "due" | "waiting" | "held" | "paused";
+export interface ScheduleView {
+  id: string;
+  every: string;
+  class: string;
+  queue: "backlog" | "ready";
+  next: number;
+  last?: number;
+  task?: number;
+  state: ScheduleState;
+  coalesced?: number;
+  error?: string;
+}
+
+/**
+ * What status shows for each schedule. `open` maps a schedule id to the open task it made. A due schedule that is held or whose task is open says so;
+ * one that is simply due (before its next tick) reads `due`. Titles and details are never shown: they are task text.
+ */
+export function scheduleViews(entries: readonly ScheduleEntry[], rows: readonly ScheduleRow[], now: number, open: ReadonlyMap<string, number>, held: boolean): ScheduleView[] {
+  const byId = new Map(rows.map(row => [row.id, row]));
+  return entries.map(entry => {
+    const row = byId.get(entry.id), anchor = row?.anchor ?? now, next = anchor + parseEvery(entry.every), openTask = open.get(entry.id);
+    const state: ScheduleState = row?.paused ? "paused" : now < next ? "scheduled" : held ? "held" : openTask !== undefined ? "waiting" : "due";
+    return {
+      id: entry.id, every: entry.every, class: entry.class, queue: entry.queue, next, state,
+      ...(row?.last_run != null ? { last: row.last_run } : {}), ...(openTask !== undefined ? { task: openTask } : row?.last_task != null ? { task: row.last_task } : {}),
+      ...(row?.coalesced ? { coalesced: row.coalesced } : {}), ...(row?.last_error ? { error: row.last_error } : {}),
+    };
+  });
+}
+
+/** The detail of a scheduled task: the marker line first, then the person's text and the sources it names, all fixed words around config text. */
+export function scheduledDetail(entry: ScheduleEntry): string {
+  return [`${SCHEDULE_MARKER}${entry.id}`, `Scheduled every ${entry.every} by the machine-local schedule "${entry.id}".`, ...(entry.detail ? ["", entry.detail] : []),
+    ...(entry.sources?.length ? ["", ...entry.sources.map(id => `Source: ${id}`)] : [])].join("\n");
+}
+
+export const scheduleKeyOf = (detail: string | undefined): string | undefined => detail?.startsWith(SCHEDULE_MARKER) ? detail.slice(SCHEDULE_MARKER.length).split("\n")[0] : undefined;

package/src/hub/sdlc-merge.ts

@@ -1,6 +1,8 @@
 import { findingsForHead, findingHead, findingTally } from "./review-findings.ts";
 import { readMergeQueue, type DeliveryTask, type MergeQueue } from "./sdlc-queue.ts";
-import { readSdlcPr, stageDefinition, type AutoMergeMode, type PrEvidence, type SdlcConfig, type SdlcGh, type MergeRecord } from "./sdlc.ts";
+import { evalGapBlockers, evalGateView, evalReportedGap, evalRequiredChecks, readEvalFor, type EvalResult } from "./eval-gate.ts";
+import { mergeCostFrom } from "./cost-governance.ts";
+import { readPrCostHistory, readSdlcPr, stageDefinition, type AutoMergeMode, type PrEvidence, type SdlcConfig, type SdlcGh, type MergeRecord } from "./sdlc.ts";
 
 /**
  * #786 T1/T2: the one guarded merge. Given a task and the head its reviewer approved, it re-reads the PR (`readSdlcPr`) and the merge queue
@@ -26,7 +28,7 @@ export interface MergeInput {
   run: SdlcGh;
   readableMetadata?: (path: string) => boolean;
   /** Final synchronous authority and queue-input fence, after fresh gates and immediately before the gh call. */
-  beforeMerge?: () => string | undefined;
+  beforeMerge?: (queue: MergeQueue | undefined) => string | undefined;
   /** Post-run host fence and durable progress record. False or a throw withholds cleanup. No remote text is supplied. */
   recordMerge?: (record: MergeRecord) => boolean;
   /**
@@ -55,7 +57,7 @@ const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
  * threads, draft). Its other blockers (identity, local gate, GitHub approval) are the lifecycle's, not this merge's, and are not repeated here.
  */
 const QUEUE_BLOCKERS = [/^touching PRs require a person order$/, /^dependency /, /^artifact dependency cycle/, /^open PR /, /^PR file coverage is incomplete/,
-  /^required check .*: not successful on current head$/, /^review requests pending or unknown$/, /^review threads unresolved or unknown$/, /^PR is draft or draft status unknown$/];
+  /^required check .*: not successful on current head$/, /^review requests pending or unknown$/, /^review threads unresolved or unknown$/, /^PR is draft or draft status is unknown$/];
 
 /** The mode that applies to one repository: its own table first, then the top-level key, default off. */
 export function mergeModeFor(config: SdlcConfig, repo: string | undefined): AutoMergeMode {
@@ -78,10 +80,10 @@ export function assertMergeArgv(argv: readonly string[], head: string): void {
   if (!shape) throw new Error("refusing a merge argv outside the guarded shape");
 }
 
-function checkGates(evidence: PrEvidence, required: readonly string[]): string[] {
+function checkGates(evidence: PrEvidence, required: readonly string[], extra: readonly string[] = []): string[] {
   if (!required.length) return ["required checks unknown: name them in sdlc.toml"];
   const gates: string[] = [];
-  for (const name of required) {
+  for (const name of [...new Set([...required, ...extra])]) {
     const matches = evidence.checks.filter(check => check.name === name);
     const state = !matches.length ? "missing" : matches.some(c => c.state === "failed") ? "failing" : matches.some(c => c.state === "pending") ? "pending" : matches.some(c => c.state !== "passed") ? "unknown" : undefined;
     if (state) gates.push(`required check ${name}: ${state}`);
@@ -112,18 +114,18 @@ function dropEchoes(gates: string[]): string[] {
     if (check) return !named(new RegExp(`^required check ${check[1]!.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}: `));
     if (gate === "queue: review requests pending or unknown") return !named(/review requests? (unknown|pending)|^\d+ review requests? pending$/);
     if (gate === "queue: review threads unresolved or unknown") return !named(/review threads unknown|unresolved review thread/);
-    if (gate === "queue: PR is draft or draft status unknown") return !named(/^draft /);
+    if (gate === "queue: PR is draft or draft status is unknown") return !named(/^draft /);
     return true;
   });
 }
 
 /** The gates one reading of the PR can fail. Run on every reading this decision takes, so a gate that changes between reads is never judged on the older one. */
-function evidenceGates(evidence: PrEvidence, approved: string | undefined, required: readonly string[]): string[] {
+function evidenceGates(evidence: PrEvidence, approved: string | undefined, required: readonly string[], extra: readonly string[] = []): string[] {
   const gates: string[] = [];
   if (approved && evidence.head !== approved) gates.push(`head changed: reviewed ${approved.slice(0, 8)}, PR is at ${evidence.head.slice(0, 8)}`);
   if (evidence.state !== "OPEN") gates.push(`PR is ${evidence.state.toLowerCase()}`);
   if (evidence.draft !== false) gates.push("draft (or draft status unknown)");
-  gates.push(...checkGates(evidence, required));
+  gates.push(...checkGates(evidence, required, extra));
   if (evidence.review === "changes_requested") gates.push("change request pending");
   if (evidence.pendingReviews === null) gates.push("review requests unknown");
   else if (evidence.pendingReviews > 0) gates.push(`${evidence.pendingReviews} review request${evidence.pendingReviews === 1 ? "" : "s"} pending`);
@@ -151,11 +153,22 @@ export function localGates(input: { subject: DeliveryTask; state: string; taskSt
   return gates;
 }
 
+/**
+ * #481 S5: in enforce, a configuration PR whose eval check passed but reported no pass rate or suite version, or whose file coverage is unknown, does not merge.
+ * Advise and off add nothing here. Synchronous on purpose: the result is read before the final PR read, so judging the last reading awaits nothing remote.
+ * A result read for another head is ignored by the view, and a passed check with no result read at all counts as unreported (the PR moved into scope after the read).
+ */
+function evalGaps(config: SdlcConfig, evidence: PrEvidence, result: EvalResult | undefined): string[] {
+  if (config.mode !== "enforce") return [];
+  const view = evalGateView(config, evidence, result);
+  return [...new Set([...evalGapBlockers(view), ...(view?.state === "passed" && !result && view.check ? [evalReportedGap(view.check)] : [])])];
+}
+
 /**
  * Every failing gate, never the first only: a person reading a refusal fixes them in one pass. Unknown evidence is a failing gate, never a pass.
  * `approvedHead` is the head the reviewer's verdict recorded (`receipt.reviewedHead`); a head that moved since is `head changed`.
  */
-export async function decideMerge(input: MergeInput): Promise<MergeDecision> {
+export async function decideMerge(input: MergeInput, seen?: { queue?: MergeQueue }): Promise<MergeDecision> {
   const { subject, config, run } = input, receipt = subject.receipt, repo = receipt?.repo, pr = receipt?.pr, approved = receipt?.reviewedHead;
   const gates: string[] = [];
   if (subject.private) return { refused: ["private task: a person merges"] };
@@ -164,16 +177,19 @@ export async function decideMerge(input: MergeInput): Promise<MergeDecision> {
   const evidence = await readSdlcPr(receipt, run);
   if (!evidence) return { refused: [...gates, "PR evidence unavailable"] };
   const required = requiredChecksFor(config, repo);
-  gates.push(...evidenceGates(evidence, approved, required));
+  // The eval metadata is read before the final PR read, never after it: nothing remote is awaited between the last reading and its judgment.
+  const evalResult = config.mode === "enforce" ? await readEvalFor(config, evidence, repo, run) : undefined;
+  gates.push(...evidenceGates(evidence, approved, required, evalRequiredChecks(config, evidence)), ...evalGaps(config, evidence, evalResult));
   gates.push(...localGates({ subject, state: input.state, taskState: input.taskState, config, head: evidence.head }));
   let queue: MergeQueue | undefined;
   try { queue = await readMergeQueue(repo, config, input.tasks, run, input.readableMetadata); } catch { queue = undefined; }
+  if (seen) seen.queue = queue;   // `guardedMerge` hands it to the final fence: that fence compares the board links this queue read and no others (#491)
   gates.push(...queueGates(queue, pr));
   // The queue read newer evidence than the first read. Read the PR once more, last, and judge every gate on it too: a check, review request, thread, draft or
   // head that moved between the reads refuses here. `--match-head-commit` pins the head only, never these gates.
   const last = await readSdlcPr(receipt, run);
   if (!last) gates.push("PR evidence unavailable on the final read");
-  else { gates.push(...evidenceGates(last, approved, required)); gates.push(...localGates({ subject, state: input.state, taskState: input.taskState, config, head: last.head })); }
+  else { gates.push(...evidenceGates(last, approved, required, evalRequiredChecks(config, last)), ...evalGaps(config, last, evalResult)); gates.push(...localGates({ subject, state: input.state, taskState: input.taskState, config, head: last.head })); }
   const row = queue?.rows.find(r => r.pr === pr);
   if (row?.head !== undefined && approved && row.head !== approved && !gates.some(g => g.startsWith("head changed"))) gates.push(`head changed: the queue read ${row.head.slice(0, 8)}`);
   if (gates.length) return { refused: dropEchoes([...new Set(gates)]) };
@@ -204,7 +220,8 @@ export function dispatchGates(input: Pick<MergeInput, "subject" | "taskState"> &
  */
 export async function guardedMerge(input: MergeInput & { mode: AutoMergeMode }): Promise<MergeOutcome> {
   if (input.mode === "off") return { mode: "off", decision: { refused: ["auto_merge is off for this repository"] }, ran: false };
-  const decision = await decideMerge(input);
+  const seen: { queue?: MergeQueue } = {};
+  const decision = await decideMerge(input, seen);
   if (!("action" in decision) || input.mode !== "on") return { mode: input.mode, decision, ran: false };
   // ---- synchronous dispatch segment: no await from here to the call to `run` ----
   assertMergeArgv(decision.argv, decision.head);
@@ -213,7 +230,7 @@ export async function guardedMerge(input: MergeInput & { mode: AutoMergeMode }):
     if (refused.length) return { mode: input.mode, decision: { refused }, ran: false };
   }
   let started: Promise<{ code: number; stdout: string }>;
-  const moved = input.beforeMerge?.();
+  const moved = input.beforeMerge?.(seen.queue);
   if (moved) return { mode: input.mode, decision: { refused: [moved] }, ran: false };
   try { started = Promise.resolve(input.run(decision.argv, 10_000)); } catch { started = Promise.resolve({ code: 1, stdout: "" }); }
   // ---- end of the synchronous segment ----
@@ -236,7 +253,14 @@ export async function guardedMerge(input: MergeInput & { mode: AutoMergeMode }):
   }
   const result: NonNullable<MergeOutcome["result"]> = after?.state === "MERGED" ? {exit,state:"merged",...(after.mergeCommit?{mergeCommit:after.mergeCommit}:{})} : after ? {exit,state:"not_merged"} : {exit,state:"unknown"};
   if (input.recordMerge) {
-    let record: MergeRecord={repo:decision.repo,pr:decision.pr,head:decision.head,at:Date.now(),...result,cleanup:"not_started",ownerNotice:"not_started"};
+    // #481 S7: the merged PR's review and CI figures, read once now that the merge is observed. After the merge there is nothing left to race, so this await is fine;
+    // its own bound keeps a slow GitHub from holding the record, and a failed read records no cost (unknown), never a zero.
+    const costDeadline = performance.now() + 8000;
+    const cost = result.state === "merged" ? await readPrCostHistory(decision.repo, decision.pr, (args, timeout, cwd, cap) => {
+      const left = costDeadline - performance.now();
+      return left > 0 ? input.run(args, Math.min(timeout ?? 10_000, left), cwd, cap) : Promise.resolve({ code: 1, stdout: "" });
+    }).then(mergeCostFrom, () => undefined) : undefined;
+    let record: MergeRecord={repo:decision.repo,pr:decision.pr,head:decision.head,at:Date.now(),...result,...(cost?{cost}:{}),cleanup:"not_started",ownerNotice:"not_started"};
     const save = () => {try {return input.recordMerge!({...record});}catch{return false;}};
     if (!save()) {record={...record,cleanup:"skipped",reason:"authority_changed"};save();}
     else if (result.state!=="merged" || !result.mergeCommit) {record={...record,cleanup:"skipped",reason:result.state==="merged"?"missing_commit":"not_merged"};save();}

package/src/hub/sdlc-metrics.ts

@@ -2,8 +2,11 @@
 // A metric that cannot be derived is `unknown` and counted as such, never 0.
 // `first_pass_check` reads the hub's own completion check (`check passed` / `check failed` at hub_task_done), not PR CI: it is unknown where completion checks are off.
 
-export const BAND_METRICS = ["acceptance_to_plan_ms", "acceptance_to_first_review_ms", "first_pass_approval", "rework_rounds", "first_pass_check", "stale_head_re_reviews"] as const;
+export const BAND_METRICS = ["acceptance_to_plan_ms", "acceptance_to_first_review_ms", "first_pass_approval", "rework_rounds", "first_pass_check", "stale_head_re_reviews", "hotfix_rate", "security_open_alerts"] as const;
 export type BandMetric = typeof BAND_METRICS[number];
+/** Metrics whose series is not made of tasks: one value per shipped release (`hotfix_rate`, 1 for a hotfix) or per recorded security scan (`security_open_alerts`). The caller supplies them; the point's `task` is then a release or scan id. */
+export const EXTERNAL_METRICS: readonly BandMetric[] = ["hotfix_rate", "security_open_alerts"];
+export type SeriesPoint = { value: number; task: number };
 export const BAND_TIERS = ["ok", "log", "diagnose", "propose"] as const;
 export type BandTier = typeof BAND_TIERS[number];
 
@@ -30,6 +33,10 @@ export interface TaskSample {
   first_pass_check: 0 | 1 | null;
   same_head_ci_reruns: number | null;
   stale_head_re_reviews: number | null;
+  /** #481 S7 merge-time readback: review handoffs (dones) up to the merge, CI runs of the merged PR and GitHub reviews on it. Null where the merge was not read. */
+  review_rounds_at_merge: number | null;
+  ci_runs_at_merge: number | null;
+  github_reviews_at_merge: number | null;
 }
 
 export interface Summary { n: number; unknown: number; mean: number | null; median: number | null; p90: number | null; max: number | null }
@@ -50,20 +57,23 @@ export interface BandResult {
   lastTask: number | null;
   /** The task whose value started the run of non-ok values this one belongs to, else null: one breach episode has one card. */
   episode: number | null;
+  /** What `lastTask` and `episode` number: a task unless the metric is an external series (a release or a security scan). */
+  subject?: "task" | "release" | "scan";
 }
+export const SUBJECT: Partial<Record<BandMetric, "release" | "scan">> = { hotfix_rate: "release", security_open_alerts: "scan" };
 
 /** Which way is worse. A rate that falls and a time that grows are both breaches. */
 export const BAD_DIRECTION: Record<BandMetric, "up" | "down"> = {
-  acceptance_to_plan_ms: "up", acceptance_to_first_review_ms: "up", first_pass_approval: "down", rework_rounds: "up", first_pass_check: "down", stale_head_re_reviews: "up",
+  acceptance_to_plan_ms: "up", acceptance_to_first_review_ms: "up", first_pass_approval: "down", rework_rounds: "up", first_pass_check: "down", stale_head_re_reviews: "up", hotfix_rate: "up", security_open_alerts: "up",
 };
 const HOUR = 3_600_000;
 /** Per-metric floor on the absolute deviation, so a flat baseline does not make every wobble a breach. */
 export const DEFAULT_MIN_DELTA: Record<BandMetric, number> = {
-  acceptance_to_plan_ms: HOUR, acceptance_to_first_review_ms: HOUR, first_pass_approval: 0.5, rework_rounds: 1, first_pass_check: 0.5, stale_head_re_reviews: 1,
+  acceptance_to_plan_ms: HOUR, acceptance_to_first_review_ms: HOUR, first_pass_approval: 0.5, rework_rounds: 1, first_pass_check: 0.5, stale_head_re_reviews: 1, hotfix_rate: 0.5, security_open_alerts: 1,
 };
 /** Per-metric floor on the baseline deviation: a flat baseline (every value the same) must not turn one step into thousands of deviations. */
 export const SD_FLOOR: Record<BandMetric, number> = {
-  acceptance_to_plan_ms: HOUR / 2, acceptance_to_first_review_ms: HOUR / 2, first_pass_approval: 0.5, rework_rounds: 0.5, first_pass_check: 0.5, stale_head_re_reviews: 0.5,
+  acceptance_to_plan_ms: HOUR / 2, acceptance_to_first_review_ms: HOUR / 2, first_pass_approval: 0.5, rework_rounds: 0.5, first_pass_check: 0.5, stale_head_re_reviews: 0.5, hotfix_rate: 0.5, security_open_alerts: 0.5,
 };
 export const DEFAULT_BAND: Omit<BandConfig, "minDelta"> = { window: 20, minSamples: 8, logSigma: 2, diagnoseSigma: 3, proposeSigma: 4, driftRun: 6 };
 
@@ -91,7 +101,7 @@ function staleHeadRounds(history: MetricTask["history"]): number | null {
 }
 
 /** One task's values from its own history. A private task never reaches here. */
-export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciReruns?: number | null } = {}): TaskSample {
+export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciReruns?: number | null; ciRuns?: number | null; reviews?: number | null } = {}): TaskSample {
   const history = [...task.history].filter(entry => Number.isFinite(entry.at) && entry.at >= 0).sort((a, b) => a.at - b.at);
   const view: MetricTask = { id: task.id, history };
   const accepted = first(view, ["accepted"]);
@@ -116,6 +126,10 @@ export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciRerun
     rework_rounds: dones.length && approvedAt !== null ? history.filter(entry => entry.event === "changes_requested" && entry.evidenceOnly !== true).length : null,
     first_pass_check: ci ? (ci.event === "check passed" ? 1 : 0) : null,
     same_head_ci_reruns: extra.ciReruns === undefined ? null : extra.ciReruns,
+    // Counted only for a merged PR whose figures were read: a done before the merge is one review round.
+    review_rounds_at_merge: extra.mergedAt !== undefined && Number.isFinite(extra.mergedAt) ? dones.filter(entry => entry.at <= extra.mergedAt!).length : null,
+    ci_runs_at_merge: extra.ciRuns === undefined ? null : extra.ciRuns,
+    github_reviews_at_merge: extra.reviews === undefined ? null : extra.reviews,
     stale_head_re_reviews: approvedAt !== null ? staleHeadRounds(history) : null,
   };
 }
@@ -131,7 +145,8 @@ export function summarize(values: readonly (number | null)[]): Summary {
 const round = (value: number) => Math.round(value * 1000) / 1000;
 
 /** The values of one metric in the order they happened, unknown ones left out. */
-export function series(samples: readonly TaskSample[], metric: BandMetric): { value: number; task: number }[] {
+export type TaskMetric = Exclude<BandMetric, "hotfix_rate" | "security_open_alerts">;
+export function series(samples: readonly TaskSample[], metric: TaskMetric): SeriesPoint[] {
   const final = metric === "rework_rounds" || metric === "stale_head_re_reviews";
   const when = (sample: TaskSample) => final ? sample.approved_at ?? sample.at : sample.at;
   return [...samples].sort((a, b) => when(a) - when(b) || a.id - b.id).flatMap(sample => sample[metric] === null ? [] : [{ value: sample[metric] as number, task: sample.id }]);
@@ -172,7 +187,8 @@ export const EPISODE_LOOKBACK = 200;
  * key for as long as it lasts, and it is derived from history alone, so it survives a restart.
  */
 export function controlEpisode(points: readonly { value: number; task: number }[], metric: BandMetric, config: BandConfig): BandResult {
-  const now = controlBands(points, metric, config);
+  const subject = SUBJECT[metric];
+  const now = { ...controlBands(points, metric, config), ...(subject ? { subject } : {}) };
   if (now.tier === "ok") return now;
   let start = points.length - 1;
   for (let end = points.length - 2; end >= 0 && points.length - 1 - end <= EPISODE_LOOKBACK; end--) {
@@ -193,7 +209,10 @@ export interface MetricsReport {
     first_pass_check: { n: number; unknown: number; rate: number | null };
     same_head_ci_reruns: Summary;
     stale_head_re_reviews: Summary;
+    review_rounds_at_merge: Summary; ci_runs_at_merge: Summary; github_reviews_at_merge: Summary;
   };
+  /** Merged PRs whose review and CI figures were read at merge, and how many of the counted tasks have none (unknown, never 0). */
+  merged: { read: number; unknown: number };
   stalls: StallCounts;
   bands: BandResult[] | "off";
 }
@@ -207,12 +226,12 @@ const rate = (values: readonly (number | null)[]) => {
  * The whole report from board tasks. `since` keeps samples that count at or after it; `mergedAt` and `ciReruns` come from bounded
  * PR readbacks keyed by task id and are optional. Private tasks are counted as withheld and read for nothing else.
  */
-export function sdlcMetrics(tasks: readonly MetricTask[], opts: { since?: number; bands?: BandsConfig; stalls?: StallCounts; mergedAt?: Readonly<Record<number, number>>; ciReruns?: Readonly<Record<number, number | null>> } = {}): MetricsReport {
+export function sdlcMetrics(tasks: readonly MetricTask[], opts: { since?: number; bands?: BandsConfig; stalls?: StallCounts; mergedAt?: Readonly<Record<number, number>>; ciReruns?: Readonly<Record<number, number | null>>; ciRuns?: Readonly<Record<number, number | null>>; reviews?: Readonly<Record<number, number | null>>; external?: Partial<Record<BandMetric, readonly SeriesPoint[]>> } = {}): MetricsReport {
   const visible = tasks.filter(task => !task.private);
-  const all = visible.map(task => taskSample(task, { mergedAt: opts.mergedAt?.[task.id], ciReruns: opts.ciReruns?.[task.id] }));
+  const all = visible.map(task => taskSample(task, { mergedAt: opts.mergedAt?.[task.id], ciReruns: opts.ciReruns?.[task.id], ciRuns: opts.ciRuns?.[task.id], reviews: opts.reviews?.[task.id] }));
   const samples = opts.since === undefined ? all : all.filter(sample => sample.at >= opts.since!);
   const bands: BandResult[] | "off" = opts.bands && Object.keys(opts.bands).length
-    ? BAND_METRICS.flatMap(metric => opts.bands![metric] ? [controlEpisode(series(samples, metric), metric, opts.bands![metric]!)] : [])
+    ? BAND_METRICS.flatMap(metric => opts.bands![metric] ? [controlEpisode(EXTERNAL_METRICS.includes(metric) ? [...(opts.external?.[metric] ?? [])] : series(samples, metric as TaskMetric), metric, opts.bands![metric]!)] : [])
     : "off";
   return {
     since: opts.since ?? null, tasks: samples.length, withheldPrivate: tasks.length - visible.length,
@@ -222,7 +241,10 @@ export function sdlcMetrics(tasks: readonly MetricTask[], opts: { since?: number
       first_pass_approval: rate(samples.map(s => s.first_pass_approval)), rework_rounds: summarize(samples.map(s => s.rework_rounds)),
       first_pass_check: rate(samples.map(s => s.first_pass_check)), same_head_ci_reruns: summarize(samples.map(s => s.same_head_ci_reruns)),
       stale_head_re_reviews: summarize(samples.map(s => s.stale_head_re_reviews)),
+      review_rounds_at_merge: summarize(samples.map(s => s.review_rounds_at_merge)), ci_runs_at_merge: summarize(samples.map(s => s.ci_runs_at_merge)),
+      github_reviews_at_merge: summarize(samples.map(s => s.github_reviews_at_merge)),
     },
+    merged: { read: samples.filter(s => s.ci_runs_at_merge !== null || s.github_reviews_at_merge !== null).length, unknown: samples.filter(s => s.ci_runs_at_merge === null && s.github_reviews_at_merge === null).length },
     stalls: opts.stalls ?? { open: 0, byKind: {}, doneWithoutWrites: 0 }, bands,
   };
 }

package/src/hub/sdlc-queue.ts

@@ -1,10 +1,11 @@
 import { publicTestIntegrity, parseIssueLabels, readTestIntegrity, testIntegrityBlockers, type TestIntegrity } from "./test-integrity.ts";
 import { planConformance, planConformanceBlockers } from "./plan-conformance.ts";
+import { evalGapBlockers, evalGateView, readEvalFor, type EvalGate } from "./eval-gate.ts";
 import { findingsForHead, findingHead, findingTally, type ReviewFindingSet, type ReviewFindingTally } from "./review-findings.ts";
 import type { CriteriaView } from "./workflow.ts";
 import { parsePrEvidence, readSdlcPr, sdlcGh, sdlcStatus, type PrEvidence, type SdlcConfig, type SdlcGh, type SdlcReceipt } from "./sdlc.ts";
 export interface DeliveryTask { plan?: { paths?: string[]; revision: number; fingerprint: string; accepted: { repo: string; pr: number; head: string; revision: number; fingerprint: string; paths: string[] }[] }; findings?: readonly ReviewFindingSet[]; id: number; after: number[]; private: boolean; receipt?: SdlcReceipt; phase?: CriteriaView; }
-export interface MergeQueueRow { testIntegrity?: (TestIntegrity & { task?: number })[]; planConformance?: { task?: number; state: string; outside: number; untouched: number; accepted: boolean }[]; findings?: ReviewFindingTally; pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
+export interface MergeQueueRow { evalGate?: EvalGate; testIntegrity?: (TestIntegrity & { task?: number })[]; planConformance?: { task?: number; state: string; outside: number; untouched: number; accepted: boolean }[]; findings?: ReviewFindingTally; pr: number; tasks: number[]; head?: string; private?: true; ready: boolean; blockers: string[]; after: number[]; }
 export interface MergeConflict { left: number; right: number; files: number; order: "dependency" | "person_required"; }
 export interface MergeQueue { repo: string; rows: MergeQueueRow[]; order: number[]; unordered?: number[]; conflicts: MergeConflict[]; complete: boolean; truncated: boolean; }
 const validRepo = (value: string) => /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value) && !value.startsWith("-");
@@ -93,6 +94,11 @@ export async function readMergeQueue(repo: string, config: SdlcConfig, tasks: De
       const integrity = rawIntegrity ? publicTestIntegrity(rawIntegrity, readableMetadata) : undefined;
       if (integrity) (row.testIntegrity ??= []).push({ task: holder!.id, ...integrity });
       row.blockers.push(...sdlcStatus(config, holder?.receipt, read, holder?.phase).blockers);
+      // #481 S5: the eval check itself is a required check inside sdlcStatus; its recorded pass rate and suite are read once per PR here.
+      if (!row.evalGate) {
+        const gate = evalGateView(config, read, await readEvalFor(config, read, repo, bounded));
+        if (gate) { row.evalGate = gate; if (config.mode === "enforce") row.blockers.push(...evalGapBlockers(gate)); }
+      }
       if (config.mode === "enforce") row.blockers.push(...planConformanceBlockers(conformance), ...testIntegrityBlockers(integrity));
     }
   }

package/src/hub/sdlc-release.ts

@@ -21,7 +21,7 @@ const sdlcGh: SdlcGh = async (...args) => {
   catch { return { code: 1, stdout: "" }; }
 };
 export interface DocEvidence { schemaVersion: 1; head?: string; version?: string; documents: { path?: string; state: "fresh" | "stale" | "nonancestor" | "unknown"; verifiedAgainst?: string; commits?: number; dirty?: boolean }[]; errors: number; fresh: boolean; }
-export interface ReleaseReadiness { repo: string; head?: string; version?: string; tag?: string; tagCommit?: string; commits: string[]; mergedPrs: { pr: number; commit: string }[]; documents?: DocEvidence; liveIssues: { id: number; state: "open" | "closed" | "unknown" }[]; blockers: string[]; sourceReady: boolean; native: "unverified"; ready: false; }
+export interface ReleaseReadiness { /** #481 AC12: interval, approval-to-release lead time and hotfix rate over shipped releases, filled by Tasks.releaseReadiness. */ releaseMetrics?: ReturnType<typeof releaseMetrics>; repo: string; head?: string; version?: string; tag?: string; tagCommit?: string; commits: string[]; mergedPrs: { pr: number; commit: string }[]; documents?: DocEvidence; liveIssues: { id: number; state: "open" | "closed" | "unknown" }[]; blockers: string[]; sourceReady: boolean; native: "unverified"; ready: false; }
 export type ReleaseGit = (args: string[]) => { code: number; stdout: string };
 export interface ReleaseReaders { gh?: SdlcGh; git?: ReleaseGit; docs?: (root: string, timeoutMs: number) => Promise<DocEvidence | undefined>; }
 const SHA = /^[0-9a-f]{40}$/;