code-foundry 0.34.4 → 0.34.6

package/.github/code-foundry.yml

@@ -11,7 +11,7 @@ dependency_review: auto
 package_manager: bun
 toolchain: auto
 runtime_repository: 0xPlayerOne/code-foundry
-runtime_ref: v0.32.3
+runtime_ref: v0.34.4
 release_type: node
 npm_publish: true
 license: agpl-3.0-or-later

package/.github/workflows/opencode-security_self-ci.yml

@@ -41,7 +41,9 @@ jobs:
     if: needs.detect.outputs.enabled == 'true' && needs.detect.outputs.token == 'true'
     uses: 0xPlayerOne/opencode-security/.github/workflows/opencode-security.yml@b3dce823322672b285fbe99b870ea984c01826cb # main
     with:
-      source_ref: ${{ github.event.pull_request.head.ref || 'main' }}
+      # This is the scanner checkout ref, not the consumer PR ref. The
+      # reusable workflow already checks out the consumer repository.
+      source_ref: b3dce823322672b285fbe99b870ea984c01826cb
       runner: ubuntu-latest
       mode: standard
       fail_on_severity: high

package/.github/workflows/release.yml

@@ -44,7 +44,7 @@ env:
 
 jobs:
   release:
-    name: Release / Version
+    name: Version
     runs-on: ${{ inputs.runner }}
     timeout-minutes: 20
     concurrency:
@@ -284,7 +284,7 @@ jobs:
           done
 
   reconcile:
-    name: Release / Reconcile
+    name: Reconcile
     needs: release
     # A normal promotion push can successfully run Release Please without
     # creating a release. Reconciliation is only meaningful after a release
@@ -376,7 +376,7 @@ jobs:
         run: echo 'No staging branch exists; release reconciliation is not applicable.'
 
   post-release:
-    name: Release / Post Hook
+    name: Post Hook
     needs: release
     if: needs.release.outputs.release_created == 'true'
     runs-on: ${{ inputs.runner }}
@@ -432,7 +432,7 @@ jobs:
         run: echo 'No post-release workflow configured; artifact delivery is intentionally skipped.'
 
   npm:
-    name: Release / Publish npm
+    name: Publish npm
     needs: release
     if: needs.release.outputs.release_created == 'true' && needs.release.outputs.npm_publish == 'true'
     runs-on: ${{ inputs.runner }}

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.34.6](https://github.com/0xPlayerOne/code-foundry/compare/v0.34.5...v0.34.6) (2026-08-02)
+
+
+### Bug Fixes
+
+* **sync:** keep prettier ignores idempotent ([5db5307](https://github.com/0xPlayerOne/code-foundry/commit/5db53072fded27a57cca3cedf7c40527cd238507))
+
+## [0.34.5](https://github.com/0xPlayerOne/code-foundry/compare/v0.34.4...v0.34.5) (2026-08-02)
+
+
+### Bug Fixes
+
+* **release:** reconcile protected staging branches ([fa18bfb](https://github.com/0xPlayerOne/code-foundry/commit/fa18bfbb90aaed5c78ff70dbb3dc17d5633e7e5f))
+
 ## [0.34.4](https://github.com/0xPlayerOne/code-foundry/compare/v0.34.3...v0.34.4) (2026-08-02)
 
 

package/docs/WORKFLOWS.md

@@ -79,6 +79,16 @@ after the step.
 When absent, the job keeps `GH_TOKEN = github.token` and runs `gh auth setup-git`
 so repositories without a Deploy Key ruleset bypass still reconcile successfully.
 
+When the protected `staging` branch rejects the exact-lease reconcile push with
+a branch-policy/ruleset/required-PR error, the reconcile job does not fail:
+it opens (or reuses) a generated `code-foundry/reconcile/main-to-staging`
+pull request whose head contains the exact target tip (the `main` tip for a
+fast-forward, the replay tip when staging-only commits are replayed) and whose
+body documents the reconciliation. Reruns reuse the open pull request instead
+of duplicating it; unexpected code divergence, replay conflicts, authentication
+errors, and ambiguous or stale pull request state still fail the job closed,
+and exact-lease protection stays in place for every direct push.
+
 For this reconciliation path, maintainer PATs and administrator roles are not
 authorized bypasses; the job deliberately authenticates with `github.token`,
 not `CODE_FOUNDRY_TOKEN` or `RELEASE_PLEASE_TOKEN`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "0.34.4",
+  "version": "0.34.6",
   "description": "A fast, language-aware repository factory for agent-ready workflows, testing, security, and release automation.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/src/commands/release.mjs

@@ -4,7 +4,7 @@ import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { approvedReleaseFiles, buildReleaseRecoveryPlan, classifyReconciliation, readReleaseConfig, selectGeneratedReleasePrs, validateReleasePullRequests } from '../lib/release-policy.mjs'
+import { approvedReleaseFiles, buildReleaseRecoveryPlan, buildReconciliationPullRequestBody, classifyReconciliation, readReleaseConfig, reconciliationPullRequestBranch, reconciliationPullRequestTitle, selectGeneratedReleasePrs, selectReconciliationPullRequest, validateReleasePullRequests } from '../lib/release-policy.mjs'
 import { hasDeliveredHook, releaseDeliveryKey, selectHookDelivery } from '../lib/release-hook.mjs'
 
 /** @typedef {{ target: string, dryRun: boolean, github: boolean, base: string, head: string }} ReleaseOptions */
@@ -14,7 +14,10 @@ import { hasDeliveredHook, releaseDeliveryKey, selectHookDelivery } from '../lib
  *
  * Local mode is deterministic and suitable for CI; --github uses strict
  * lease-based mirror retries with fresh refetch/reclassification and fails
- * closed if classification or remote mutation fails.
+ * closed if classification or remote mutation fails. When the protected
+ * staging branch rejects the exact lease push with a branch-policy/ruleset/
+ * required-PR error, the mutation is delivered through an idempotent
+ * automated synchronization pull request instead of failing the job.
  * @param {string} root
  * @param {ReleaseOptions} options
  */
@@ -38,14 +41,14 @@ export function reconcileRelease(root, options) {
     state = resolveReconciliationState(target, base, head, allowed, true)
     if (state.plan.action === 'fail') throw new Error(formatReconciliationFailure(state.plan))
     if (state.plan.action === 'aligned' && state.mainSha === state.stagingSha) return state.plan
-    const mutation = executeReconciliationMutation(target, head, state)
-    if (mutation.success) return { ...state.plan, ...mutation.result }
-    if (!mutation.retry) throw new Error(mutation.error)
+    const mutation = executeReconciliationMutation(target, base, head, state)
+    if (mutation.success === true) return { ...state.plan, ...(mutation.result ?? {}) }
+    if (mutation.retry !== true) throw new Error(mutation.error ?? `${head} reconciliation failed.`)
     const remoteSha = remoteRefSha(target, head)
     if (remoteSha === state.stagingSha) {
       throw new Error(`${head} synchronization was rejected by an exact lease while remote ${head} tip remained ${state.stagingSha}. ` +
         'Update branch protection or remote policy to permit this mutation, then retry. ' +
-        `Last failure detail: ${mutation.error}`)
+        `Last failure detail: ${mutation.error ?? 'unknown synchronization failure'}`)
     }
   }
   throw new Error(`Reconciliation of ${head} was retried but failed while the branch moved concurrently.`)
@@ -128,10 +131,10 @@ function refreshRemoteRefs(target, base, head) {
   if (result.status !== 0) throw new Error(`Failed to refresh origin/${base} and origin/${head} before reconciliation.`)
 }
 
-/** @param {string} target @param {string} branch */
+/** @param {string} target @param {string} branch @returns {string | null} */
 function remoteRefSha(target, branch) {
   const result = spawnSync('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], { cwd: target, encoding: 'utf8' })
-  if (result.status !== 0) return ''
+  if (result.status !== 0) return null
   const [sha] = result.stdout.trim().split(/\t/, 1)
   return sha || ''
 }
@@ -139,6 +142,7 @@ function remoteRefSha(target, branch) {
 /**
  * Reconcile a single attempt from fresh state.
  * @param {string} target
+ * @param {string} base
  * @param {string} head
  * @param {{
  *  plan: ReturnType<typeof classifyReconciliation>,
@@ -147,8 +151,9 @@ function remoteRefSha(target, branch) {
  *  mainOnlyCommits: Array<{ sha: string, changedPaths: string[] }>,
  *  stagingOnlyCommits: Array<{ sha: string, changedPaths: string[] }>,
  * }} state
+ * @returns {{ success: false, retry: boolean, error: string } | { success: true, result: ReconciliationMutationResult }}
  */
-function executeReconciliationMutation(target, head, state) {
+function executeReconciliationMutation(target, base, head, state) {
   if (!state.plan.targetSha) return { success: false, retry: false, error: `No target SHA for ${head} reconciliation.` }
   if (state.plan.action === 'rebase-staging') {
     let replaySha
@@ -173,11 +178,7 @@ function executeReconciliationMutation(target, head, state) {
       }
     }
     if (classification.category === 'policy') {
-      return {
-        success: false,
-        retry: false,
-        error: `${head} reconciliation was blocked by branch policy: ${classification.message}`,
-      }
+      return deliverReconciliationPullRequest(target, base, head, state, replaySha, { synchronization: 'replay', replaySha }, classification.message)
     }
     return { success: false, retry: true, error: `${head} synchronization failed with lease: ${classification.message}` }
   }
@@ -193,15 +194,189 @@ function executeReconciliationMutation(target, head, state) {
     }
   }
   if (classification.category === 'policy') {
-    return {
-      success: false,
-      retry: false,
-      error: `${head} reconciliation was blocked by branch policy: ${classification.message}`,
-    }
+    return deliverReconciliationPullRequest(target, base, head, state, targetSha, {}, classification.message)
   }
   return { success: false, retry: true, error: `${head} synchronization failed with lease: ${classification.message}` }
 }
 
+/** @typedef {{ number: number, url: string, base: string, head: string, branch: string, title: string, body: string }} ReconciliationPullRequest */
+
+/** @typedef {{ synchronization: string, replaySha?: string, pullRequest?: ReconciliationPullRequest }} ReconciliationMutationResult */
+
+/** @param {string} error @returns {{ success: false, retry: false, error: string }} */
+function failResult(error) {
+  return { success: false, retry: false, error }
+}
+
+/**
+ * Deliver reconciliation through an automated synchronization pull request
+ * when staging branch policy rejects the exact lease push. The head branch is
+ * deterministic and namespaced, and reuse is keyed on the exact branch, base,
+ * and title so stale or ambiguous state fails closed.
+ * @param {string} target
+ * @param {string} base
+ * @param {string} head
+ * @param {{
+ *  plan: ReturnType<typeof classifyReconciliation>,
+ *  mainSha: string,
+ *  stagingSha: string,
+ * }} state
+ * @param {string} targetSha
+ * @param {Record<string, unknown>} extra
+ * @param {string} pushError
+ * @returns {{ success: false, retry: false, error: string } | { success: true, result: ReconciliationMutationResult }}
+ */
+function deliverReconciliationPullRequest(target, base, head, state, targetSha, extra, pushError) {
+  const repository = process.env.GITHUB_REPOSITORY
+  if (!repository) return failResult('GITHUB_REPOSITORY is required to open a reconciliation pull request.')
+  // base (main) is only the reconciliation source; the generated pull
+  // request must target the protected head branch (staging), so the PR base
+  // is always the reconcile head. Keep one named source of truth so the gh
+  // create call, the reuse selector, and the result metadata cannot drift.
+  const prBase = head
+  const branch = reconciliationPullRequestBranch(base, head)
+  const title = reconciliationPullRequestTitle({ targetHead: head, sourceBase: base })
+  const body = buildReconciliationPullRequestBody({
+    sourceBase: base,
+    targetHead: head,
+    mainSha: state.mainSha,
+    stagingSha: state.stagingSha,
+    targetSha,
+    action: state.plan.action,
+    pushError,
+  })
+  const expected = { targetBase: prBase, branch, title }
+  let prs = listOpenHeadPullRequests(target, repository, branch)
+  if (!prs) return failResult(`Failed to list open pull requests for reconciliation branch ${branch}.`)
+  let selection = selectReconciliationPullRequest(prs, expected)
+  if (selection.error) return failResult(selection.error)
+  if (!selection.create) {
+    if (!selection.reuse) return failResult(`No reusable reconciliation pull request for ${branch}.`)
+    return reuseReconciliationPullRequest(target, repository, selection.reuse, targetSha, body)
+  }
+  const pushed = pushReconciliationHead(target, branch, targetSha)
+  if (pushed.status !== 0) {
+    const classification = classifyPushFailure(branch, pushed.message)
+    if (classification.category === 'authentication') {
+      return failResult(`${branch} authentication failed while pushing the reconciliation head: ${classification.message}`)
+    }
+    return failResult(`Failed to push the reconciliation head ${branch}: ${classification.message}`)
+  }
+  prs = listOpenHeadPullRequests(target, repository, branch)
+  if (!prs) return failResult(`Failed to re-list open pull requests for reconciliation branch ${branch} after pushing its head.`)
+  selection = selectReconciliationPullRequest(prs, expected)
+  if (selection.error) return failResult(selection.error)
+  if (!selection.create) {
+    if (!selection.reuse) return failResult(`No reusable reconciliation pull request for ${branch} after pushing its head.`)
+    return reuseReconciliationPullRequest(target, repository, selection.reuse, targetSha, body)
+  }
+  const created = ghSpawn(target, ['pr', 'create', '--repo', repository, '--base', prBase, '--head', branch, '--title', title, '--body', body])
+  if (created.status !== 0) {
+    // A concurrent run may have created the pull request between our list
+    // and create; reuse it when it is exactly ours, otherwise fail closed.
+    prs = listOpenHeadPullRequests(target, repository, branch)
+    if (!prs) return failResult(`Failed to create the reconciliation pull request and to re-list open pull requests for ${branch}.`)
+    selection = selectReconciliationPullRequest(prs, expected)
+    if (selection.error) return failResult(selection.error)
+    if (selection.create) {
+      return failResult(`gh pr create failed for ${branch}: ${sanitizeReconcileOutput(created.stderr) || 'unknown error'}`)
+    }
+    if (!selection.reuse) return failResult(`No reusable reconciliation pull request for ${branch} after gh pr create failed.`)
+    return reuseReconciliationPullRequest(target, repository, selection.reuse, targetSha, body)
+  }
+  const number = parsePullRequestNumber(created.stdout)
+  if (!number) return failResult(`Created the reconciliation pull request for ${branch} but could not parse its number.`)
+  const url = created.stdout.trim()
+  return {
+    success: true,
+    result: {
+      ...extra,
+      synchronization: 'pull-request',
+      pullRequest: { number, url, base: prBase, head: branch, branch, title, body },
+    },
+  }
+}
+
+/**
+ * Refresh an existing reconciliation pull request to the exact target tip and
+ * body. The head branch is pushed under an exact lease when its tip is stale,
+ * so a concurrent move fails closed instead of being clobbered.
+ * @param {string} target
+ * @param {string} repository
+ * @param {{number?: number, title?: string, headRefName?: string, headRefOid?: string, baseRefName?: string, url?: string}} pr
+ * @param {string} targetSha
+ * @param {string} body
+ * @returns {{ success: false, retry: false, error: string } | { success: true, result: ReconciliationMutationResult }}
+ */
+function reuseReconciliationPullRequest(target, repository, pr, targetSha, body) {
+  const number = Number(pr.number)
+  if (String(pr.headRefOid ?? '') !== targetSha) {
+    const pushed = pushReconciliationHead(target, /** @type {string} */ (pr.headRefName), targetSha)
+    if (pushed.status !== 0) {
+      return failResult(`Failed to refresh the reconciliation branch ${pr.headRefName} to the target tip: ${sanitizeReconcileOutput(pushed.message)}`)
+    }
+    const edited = ghSpawn(target, ['pr', 'edit', String(number), '--repo', repository, '--body', body])
+    if (edited.status !== 0) {
+      return failResult(`Failed to update reconciliation pull request #${number}: ${sanitizeReconcileOutput(edited.stderr) || 'unknown error'}`)
+    }
+  }
+  return {
+    success: true,
+    result: {
+      synchronization: 'pull-request',
+      pullRequest: {
+        number,
+        url: pr.url ?? '',
+        base: pr.baseRefName ?? '',
+        head: pr.headRefName ?? '',
+        branch: pr.headRefName ?? '',
+        title: pr.title ?? '',
+        body,
+      },
+    },
+  }
+}
+
+/**
+ * Push the exact target tip to the deterministic reconciliation head branch,
+ * creating it when absent and refreshing it under an exact lease otherwise.
+ * @param {string} target @param {string} branch @param {string} targetSha
+ */
+function pushReconciliationHead(target, branch, targetSha) {
+  const existingTip = remoteRefSha(target, branch)
+  if (existingTip === null) return { status: 1, message: `could not resolve the remote reconciliation branch ${branch} before pushing.` }
+  if (existingTip === targetSha) return { status: 0, message: '' }
+  if (!existingTip) {
+    const result = spawnSync('git', ['push', 'origin', `${targetSha}:refs/heads/${branch}`], { cwd: target, encoding: 'utf8' })
+    const message = `${result.stdout?.trim() || ''}\n${result.stderr?.trim() || ''}`.trim() || `failed to create reconciliation branch ${branch}.`
+    return { status: result.status, message: sanitizeReconcileOutput(message) }
+  }
+  return pushWithLease(target, branch, existingTip, targetSha)
+}
+
+/**
+ * @param {string} target
+ * @param {string} repository
+ * @param {string} branch
+ * @returns {Array<{number?: number, title?: string, headRefName?: string, headRefOid?: string, baseRefName?: string, url?: string}> | null}
+ */
+function listOpenHeadPullRequests(target, repository, branch) {
+  const result = ghSpawn(target, ['pr', 'list', '--repo', repository, '--state', 'open', '--head', branch, '--json', 'number,title,headRefName,headRefOid,baseRefName,url'])
+  if (result.status !== 0) return null
+  try {
+    const prs = JSON.parse(result.stdout)
+    return Array.isArray(prs) ? prs : null
+  } catch {
+    return null
+  }
+}
+
+/** @param {string} stdout @returns {number | null} */
+function parsePullRequestNumber(stdout) {
+  const match = stdout.trim().match(/\/pull\/(\d+)\/?$/)
+  return match ? Number(match[1]) : null
+}
+
 /** @param {string} target @param {string} head @param {string} expectedSha @param {string} tipSha */
 function pushWithLease(target, head, expectedSha, tipSha) {
   const result = spawnSync('git', [
@@ -230,7 +405,7 @@ function classifyPushFailure(branch, raw) {
   if (/permission denied|authentication failed|could not read from remote repository|publickey|not authorized|bad credentials/.test(lower)) {
     return { category: 'authentication', message }
   }
-  if (/remote:\s*error|protected branch|required status checks|pre-receive hook|branch policy|ruleset|gh006|gh007|gh008/.test(lower)) {
+  if (/changes must be made through a pull request|protected branch|protected branch hook declined|required status checks|pre-receive hook|branch policy|repository rule|ruleset|push declined due to repository rule|gh006|gh007|gh008|gh013/.test(lower)) {
     return { category: 'policy', message }
   }
   return { category: 'other', message }
@@ -395,10 +570,15 @@ function commitChangedPaths(root, commitSha) {
   return result.stdout.split(/\r?\n/).filter(Boolean)
 }
 
+/** @param {string} root @param {string[]} args @returns {{ status: number | null, stdout: string, stderr: string }} */
+function ghSpawn(root, args) {
+  const token = process.env.RELEASE_PLEASE_TOKEN || process.env.GH_TOKEN || process.env.GITHUB_TOKEN
+  return spawnSync('gh', args, { cwd: resolve(root), encoding: 'utf8', env: { ...process.env, ...(token ? { GH_TOKEN: token } : {}) } })
+}
+
 /** @param {string} root @param {string[]} args @returns {unknown} */
 function ghJson(root, args) {
-  const token = process.env.RELEASE_PLEASE_TOKEN || process.env.GH_TOKEN || process.env.GITHUB_TOKEN
-  const result = spawnSync('gh', args, { cwd: resolve(root), encoding: 'utf8', env: { ...process.env, ...(token ? { GH_TOKEN: token } : {}) } })
+  const result = ghSpawn(root, args)
   if (result.status !== 0) return []
   try { return JSON.parse(result.stdout) }
   catch { return [] }

package/src/commands/sync.mjs

@@ -412,9 +412,12 @@ function mergeGitignore(baseline, existing) {
 
 /** @param {string} baseline @param {string} existing */
 function mergeIgnoreFile(baseline, existing) {
+  const marker = '# Repository-specific rules'
   const baselineLines = new Set(baseline.split(/\r?\n/).map((line) => line.trim()).filter(Boolean))
-  const custom = existing.split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim() && !baselineLines.has(line.trim()))
-  return custom.length ? `${baseline.trimEnd()}\n\n# Repository-specific rules\n${custom.join('\n')}\n` : baseline
+  const custom = existing.split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() && line.trim() !== marker && !baselineLines.has(line.trim()))
+  return custom.length ? `${baseline.trimEnd()}\n\n${marker}\n${custom.join('\n')}\n` : baseline
 }
 
 /** @param {string} file @param {string} content */

package/src/lib/release-policy.mjs

@@ -273,3 +273,89 @@ export function classifyReconciliation(input) {
 }
 
 export { DEFAULT_RELEASE_FILES }
+
+/**
+ * Deterministic head branch for the automated synchronization pull request
+ * used when branch policy rejects the direct reconcile push. The branch is
+ * namespaced under code-foundry/ so it never collides with release-please or
+ * user branches, and the name is a pure function of the reconciled refs so
+ * reruns converge on the same branch and PR.
+ * @param {string} sourceBase
+ * @param {string} targetHead
+ */
+export function reconciliationPullRequestBranch(sourceBase, targetHead) {
+  return `code-foundry/reconcile/${sourceBase}-to-${targetHead}`
+}
+
+/** @param {{ targetHead: string, sourceBase: string }} input */
+export function reconciliationPullRequestTitle({ targetHead, sourceBase }) {
+  return `chore(${targetHead}): reconcile release metadata from ${sourceBase}`
+}
+
+/**
+ * Deterministic pull request body for the automated synchronization PR. The
+ * body explains that this is generated reconciliation and preserves the
+ * fail-closed contract: unexpected divergence, conflicts, authentication
+ * errors, and ambiguous state are never pushed around branch protection.
+ * @param {{
+ *   sourceBase: string,
+ *   targetHead: string,
+ *   mainSha: string,
+ *   stagingSha: string,
+ *   targetSha: string,
+ *   action: string,
+ *   pushError?: string,
+ * }} input
+ */
+export function buildReconciliationPullRequestBody(input) {
+  const { sourceBase, targetHead, mainSha, stagingSha, targetSha, action, pushError = '' } = input
+  const lines = [
+    '## Automated release reconciliation',
+    '',
+    `This pull request was generated by Code Foundry release reconciliation. The protected \`${targetHead}\` branch rejected the exact-lease synchronization push that carries release metadata published on \`${sourceBase}\` (branch policy, ruleset, or required pull request review), so this pull request delivers the exact target tip through the normal review flow instead.`,
+    '',
+    `- Base \`${targetHead}\`: \`${stagingSha}\``,
+    `- \`${sourceBase}\` tip: \`${mainSha}\``,
+    `- Target tip in this branch: \`${targetSha}\``,
+    `- Synchronization: \`${action}\``,
+  ]
+  const reason = pushError.replace(/\s+/g, ' ').trim()
+  if (reason) lines.push(`- Direct push rejection: \`${reason}\``)
+  lines.push(
+    '',
+    `Merging this pull request synchronizes \`${targetHead}\` with the exact target tip above; no other commits are introduced.`,
+    '',
+    'Code Foundry reconciles only release metadata. Unexpected code divergence, replay conflicts, authentication failures, and ambiguous or stale state fail the release job closed and are never pushed around branch protection. Later releases retry the direct push first; when branch policy still rejects it, this pull request is updated instead of duplicated.',
+  )
+  return lines.join('\n')
+}
+
+/**
+ * Select the single reusable automated synchronization pull request from the
+ * open pull requests that use the deterministic reconciliation branch. Reuse
+ * requires the exact generated target base and title; foreign or ambiguous
+ * state fails closed so a generated PR is never reused or overwritten by
+ * accident. targetBase is the PR base branch (the protected branch being
+ * synchronized, e.g. staging), branch is the generated head branch, and
+ * title is the exact generated title.
+ * @param {Array<{number?: number, title?: string, headRefName?: string, baseRefName?: string}>} prs
+ * @param {{ targetBase: string, branch: string, title: string }} input
+ * @returns {{ create: boolean, reuse?: {number?: number, title?: string, headRefName?: string, headRefOid?: string, baseRefName?: string, url?: string}, error?: string }}
+ */
+export function selectReconciliationPullRequest(prs, input) {
+  const { targetBase, branch, title } = input
+  const owned = prs.filter((pr) => String(pr.headRefName ?? '') === branch)
+  if (!owned.length) return { create: true }
+  const reusable = owned.filter((pr) => String(pr.baseRefName ?? '') === targetBase && String(pr.title ?? '') === title)
+  if (reusable.length === 1) return { create: false, reuse: reusable[0] }
+  if (reusable.length > 1) {
+    return { create: false, error: `Multiple open pull requests use the reconciliation branch ${branch}; refusing to pick one.` }
+  }
+  const foreign = owned
+    .map((pr) => `#${pr.number ?? '?'} (base ${pr.baseRefName ?? '?'}, title ${JSON.stringify(pr.title ?? '')})`)
+    .join(', ')
+  return {
+    create: false,
+    error: `Open pull request ${foreign} uses the reconciliation branch ${branch} with an unexpected base or title; refusing to reuse or overwrite it.`,
+  }
+}