@cat-factory/executor-harness 1.60.0 → 1.62.0

package/src/pr-description.ts

@@ -0,0 +1,171 @@
+import { readFile, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { inertInline, inertMarkdown, walkFences } from './host-markdown.js'
+import { redactSecrets } from './redact.js'
+
+// ---------------------------------------------------------------------------
+// The agent-authored pull-request description side channel. A coding agent whose
+// dispatch opens a PR is asked (via the backend-composed system prompt) to end its
+// run by writing a reviewer briefing — the problem, the decisions made, what to
+// look out for — to a sentinel file at the root of the checkout the PR belongs to.
+// The harness reads it after the agent settles, removes it (so it never lands in a
+// commit), and uses it as the PR body in place of the generic dispatch-time text
+// the job body carries. Absent or unusable ⇒ the dispatch-time fallback, unchanged.
+//
+// The briefing is MODEL-AUTHORED text landing verbatim on a host-parsed surface, so
+// it crosses `host-markdown.ts` (auto-link triggers defused, open code fences closed)
+// on the way out — see that module for why a PR body is not an inert string sink.
+//
+// The filename is kept in sync with `PR_DESCRIPTION_FILE` in `@cat-factory/agents`
+// (the executor-harness has no dependency on that package), exactly like the
+// effort-report and follow-ups sentinels.
+// ---------------------------------------------------------------------------
+
+/** The sentinel file the agent writes its PR description to (relative to the checkout root). */
+export const PR_DESCRIPTION_FILE = '.cat-pr-description.md'
+
+/**
+ * Ceiling on the agent-authored body.
+ *
+ * The engine appends its verification report to the SAME body later, and that section carries
+ * its own 50,000-character ceiling (`MAX_SECTION_CHARS` in kernel's `hostMarkdown`). GitHub
+ * rejects a body over 65,536 with a 422, and the report publisher swallows its own failures —
+ * so a briefing budget that does not leave the report room would surface as a report that
+ * silently never publishes. 15,000 + 50,000 stays under the limit with room to join them.
+ */
+const MAX_PR_BODY_CHARS = 15_000
+
+/** Ceiling on an agent-supplied title (GitHub truncates around 256; a title should be short). */
+const MAX_PR_TITLE_CHARS = 160
+
+/** Opens the engine-managed region of a PR body (kept in sync with `kernel/domain/pr-report.ts`). */
+export const PR_REPORT_MARKER_START = '<!-- cat-factory:verification-report:start -->'
+/** Closes the engine-managed region of a PR body. */
+export const PR_REPORT_MARKER_END = '<!-- cat-factory:verification-report:end -->'
+
+/**
+ * A marker inside the agent-authored briefing would make the engine's splice treat part of the
+ * briefing as its own managed region and rewrite it, so any occurrence is stripped up front.
+ * Deliberately laxer than the exact constants above (whitespace-tolerant), so a near-miss the
+ * splice itself would not match cannot survive here either.
+ */
+const MANAGED_SECTION_MARKER = /<!--\s*cat-factory:verification-report:(?:start|end)\s*-->/g
+
+/** An agent-authored PR description: an optional title plus the briefing body. */
+export interface AgentPrDescription {
+  title?: string
+  body?: string
+}
+
+/**
+ * Read + parse + REMOVE the agent's PR-description sentinel from `dir`. Lenient: returns
+ * undefined when the file is absent (the agent wrote none) or carries nothing usable. Never
+ * throws — a bad description must never fail an otherwise-good run; the caller falls back to
+ * the dispatch-time text.
+ *
+ * A SINGLE `# <title>` heading on the first line sets the PR title; everything after it is the
+ * body (see {@link splitTitle} for why a LONE heading is required). The whole text is
+ * secret-scrubbed, an over-budget body is truncated WITH a visible note (a silent cut would
+ * read as the complete briefing), and both halves are made inert for the host.
+ *
+ * On scrubbing: `redactSecrets`'s credential-assignment rule is deliberately eager, so a
+ * briefing sentence like "the token: handling changed" loses its next word. That is the right
+ * trade for a surface this public — the rule is shared with every other redaction path, and
+ * narrowing it so prose reads better would weaken all of them.
+ */
+export async function readPrDescription(dir: string): Promise<AgentPrDescription | undefined> {
+  const path = join(dir, PR_DESCRIPTION_FILE)
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch {
+    return undefined // no description written — the fallback body applies
+  }
+  // Remove it so it never lands in a commit (defence in depth; the checkout also excludes it).
+  await rm(path, { force: true }).catch(() => {})
+  const text = redactSecrets(raw).replace(MANAGED_SECTION_MARKER, '').trim()
+  if (!text) return undefined
+
+  const split = splitTitle(text)
+  // Cap BEFORE the escapes on both halves, so a numeric entity can never be sliced in half.
+  const title = split.title ? inertInline(capTitle(split.title)) : undefined
+  const body = split.body ? inertMarkdown(capBody(split.body)) : undefined
+  if (!title && !body) return undefined
+  return { ...(title ? { title } : {}), ...(body ? { body } : {}) }
+}
+
+/**
+ * Split a leading `# <title>` heading off the briefing.
+ *
+ * The heading becomes the title ONLY when it is the single level-1 heading in the whole file,
+ * which is exactly what the prompt asks for ("a single `# <title>` heading line"). An agent
+ * that instead uses `#` for its section headings — `# Problem`, `# Decisions`, entirely
+ * idiomatic for the briefing the prompt describes — would otherwise have its first section
+ * silently become the pull request's title, replacing `<block> (<pipeline>)` with the word
+ * "Problem". Headings inside fenced code are not headings and are skipped, or a briefing
+ * quoting a shell snippet (`# rebuild the image`) would lose its title to the snippet.
+ */
+function splitTitle(text: string): { title?: string; body: string } {
+  const lines = text.split('\n')
+  const headings: number[] = []
+  let index = 0
+  walkFences(lines, (line, insideFence) => {
+    if (!insideFence && /^#\s+\S/.test(line)) headings.push(index)
+    index += 1
+  })
+  if (headings.length !== 1 || headings[0] !== 0) return { body: text }
+  const title = lines[0]!.replace(/^#\s+/, '').trim()
+  if (!title) return { body: text }
+  return { title, body: lines.slice(1).join('\n').trim() }
+}
+
+/** Cut an over-long title at a word boundary when one is near, marking the cut. */
+function capTitle(value: string): string {
+  const collapsed = value.trim()
+  if (collapsed.length <= MAX_PR_TITLE_CHARS) return collapsed
+  const head = collapsed.slice(0, MAX_PR_TITLE_CHARS - 1)
+  const space = head.lastIndexOf(' ')
+  const kept = space > MAX_PR_TITLE_CHARS * 0.6 ? head.slice(0, space) : head
+  return `${kept.trimEnd()}…`
+}
+
+/** Cut an over-budget body, marking the cut so it is never read as the whole briefing. */
+function capBody(value: string): string {
+  if (value.length <= MAX_PR_BODY_CHARS) return value
+  return (
+    value.slice(0, MAX_PR_BODY_CHARS).trimEnd() +
+    '\n\n_Truncated by the platform: the description exceeded the size budget._'
+  )
+}
+
+/**
+ * Fold an agent-authored description over the dispatch-time fallback the job body carries.
+ * Field-wise: the agent's title/body each win when present, so a body-only briefing keeps the
+ * backend-composed title and vice versa.
+ */
+export function applyPrDescription(
+  fallback: { title: string; body: string },
+  agent: AgentPrDescription | undefined,
+): { title: string; body: string } {
+  if (!agent) return fallback
+  return { title: agent.title ?? fallback.title, body: agent.body ?? fallback.body }
+}
+
+/**
+ * The body to PATCH onto an ALREADY-OPEN pull request when a resumed run produced a fresh
+ * briefing: the new description followed by whatever the engine's managed verification-report
+ * region currently holds.
+ *
+ * Carrying the region across is what makes the refresh safe. The engine re-publishes the report
+ * on every step settlement, so dropping it here would usually self-heal — but "usually" is not
+ * a property to rest the one artefact a reviewer reads on, and a run that settles no further
+ * step (the work is already merged, the run failed after its push) would never restore it.
+ */
+export function preserveManagedSection(currentBody: string | undefined, nextBody: string): string {
+  const existing = currentBody ?? ''
+  const start = existing.indexOf(PR_REPORT_MARKER_START)
+  const end = existing.indexOf(PR_REPORT_MARKER_END)
+  if (start === -1 || end <= start) return nextBody
+  const region = existing.slice(start, end + PR_REPORT_MARKER_END.length)
+  return `${nextBody.trim()}\n\n${region}\n`
+}

package/src/vcs-api.ts

@@ -0,0 +1,512 @@
+// ---------------------------------------------------------------------------
+// The VCS HOST REST surface: opening a pull request / merge request, finding the one that is
+// already open, and refreshing its title + description.
+//
+// Split out of `git.ts`, which is otherwise entirely the git CLI. The seam is real rather than
+// arithmetic: nothing here shells out to git, nothing in `git.ts` speaks HTTP, and the two
+// halves fail in completely different ways (a rejected credential and a 403 from an App
+// permission want different remedies). `test/git-pr.test.ts` already covered exactly this
+// surface before it had a file of its own.
+//
+// Provider-agnostic by construction: GitHub and GitLab each get their own request shapes behind
+// one `openPullRequest` entry point, and every capability added to one is added to the other.
+// ---------------------------------------------------------------------------
+
+import type { PrSpec } from './job.js'
+import { HarnessFailure } from './failure.js'
+import { preserveManagedSection } from './pr-description.js'
+import { redactSecrets } from './redact.js'
+
+/**
+ * Classify a PR/MR-open REST failure by its HTTP status into an actionable remedy, else
+ * undefined (an unmapped status keeps just the raw `Failed to open … (HTTP n)` line). Like
+ * {@link describeGitFailure} this only APPENDS a cause + fix — the raw status line is
+ * load-bearing detail and stays. `provider` tailors the scope/permission wording (GitHub App
+ * Pull-requests permission / `repo` PAT scope vs GitLab `api` scope) and the noun (pull
+ * request vs merge request). Pure, so it is unit-tested per status.
+ */
+export function describePrOpenFailure(
+  status: number,
+  provider: 'github' | 'gitlab',
+): string | undefined {
+  const noun = provider === 'gitlab' ? 'merge request' : 'pull request'
+  if (status === 401) {
+    return (
+      `The credential was rejected while opening the ${noun}. The GitHub App installation token ` +
+      '(or, in local mode, the GITHUB_PAT) is most likely expired, rotated, or revoked — reconnect ' +
+      'the GitHub App for the workspace (or regenerate the PAT), then retry.'
+    )
+  }
+  if (status === 403) {
+    const scope =
+      provider === 'gitlab'
+        ? 'the GitLab token needs the `api` scope and Developer+ access to the project'
+        : 'the GitHub App needs the "Pull requests: write" permission (or the PAT the `repo` scope) and write access to the repository'
+    return `The credential lacks permission to open a ${noun}: ${scope}. Grant it, then retry.`
+  }
+  if (status === 404) {
+    return (
+      `The repository could not be found while opening the ${noun} — it may have been deleted, ` +
+      'renamed, or made private, or the credential can no longer see it. Confirm the repo and the ' +
+      "credential's access to it, then retry."
+    )
+  }
+  if (status === 422 || status === 400) {
+    return (
+      `GitHub/GitLab rejected the ${noun} as invalid. Usually the head or base branch does not ` +
+      'exist, the two branches are identical (nothing to compare), or the base branch is protected ' +
+      'against direct PRs. Check the branch names and that the head has commits ahead of the base, ' +
+      'then retry.'
+    )
+  }
+  return undefined
+}
+export interface OpenPullRequestOptions {
+  owner: string
+  name: string
+  ghToken: string
+  head: string
+  base: string
+  pr: PrSpec
+  apiBase?: string
+  /**
+   * The repo's clone URL. Used (when {@link provider} is absent) to detect the provider and,
+   * for GitLab, to derive the REST base + project path from its host — so the harness opens a
+   * GitLab **merge request** rather than POSTing to GitHub's pulls API. Absent ⇒ GitHub.
+   */
+  cloneUrl?: string
+  /**
+   * The VCS provider, when the dispatcher knows it (the server derives it from the configured
+   * source-control backend and sets `repo.provider`). AUTHORITATIVE — it overrides host
+   * inference — so a self-managed GitLab on an arbitrarily-named host (e.g. `git.acme.com`,
+   * which {@link inferVcsProvider} can't recognise) still opens a merge request instead of
+   * being misrouted to GitHub's API. Absent ⇒ inferred from {@link cloneUrl}'s host.
+   */
+  provider?: 'github' | 'gitlab'
+  /**
+   * When the PR/MR for {@link head} ALREADY exists (a resumed run pushing onto a branch whose PR
+   * is open), replace its title and description with {@link pr} instead of leaving them alone.
+   *
+   * Set ONLY when {@link pr} carries the agent's own reviewer briefing. A resumed run is exactly
+   * the case that matters — eviction + re-dispatch, a ralph iteration, a retry — and without this
+   * the agent writes a briefing the platform reads, scrubs, caps and then silently drops. It must
+   * stay opt-in, though: refreshing from the GENERIC dispatch-time fallback would overwrite a
+   * description a human (or an earlier, better-informed run) had already written.
+   *
+   * The engine's managed verification-report region is carried across the rewrite by
+   * {@link preserveManagedSection}, and the update is best-effort — a failed refresh keeps the
+   * run's real outcome, which is the pushed work.
+   */
+  refreshExisting?: boolean
+  signal?: AbortSignal
+}
+
+/**
+ * The VCS host a clone URL points at. The harness is otherwise provider-agnostic (its git
+ * auth is a host-neutral GIT_ASKPASS credential), but the "open the PR/MR" REST call is not:
+ * GitHub and GitLab have different endpoints, so infer which to call from the host. GitHub is
+ * the default; a host of `gitlab.com` or one in the `gitlab.*` / `*.gitlab.*` family (covering
+ * self-managed instances named that way) is treated as GitLab.
+ */
+export function inferVcsProvider(cloneUrl: string): 'github' | 'gitlab' {
+  let host = ''
+  try {
+    host = new URL(cloneUrl).host.toLowerCase()
+  } catch {
+    return 'github'
+  }
+  if (host === 'gitlab.com' || host.startsWith('gitlab.') || host.includes('.gitlab.')) {
+    return 'gitlab'
+  }
+  return 'github'
+}
+
+/** The GitLab REST v4 base for a clone URL's host, e.g. `https://gitlab.com/api/v4`. */
+export function gitlabApiBaseFromCloneUrl(cloneUrl: string): string {
+  const u = new URL(cloneUrl)
+  return `${u.protocol}//${u.host}/api/v4`
+}
+
+/**
+ * The URL-encoded GitLab project path from a clone URL — the full namespace path (so subgroups
+ * survive), with the trailing `.git` stripped, e.g.
+ * `https://gitlab.com/group/sub/proj.git` → `group%2Fsub%2Fproj`.
+ */
+export function gitlabProjectPath(cloneUrl: string): string {
+  const path = new URL(cloneUrl).pathname.replace(/^\/+/, '').replace(/\.git$/, '')
+  return encodeURIComponent(path)
+}
+
+/** The abort reason as an Error (the watchdog aborts with one), or a generic fallback. */
+function abortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error ? signal.reason : new Error('aborted')
+}
+
+/** Whether a thrown fetch error is an AbortError (caller-initiated, never retried). */
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === 'AbortError'
+}
+
+/**
+ * Parse a `Retry-After` header into ms, bounded so it can't stall the job. Accepts BOTH
+ * forms the spec allows: integer delay-seconds (`120`) and an HTTP-date (`Wed, 21 Oct 2026
+ * 07:28:00 GMT`); the latter is turned into a delay from now. A past/zero/unparseable value
+ * yields undefined so the caller falls back to exponential backoff.
+ */
+function retryAfterMs(res: Response): number | undefined {
+  const raw = res.headers.get('retry-after')
+  if (!raw) return undefined
+  const secs = Number(raw)
+  if (Number.isFinite(secs)) {
+    return secs > 0 ? Math.min(secs * 1000, MAX_RETRY_AFTER_MS) : undefined
+  }
+  const at = Date.parse(raw)
+  if (Number.isNaN(at)) return undefined
+  const ms = at - Date.now()
+  return ms > 0 ? Math.min(ms, MAX_RETRY_AFTER_MS) : undefined
+}
+
+/** Sleep `ms`, rejecting immediately (with the abort reason) if `signal` aborts meanwhile. */
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(abortError(signal))
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      reject(abortError(signal as AbortSignal))
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+const MAX_RETRY_AFTER_MS = 8_000
+const RETRY_BASE_MS = 500
+const RETRY_MAX_DELAY_MS = 4_000
+
+/**
+ * Run a single HTTP request with bounded retry for TRANSIENT failures, so a momentary
+ * upstream blip (a 5xx, a 429 rate-limit, or a dropped connection) no longer fails an
+ * otherwise-complete run on its very last step (opening the PR/MR). Up to 3 attempts
+ * (2 retries) with exponential backoff + jitter (honoring a `Retry-After` on a 429),
+ * every wait abort-aware so the inactivity/max-duration watchdog still cancels promptly.
+ *
+ * ONLY transient failures retry: a `>=500`/`429` response, or a network-level fetch
+ * rejection. A 4xx (incl. the 422/409 "already exists" the callers treat as success) is
+ * returned to the caller unretried, and a caller abort is rethrown at once. The response
+ * body is never read here, so the caller's existing status handling is unchanged.
+ */
+async function withApiRetry(
+  fn: () => Promise<Response>,
+  opts: { signal?: AbortSignal; attempts?: number } = {},
+): Promise<Response> {
+  const maxAttempts = opts.attempts ?? 3
+  let lastError: unknown
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (opts.signal?.aborted) throw abortError(opts.signal)
+    let res: Response | undefined
+    try {
+      res = await fn()
+    } catch (err) {
+      // A caller/watchdog abort is terminal; a network error is transient → retry.
+      if (isAbortError(err) || opts.signal?.aborted) throw err
+      lastError = err
+    }
+    if (res) {
+      const transient = res.status >= 500 || res.status === 429
+      if (!transient || attempt >= maxAttempts) return res
+      const after = retryAfterMs(res)
+      // Discard the unread body before retrying so the connection can be reused.
+      await res.body?.cancel().catch(() => {})
+      await abortableDelay(after ?? backoffMs(attempt), opts.signal)
+      continue
+    }
+    if (attempt >= maxAttempts) break
+    await abortableDelay(backoffMs(attempt), opts.signal)
+  }
+  // Exhausted on a network-level rejection (no HTTP response): an upstream API failure.
+  const message =
+    lastError instanceof Error ? lastError.message : 'API request failed after retries'
+  throw new HarnessFailure('api', redactSecrets(message))
+}
+
+/** Exponential backoff (base 500ms, capped 4s) with up to 25% positive jitter. */
+function backoffMs(attempt: number): number {
+  const base = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_MS * 2 ** (attempt - 1))
+  return base + Math.floor(base * 0.25 * Math.random())
+}
+
+/**
+ * Open a PR (GitHub) or merge request (GitLab) for the pushed branch; returns its web URL.
+ * The provider is chosen from the EXPLICIT `opts.provider` when the dispatcher set it,
+ * falling back to host inference from the clone URL only when it didn't — so a self-managed
+ * GitLab whose host isn't named `gitlab.*` still opens an MR instead of being misrouted to
+ * GitHub's API. The GitHub path is unchanged.
+ */
+export async function openPullRequest(opts: OpenPullRequestOptions): Promise<string | null> {
+  const provider = opts.provider ?? (opts.cloneUrl ? inferVcsProvider(opts.cloneUrl) : 'github')
+  if (provider === 'gitlab') {
+    if (!opts.cloneUrl) {
+      throw new Error('Cannot open a GitLab merge request without the repo clone URL')
+    }
+    return openGitLabMergeRequest({ ...opts, cloneUrl: opts.cloneUrl })
+  }
+  const apiBase = opts.apiBase ?? 'https://api.github.com'
+  const path = `${encodeURIComponent(opts.owner)}/${encodeURIComponent(opts.name)}`
+  const res = await withApiRetry(
+    () =>
+      fetch(`${apiBase}/repos/${path}/pulls`, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${opts.ghToken}`,
+          accept: 'application/vnd.github+json',
+          'user-agent': 'cat-factory-executor',
+          'x-github-api-version': '2022-11-28',
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+          title: opts.pr.title,
+          head: opts.head,
+          base: opts.base,
+          body: opts.pr.body,
+        }),
+        // Bound on the watchdog so a hung GitHub call can't stall the job.
+        ...(opts.signal ? { signal: opts.signal } : {}),
+      }),
+    { signal: opts.signal },
+  )
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '')
+    // A resumed run pushes to a branch that already has an open PR; GitHub answers
+    // 422 "A pull request already exists". That's success for us — return the
+    // existing PR's url rather than failing the resumed run.
+    if (res.status === 422 && /pull request already exists/i.test(detail)) {
+      const existing = await findOpenPullRequest(opts)
+      if (existing) {
+        if (opts.refreshExisting) await refreshPullRequest(opts, existing)
+        return existing.url
+      }
+    }
+    // The head branch has nothing ahead of base ("No commits between <base> and <head>").
+    // That is not an API failure — there is simply nothing to open a PR for (e.g. a resumed
+    // branch whose earlier PR was merged with a merge commit, leaving the branch reachable
+    // from base). Signal it with null so the caller records a clean no-op instead of failing
+    // the run with GitHub's opaque 422.
+    if (res.status === 422 && /no commits between/i.test(detail)) return null
+    const remedy = describePrOpenFailure(res.status, 'github')
+    const base = redactSecrets(`Failed to open PR (HTTP ${res.status}): ${detail.slice(0, 300)}`)
+    throw new HarnessFailure('api', remedy ? `${base}\n${remedy}` : base)
+  }
+  const body = (await res.json()) as { html_url?: string }
+  if (!body.html_url) throw new HarnessFailure('api', 'GitHub did not return a PR url')
+  return body.html_url
+}
+
+/** GitLab API headers for the PAT (the `PRIVATE-TOKEN` auth GitLab uses). */
+function gitlabHeaders(token: string): Record<string, string> {
+  return {
+    'private-token': token,
+    accept: 'application/json',
+    'user-agent': 'cat-factory-executor',
+    'content-type': 'application/json',
+  }
+}
+
+/**
+ * Open a GitLab merge request (the analogue of {@link openPullRequest} for GitLab). The REST
+ * base + project path are derived from the clone URL's host, so it works for gitlab.com and a
+ * self-managed instance alike. `head`→`source_branch`, `base`→`target_branch`. On a duplicate
+ * (a resumed run whose branch already has an open MR — GitLab answers 409) the existing MR's
+ * web URL is returned instead of failing the run, mirroring the GitHub 422 handling.
+ */
+async function openGitLabMergeRequest(
+  opts: OpenPullRequestOptions & { cloneUrl: string },
+): Promise<string> {
+  const apiBase = gitlabApiBaseFromCloneUrl(opts.cloneUrl)
+  const project = gitlabProjectPath(opts.cloneUrl)
+  const res = await withApiRetry(
+    () =>
+      fetch(`${apiBase}/projects/${project}/merge_requests`, {
+        method: 'POST',
+        headers: gitlabHeaders(opts.ghToken),
+        body: JSON.stringify({
+          source_branch: opts.head,
+          target_branch: opts.base,
+          title: opts.pr.title,
+          description: opts.pr.body,
+        }),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+      }),
+    { signal: opts.signal },
+  )
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '')
+    // GitLab returns 409 (sometimes 400) when an open MR already exists for this source
+    // branch; that is success for a resumed run — return the existing MR's url.
+    if (
+      (res.status === 409 || res.status === 400) &&
+      /already exists|open merge request/i.test(detail)
+    ) {
+      const existing = await findOpenMergeRequest(apiBase, project, opts)
+      if (existing) {
+        if (opts.refreshExisting) await refreshMergeRequest(apiBase, project, opts, existing)
+        return existing.url
+      }
+    }
+    const remedy = describePrOpenFailure(res.status, 'gitlab')
+    const base = redactSecrets(
+      `Failed to open merge request (HTTP ${res.status}): ${detail.slice(0, 300)}`,
+    )
+    throw new HarnessFailure('api', remedy ? `${base}\n${remedy}` : base)
+  }
+  const body = (await res.json()) as { web_url?: string }
+  if (!body.web_url) throw new HarnessFailure('api', 'GitLab did not return a merge request url')
+  return body.web_url
+}
+
+/**
+ * Rewrite an already-open MR's title and description — the GitLab half of
+ * {@link refreshPullRequest}, so a resumed run's agent briefing reaches both hosts alike.
+ * Best-effort for the same reason.
+ */
+async function refreshMergeRequest(
+  apiBase: string,
+  project: string,
+  opts: OpenPullRequestOptions,
+  existing: ExistingPullRequest,
+): Promise<void> {
+  if (existing.number === undefined) return
+  await fetch(`${apiBase}/projects/${project}/merge_requests/${existing.number}`, {
+    method: 'PUT',
+    headers: gitlabHeaders(opts.ghToken),
+    body: JSON.stringify({
+      title: opts.pr.title,
+      description: preserveManagedSection(existing.body, opts.pr.body),
+    }),
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  }).catch(() => undefined)
+}
+
+/** Find the open GitLab MR for `opts.head`→`opts.base`, or undefined when there is none. */
+async function findOpenMergeRequest(
+  apiBase: string,
+  project: string,
+  opts: { head: string; base: string; ghToken: string; signal?: AbortSignal },
+): Promise<ExistingPullRequest | undefined> {
+  // Filter by BOTH branches: a source branch can have open MRs to several targets, so the
+  // source alone could match an MR against a different base than the one we just tried to open.
+  const query = new URLSearchParams({
+    source_branch: opts.head,
+    target_branch: opts.base,
+    state: 'opened',
+  })
+  const res = await fetch(`${apiBase}/projects/${project}/merge_requests?${query}`, {
+    headers: gitlabHeaders(opts.ghToken),
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  })
+  if (!res.ok) return undefined
+  const list = (await res.json().catch(() => [])) as Array<{
+    web_url?: string
+    iid?: number
+    description?: string | null
+  }>
+  const found = Array.isArray(list) ? list[0] : undefined
+  if (!found?.web_url) return undefined
+  return {
+    url: found.web_url,
+    // `iid` (project-scoped) is what the update endpoint addresses, not the global `id`.
+    ...(typeof found.iid === 'number' ? { number: found.iid } : {}),
+    body: found.description ?? undefined,
+  }
+}
+
+/**
+ * An already-open PR: enough to return it as the run's PR and, when the host told us its
+ * number, to rewrite its description.
+ *
+ * `number` is OPTIONAL on purpose. Returning the existing PR's url is what keeps a resumed run
+ * from failing, and that must not become contingent on a second field parsing: a response we
+ * can read a url but not a number out of degrades to "found it, can't refresh it", never to a
+ * failed run.
+ */
+interface ExistingPullRequest {
+  url: string
+  number?: number
+  body: string | undefined
+}
+
+/**
+ * Rewrite an already-open PR's title and description from `opts.pr` (a resumed run whose agent
+ * wrote a fresh reviewer briefing — see {@link OpenPullRequestOptions.refreshExisting}).
+ *
+ * Best-effort by construction: the work is already pushed and the PR already exists, so a failed
+ * refresh must degrade to the stale description rather than fail the run.
+ */
+async function refreshPullRequest(
+  opts: OpenPullRequestOptions,
+  existing: ExistingPullRequest,
+): Promise<void> {
+  if (existing.number === undefined) return
+  const apiBase = opts.apiBase ?? 'https://api.github.com'
+  const path = `${encodeURIComponent(opts.owner)}/${encodeURIComponent(opts.name)}`
+  await fetch(`${apiBase}/repos/${path}/pulls/${existing.number}`, {
+    method: 'PATCH',
+    headers: {
+      authorization: `Bearer ${opts.ghToken}`,
+      accept: 'application/vnd.github+json',
+      'user-agent': 'cat-factory-executor',
+      'x-github-api-version': '2022-11-28',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      title: opts.pr.title,
+      body: preserveManagedSection(existing.body, opts.pr.body),
+    }),
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  }).catch(() => undefined)
+}
+
+/** Find the open PR for `opts.head` on `opts.base`, or undefined when there is none. */
+async function findOpenPullRequest(opts: {
+  owner: string
+  name: string
+  ghToken: string
+  head: string
+  base: string
+  apiBase?: string
+  signal?: AbortSignal
+}): Promise<ExistingPullRequest | undefined> {
+  const apiBase = opts.apiBase ?? 'https://api.github.com'
+  // Encode the ref-derived query params: a branch/owner containing `&` or `#` would
+  // otherwise split the query string or inject an unintended parameter.
+  const query = new URLSearchParams({
+    head: `${opts.owner}:${opts.head}`,
+    base: opts.base,
+    state: 'open',
+  })
+  const path = `${encodeURIComponent(opts.owner)}/${encodeURIComponent(opts.name)}`
+  const res = await fetch(`${apiBase}/repos/${path}/pulls?${query}`, {
+    headers: {
+      authorization: `Bearer ${opts.ghToken}`,
+      accept: 'application/vnd.github+json',
+      'user-agent': 'cat-factory-executor',
+      'x-github-api-version': '2022-11-28',
+    },
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  })
+  if (!res.ok) return undefined
+  const list = (await res.json().catch(() => [])) as Array<{
+    html_url?: string
+    number?: number
+    body?: string | null
+  }>
+  const found = Array.isArray(list) ? list[0] : undefined
+  if (!found?.html_url) return undefined
+  return {
+    url: found.html_url,
+    ...(typeof found.number === 'number' ? { number: found.number } : {}),
+    body: found.body ?? undefined,
+  }
+}