@erclx/canon 5.47.0 → 5.49.0

package/src/commands/pr.ts

@@ -1,5 +1,5 @@
 import { existsSync, statSync } from 'node:fs'
-import { readFile, realpath } from 'node:fs/promises'
+import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
 import { $ } from 'bun'
 import type { Command } from 'commander'
@@ -63,6 +63,7 @@ import {
 } from '@/pr/frames'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
 import {
+  type ChecksGate,
   DEFAULT_WAIT_SECONDS,
   type EvidenceGate,
   type GitRunner,
@@ -73,10 +74,27 @@ import {
   readBaseStanding,
   readChangedPaths,
 } from '@/pr/lift'
+import {
+  merge,
+  type MergeApi,
+  type MergeOutcome,
+  type MergeRefusal,
+  type MergeRequest,
+} from '@/pr/merge'
+import { listWorktrees } from '@/git/worktree'
+import {
+  branchSlug,
+  buildDriveCopy,
+  changedSince,
+  loadPreviewConfig,
+  readWorktreeStatus,
+  type StatusEntry,
+} from '@/pr/drive-copy'
 import { machineListenerReader } from '@/listeners/machine'
 import { loadPaintedPatterns } from '@/pr/painted'
 import {
   dropAddressLine,
+  maskLocalAddress,
   findLocalServer,
   type LocalRefusal,
   type LocalRunner,
@@ -93,7 +111,9 @@ import {
   servesChange,
   type WorkflowFile,
 } from '@/pr/preview'
+import { coversHead, resolveUiScope } from '@/pr/review-scope'
 import {
+  countTicksAtHead,
   readUiPassHead,
   type TickRefusal,
   tickBoxes,
@@ -150,6 +170,10 @@ interface LiftCommandOptions extends ReadOptions {
   readonly wait?: string
 }
 
+interface MergeCommandOptions extends ReadOptions {
+  readonly dryRun?: boolean
+}
+
 interface ReviewStateOptions extends ReadOptions {
   readonly wait?: string
 }
@@ -163,8 +187,32 @@ interface TickOptions extends ReadOptions {
   readonly head?: string
 }
 
+interface DriveCopyOptions extends ReadOptions {
+  readonly baseline?: boolean
+  readonly check?: boolean
+}
+
+type DriveCopyRefusal =
+  | 'no-worktree'
+  | 'no-branch'
+  | 'no-baseline'
+  | 'unreadable-tree'
+  | 'bad-flags'
+
+const DRIVE_COPY_REFUSALS: Record<DriveCopyRefusal, string> = {
+  'no-worktree':
+    'No local worktree holds the pull request branch, so there is no tree to copy from or check.',
+  'no-branch':
+    'The checkout holds no branch, so no copy root could be named. Pass the pull request number.',
+  'no-baseline':
+    'No baseline was recorded for this pull request. Run --baseline before --check.',
+  'unreadable-tree': 'git could not read the worktree status.',
+  'bad-flags': '--baseline and --check cannot be combined.',
+}
+
 type TickReason =
   | TickRefusal
+  | 'count-mismatch'
   | 'stale-head'
   | 'bad-boxes'
   | 'no-comment'
@@ -177,6 +225,8 @@ const TICK_REFUSALS: Record<TickReason | 'gh-failed', string> = {
     'The head named is not the branch tip on the remote, so a tick would claim a pass on a commit that is no longer the pull request. Re-drive the checklist at the tip.',
   'bad-boxes':
     '--boxes takes box numbers as a comma-separated list of positive whole numbers, such as 1,3, and --head takes the commit that was driven.',
+  'count-mismatch':
+    'The newest UI verdict at this head passed a different number of boxes than the ticks this call would leave at the head. Nothing was written. With fewer ticks than passed, re-run once with every box that passed. With more, a box ticked earlier at this head has since failed, which only the operator can untick.',
   'no-comment': 'No comment on this pull request carries the evidence marker.',
   'no-checklist': 'The evidence comment carries no checklist to tick.',
   'no-box':
@@ -834,7 +884,9 @@ export function register(program: Command): void {
         '            on an earlier commit still holds when it is an ancestor of the',
         '            head and no painted path changed since, and the record names',
         '            it as `carriedFrom`. A painted change refuses `ui-behind` and',
-        '            lists the paths as `paintedPaths`',
+        '            lists the paths as `paintedPaths`. A close whose count line',
+        '            shows boxes not driven and none passed, failed, or needing',
+        '            eyes refuses `ui-undriven`, carried or not',
         '  evidence  the evidence check reads settled',
         '  standing  the head is fresh against the base, not stale or conflicted',
         '  ci        every check run on the tip passed, waited on up to --wait',
@@ -860,7 +912,7 @@ export function register(program: Command): void {
         '  lifted, already-ready, redrafted, clear (--check)',
         '  pull-closed, review-missing, review-open, review-unmarked,',
         '  review-behind, ui-missing, ui-open, ui-unmarked, ui-behind,',
-        '  evidence-owed, standing-stale, standing-conflict, standing-unknown,',
+        '  ui-undriven, evidence-owed, standing-stale, standing-conflict, standing-unknown,',
         '  ci-pending (--check), ci-failing, ci-conflicted, ci-timeout,',
         '  head-moved, gh-failed',
         '',
@@ -881,6 +933,57 @@ export function register(program: Command): void {
       process.exitCode = await runLift(number, opts)
     })
 
+  pr.command('merge')
+    .description(
+      'Squash-merge a ready pull request with a message carrying only its Summary, Key changes, and Technical context',
+    )
+    .argument('[number]', 'Pull request to merge, defaulting to this branch')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--dry-run', 'Print the title and description and merge nothing')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The operator runs this verb, and no skill calls it. A permissions deny',
+        'rule on `canon pr merge` and `gh pr merge` keeps an agent off it.',
+        '',
+        'The title is the pull request title plus ` (#<number>)`. The',
+        "description is the body's `## Summary`, `## Key changes`, and",
+        '`## Technical context`, in that order under their headings, with the',
+        'UI pass line dropped. Technical context is optional. Testing, the',
+        'reviewer requests, and every other section stay out of the trunk.',
+        '',
+        'Refusals are read before the one write, which sends the head it read',
+        'as `sha`, so a push after the read refuses rather than merging. The',
+        'verb reads the draft flag and not the reviews, since a ready pull',
+        'request already passed `canon pr lift`. It does not wait on checks or',
+        'delete the branch.',
+        '',
+        'Reasons:',
+        '  merged, dry-run (--dry-run)',
+        '  pull-closed, pull-draft, missing-summary, missing-key-changes,',
+        '  ci-failing, ci-conflicted, ci-pending, head-moved, not-mergeable,',
+        '  gh-failed',
+        '',
+        'The merge is the REST `PUT pulls/<number>/merge` with',
+        '`merge_method=squash`, never `gh pr merge`, which runs on GraphQL.',
+        '',
+        'Exit codes:',
+        '  0  merged, or every refusal clear under --dry-run',
+        '  1  refused, with the reason in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr merge 1341 --dry-run',
+        '  canon pr merge 1341 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: MergeCommandOptions) => {
+      process.exitCode = await runMerge(number, opts)
+    })
+
   pr.command('preview')
     .description(
       "Deploy the pull request's branch to a Cloudflare Pages preview and report its address",
@@ -967,7 +1070,10 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--root <path>', 'Worktree to read, defaulting to the cwd')
     .option('--json', 'Add a machine-readable record on stdout')
-    .option('--remove', "Drop the evidence comment's preview address line")
+    .option(
+      '--remove',
+      "Drop the evidence comment's preview address line and mask local addresses in UI reviews",
+    )
     .addHelpText(
       'after',
       [
@@ -990,6 +1096,11 @@ export function register(program: Command): void {
         'and drops the hosted link too because the same close deletes the',
         "branch's preview deployments.",
         '',
+        'It also rewrites the loopback address on the Driven at line of every',
+        'review carrying the review-ui marker to "a local preview", keeping',
+        'the head and the renderer. A hosted address and a code review are',
+        'left alone, and `reviews` on the JSON record counts the rewrites.',
+        '',
         'Read `reason` on the JSON record:',
         '  ok                  a page answered, with its address in `url`',
         '  no-server           nothing inside this worktree served a page',
@@ -1000,7 +1111,8 @@ export function register(program: Command): void {
         '',
         'Refusals, read off `reason`:',
         '  gh-missing  `--remove` needs `gh` and it is not on the path',
-        '  gh-failed   `--remove` could not read or edit the comment',
+        '  gh-failed   `--remove` could not read the thread, or edit the',
+        '              comment or a review, after trying every edit',
         '',
         'Exit codes:',
         '  0  a server was found, or --remove finished, including a no-op',
@@ -1048,9 +1160,19 @@ export function register(program: Command): void {
         'driver can run is ticked, counts taste boxes apart, and is the only',
         'body text this verb writes, so hand edits elsewhere survive.',
         '',
+        'Before writing it reads the newest UI verdict. One that covers the tip',
+        'and carries a count line must match the ticks this call leaves at the',
+        'tip, so a re-drive passes every box that passed, since a new head',
+        'clears the older ticks. Any other verdict leaves the check unrun.',
+        '',
         'Read `reason` on the JSON record:',
         '  ticked       the boxes were ticked and the body line written, with the',
-        '               tip in `head`',
+        '               tip in `head` and `countCheck` as matched or unchecked',
+        '  count-mismatch the verdict passed a different number of boxes than',
+        '               this call leaves ticked at the tip, nothing written,',
+        '               `passed` and `ticked` carry the two counts. Fewer ticks',
+        '               owe a re-run with every passed box, more ticks owe the',
+        '               operator an untick of a box that has since failed',
         '  body-refused the comment is ticked but gh could not edit the body,',
         '               exit 1 with `commentTicked`. Re-run to retry the body.',
         '  stale-head   --head is not the remote branch tip, nothing written',
@@ -1073,6 +1195,83 @@ export function register(program: Command): void {
       process.exitCode = await runTick(number, opts)
     })
 
+  pr.command('drive-copy')
+    .description(
+      "Copy the folders a running preview saves into, so a UI pass drives a throwaway copy, and check the worker's worktree gained no change",
+    )
+    .argument(
+      '[number]',
+      'Pull request whose worktree to read, defaulting to the checkout at --root',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--baseline',
+      "Rebuild the copy, then record the worktree's git status",
+    )
+    .option(
+      '--check',
+      'Report each path changed since the baseline, copying nothing',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A project names what its preview writes in',
+        '`canon/config/preview.json` as `{ "writes": [path], "env": "<NAME>" }`.',
+        'Each `writes` path is relative to the worktree, and `env`, defaulting',
+        'to `CANON_PREVIEW_ROOT`, is the variable the server reads for the copy',
+        'root. The server resolves each declared path under that root.',
+        '',
+        'The copy lives at `.canon/tmp/pr/review-ui/<slug>/board/` at the main',
+        'worktree root, where `<slug>` is the branch with a leading type',
+        'segment dropped and each `/` made `-`. With a number the branch is the',
+        "pull request's head, and without one it is the checkout's, so the",
+        'worker starting its server before a pull request exists and the',
+        'reviewer naming the number land on one copy. Every run but --check',
+        "rebuilds it from the worktree, dropping the last pass's drives.",
+        '',
+        '--baseline records `git status` for the worktree under',
+        '`.canon/tmp/pr/review-ui/<number>/`, and --check reports each path',
+        'whose status or content changed since, an untracked file included.',
+        'Both run with no config, since a project that saves drives and never',
+        'declared it is the case the check exists for. An edit the worker makes',
+        'during the pass reads as changed too.',
+        '',
+        'Read `reason` on the JSON record:',
+        '  copied     the copy was rebuilt, with `copyRoot`, `env`, `copied`, and',
+        '             `missing` for a declared path the worktree does not hold',
+        '  no-config  the project declares no preview, so nothing was copied',
+        '  clean      --check found no change since the baseline',
+        '  changed    --check found changes, listed in `paths`, exit 1',
+        '',
+        'Refusals, read off `reason`:',
+        '  no-worktree      no local worktree holds the branch, as for a cloud',
+        "                   worker's, so there is no tree to check",
+        '  no-branch        the checkout holds no branch',
+        '  no-baseline      --check ran before any --baseline for this number',
+        '  bad-config       preview.json does not parse or lacks a writes list',
+        '  unsafe-path      a writes path is absolute or climbs with `..`',
+        '  unreadable-tree  git could not read the worktree status',
+        '  bad-flags        --baseline and --check were combined',
+        '  gh-failed, ambiguous-pull, gh-missing',
+        '',
+        'Exit codes:',
+        '  0  copied, no-config, or clean',
+        '  1  changed, or refused, with the reason in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr drive-copy --json',
+        '  canon pr drive-copy 1341 --baseline --json',
+        '  canon pr drive-copy 1341 --check --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: DriveCopyOptions) => {
+      process.exitCode = await runDriveCopy(number, opts)
+    })
+
   pr.command('frames')
     .description(
       `Push a UI review frame to the never-merged ${FRAMES_BRANCH} branch and return its embed link, or drop frames from it`,
@@ -1653,7 +1852,7 @@ async function listReviews(cwd: string, number: string) {
   return listPages<RestReview>(
     cwd,
     `repos/{owner}/{repo}/pulls/${number}/reviews`,
-    'body, commit_id, submitted_at',
+    'id, body, commit_id, submitted_at',
   )
 }
 
@@ -2842,9 +3041,9 @@ async function runLocal(opts: LocalOptions): Promise<number> {
 }
 
 /**
- * Drops the address line on the marked comment. The verb writes here rather
- * than handing a body back, because its caller is a close workflow with no
- * session to post one.
+ * Drops the address line on the marked comment and masks the loopback address
+ * on every UI review. The verb writes here rather than handing a body back,
+ * because its caller is a close workflow with no session to post one.
  */
 async function runLocalRemove(
   number: string | undefined,
@@ -2871,32 +3070,79 @@ async function runLocalRemove(
       root,
     )
   }
-  const comments = await listComments(root, resolved.number)
-  if (comments === undefined) {
+  const [comments, reviews] = await Promise.all([
+    listComments(root, resolved.number),
+    listReviews(root, resolved.number),
+  ])
+  if (comments === undefined && reviews.kind === 'refused') {
     return refuseWith('gh-failed', LOCAL_REFUSALS['gh-failed'], emitJson, root)
   }
 
-  const finish = (reason: string, message: string): number => {
-    logStep(reason === 'removed' ? 'Removed' : 'Skipped')
-    logInfo(message)
-    outro()
-    if (emitJson) {
-      process.stdout.write(`${JSON.stringify({ root, reason })}\n`)
-    }
-    return 0
+  // A refused read on one side still lets the other side's edits land, and
+  // counts as a failure beside them, so one unread listing never strands both.
+  const [evidence, masked] = await Promise.all([
+    comments === undefined
+      ? Promise.resolve<EvidenceRemoval>({ kind: 'failed' })
+      : removeEvidenceAddress(root, comments),
+    reviews.kind === 'refused'
+      ? Promise.resolve({ rewritten: 0, failed: true })
+      : maskUiReviews(root, resolved.number, reviews.rows),
+  ])
+  if (evidence.kind === 'failed' || masked.failed) {
+    return refuseWith(
+      'gh-failed',
+      LOCAL_REFUSALS['gh-failed'],
+      emitJson,
+      root,
+      {
+        reviews: masked.rewritten,
+      },
+    )
   }
 
+  logStep(evidence.reason === 'removed' ? 'Removed' : 'Skipped')
+  logInfo(evidence.message)
+  logInfo(`${masked.rewritten} UI review addresses masked`)
+  outro()
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ root, reason: evidence.reason, reviews: masked.rewritten })}\n`,
+    )
+  }
+  return 0
+}
+
+type EvidenceRemoval =
+  | {
+      readonly kind: 'done'
+      readonly reason: 'removed' | 'no-comment' | 'no-line'
+      readonly message: string
+    }
+  | { readonly kind: 'failed' }
+
+async function removeEvidenceAddress(
+  root: string,
+  comments: readonly { url?: string; body: string }[],
+): Promise<EvidenceRemoval> {
   const commentId = findEvidenceCommentId(comments)
   const marked = comments.find((comment) =>
     comment.url?.endsWith(`#issuecomment-${commentId}`),
   )
   if (commentId === undefined || marked === undefined) {
-    return finish('no-comment', 'No comment carries the evidence marker.')
+    return {
+      kind: 'done',
+      reason: 'no-comment',
+      message: 'No comment carries the evidence marker.',
+    }
   }
 
   const dropped = dropAddressLine(marked.body)
   if (dropped === undefined) {
-    return finish('no-line', 'The evidence comment carries no address line.')
+    return {
+      kind: 'done',
+      reason: 'no-line',
+      message: 'The evidence comment carries no address line.',
+    }
   }
 
   const patched = await gh(root, [
@@ -2907,11 +3153,43 @@ async function runLocalRemove(
     '-f',
     `body=${dropped}`,
   ])
-  if (patched === null) {
-    return refuseWith('gh-failed', LOCAL_REFUSALS['gh-failed'], emitJson, root)
-  }
+  return patched === null
+    ? { kind: 'failed' }
+    : { kind: 'done', reason: 'removed', message: `comment ${commentId}` }
+}
+
+const UI_REVIEW_MARKER = '<!-- review-ui: head='
 
-  return finish('removed', `comment ${commentId}`)
+/**
+ * Masks the loopback address on each review `review-ui` posted, selected by
+ * its marker so a code review quoting a local URL is never edited. Every
+ * update is tried before a refusal is reported, so one refused review leaves
+ * the rest masked.
+ */
+async function maskUiReviews(
+  root: string,
+  number: string,
+  reviews: readonly RestReview[],
+): Promise<{ readonly rewritten: number; readonly failed: boolean }> {
+  const updates = reviews.flatMap((review) => {
+    const body = review.body ?? ''
+    if (review.id === undefined || !body.includes(UI_REVIEW_MARKER)) return []
+    const masked = maskLocalAddress(body)
+    if (masked === undefined) return []
+    return [
+      gh(root, [
+        'api',
+        '-X',
+        'PUT',
+        `repos/{owner}/{repo}/pulls/${number}/reviews/${review.id}`,
+        '-f',
+        `body=${masked}`,
+      ]),
+    ]
+  })
+  const results = await Promise.all(updates)
+  const rewritten = results.filter((stdout) => stdout !== null).length
+  return { rewritten, failed: rewritten < results.length }
 }
 
 const POSITIVE_WHOLE = /^[1-9]\d*$/
@@ -2977,6 +3255,32 @@ async function runTick(
   const result = tickBoxes(marked.body, numbers.map(Number), reading.tip)
   if (result.kind === 'refused') return refuseTick(result.reason)
 
+  // Read ahead of the write so a short list refuses before it leaves the
+  // comment half ticked. A verdict that does not cover the tip, carries no
+  // count line, or cannot be read leaves the check unrun and says so.
+  const ticked = countTicksAtHead(
+    readChecklistBoxes(findEvidenceChecklist([{ body: result.body }]) ?? ''),
+    reading.tip,
+  )
+  const reviews = await listReviews(root, String(identity.number))
+  const verdict = resolveUiScope({
+    reviews: reviews.kind === 'read' ? reviews.rows.map(reviewRowOf) : [],
+  })
+  const isCounted =
+    verdict.counts !== undefined &&
+    verdict.commit !== undefined &&
+    coversHead(verdict.commit, reading.tip)
+  if (isCounted && verdict.counts.passed !== ticked) {
+    return refuseWith(
+      'count-mismatch',
+      TICK_REFUSALS['count-mismatch'],
+      emitJson,
+      root,
+      { passed: verdict.counts.passed, ticked },
+    )
+  }
+  const countCheck = isCounted ? 'matched' : 'unchecked'
+
   if (result.body !== marked.body) {
     const patched = await gh(root, [
       'api',
@@ -2995,14 +3299,7 @@ async function runTick(
   const driven = boxes.filter((box) => !box.isTaste)
   const summary: UiPassSummary = {
     kind: 'passed',
-    // A tick counts as this pass's only when stamped at the tip, since an
-    // unstamped one is the author's claim and an older stamp names another head.
-    passed: driven.filter(
-      (box) =>
-        box.isTicked &&
-        box.stamp !== undefined &&
-        reading.tip.startsWith(box.stamp),
-    ).length,
+    passed: countTicksAtHead(boxes, reading.tip),
     total: driven.length,
     taste: boxes.length - driven.length,
     head: reading.tip,
@@ -3024,6 +3321,7 @@ async function runTick(
           reason: 'body-refused',
           message: TICK_REFUSALS['body-refused'],
           commentTicked: true,
+          countCheck,
           head: reading.tip,
           boxes: numbers.map(Number),
           commentId,
@@ -3044,6 +3342,7 @@ async function runTick(
         root,
         number: identity.number,
         reason: 'ticked',
+        countCheck,
         head: reading.tip,
         boxes: numbers.map(Number),
         commentId,
@@ -3443,6 +3742,8 @@ const LIFT_REFUSALS: Record<LiftRefusal | 'bad-wait' | 'gh-missing', string> = {
     'The newest UI review carries no head marker, so the commit it covers is a GitHub stamp this gate does not trust.',
   'ui-behind':
     'The newest UI review closed on an earlier commit than the head.',
+  'ui-undriven':
+    'The newest UI review closed having driven no box, so it looked at nothing. Re-drive the checklist on an address that answers.',
   'evidence-owed':
     'The evidence check reads owed, so the ship chain left a step undone.',
   'standing-stale':
@@ -3564,6 +3865,34 @@ async function readEvidenceGate(
   }
 }
 
+async function readChecksGate(
+  root: string,
+  number: string,
+  tip: string,
+): Promise<ChecksGate | undefined> {
+  const [listed, pulled] = await Promise.all([
+    gh(root, [
+      'api',
+      `repos/{owner}/{repo}/commits/${tip}/check-runs?per_page=100`,
+    ]),
+    gh(root, ['api', `repos/{owner}/{repo}/pulls/${number}`]),
+  ])
+  if (listed === null) return undefined
+  try {
+    const mergeState =
+      pulled === null
+        ? undefined
+        : mergeStateOf((JSON.parse(pulled) as RestPull).mergeable_state)
+    const reading = withMergeState(
+      mergeState,
+      collapseChecks(tip, JSON.parse(listed) as CheckRunListing),
+    )
+    return { state: reading.state, isConflicted: reading.conflicted }
+  } catch {
+    return undefined
+  }
+}
+
 function liftApi(root: string, number: string, baseRef: string): LiftApi {
   const git = gitRunner(root)
 
@@ -3601,29 +3930,7 @@ function liftApi(root: string, number: string, baseRef: string): LiftApi {
     readEvidence: () => readEvidenceGate(root, number),
     readStanding: (head) =>
       readBaseStanding(git, Number(number), head, baseRef),
-    readChecks: async (tip) => {
-      const [listed, pulled] = await Promise.all([
-        gh(root, [
-          'api',
-          `repos/{owner}/{repo}/commits/${tip}/check-runs?per_page=100`,
-        ]),
-        gh(root, ['api', `repos/{owner}/{repo}/pulls/${number}`]),
-      ])
-      if (listed === null) return undefined
-      try {
-        const mergeState =
-          pulled === null
-            ? undefined
-            : mergeStateOf((JSON.parse(pulled) as RestPull).mergeable_state)
-        const reading = withMergeState(
-          mergeState,
-          collapseChecks(tip, JSON.parse(listed) as CheckRunListing),
-        )
-        return { state: reading.state, isConflicted: reading.conflicted }
-      } catch {
-        return undefined
-      }
-    },
+    readChecks: (tip) => readChecksGate(root, number, tip),
     markReady: (nodeId) =>
       flipDraft(
         root,
@@ -3725,6 +4032,160 @@ async function runLift(
   return record.isOk ? 0 : 1
 }
 
+const MERGE_REFUSALS: Record<MergeRefusal | 'gh-missing', string> = {
+  'gh-missing': PULL_REFUSALS['gh-missing'],
+  'pull-closed': 'The pull request is closed, so there is nothing to merge.',
+  'pull-draft':
+    'The pull request is a draft, so its reviews have not lifted the mark.',
+  'missing-summary':
+    'The body carries no `## Summary` with text under it, so the description has no change to state.',
+  'missing-key-changes':
+    'The body carries no `## Key changes` with text under it, so the description has no change to state.',
+  'ci-failing': 'A check run on the head failed.',
+  'ci-conflicted': 'The branch conflicts with its base.',
+  'ci-pending':
+    'A check run on the head has yet to conclude. Run the verb again once it does.',
+  'head-moved':
+    'The head moved after the read, so GitHub refused rather than merging unread commits.',
+  'not-mergeable': 'GitHub answered that the pull request is not mergeable.',
+  'gh-failed':
+    'A read or the merge was refused, so nothing is reported as merged.',
+}
+
+/**
+ * The REST merge, never `gh pr merge`, which runs on the GraphQL a cloud
+ * session's proxy refuses. gh reports the status only as the `(HTTP <code>)`
+ * tail of its stderr, so 409 and 405 are read off it.
+ */
+async function putSquashMerge(
+  root: string,
+  number: string,
+  request: MergeRequest,
+): Promise<MergeOutcome> {
+  const result = await execa(
+    'gh',
+    [
+      'api',
+      '-X',
+      'PUT',
+      `repos/{owner}/{repo}/pulls/${number}/merge`,
+      '-f',
+      `commit_title=${request.title}`,
+      '-f',
+      `commit_message=${request.description}`,
+      '-f',
+      `sha=${request.sha}`,
+      '-f',
+      'merge_method=squash',
+    ],
+    {
+      cwd: root,
+      reject: false,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    },
+  )
+  if (result.exitCode !== 0) {
+    const status = /\(HTTP (\d{3})\)/.exec(String(result.stderr))?.[1]
+    if (status === '409') return { kind: 'head-moved' }
+    if (status === '405') return { kind: 'not-mergeable' }
+    return { kind: 'failed' }
+  }
+  try {
+    const body = JSON.parse(String(result.stdout)) as {
+      merged?: unknown
+      sha?: unknown
+    }
+    return body.merged === true && typeof body.sha === 'string'
+      ? { kind: 'merged', sha: body.sha }
+      : { kind: 'failed' }
+  } catch {
+    return { kind: 'failed' }
+  }
+}
+
+function mergeApi(root: string, number: string): MergeApi {
+  return {
+    readPull: async () => {
+      const stdout = await gh(root, [
+        'api',
+        `repos/{owner}/{repo}/pulls/${number}`,
+      ])
+      if (stdout === null) return undefined
+      try {
+        const row = JSON.parse(stdout) as RestPull
+        if (row.head?.sha === undefined || typeof row.title !== 'string') {
+          return undefined
+        }
+        return {
+          isOpen: row.state === 'open',
+          isDraft: row.draft === true,
+          title: row.title,
+          body: row.body ?? '',
+          head: row.head.sha,
+        }
+      } catch {
+        return undefined
+      }
+    },
+    readChecks: (head) => readChecksGate(root, number, head),
+    putMerge: (request) => putSquashMerge(root, number, request),
+  }
+}
+
+async function runMerge(
+  number: string | undefined,
+  opts: MergeCommandOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr merge')
+
+  if (Bun.which('gh') === null) {
+    return refuseWith(
+      'gh-missing',
+      MERGE_REFUSALS['gh-missing'],
+      emitJson,
+      root,
+    )
+  }
+
+  const resolved = await resolvePullNumber(root, number)
+  if (resolved.kind === 'refused') {
+    return refuseWith(
+      resolved.reason,
+      PULL_REFUSALS[resolved.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  const record = await merge(mergeApi(root, resolved.number), {
+    number: Number(resolved.number),
+    isDryRun: opts.dryRun ?? false,
+  })
+
+  logStep(record.reason)
+  logInfo(
+    record.reason === 'merged'
+      ? `#${record.number} squash-merged as ${record.sha?.slice(0, 8)}`
+      : record.reason === 'dry-run'
+        ? `#${record.number} would merge with the message below`
+        : MERGE_REFUSALS[record.reason],
+  )
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, ...record })}\n`)
+  } else if (record.reason === 'dry-run') {
+    process.stdout.write(`${record.title}\n\n${record.description}\n`)
+  }
+
+  return record.isOk ? 0 : 1
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command
@@ -3734,18 +4195,211 @@ function refuse(reason: Refusal, emitJson: boolean, root: string): number {
   return refuseWith(reason, REFUSALS[reason], emitJson, root)
 }
 
+/** The scratch folder `review-ui` writes under, at the main worktree root. */
+const REVIEW_UI_SCRATCH = join('.canon', 'tmp', 'pr', 'review-ui')
+
+type DriveTarget =
+  | {
+      readonly kind: 'found'
+      readonly main: string
+      readonly worktree: string
+      readonly branch: string
+      readonly number: string | undefined
+    }
+  | {
+      readonly kind: 'refused'
+      readonly reason: DriveCopyRefusal | PullRefusal
+    }
+
+/**
+ * The worker's worktree and its branch. A named pull request resolves through
+ * its head ref, since a reviewer runs at the main root on the trunk. With no
+ * number the checkout at `root` answers, and a number is looked up only when
+ * the mode needs one, so a worker can build the copy before its pull request
+ * exists.
+ */
+async function resolveDriveTarget(
+  root: string,
+  number: string | undefined,
+  needsNumber: boolean,
+): Promise<DriveTarget> {
+  const worktrees = await listWorktrees(root)
+  const main = worktrees[0]?.path ?? root
+
+  if (number === undefined) {
+    const toplevel = await resolveWorktreeRoot(root)
+    const realPaths = await Promise.all(
+      worktrees.map((candidate) =>
+        realpath(candidate.path).catch(() => candidate.path),
+      ),
+    )
+    const entry = worktrees[realPaths.indexOf(toplevel)]
+    const branch = entry?.branch ?? null
+    if (branch === null) return { kind: 'refused', reason: 'no-branch' }
+    if (!needsNumber) {
+      return { kind: 'found', main, worktree: toplevel, branch, number }
+    }
+    if (Bun.which('gh') === null) {
+      return { kind: 'refused', reason: 'gh-missing' }
+    }
+    const resolved = await resolvePullNumber(root, undefined)
+    if (resolved.kind === 'refused') return resolved
+    return {
+      kind: 'found',
+      main,
+      worktree: toplevel,
+      branch,
+      number: resolved.number,
+    }
+  }
+
+  if (Bun.which('gh') === null) return { kind: 'refused', reason: 'gh-missing' }
+  const read = await readPull(root, number)
+  if (read.kind === 'refused') return read
+  const headRef = read.row.head?.ref
+  if (headRef === undefined || headRef === '') {
+    return { kind: 'refused', reason: 'no-worktree' }
+  }
+  const entry = worktrees.find((candidate) => candidate.branch === headRef)
+  if (entry === undefined) return { kind: 'refused', reason: 'no-worktree' }
+  return {
+    kind: 'found',
+    main,
+    worktree: entry.path,
+    branch: headRef,
+    number,
+  }
+}
+
+async function runDriveCopy(
+  number: string | undefined,
+  opts: DriveCopyOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+  const baseline = opts.baseline ?? false
+  const check = opts.check ?? false
+
+  intro('canon pr drive-copy')
+
+  const refuse = (
+    reason: DriveCopyRefusal | PullRefusal | string,
+    message: string,
+  ) => refuseWith(reason, message, emitJson, root)
+
+  if (baseline && check) {
+    return refuse('bad-flags', DRIVE_COPY_REFUSALS['bad-flags'])
+  }
+
+  const target = await resolveDriveTarget(root, number, baseline || check)
+  if (target.kind === 'refused') {
+    const reason = target.reason
+    return refuse(
+      reason,
+      reason in DRIVE_COPY_REFUSALS
+        ? DRIVE_COPY_REFUSALS[reason as DriveCopyRefusal]
+        : PULL_REFUSALS[reason as PullRefusal],
+    )
+  }
+
+  const scratch = join(target.main, REVIEW_UI_SCRATCH)
+  const baselinePath =
+    target.number === undefined
+      ? undefined
+      : join(scratch, target.number, 'drive-baseline.json')
+  const emit = (record: Record<string, unknown>) => {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ root, worktree: target.worktree, branch: target.branch, ...record })}\n`,
+      )
+    }
+  }
+
+  if (check && baselinePath !== undefined) {
+    let prior: readonly StatusEntry[]
+    try {
+      prior = JSON.parse(await readFile(baselinePath, 'utf8'))
+    } catch {
+      return refuse('no-baseline', DRIVE_COPY_REFUSALS['no-baseline'])
+    }
+    const current = await readWorktreeStatus(target.worktree)
+    if (current === undefined) {
+      return refuse('unreadable-tree', DRIVE_COPY_REFUSALS['unreadable-tree'])
+    }
+    const paths = changedSince(prior, current)
+    if (paths.length === 0) {
+      logStep('Clean')
+      logInfo(`No change in ${target.worktree} since the baseline.`)
+      outro()
+      emit({ reason: 'clean', paths })
+      return 0
+    }
+    logStep('Changed')
+    for (const path of paths) logWarn(path)
+    outro()
+    emit({ reason: 'changed', paths })
+    return 1
+  }
+
+  const config = loadPreviewConfig(target.worktree)
+  if (config.kind === 'refused') return refuse(config.reason, config.detail)
+
+  let copy: Record<string, unknown>
+  if (config.kind === 'absent') {
+    logStep('No config')
+    logInfo('The project declares no preview writes, so nothing was copied.')
+    copy = { reason: 'no-config' }
+  } else {
+    const copyRoot = join(scratch, branchSlug(target.branch), 'board')
+    const { copied, missing } = buildDriveCopy(
+      target.worktree,
+      copyRoot,
+      config.config.writes,
+    )
+    logStep('Copied')
+    logInfo(`${config.config.env}=${copyRoot}`)
+    for (const path of missing) logWarn(`${path} is not in the worktree`)
+    copy = {
+      reason: 'copied',
+      copyRoot,
+      env: config.config.env,
+      copied,
+      missing,
+    }
+  }
+
+  if (baseline && baselinePath !== undefined) {
+    const status = await readWorktreeStatus(target.worktree)
+    if (status === undefined) {
+      return refuse('unreadable-tree', DRIVE_COPY_REFUSALS['unreadable-tree'])
+    }
+    await mkdir(join(baselinePath, '..'), { recursive: true })
+    await writeFile(baselinePath, `${JSON.stringify(status)}\n`)
+    logStep('Baseline')
+    logInfo(`Recorded ${plural(status.length, 'status line')}.`)
+    copy = { ...copy, baseline: baselinePath }
+  }
+
+  outro()
+  emit(copy)
+  return 0
+}
+
 function refuseWith(
   reason: string,
   message: string,
   emitJson: boolean,
   root: string,
+  extra: Record<string, unknown> = {},
 ): number {
   logStep('Refused')
   logWarn(message)
   outro()
 
   if (emitJson) {
-    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+    process.stdout.write(
+      `${JSON.stringify({ root, reason, message, ...extra })}\n`,
+    )
   }
   return 1
 }