src/auto-merge-tick.ts

Functions

Imports

It imports src/approval-executor.ts, src/auto-merge-policy.ts, src/doc-statements.ts, src/env.ts, src/github/client.ts, src/github/pr-files.ts, src/github/refs.ts, src/log.ts, src/merge-class.ts, src/merge-safety.ts, src/merge-units.ts, src/visual-pr.ts. Imported by src/digest.ts, src/inbox.ts, src/ops-feed.ts, src/pr-approvals.ts, src/push.ts, src/status.ts, src/tick.ts.

Source

1import { readSuspended, unitKey } from "./merge-units";
2import { readPaused } from "./merge-safety";
3import type { Env } from "./env";
4import { existingTestReason, mergeClass, pathClassOfAll, type Classification, type MergeClass, type PathClass } from "./merge-class";
5import { getDefaultBranch, ghFetch, resolveRepo } from "./github/client";
6import { HeadMovedError, managePr } from "./github/refs";
7import { PER_PAGE, readCheckRuns, readPrFiles } from "./github/pr-files";
8import { systemAudit } from "./doc-statements";
9import {
10  type PolicyCheck,
11  requiredCiFor,
12  loadMergePolicy,
13  type PrFacts,
14  jobIdFromBody,
15  evaluatePolicy,
16  ciVerdict,
17} from "./auto-merge-policy";
18import { logEvent } from "./log";
19import { isVisual, visualDetails, type VisualPr } from "./visual-pr";
20import { closeAsAutoMerged, executeApproval, expireStaleApprovals, readOpenApprovals, type OpenApproval } from "./approval-executor";
21
22// The auto-merge tick: read each open pull request's facts from GitHub and D1, judge
23// them with evaluatePolicy (src/auto-merge-policy.ts), and merge or record the refusal.
24
25interface OpenPr {
26  number: number;
27  title?: string | null;
28  body: string | null;
29  labels?: Array<{ name?: string }> | null;
30  base: { ref: string };
31  // repo is null when the head was on a fork that has since been deleted.
32  head: { sha: string; repo?: { full_name?: string } | null };
33  user?: { login?: string } | null;
34  draft?: boolean;
35}
36
37const CHECKS_MAX_PAGES = 10;
38
39interface WorkflowRun {
40  id: number;
41  path: string;
42}
43
44// The steps of the newest run of each required workflow on this head sha. Only
45// workflows this namespace's required steps name are read.
46async function ciStepsFor(
47  env: Env,
48  namespace: string,
49  owner: string,
50  repo: string,
51  headSha: string
52): Promise<{ steps: PrFacts["ciSteps"]; problem: string | null }> {
53  const runsResp = await ghFetch(
54    env, owner, repo, `/repos/${owner}/${repo}/actions/runs?head_sha=${encodeURIComponent(headSha)}&per_page=${PER_PAGE}`
55  );
56  if (!runsResp.ok) return { steps: [], problem: `the workflow run list returned ${runsResp.status}` };
57  const runs = ((await runsResp.json()) as { workflow_runs?: WorkflowRun[] }).workflow_runs ?? [];
58  const steps: PrFacts["ciSteps"] = [];
59  for (const workflow of new Set((requiredCiFor(namespace) ?? []).map((r) => r.workflow))) {
60    const newest = runs.filter((r) => r.path === workflow).sort((a, b) => b.id - a.id)[0];
61    // No run of a required workflow leaves its steps absent, which ci_green names.
62    if (!newest) continue;
63    const jobsResp = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/actions/runs/${newest.id}/jobs?per_page=${PER_PAGE}`);
64    if (!jobsResp.ok) return { steps: [], problem: `the jobs of run ${newest.id} returned ${jobsResp.status}` };
65    const jobs = ((await jobsResp.json()) as {
66      jobs?: Array<{ name: string; steps?: Array<{ name: string; conclusion: string | null }> }>;
67    }).jobs ?? [];
68    for (const job of jobs) {
69      for (const step of job.steps ?? []) {
70        steps.push({ workflow, job: job.name, step: step.name, conclusion: step.conclusion });
71      }
72    }
73  }
74  return { steps, problem: null };
75}
76
77async function factsForPr(
78  env: Env,
79  namespace: string,
80  owner: string,
81  repo: string,
82  defaultBranch: string,
83  pr: OpenPr
84): Promise<PrFacts> {
85  const body = pr.body ?? "";
86  const jobId = jobIdFromBody(body);
87
88  let jobClaimedBy: string | null = null;
89  let jobStatus: string | null = null;
90  const jobPrUrls: string[] = [];
91  if (jobId) {
92    const job = await env.DB.prepare("SELECT claimed_by, status, result_ref FROM jobs WHERE id = ?1 AND namespace = ?2")
93      .bind(jobId, namespace)
94      .first<{ claimed_by: string | null; status: string | null; result_ref: string | null }>();
95    jobClaimedBy = job?.claimed_by ?? null;
96    jobStatus = job?.status ?? null;
97    if (job) {
98      if (job.result_ref) jobPrUrls.push(job.result_ref);
99      const recorded = await env.DB.prepare("SELECT pr_url FROM job_outcome_prs WHERE job_id = ?1")
100        .bind(jobId)
101        .all<{ pr_url: string }>();
102      jobPrUrls.push(...(recorded.results ?? []).map((r) => r.pr_url));
103    }
104  }
105
106  const [files, checks] = await Promise.all([
107    readPrFiles(env, owner, repo, pr.number),
108    readCheckRuns(env, owner, repo, pr.head.sha, CHECKS_MAX_PAGES),
109  ]);
110  const filesProblem = files.problem;
111  const changedPaths = files.paths;
112  // An incomplete check-run list is not a pass; ci_green refuses it with the reason.
113  const ci = checks.problem
114    ? { conclusion: null, note: `the check-run list is incomplete (${checks.problem}), so this PR is not evaluated` }
115    : ciVerdict(checks.items);
116  const steps = await ciStepsFor(env, namespace, owner, repo, pr.head.sha);
117
118  return {
119    number: pr.number,
120    repo: `${owner}/${repo}`,
121    namespace,
122    baseRef: pr.base.ref,
123    defaultBranch,
124    headSha: pr.head.sha,
125    body,
126    changedPaths,
127    filesProblem,
128    changedLines: files.changedLines,
129    existingTestEdits: files.testEdits,
130    ciConclusion: ci.conclusion,
131    ciNote: ci.note,
132    ciSteps: steps.steps,
133    ciStepsProblem: steps.problem,
134    headRepo: pr.head.repo?.full_name ?? null,
135    prAuthor: pr.user?.login ?? null,
136    jobId,
137    jobClaimedBy,
138    jobStatus,
139    jobPrUrls,
140  };
141}
142
143// The audit row shapes, built by pure functions so test/auto-merge.test.ts asserts them.
144
145export function declineParams(
146  policyVersion: string,
147  // Only the PR and head, so a PR declined before its facts were read is audited alike.
148  facts: Pick<PrFacts, "repo" | "number" | "headSha">,
149  // A policy refusal, "head_moved" when GitHub refused the pinned merge, or
150  // "unit_suspended" when a rollback suspended the PR's merge unit (src/merge-units.ts),
151  // "namespace_paused" when the safety shutoff paused the namespace (src/merge-safety.ts),
152  // "changes_existing_test" when the PR edits an existing test (src/merge-class.ts), or
153  // "pr_is_draft" when the PR is still a draft.
154  verdict: { failed: PolicyCheck | "head_moved" | "unit_suspended" | "namespace_paused" | "changes_existing_test" | "visual_awaits_look" | "pr_is_draft"; why: string; passed: PolicyCheck[] },
155  now: Date
156): Record<string, unknown> {
157  return {
158    policy_version: policyVersion,
159    repo: facts.repo,
160    pr: facts.number,
161    head_sha: facts.headSha,
162    failed: verdict.failed,
163    why: verdict.why,
164    passed: verdict.passed,
165    at: now.toISOString(),
166  };
167}
168
169export function mergeParams(
170  policyVersion: string,
171  facts: PrFacts,
172  passed: PolicyCheck[],
173  mergeSha: string | null,
174  now: Date,
175  // The merge unit's path class (src/merge-units.ts), so a later rollback of this merge
176  // can be traced to its unit.
177  pathClass: string | null = null
178): Record<string, unknown> {
179  return {
180    policy_version: policyVersion,
181    path_class: pathClass,
182    repo: facts.repo,
183    pr: facts.number,
184    head_sha: facts.headSha,
185    job: facts.jobId,
186    driver: facts.jobClaimedBy,
187    merge_sha: mergeSha,
188    passed,
189    at: now.toISOString(),
190  };
191}
192
193// A decline is logged when the decision for that PR changes, not on every look. The tick
194// runs every five minutes and a PR the policy keeps refusing was logged about 1,400 times
195// a day, with the same PR and the same reason. The last logged decision per PR lives in
196// APP_KV, which the tick already writes: "<head sha> <failed check>". A first decline, a
197// different check, or a new head sha is a change. The reason text (`why`) is not part of
198// the key, because it can carry counts and times that move without the decision moving.
199// The TTL bounds what a closed PR leaves behind; a decline that outlives it is logged
200// once more.
201const LAST_DECLINE_PREFIX = "improve:auto-merge-last-decline:";
202const LAST_DECLINE_TTL_SECONDS = 14 * 24 * 60 * 60;
203
204/** Audit a decline unless the same PR was already logged with this head sha and check.
205 *  A KV failure logs the row anyway: a repeated row is better than a lost one. */
206async function auditDeclineOnChange(
207  env: Env,
208  facts: { repo: string; number: number; headSha: string },
209  failed: string,
210  statement: D1PreparedStatement
211): Promise<void> {
212  const key = `${LAST_DECLINE_PREFIX}${facts.repo}#${facts.number}`;
213  const decision = `${facts.headSha} ${failed}`;
214  try {
215    if ((await env.APP_KV.get(key)) === decision) return;
216  } catch (err) {
217    logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not read the last decline of ${key}: ${err instanceof Error ? err.message : String(err)}` });
218  }
219  // The row first, so a failed KV write repeats a row on the next tick rather than
220  // losing one.
221  await env.DB.batch([statement]);
222  try {
223    await env.APP_KV.put(key, decision, { expirationTtl: LAST_DECLINE_TTL_SECONDS });
224  } catch (err) {
225    logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not record the last decline of ${key}: ${err instanceof Error ? err.message : String(err)}` });
226  }
227}
228
229// The merge units held back this tick (src/merge-units.ts), and the namespaces the safety
230// shutoff paused (src/merge-safety.ts): each a set, or "all" when it could not be read.
231type Suspended = ReadonlySet<string> | "all";
232type PausedNamespaces = ReadonlyMap<string, string> | "all";
233
234interface AutoMergeOutcome {
235  namespace: string;
236  repo: string;
237  number: number;
238  merged: boolean;
239  // The check that refused, for a PR left open.
240  failed: string | null;
241  // The head the tick judged, which the Portal's Approve records as the sha Dustin saw.
242  head_sha?: string;
243  why: string | null;
244  passed: string[];
245  // The merge pipeline's class (src/merge-class.ts), report-only; null when the PR's
246  // files were never read (the body names no job, or the tick threw).
247  merge_class?: Classification | null;
248  // For a pull request labelled visual: what Dustin looks at before he approves it
249  // (src/visual-pr.ts).
250  visual?: VisualPr;
251}
252
253// Where the awaiting-seat set lives. Rewritten whole on every tick rather than
254// appended to, because the tick recomputes the full set of open pull requests each
255// time: a PR a human merged or closed stops appearing, with no second mechanism needed
256// to expire it. capsid_run_improve action status reads this key rather than calling GitHub, so asking
257// for status costs nothing.
258export const AWAITING_SEAT_KEY = "improve:awaiting-seat";
259
260export interface AwaitingSeat {
261  namespace: string;
262  repo: string;
263  number: number;
264  failed: string;
265  why: string;
266  at: string;
267  // Report-only (docs/design/design-merge-pipeline.md, PR 2): the class, its path class
268  // and why. Absent on sets written before this field, and null when unclassified.
269  class?: MergeClass | null;
270  path_class?: PathClass | null;
271  class_reasons?: string[];
272  // The head the tick judged (absent on sets written before this field). The Portal's
273  // Approve sends it as the sha Dustin approved, so a later push voids the approval.
274  head_sha?: string;
275  // A pull request labelled visual: its title, preview and screenshots (src/visual-pr.ts).
276  visual?: VisualPr;
277}
278
279export interface AutoMergeReport {
280  ran: boolean;
281  note: string;
282  policy_version: string | null;
283  outcomes: AutoMergeOutcome[];
284}
285
286/** One pass over every open PR on every namespace the policy covers. */
287export async function autoMergeTick(env: Env, now: Date): Promise<AutoMergeReport> {
288  const loaded = await loadMergePolicy(env);
289  if ("error" in loaded) return { ran: false, note: loaded.error, policy_version: null, outcomes: [] };
290  const policy = loaded.policy;
291  if (!policy.enabled) {
292    return { ran: false, note: `merge policy ${policy.version} is present and disabled, so nothing is auto-merged.`, policy_version: policy.version, outcomes: [] };
293  }
294
295  const outcomes: AutoMergeOutcome[] = [];
296
297  // The merge units a rollback suspended (src/merge-units.ts). A suspension only narrows,
298  // so a list that cannot be read holds every unit back this tick rather than none.
299  let suspended: Suspended;
300  try {
301    suspended = new Set((await readSuspended(env.APP_KV)).map((s) => s.unit));
302  } catch (err) {
303    logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not read the suspended merge units, so nothing merges unattended this tick: ${err instanceof Error ? err.message : String(err)}` });
304    suspended = "all";
305  }
306
307  // The namespaces the safety shutoff paused: the same rule, an unreadable value pauses
308  // every namespace this tick.
309  let paused: PausedNamespaces;
310  try {
311    paused = new Map(Object.entries(await readPaused(env.APP_KV)).map(([ns, p]) => [ns, p.reason]));
312  } catch (err) {
313    logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not read the paused namespaces, so nothing merges unattended this tick: ${err instanceof Error ? err.message : String(err)}` });
314    paused = "all";
315  }
316
317  for (const namespace of policy.namespaces) {
318    let owner: string;
319    let repo: string;
320    let defaultBranch: string;
321    let prs: OpenPr[];
322    // The open approvals on this repo (src/pr-approvals.ts), for the executor below. A
323    // read that fails (the table not migrated yet) leaves none, so the tick goes on as
324    // the policy alone and merges nothing on an approval it could not read.
325    let approvals = new Map<number, OpenApproval>();
326    // A namespace that cannot be read is skipped, not the whole tick. The default-branch
327    // read and the list parse throw on a GitHub failure, and a throw here would stop
328    // every later namespace and the awaiting-seat write.
329    try {
330      ({ owner, repo } = await resolveRepo(env, namespace));
331      defaultBranch = await getDefaultBranch(env, owner, repo);
332      // Every page, so a PR past the first hundred is judged and stays in the seat's
333      // queue. A list that cannot be read whole skips the namespace (Grok audit
334      // 2026-10-21, CA-15).
335      const listedPrs = await listOpenPrs(env, owner, repo);
336      if (typeof listedPrs === "string") {
337        logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not list PRs on ${owner}/${repo} (${listedPrs})` });
338        continue;
339      }
340      prs = listedPrs;
341      try {
342        approvals = await readOpenApprovals(env.DB, `${owner}/${repo}`);
343      } catch (err) {
344        logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not read the approvals on ${owner}/${repo}: ${err instanceof Error ? err.message : String(err)}` });
345      }
346    } catch (err) {
347      logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not read ${namespace}: ${err instanceof Error ? err.message : String(err)}` });
348      continue;
349    }
350
351    for (const pr of prs) {
352      // A PR whose body names no job is declined before any GitHub read, since
353      // body_names_job refuses it anyway and the reads share the rate limit. A visual PR,
354      // or one Dustin approved, is judged all the same: body_names_job leaves it class
355      // approve, so his approval merges it on green CI (job_0368576da167).
356      const visual = isVisual(pr);
357      if (!jobIdFromBody(pr.body ?? "") && !visual && !approvals.has(pr.number)) {
358        const skipped = {
359          failed: "body_names_job" as const,
360          why: "the PR body names no job id, so there is no request this change can be traced back to. Its files and checks were not read.",
361          passed: [] as PolicyCheck[],
362        };
363        outcomes.push({ namespace, repo: `${owner}/${repo}`, number: pr.number, merged: false, head_sha: pr.head.sha, ...skipped });
364        try {
365          const skippedFacts = { repo: `${owner}/${repo}`, number: pr.number, headSha: pr.head.sha };
366          await auditDeclineOnChange(
367            env,
368            skippedFacts,
369            skipped.failed,
370            systemAudit(env.DB, "auto-merge-declined", namespace, declineParams(policy.version, skippedFacts, skipped, now))
371          );
372        } catch (err) {
373          logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not audit the decline of ${owner}/${repo}#${pr.number}: ${err instanceof Error ? err.message : String(err)}` });
374        }
375        continue;
376      }
377      // One PR that throws does not end the tick. A 405 on a PR that is not mergeable,
378      // a failed read or a D1 error would otherwise abort every later PR and namespace,
379      // leave no audit row, and skip the awaiting-seat write. The PR is reported as not
380      // merged with the error, and an auto-merge-failed row says why.
381      const before = outcomes.length;
382      try {
383        try {
384          await judgeOnePr(env, policy.version, policy.authors, namespace, owner, repo, defaultBranch, pr, outcomes, now, approvals.get(pr.number) ?? null, suspended, policy.units, paused, visual);
385        } catch (err) {
386          const why = err instanceof Error ? err.message : String(err);
387          logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE failed on ${owner}/${repo}#${pr.number}: ${why}` });
388          // An outcome already pushed is the true one; only its audit row failed.
389          if (outcomes.length > before) continue;
390          outcomes.push({ namespace, repo: `${owner}/${repo}`, number: pr.number, merged: false, failed: "error", why: `the tick could not judge or merge this PR: ${why}`, passed: [] });
391          try {
392            await env.DB.batch([
393              systemAudit(env.DB, "auto-merge-failed", namespace, {
394                policy_version: policy.version,
395                repo: `${owner}/${repo}`,
396                pr: pr.number,
397                head_sha: pr.head.sha,
398                error: why,
399                at: now.toISOString(),
400              }),
401            ]);
402          } catch (auditErr) {
403            logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not audit the failure on ${owner}/${repo}#${pr.number}: ${auditErr instanceof Error ? auditErr.message : String(auditErr)}` });
404          }
405        }
406      } finally {
407        for (let k = before; k < outcomes.length; k++) {
408          outcomes[k]!.head_sha ??= pr.head.sha;
409          if (visual && !outcomes[k]!.merged) outcomes[k]!.visual = visualDetails(pr);
410        }
411      }
412    }
413  }
414
415  // An approval on a pull request the tick no longer sees (closed or merged by hand) is
416  // expired at 7 days here, since the executor sees only open pull requests.
417  try {
418    await expireStaleApprovals(env, now);
419  } catch (err) {
420    logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not expire old approvals: ${err instanceof Error ? err.message : String(err)}` });
421  }
422
423  // The full awaiting-seat set, written whole, and written even when it is empty, so a
424  // tick that cleared the last one leaves no stale entry behind.
425  const awaiting: AwaitingSeat[] = outcomes
426    .filter((o) => !o.merged)
427    .map((o) => ({
428      namespace: o.namespace,
429      repo: o.repo,
430      number: o.number,
431      failed: o.failed ?? "unknown",
432      why: o.why ?? "",
433      at: now.toISOString(),
434      class: o.merge_class?.class ?? null,
435      path_class: o.merge_class?.path_class ?? null,
436      class_reasons: o.merge_class?.reasons ?? [],
437      ...(o.head_sha ? { head_sha: o.head_sha } : {}),
438      ...(o.visual ? { visual: o.visual } : {}),
439    }));
440  try {
441    await env.APP_KV.put(AWAITING_SEAT_KEY, JSON.stringify(awaiting));
442  } catch (err) {
443    logEvent("error", "AUTO_MERGE", { message: `AUTO_MERGE could not record the awaiting-seat set: ${err instanceof Error ? err.message : String(err)}` });
444  }
445
446  const merged = outcomes.filter((o) => o.merged).length;
447  return {
448    ran: true,
449    note: `policy ${policy.version}: ${merged} merged, ${outcomes.length - merged} left for the seat`,
450    policy_version: policy.version,
451    outcomes,
452  };
453}
454
455const OPEN_PR_PAGES = 10;
456
457/** Every open PR on the repo, page by page until a short page, or why the list is not whole. */
458async function listOpenPrs(env: Env, owner: string, repo: string): Promise<OpenPr[] | string> {
459  const all: OpenPr[] = [];
460  for (let page = 1; page <= OPEN_PR_PAGES; page++) {
461    const listed = await ghFetch(env, owner, repo, `/repos/${owner}/${repo}/pulls?state=open&per_page=100&page=${page}`);
462    if (!listed.ok) return String(listed.status);
463    const batch = (await listed.json()) as OpenPr[];
464    all.push(...batch);
465    if (batch.length < 100) return all;
466  }
467  return `more than ${OPEN_PR_PAGES * 100} open PRs`;
468}
469
470/** Judge one PR that names a job, merge it when the policy passes, and audit either way.
471 *  Pushes exactly one outcome, before its audit row, so a caller can tell a PR that was
472 *  judged from one that threw first. */
473async function judgeOnePr(
474  env: Env,
475  policyVersion: string,
476  allowedAuthors: string[],
477  namespace: string,
478  owner: string,
479  repo: string,
480  defaultBranch: string,
481  pr: OpenPr,
482  outcomes: AutoMergeOutcome[],
483  now: Date,
484  // The pull request's open approval (src/pr-approvals.ts), or null.
485  approval: OpenApproval | null = null,
486  // The merge units a rollback suspended, or "all" when they could not be read.
487  suspended: Suspended = new Set(),
488  // The units the signed policy promoted to auto, each `<namespace> / <path class>`.
489  units: readonly string[] = [],
490  // The namespaces the safety shutoff paused, or "all" when they could not be read.
491  paused: PausedNamespaces = new Map(),
492  // Labelled visual: it waits for Dustin's look even when the policy would merge it.
493  visual = false
494): Promise<void> {
495  const facts = await factsForPr(env, namespace, owner, repo, defaultBranch, pr);
496  // A promoted unit widens only the namespace's allowed paths (src/auto-merge-policy.ts).
497  const pathClass = facts.filesProblem ? null : pathClassOfAll(facts.changedPaths);
498  const promotedUnit = pathClass && units.includes(`${namespace} / ${pathClass}`) ? { unit: `${namespace} / ${pathClass}` } : null;
499  const verdict = evaluatePolicy(facts, allowedAuthors, promotedUnit);
500  let merge_class = mergeClass(facts, verdict, pr.draft === true);
501  // Five holds that only narrow. A draft waits as class wait. The other four leave the PR for Dustin as class approve (his
502  // approval still executes below): a visual change (src/visual-pr.ts), an existing test it changes (src/merge-class.ts), a
503  // paused namespace (src/merge-safety.ts), and a unit a rollback suspended
504  // (src/merge-units.ts). The policy would merge it, so it is held with the reason.
505  const unit = merge_class.path_class ? unitKey(namespace, merge_class.path_class) : null;
506  let hold: { failed: "pr_is_draft" | "changes_existing_test" | "namespace_paused" | "unit_suspended" | "visual_awaits_look"; reason: string } | null = null;
507  // A draft first, and it keeps its class wait: GitHub refuses to merge a draft with a
508  // 405, so sending it would only fail (Grok audit 2026-10, C2).
509  if (verdict.merge && pr.draft === true) {
510    hold = { failed: "pr_is_draft", reason: "the PR is a draft: it is judged again once it is marked ready for review" };
511  } else if (verdict.merge && visual) {
512    hold = { failed: "visual_awaits_look", reason: "a visual change: Dustin looks at its preview or screenshots before it merges" };
513  } else if (verdict.merge && facts.existingTestEdits.length > 0) {
514    hold = { failed: "changes_existing_test", reason: existingTestReason(facts.existingTestEdits) };
515  } else if (verdict.merge && (paused === "all" || paused.has(namespace))) {
516    hold = {
517      failed: "namespace_paused",
518      reason: paused === "all" ? "the paused namespaces could not be read, so nothing merges unattended this tick" : `auto-merge for ${namespace} is paused: ${paused.get(namespace)}`,
519    };
520  } else if (verdict.merge && (suspended === "all" || (unit !== null && suspended.has(unit)))) {
521    hold = {
522      failed: "unit_suspended",
523      reason: suspended === "all" ? "the suspended merge units could not be read, so nothing merges unattended this tick" : `the merge unit ${unit} is suspended after a rollback`,
524    };
525  }
526  if (hold && hold.failed !== "pr_is_draft") merge_class = { class: "approve", path_class: merge_class.path_class, reasons: [hold.reason] };
527  const held = hold !== null;
528  const merges = verdict.merge && !held;
529  // The executor (docs/design/design-merge-pipeline.md section 4): a pull request the
530  // policy leaves open but Dustin approved merges here once CI is green on the approved
531  // sha, or its approval is voided, expired or refused, and the PR is judged as before.
532  // Not for a draft: GitHub refuses to merge one, and the hold below says why (Grok audit
533  // 2026-10-21, CA-16).
534  if (!merges && approval && pr.draft !== true) {
535    const done = await executeApproval(env, namespace, facts, merge_class, approval, now);
536    if (done.done === "merged") {
537      outcomes.push({ namespace, repo: facts.repo, number: pr.number, merged: true, failed: null, why: done.why, passed: verdict.passed, merge_class });
538      return;
539    }
540  }
541  if (!verdict.merge) {
542    outcomes.push({
543      namespace,
544      repo: facts.repo,
545      number: pr.number,
546      merged: false,
547      failed: verdict.failed,
548      why: verdict.why,
549      passed: verdict.passed,
550      merge_class,
551    });
552    await auditDeclineOnChange(
553      env,
554      facts,
555      verdict.failed,
556      systemAudit(env.DB, "auto-merge-declined", namespace, declineParams(policyVersion, facts, verdict, now))
557    );
558    return;
559  }
560  if (hold) {
561    const held = { failed: hold.failed, why: hold.reason, passed: verdict.passed };
562    outcomes.push({ namespace, repo: facts.repo, number: pr.number, merged: false, ...held, merge_class });
563    await auditDeclineOnChange(env, facts, held.failed, systemAudit(env.DB, "auto-merge-declined", namespace, declineParams(policyVersion, facts, held, now)));
564    return;
565  }
566  // merge_method "merge", because a squash would not keep the audited head sha. Pinned
567  // to the sha the checks read: a push since then gets a 409 and the next tick judges
568  // the new head.
569  let result: unknown;
570  try {
571    result = await managePr(env, namespace, pr.number, "merge", "merge", undefined, undefined, facts.headSha);
572  } catch (err) {
573    if (!(err instanceof HeadMovedError)) throw err;
574    const moved = {
575      failed: "head_moved" as const,
576      why: `the PR head moved after the policy judged ${facts.headSha}, so GitHub refused the pinned merge. ${err.message}`,
577      passed: verdict.passed,
578    };
579    outcomes.push({ namespace, repo: facts.repo, number: pr.number, merged: false, ...moved, merge_class });
580    await auditDeclineOnChange(
581      env,
582      facts,
583      moved.failed,
584      systemAudit(env.DB, "auto-merge-declined", namespace, declineParams(policyVersion, facts, moved, now))
585    );
586    return;
587  }
588  outcomes.push({ namespace, repo: facts.repo, number: pr.number, merged: true, failed: null, why: null, passed: verdict.passed, merge_class });
589  // Merged by the policy on its own: an approval it held has nothing left to do.
590  if (approval) await closeAsAutoMerged(env, namespace, facts, approval, (result as { sha?: string }).sha ?? null, now);
591  // The merge has landed, and the tick's catch does not retry a PR whose outcome is pushed,
592  // so the row the safety meter and the merge units read is tried a second time before the
593  // failure is left to that catch (Grok audit 2026-10-21, CA-18).
594  const writeMerged = () =>
595    env.DB.batch([
596      systemAudit(
597        env.DB,
598        "auto-merged",
599        namespace,
600        mergeParams(policyVersion, facts, verdict.passed, (result as { sha?: string }).sha ?? null, now, merge_class.path_class)
601      ),
602    ]);
603  try {
604    await writeMerged();
605  } catch {
606    await writeMerged();
607  }
608}