@staix/agent-hub 0.17.0 → 0.19.0

package/src/hub/routing.ts

@@ -419,7 +419,7 @@ export function assign(
     namedPlanner?: PeerId;
     /** The planner already recorded on the task (525-2): kept while it is still a holder. */
     keptPlanner?: PeerId;
-    reviewPool?: { pool: readonly string[]; rerotate?: boolean; failed?: readonly string[]; required?: boolean };
+    reviewPool?: { pool: readonly string[]; rerotate?: boolean; failed?: readonly string[]; required?: boolean; sameFamily?: "fallback" | "never" };
     candidates?: PeerId[];
     notReviewer?: PeerId;
     waitsFor?: number[];
@@ -602,8 +602,13 @@ export function assign(
       trace.push(opts.namedReviewer === undefined ? `  reviewer candidates: [classes.review] peers ${classPeers.join(", ") || "none"}${rolePeers.length ? `; reviewer role ${rolePeers.join(", ")}` : ""}` : `  reviewer candidate explicitly named: ${opts.namedReviewer}`);
       const reviewOwner = owner ?? opts.notReviewer;
       const automatic = [...new Set([...expandClassPeers(classPeers, states, opts), ...rolePeers])];
-      const ownerFamily = instanceMode && reviewOwner ? (opts.adapterCatalog?.familyOf ?? familyOf)(reviewOwner, opts.instances) : undefined;
+      // #820: the rule needs the owner's family even when no instance is declared (builtin peers have families too).
+      const never = opts.reviewPool?.sameFamily === "never" && reviewOwner !== undefined;
+      const ownerFamily = (instanceMode || never) && reviewOwner ? (opts.adapterCatalog?.familyOf ?? familyOf)(reviewOwner, opts.instances) : undefined;
       const sameFamily = (peer: PeerId) => ownerFamily !== undefined && (opts.adapterCatalog?.familyOf ?? familyOf)(peer, opts.instances) === ownerFamily;
+      // #820: with review.same_family = never, a reviewer of the owner's family is never chosen; the planner or the person reviews instead.
+      const neverSame = never;
+      if (neverSame) trace.push(`  review.same_family = never: no reviewer of the owner's family (${ownerFamily ?? "unknown"}) is chosen; another family, the planner or the person reviews`);
       const independent = ownerFamily === undefined ? [] : automatic.filter(peer => peer !== reviewOwner && !blocked(peer, "reviewer") && !sameFamily(peer));
       const named = opts.namedReviewer;
       const declaredPool = opts.reviewPool && named === undefined ? Object.keys(opts.instances ?? {}).flatMap(id => {
@@ -622,21 +627,25 @@ export function assign(
         const continuityFamily = last && "reviewerFamily" in last && typeof last.reviewerFamily === "string" ? last.reviewerFamily : last ? (opts.adapterCatalog?.familyOf ?? familyOf)(last.by, opts.instances) : undefined;
         const pr = task.sdlc?.pr;
         const seed = typeof pr === "number" && Number.isSafeInteger(pr) && pr > 0 ? pr : task.id ?? 0;
-        reviewSelection = selectReviewerPool({ pool: opts.reviewPool!.pool, candidates: declaredPool, seed, implementerFamily: ownerFamily, continuityFamily, rerotate: opts.reviewPool!.rerotate, failed: opts.reviewPool!.failed });
+        reviewSelection = selectReviewerPool({ pool: opts.reviewPool!.pool, candidates: declaredPool, seed, implementerFamily: ownerFamily, continuityFamily, rerotate: opts.reviewPool!.rerotate, failed: opts.reviewPool!.failed, ...(neverSame ? { sameFamily: "never" as const } : {}) });
         for (const row of reviewSelection.walk) trace.push(row.id ? `  reviewer pool candidate ${row.id} (${row.family}): ${row.reason}` : `  reviewer pool kind ${row.kind}: ${row.reason}`);
         reviewer = reviewSelection.reviewer ?? "user";
         if (reviewSelection.blocked) {
           trace.push("blocked: no reviewer can run");
           // Optional defaults retain the legacy planner escape when no fresh reviewer can run.
-          const planners = opts.reviewPool?.required ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && !(opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
+          const planners = opts.reviewPool?.required && !neverSame ? [] : automatic.filter(peer => peer !== reviewOwner && peerEntry(opts.roles, peer)?.includes("planner") && (!neverSame || peerEntry(opts.roles, peer)?.includes("reviewer") === true) && !(opts.adapterCatalog?.definitionOf ?? definitionOf)(peer, opts.instances)?.routing?.reviewOnly && !blocked(peer, "reviewer"));
           const otherFamily = planners.filter(peer => !sameFamily(peer));
-          const planner = pick(otherFamily.length ? otherFamily : planners, "reviewer", reviewOwner);
+          const planner = pick(neverSame || otherFamily.length ? otherFamily : planners, "reviewer", reviewOwner);
           if (planner) {
             reviewer = planner;
             plannerFallback = true;
             trace.push(`  planner fallback: no declared reviewer-only instance is eligible; ${planner} reviews`);
           } else reviewBlocked = true;
         }
+      } else if (neverSame && named !== undefined && named !== reviewOwner && !blocked(named, "reviewer") && sameFamily(named)) {
+        const reason = `same family as ${reviewOwner}; review.same_family is never`;
+        refusals.set(`reviewer:${named}`, { peer: named, role: "reviewer", code: "family", reason });
+        trace.push(`  reviewer candidate ${named}: skipped, ${reason}`);
       } else if (named !== undefined && named !== reviewOwner && !blocked(named, "reviewer") && sameFamily(named) && independent.length) {
         const reason = `same family as ${reviewOwner}; eligible other-family reviewer available`;
         refusals.set(`reviewer:${named}`, { peer: named, role: "reviewer", code: "family", reason });
@@ -645,7 +654,9 @@ export function assign(
         // #223 R1: a declared instance that reviews and does not plan goes first, busy or not.
         const holds = (peer: PeerId, role: string) => opts.roles?.[peer]?.includes(role) === true;
         const dedicated = (peer: PeerId) => !!opts.instances && Object.hasOwn(opts.instances, peer) && holds(peer, "reviewer") && !holds(peer, "planner");
-        const pool = independent.length ? independent : automatic;
+        // Under never the planner escape needs the reviewer role: a peer that plans and does not review is not a reviewer here, class listing or not.
+        const planOnly = (peer: PeerId) => neverSame && holds(peer, "planner") && !holds(peer, "reviewer");
+        const pool = independent.length || neverSame ? independent.filter(peer => !planOnly(peer)) : automatic;
         const ready = named === undefined ? pool.filter(peer => dedicated(peer) && peer !== reviewOwner && !blocked(peer, "reviewer")) : [];
         reviewer = pick(named === undefined ? ready.length ? ready : pool : [named], "reviewer", reviewOwner, named === undefined);
         if (named === undefined && !ready.length && reviewer && holds(reviewer, "planner") && Object.keys(opts.roles ?? {}).some(dedicated)) {
@@ -657,6 +668,12 @@ export function assign(
         sameFamilyFallback = true;
         trace.push(`  same-family fallback: ${reviewer} and ${reviewOwner} share ${ownerFamily}; no eligible other family`);
       }
+      // Under never an exhausted automatic choice (nobody eligible, all offline, no candidate at all) is the person's, never an approval without review.
+      if (neverSame && !reviewer && named === undefined && !reviewSelection) {
+        reviewer = "user";
+        reviewBlocked = true;
+        trace.push("  review.same_family = never: no reviewer of another family and no eligible planner; the person reviews");
+      }
       // I-2 (#525-3): when the peers that implemented this task were the only candidates left, the person reviews. Never a fallback to an implementer.
       if (!reviewer && [...refusals.values()].some(row => row.role === "reviewer" && row.code === "policy" && row.reason === "implemented this task")) {
         reviewer = "user";

package/src/hub/sdlc-merge.ts

@@ -0,0 +1,299 @@
+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";
+
+/**
+ * #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
+ * (`readMergeQueue`) and answers either `{ action: "merge", argv }` or `{ refused: [gate, ...] }` naming every gate that fails. In `on` mode
+ * it runs exactly that argv; in `dry-run` it runs nothing. Nothing here writes the board: `Tasks.guardedMerge` owns authority, privacy and notices.
+ *
+ * The only merge method is `gh pr merge <pr> --repo <repo> --squash --match-head-commit <head>`. Never `--admin` (it bypasses branch protection),
+ * and no `--auto` while the repository does not allow auto-merge. The sole ref write is a post-MERGED CAS deletion of that PR's eligible remote head;
+ * a ref-update API never performs the merge. Off/dry-run write neither GitHub nor the board; Tasks owns on-mode host result records.
+ * `assertMergeArgv` pins that shape right before the call, so a later edit cannot widen it without failing a test.
+ */
+
+export interface MergeInput {
+  /** The task as the queue sees it: its receipt (repo, PR, reviewed head), findings and dependencies. */
+  subject: DeliveryTask;
+  /** The board state now. Only `approved` work merges. */
+  state: string;
+  /** Board state of a dependency task, for "its task dependencies are approved". */
+  taskState: (id: number) => string | undefined;
+  config: SdlcConfig;
+  /** Every board task, as `Tasks.deliveryQueue` builds them: the queue links PRs to tasks through these. */
+  tasks: DeliveryTask[];
+  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;
+  /** Post-run host fence and durable progress record. False or a throw withholds cleanup. No remote text is supplied. */
+  recordMerge?: (record: MergeRecord) => boolean;
+  /**
+   * The board and the authority to act, read NOW and synchronously: `guardedMerge` calls it once, after the last PR read and in the same synchronous segment as the
+   * `gh pr merge` call (nothing is awaited between them), and refuses unless every input still equals what the decision judged. Absent (a library caller): the
+   * decision's own snapshot is all there is. `undefined` means the task is gone.
+   */
+  fresh?: () => FreshBoard | undefined;
+}
+/** What the board says at the moment of dispatch. `allowed` is the asker's authority and the hub being free to write (no recovery hold). */
+export interface FreshBoard { subject: DeliveryTask; state: string; config: SdlcConfig; mode: AutoMergeMode; allowed: boolean }
+export type MergeDecision = { action: "merge"; argv: string[]; repo: string; pr: number; head: string } | { refused: string[] };
+export interface MergeOutcome {
+  mode: AutoMergeMode;
+  decision: MergeDecision;
+  /** True only when `gh pr merge` was started. A dry-run and every refusal leave it false. */
+  ran: boolean;
+  /** After a run: what GitHub reports when read back. `merged` is the only success; a nonzero exit can still end merged, so the PR is read again. */
+  result?: { exit: number; state: "merged" | "not_merged" | "unknown"; mergeCommit?: string; cleanup?: MergeRecord["cleanup"]; reason?: MergeRecord["reason"] };
+}
+
+const SHA = /^[0-9a-f]{40}$/;
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/**
+ * Queue blockers this decision keeps: order and open-set facts, and the queue's own reading of the gates that can change between reads (checks, review requests,
+ * 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$/];
+
+/** 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 {
+  return (repo ? config.repos?.[repo.toLowerCase()]?.autoMerge : undefined) ?? config.autoMerge ?? "off";
+}
+/** Required checks of one repository: its table first, then the top-level `required_checks`, each name once. */
+export function requiredChecksFor(config: SdlcConfig, repo: string | undefined): string[] {
+  return [...new Set([...(repo ? config.repos?.[repo.toLowerCase()]?.requiredChecks ?? [] : []), ...config.requiredChecks])];
+}
+
+/** The exact argv `on` mode runs, or an error. A closed shape: anything else is refused before it reaches gh. */
+export function mergeArgv(repo: string, pr: number, head: string): string[] {
+  if (!REPO.test(repo) || repo.startsWith("-") || !Number.isSafeInteger(pr) || pr <= 0 || !SHA.test(head)) throw new Error("merge argv needs owner/repository, a PR number and a full head");
+  return ["pr", "merge", String(pr), "--repo", repo, "--squash", "--match-head-commit", head];
+}
+export function assertMergeArgv(argv: readonly string[], head: string): void {
+  const [verb, sub, pr, flag, repo, ...rest] = argv;
+  const shape = verb === "pr" && sub === "merge" && /^[1-9][0-9]*$/.test(pr ?? "") && flag === "--repo" && REPO.test(repo ?? "") && !repo!.startsWith("-")
+    && rest.length === 3 && rest[0] === "--squash" && rest[1] === "--match-head-commit" && rest[2] === head && SHA.test(head);
+  if (!shape) throw new Error("refusing a merge argv outside the guarded shape");
+}
+
+function checkGates(evidence: PrEvidence, required: readonly string[]): string[] {
+  if (!required.length) return ["required checks unknown: name them in sdlc.toml"];
+  const gates: string[] = [];
+  for (const name of required) {
+    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}`);
+  }
+  return gates;
+}
+
+function queueGates(queue: MergeQueue | undefined, pr: number): string[] {
+  const row = queue?.rows.find(r => r.pr === pr);
+  if (!queue || !row) return ["merge queue unavailable: this PR is not in the open snapshot"];
+  const gates: string[] = row.blockers.filter(text => QUEUE_BLOCKERS.some(re => re.test(text))).map(text => `queue: ${text}`);
+  const place = queue.order.indexOf(pr);
+  for (const conflict of queue.conflicts) {
+    if (conflict.left !== pr && conflict.right !== pr) continue;
+    const other = conflict.left === pr ? conflict.right : conflict.left, before = queue.order.indexOf(other);
+    if (before !== -1 && place !== -1 && before < place) gates.push(`not first among touching PRs: #${other} merges first`);
+  }
+  if (queue.unordered?.includes(pr) && !gates.length) gates.push("queue: touching PR order is unresolved");
+  return [...new Set(gates)];
+}
+
+/** A queue blocker that only repeats a gate the evidence already named adds nothing: drop it, and keep the ones that say something new (a disagreement between reads). */
+function dropEchoes(gates: string[]): string[] {
+  const named = (re: RegExp) => gates.some(g => !g.startsWith("queue: ") && re.test(g));
+  return gates.filter(gate => {
+    if (!gate.startsWith("queue: ")) return true;
+    const check = /^queue: required check (.*): not successful on current head$/.exec(gate);
+    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 /);
+    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[] {
+  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));
+  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`);
+  if (evidence.unresolved === null) gates.push("review threads unknown");
+  else if (evidence.unresolved > 0) gates.push(`${evidence.unresolved} unresolved review thread${evidence.unresolved === 1 ? "" : "s"}`);
+  // A release goes out with the person's consent, whatever the other gates say (#784 release consent).
+  if (/^release[/-]/i.test(evidence.headBranch ?? "")) gates.push("release PR: person consent required");
+  return gates;
+}
+
+/**
+ * The gates that come from the board, not from GitHub: privacy, approval, task dependencies, open Important findings on this head and a release stage. Pure and
+ * synchronous on purpose: `decideMerge` runs it on its starting snapshot and `guardedMerge` runs it again on a fresh board read right before `gh pr merge`.
+ */
+export function localGates(input: { subject: DeliveryTask; state: string; taskState: (id: number) => string | undefined; config: SdlcConfig; head: string | undefined }): string[] {
+  const { subject, config } = input, gates: string[] = [];
+  if (subject.private) return ["private task: a person merges"];
+  if (input.state !== "approved") gates.push(`task not approved (state ${input.state})`);
+  for (const id of subject.after) {
+    const state = input.taskState(id);
+    if (state !== "approved") gates.push(`dependency task #${id} is not approved (${state ?? "unknown"})`);
+  }
+  if (findingTally(findingsForHead(subject.findings ?? [], findingHead(subject.receipt, input.head ? { head: input.head } : undefined))).openImportant > 0) gates.push("open Important finding");
+  if (subject.receipt && stageDefinition(config, subject.receipt.stage)?.base === "release") gates.push("release PR: person consent required");
+  return gates;
+}
+
+/**
+ * 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> {
+  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"] };
+  if (!repo || !pr) return { refused: [...gates, "PR identity missing"] };
+  if (!approved || !SHA.test(approved)) gates.push("reviewed head not recorded: the approving verdict must name the head");
+  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));
+  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; }
+  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 })); }
+  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)]) };
+  return { action: "merge", argv: mergeArgv(repo, pr, approved!), repo, pr, head: approved! };
+}
+
+/**
+ * Every board-side input the decision rested on, compared with the board as it is at dispatch. Pure and synchronous. The decision's inputs are: the task's state, repo,
+ * PR and reviewed head, its privacy, its dependencies (the edges and each one's state), its open Important findings for the head, the merge mode and required checks in
+ * force, and the asker's authority. Any difference refuses: a gate checked before an await is never trusted after it.
+ */
+export function dispatchGates(input: Pick<MergeInput, "subject" | "taskState"> & { config: SdlcConfig; mode: AutoMergeMode }, decision: { repo: string; pr: number; head: string }, now: FreshBoard | undefined): string[] {
+  const moved = ["task changed during the merge check: nothing was run"];
+  if (!now) return moved;
+  const receipt = now.subject.receipt;
+  if (receipt?.repo !== decision.repo || receipt?.pr !== decision.pr || receipt?.reviewedHead !== decision.head) return moved;
+  if (now.mode !== input.mode) return ["merge mode changed during the merge check: nothing was run"];
+  if (JSON.stringify(requiredChecksFor(now.config, decision.repo)) !== JSON.stringify(requiredChecksFor(input.config, decision.repo))) return ["required checks changed during the merge check: nothing was run"];
+  if (!now.allowed) return ["authority or hub availability changed during the merge check: nothing was run"];
+  if (JSON.stringify([...now.subject.after].sort((x, y) => x - y)) !== JSON.stringify([...input.subject.after].sort((x, y) => x - y))) return ["task dependencies changed during the merge check: nothing was run"];
+  return localGates({ subject: now.subject, state: now.state, taskState: input.taskState, config: now.config, head: decision.head });
+}
+
+/**
+ * Decide, then act by mode: `on` runs the one argv and reads the PR back, `dry-run` reports the same decision and runs nothing, `off` reads nothing.
+ * The dispatch segment below has no await: the board is read (`fresh`), every input is compared with the decision, and `run` is called, all in one synchronous
+ * stretch that starts after the last PR read.
+ */
+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);
+  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);
+  if (input.fresh) {
+    const refused = dispatchGates(input, decision, input.fresh());
+    if (refused.length) return { mode: input.mode, decision: { refused }, ran: false };
+  }
+  let started: Promise<{ code: number; stdout: string }>;
+  const moved = input.beforeMerge?.();
+  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 ----
+  let exit = 1;
+  try { exit = (await started).code; } catch { exit = 1; }
+  // A transport failure can still have merged. Bound lag readback within this one invocation; never repeat the merge.
+  const deadline = performance.now() + 6000;
+  const bounded: SdlcGh = (args, timeout, cwd, cap) => {
+    const left = deadline - performance.now();
+    return left > 0 ? input.run(args, Math.min(timeout ?? 2000, left), cwd, Math.min(cap ?? 65536, 65536)) : Promise.resolve({ code: 1, stdout: "" });
+  };
+  let after: PrEvidence | undefined;
+  for (let attempt = 0; attempt < 3 && performance.now() < deadline; attempt++) {
+    const observed = await readSdlcPr({ stage: input.subject.receipt!.stage, repo: decision.repo, pr: decision.pr }, bounded).catch(() => undefined);
+    // MERGED is terminal evidence. Retry for its commit without losing that fact to a stale or failed read.
+    if (observed && (after?.state !== "MERGED" || observed.state === "MERGED" && observed.mergeCommit)) after = observed;
+    if (after?.state === "MERGED" && after.mergeCommit || after?.state === "CLOSED") break;
+    const left = deadline - performance.now();
+    if (attempt < 2 && left > 0) await Bun.sleep(Math.min(100, left));
+  }
+  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"};
+    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();}
+    else {
+      const cleanup=await cleanupMergedBranch(decision,result.mergeCommit,bounded,progress=>{record={...record,...progress};return save();});
+      record={...record,...cleanup};save();
+    }
+    result.cleanup=record.cleanup;
+    if(record.reason)result.reason=record.reason;
+  }
+  return { mode: "on", decision, ran: true, result };
+}
+
+/** Only the merged PR's exact same-repository, unprotected nondefault head can be deleted. No local git command is used. */
+async function cleanupMergedBranch(decision:{repo:string;pr:number;head:string},mergeCommit:string,run:SdlcGh,claim:(progress:Pick<MergeRecord,"cleanup"> & Partial<Pick<MergeRecord,"reason">>)=>boolean):Promise<Pick<MergeRecord,"cleanup"> & Partial<Pick<MergeRecord,"reason">>> {
+  const skip=(reason:NonNullable<MergeRecord["reason"]>)=>({cleanup:"skipped" as const,reason});
+  const read=async(args:string[])=>{try{const r=await run(args);if(r.code!==0)return;const data=JSON.parse(r.stdout);return data?.errors?undefined:data;}catch{return;}};
+  const [owner,name]=decision.repo.split("/");
+  const query="query($owner:String!,$name:String!,$pr:Int!){repository(owner:$owner,name:$name){id nameWithOwner defaultBranchRef{name} pullRequest(number:$pr){state headRefName headRefOid headRepository{nameWithOwner} mergeCommit{oid}}}}";
+  const args=["api","graphql","-f",`query=${query}`,"-f",`owner=${owner}`,"-f",`name=${name}`,"-F",`pr=${decision.pr}`];
+  const initial=(await read(args))?.data?.repository,p=initial?.pullRequest;
+  if (!initial) return skip("metadata_unknown");
+  if (!initial || p?.state!=="MERGED" || p.mergeCommit?.oid!==mergeCommit || p.headRefOid!==decision.head || p.headRepository?.nameWithOwner?.toLowerCase()!==decision.repo.toLowerCase()) return skip("identity_changed");
+  const branch=p.headRefName;
+  // ponytail: cleanup accepts only this ASCII 200-character ref subset; use a shared validated Git ref-name parser before widening it. Unknown spelling never reaches a mutation.
+  if(typeof branch!=="string" || !/^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/.test(branch) || branch.includes("..") || branch.includes("//") || branch.endsWith("/") || branch.endsWith(".") || branch.endsWith(".lock"))return skip("metadata_unknown");
+  if(typeof initial.defaultBranchRef?.name!=="string")return skip("metadata_unknown");
+  if(branch===initial.defaultBranchRef.name)return skip("default_branch");
+  const lastQuery=query.replace("mergeCommit{oid}}}}","mergeCommit{oid}} ref(qualifiedName:$ref){name prefix target{oid} branchProtectionRule{id}}}}").replace("$pr:Int!","$pr:Int!,$ref:String!");
+  const current=(await read(["api","graphql","-f",`query=${lastQuery}`,"-f",`owner=${owner}`,"-f",`name=${name}`,"-F",`pr=${decision.pr}`,"-f",`ref=refs/heads/${branch}`]))?.data?.repository;
+  const now=current?.pullRequest;
+  if (!current) return skip("metadata_unknown");
+  if(typeof current.id!=="string" || !current.id || current.nameWithOwner?.toLowerCase()!==decision.repo.toLowerCase() || now?.state!=="MERGED" || now.mergeCommit?.oid!==mergeCommit || now.headRefName!==branch || now.headRefOid!==decision.head || now.headRepository?.nameWithOwner?.toLowerCase()!==decision.repo.toLowerCase())return skip("identity_changed");
+  if(typeof current.defaultBranchRef?.name!=="string")return skip("metadata_unknown");
+  if(current.defaultBranchRef.name===branch)return skip("default_branch");
+  if(!Object.hasOwn(current,"ref"))return skip("metadata_unknown");
+  if(current.ref===null)return {cleanup:"already_gone"};
+  if(current.ref?.name!==branch || current.ref?.prefix!=="refs/heads/" || !Object.hasOwn(current.ref,"branchProtectionRule"))return skip("metadata_unknown");
+  if(current.ref.branchProtectionRule!==null)return skip("protected_branch");
+  if(current.ref.target?.oid!==decision.head)return skip("head_changed");
+  // This endpoint includes all active repository/organization rulesets; any active rule conservatively protects the branch.
+  const rules=await read(["api",`repos/${decision.repo}/rules/branches/${encodeURIComponent(branch)}?per_page=100`]);
+  if(!Array.isArray(rules))return skip("metadata_unknown");
+  if(rules.length)return skip("protected_branch");
+  // Persist the claim after every await and immediately before the sole ref write. A lost acknowledgement is never retried.
+  if(!claim({cleanup:"claimed"}))return skip("authority_changed");
+  const mutation='mutation($repo:ID!,$ref:GitRefname!,$before:GitObjectID!,$after:GitObjectID!){updateRefs(input:{repositoryId:$repo,clientMutationId:"agent-hub-post-merge-cleanup",refUpdates:[{name:$ref,beforeOid:$before,afterOid:$after}]}){clientMutationId}}';
+  const reply=await read(["api","graphql","-f",`query=${mutation}`,"-f",`repo=${current.id}`,"-f",`ref=refs/heads/${branch}`,"-f",`before=${decision.head}`,"-f",`after=${"0".repeat(40)}`]);
+  if(reply?.data?.updateRefs?.clientMutationId==="agent-hub-post-merge-cleanup")return {cleanup:"deleted"};
+  const recheck=(await read(["api","graphql","-f",`query=${lastQuery}`,"-f",`owner=${owner}`,"-f",`name=${name}`,"-F",`pr=${decision.pr}`,"-f",`ref=refs/heads/${branch}`]))?.data?.repository;
+  if(recheck?.nameWithOwner?.toLowerCase()===decision.repo.toLowerCase() && recheck.ref?.name===branch && recheck.ref?.prefix==="refs/heads/" && typeof recheck.ref.target?.oid==="string" && SHA.test(recheck.ref.target.oid) && recheck.ref.target.oid!==decision.head)return skip("head_changed");
+  return {cleanup:"unknown",reason:"delete_unconfirmed"};
+}
+
+/** What a caller (the control op, the CLI, a test) sees: the decision and, after a run, GitHub's own readback. No remote text, no titles. */
+export interface MergeView { mode: AutoMergeMode; ran: boolean; decision: "merge" | "refused"; argv?: string[]; refused?: string[]; result?: MergeOutcome["result"] }
+export function mergeView(outcome: MergeOutcome): MergeView {
+  const { decision } = outcome;
+  return { mode: outcome.mode, ran: outcome.ran, ...("action" in decision ? { decision: "merge" as const, argv: decision.argv } : { decision: "refused" as const, refused: decision.refused }), ...(outcome.result ? { result: outcome.result } : {}) };
+}

package/src/hub/sdlc-metrics.ts

@@ -11,8 +11,8 @@ export type BandTier = typeof BAND_TIERS[number];
 export interface MetricTask {
   id: number;
   private?: boolean;
-  /** `requestHead` is the head a `done` asked review for (reviewCost.head); `verdictHead` the head a verdict was bound to (reviewFindings.head). Compared for equality only, never printed. */
-  history: { at: number; event: string; requestHead?: string; verdictHead?: string }[];
+  /** `evidenceOnly` marks a code-scope verdict with no open finding (#852): it is not a rework round. `requestHead` is the head a `done` asked review for (reviewCost.head); `verdictHead` the head a verdict was bound to (reviewFindings.head). Compared for equality only, never printed. */
+  history: { at: number; event: string; requestHead?: string; verdictHead?: string; evidenceOnly?: true }[];
 }
 
 /** Per-task values; `null` is unknown. */
@@ -98,6 +98,8 @@ export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciRerun
   const spec = first(view, ["spec accepted"]);
   const plan = spec ? first(view, ["plan reviewed"], spec.at) : undefined;
   const verdict = accepted ? first(view, VERDICTS, accepted.at) : first(view, VERDICTS);
+  // Evidence-only still ends the actual wait for a first review, but says nothing about whether the work passed.
+  const substantiveVerdict = history.find(entry => entry.at >= (accepted?.at ?? -Infinity) && VERDICTS.includes(entry.event) && entry.evidenceOnly !== true);
   const dones = history.filter(entry => entry.event === "done");
   const ci = first(view, ["check passed", "check failed"]);
   const approvedAt = history.find(entry => entry.event === "approved")?.at ?? null;
@@ -108,10 +110,10 @@ export function taskSample(task: MetricTask, extra: { mergedAt?: number; ciRerun
     acceptance_to_plan_ms: spec && plan ? plan.at - spec.at : null,
     acceptance_to_first_review_ms: accepted && verdict ? verdict.at - accepted.at : null,
     acceptance_to_merge_ms: accepted && extra.mergedAt !== undefined && Number.isFinite(extra.mergedAt) && extra.mergedAt >= accepted.at ? extra.mergedAt - accepted.at : null,
-    first_pass_approval: verdict ? (verdict.event === "approved" ? 1 : 0) : null,
+    first_pass_approval: substantiveVerdict ? (substantiveVerdict.event === "approved" ? 1 : 0) : null,
     // Rework grows with every round, so it is a value only once the task is approved: a task still in flight has no final one, and a
     // provisional point would move at each verdict and could start a second breach episode inside one shift.
-    rework_rounds: dones.length && approvedAt !== null ? history.filter(entry => entry.event === "changes_requested").length : null,
+    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,
     stale_head_re_reviews: approvedAt !== null ? staleHeadRounds(history) : null,

package/src/hub/sdlc-mirror.ts

@@ -0,0 +1,129 @@
+import { sanitize } from "./envelope.ts";
+import type { SdlcGh } from "./sdlc.ts";
+
+/**
+ * #786 T3 (AC1): mirror a hub verdict as ONE `COMMENT` review on the head it was given for. One GitHub account authors and merges every PR, and GitHub refuses `APPROVE` and
+ * `REQUEST_CHANGES` on your own PR, so a comment is the only review the hub can leave. It is a record for a person reading the PR, never a gate: nothing here reads it back
+ * as approval, and a failure never touches the verdict (the caller runs this after the verdict is saved and never awaits it).
+ *
+ * The call is exactly `gh api repos/<repo>/pulls/<pr>/reviews -f event=COMMENT -f commit_id=<head> -f body=<text>` (`-f` makes it a POST), checked by `assertMirrorArgv` right before
+ * it runs. The first line of the body is `agent-hub verdict: approved|changes_requested (task #N, reviewer <peer>)`; the rest is the note's public view, which the caller supplies
+ * only when the task is not private and the note was not withheld (a PII task mirrors the first line alone).
+ */
+
+export type MirrorMode = "off" | "dry-run" | "on";
+export type MirrorVerdict = "approved" | "changes_requested";
+export interface MirrorInput {
+  repo: string; pr: number;
+  /** The head the verdict was given for. A PR that is no longer at it gets nothing. */
+  head: string;
+  verdict: MirrorVerdict;
+  task: number;
+  reviewer: string;
+  /** The note's public view, already screened by the caller. Absent for a private task or a withheld note. */
+  note?: string;
+  mode: MirrorMode;
+  run: SdlcGh;
+}
+export type MirrorOutcome =
+  | { mode: MirrorMode; posted: false; reason: "off" | "stale head" | "pr not open" | "already mirrored" | "unreadable" | "in flight" | "invalid" }
+  | { mode: "dry-run"; posted: false; reason: "dry-run"; argv: string[] }
+  | { mode: "on"; posted: boolean; reason: "posted" | "post failed"; argv: string[] };
+
+const SHA = /^[0-9a-f]{40}$/;
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+/** GitHub's review body limit is far larger; a mirror is a pointer, so it stays short. */
+export const MIRROR_NOTE_MAX = 3000;
+const MARK = "agent-hub verdict: ";
+
+/** The first line the mirror starts with. The retry check matches its stable part (verdict and task), so a different reviewer's repeat of the same verdict is not posted twice. */
+export const mirrorHeadline = (verdict: MirrorVerdict, task: number, reviewer: string): string => `${MARK}${verdict} (task #${task}, reviewer ${reviewer})`;
+const stableHeadline = (verdict: MirrorVerdict, task: number): string => `${MARK}${verdict} (task #${task}, reviewer `;
+
+/** The whole body: the headline, then the note when there is one. The note cannot forge a headline of its own (`sanitize` and a header strip) and is bounded. */
+export function mirrorBody(input: { task: number; reviewer: string; verdict: MirrorVerdict; note?: string }): string {
+  const head = mirrorHeadline(input.verdict, input.task, input.reviewer);
+  const note = (input.note ?? "").replace(/\r/g, "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim();
+  if (!note) return head;
+  // A line of the note that starts like a verdict headline would read as a second mirror on the PR: keep it, indented, so it cannot.
+  const safe = sanitize(note).split("\n").map(line => line.startsWith(MARK) ? ` ${line}` : line).join("\n");
+  return `${head}\n\n${safe.length > MIRROR_NOTE_MAX ? `${safe.slice(0, MIRROR_NOTE_MAX)}\n[note cut]` : safe}`;
+}
+
+/** The only write this module makes. A closed shape: the endpoint is this PR's reviews, the event is COMMENT, and the commit is the verdict's head. */
+export function mirrorArgv(repo: string, pr: number, head: string, body: string): string[] {
+  if (!REPO.test(repo) || repo.startsWith("-") || !Number.isSafeInteger(pr) || pr <= 0 || !SHA.test(head)) throw new Error("mirror argv needs owner/repository, a PR number and a full head");
+  return ["api", `repos/${repo}/pulls/${pr}/reviews`, "-f", "event=COMMENT", "-f", `commit_id=${head}`, "-f", `body=${body}`];
+}
+export function assertMirrorArgv(argv: readonly string[], head: string): void {
+  const [verb, endpoint, f1, event, f2, commit, f3, body, ...rest] = argv;
+  const shape = verb === "api" && /^repos\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/pulls\/[1-9][0-9]*\/reviews$/.test(endpoint ?? "") && !endpoint!.startsWith("repos/-")
+    && f1 === "-f" && event === "event=COMMENT" && f2 === "-f" && commit === `commit_id=${head}` && SHA.test(head) && f3 === "-f" && typeof body === "string" && body.startsWith(`body=${MARK}`) && rest.length === 0;
+  if (!shape) throw new Error("refusing a mirror argv outside the COMMENT review shape");
+}
+
+/** One mirror at a time per (task, head, verdict) in this process; the durable check below covers a restart and another process. */
+const inFlight = new Set<string>();
+
+/** The PR's current head and state in one bounded read; undefined when GitHub does not answer cleanly (never a pass). */
+async function readHead(repo: string, pr: number, run: SdlcGh): Promise<{ head: string; open: boolean } | undefined> {
+  try {
+    const reply = await run(["pr", "view", String(pr), "--repo", repo, "--json", "headRefOid,state"]);
+    if (reply.code !== 0) return undefined;
+    const data = JSON.parse(reply.stdout);
+    return typeof data?.headRefOid === "string" && SHA.test(data.headRefOid) && typeof data.state === "string" ? { head: data.headRefOid, open: data.state === "OPEN" } : undefined;
+  } catch { return undefined; }
+}
+
+/**
+ * Did this verdict already get a mirror at this head? Reads the PR's first 100 reviews, reduced by `--jq` to commit and first line only (no body text comes back). A full
+ * page, or any read that does not parse, is unknown: unknown posts nothing, because a duplicate on a person's PR is worse than a missing comment.
+ */
+async function alreadyMirrored(repo: string, pr: number, head: string, verdict: MirrorVerdict, task: number, run: SdlcGh): Promise<boolean | undefined> {
+  try {
+    const reply = await run(["api", `repos/${repo}/pulls/${pr}/reviews?per_page=100`, "--jq", "[.[] | {c: .commit_id, l: ((.body // \"\") | split(\"\\n\")[0])}]"]);
+    if (reply.code !== 0) return undefined;
+    const rows = JSON.parse(reply.stdout);
+    if (!Array.isArray(rows) || rows.length >= 100) return undefined;
+    const stable = stableHeadline(verdict, task);
+    return rows.some((row: { c?: unknown; l?: unknown }) => row?.c === head && typeof row.l === "string" && row.l.startsWith(stable));
+  } catch { return undefined; }
+}
+
+/**
+ * The mirror. `off` does nothing and reads nothing. Otherwise: the PR must still be open at the verdict's head (a stale head posts nothing), a mirror of this verdict at this
+ * head must not exist yet (read from GitHub, so a restart or a retried verdict does not post twice), the head and state are read once more after that listing, and then
+ * `dry-run` reports the argv it would run while `on` posts it. Ceiling: GitHub offers no compare-and-set on a review, so a push that lands after the last read and before the
+ * post is not seen; the comment still names H in `commit_id` and in its headline, so it says truthfully which commit the verdict was about.
+ */
+export async function mirrorVerdict(input: MirrorInput): Promise<MirrorOutcome> {
+  if (input.mode === "off") return { mode: "off", posted: false, reason: "off" };
+  const { repo, pr, head, verdict, task, reviewer, run } = input;
+  if (!REPO.test(repo) || repo.startsWith("-") || !Number.isSafeInteger(pr) || pr <= 0 || !SHA.test(head) || !Number.isSafeInteger(task) || task <= 0 || !PEER.test(reviewer) && reviewer !== "user"
+    || verdict !== "approved" && verdict !== "changes_requested") return { mode: input.mode, posted: false, reason: "invalid" };
+  const key = JSON.stringify([repo.toLowerCase(), pr, head, verdict, task]);
+  if (inFlight.has(key)) return { mode: input.mode, posted: false, reason: "in flight" };
+  inFlight.add(key);
+  try {
+    const current = await readHead(repo, pr, run);
+    if (!current) return { mode: input.mode, posted: false, reason: "unreadable" };
+    if (current.head !== head) return { mode: input.mode, posted: false, reason: "stale head" };
+    if (!current.open) return { mode: input.mode, posted: false, reason: "pr not open" };
+    const seen = await alreadyMirrored(repo, pr, head, verdict, task, run);
+    if (seen === undefined) return { mode: input.mode, posted: false, reason: "unreadable" };
+    if (seen) return { mode: input.mode, posted: false, reason: "already mirrored" };
+    // The review list was an await: a push or a close during it makes the first read stale. Read the head and state once more, LAST, and judge on that read; nothing is awaited
+    // between it and the post below. `commit_id` pins the comment to H but does not make H still current, so this read is what keeps "a stale head posts nothing" true.
+    const last = await readHead(repo, pr, run);
+    if (!last) return { mode: input.mode, posted: false, reason: "unreadable" };
+    if (last.head !== head) return { mode: input.mode, posted: false, reason: "stale head" };
+    if (!last.open) return { mode: input.mode, posted: false, reason: "pr not open" };
+    const argv = mirrorArgv(repo, pr, head, mirrorBody({ task, reviewer, verdict, ...(input.note !== undefined ? { note: input.note } : {}) }));
+    if (input.mode === "dry-run") return { mode: "dry-run", posted: false, reason: "dry-run", argv };
+    assertMirrorArgv(argv, head);
+    let exit = 1;
+    try { exit = (await run(argv, 10_000)).code; } catch { exit = 1; }
+    return { mode: "on", posted: exit === 0, reason: exit === 0 ? "posted" : "post failed", argv };
+  } finally { inFlight.delete(key); }
+}