diff --git a/plans/2026-06-30-package-patching-implementation.md b/plans/2026-06-30-package-patching-implementation.md
new file mode 100644
index 0000000..3a743d7
--- /dev/null
+++ b/plans/2026-06-30-package-patching-implementation.md
@@ -0,0 +1,1477 @@
+# Package Patching Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let a curated registry of packages be "patched" (env/configure/Makevars overrides and/or source diffs) before `pak` installs them, including when they are transitive dependencies, so compiler-/OS-specific failures like `RcppParallel` stop cascading.
+
+**Architecture:** The mechanism lives in `bincraft`. Before `pak::local_install_deps()` runs, bincraft pre-builds each registry-matched package as a binary (reusing `pkgbuild::build(binary=TRUE)` + `cranlike::add_PACKAGES`), caches it, and serves it from a local `file://` repo prepended to `options("repos")` so `pak` installs the patched binary — direct or transitive — without recompiling. The curated registry (`registry.json` + diff files) lives in this repo and is passed in via a new `patches` argument.
+
+**Tech Stack:** R, `pak`, `pkgbuild`, `cranlike` (fork `pat-s/cranlike@s3`), `pkgsearch`, `withr`, `jsonlite`, `testthat` (3e), `mockery`. Two repos: `bincraft` at `/Users/pjs/git/codefloe.com/rpkgs/bincraftr`, and this repo `build-cran-binaries`.
+
+## Global Constraints
+
+- bincraft package name is `bincraft`; repo dir is `…/rpkgs/bincraftr`. Current version `4.2.2.9999`.
+- Logging uses bincraft's wrappers only: `log_info`, `log_warn`, `log_success`, `log_debug`, `log_error`, `log_header` (never bare `message`/`cat` in package code).
+- `cli`-style inline markup is allowed in log messages (e.g. `{.pkg %s}`, `{.path %s}`); curly braces in dynamic/error text must be escaped as already done in `install_helpers.R`.
+- Tests: `testthat` 3rd edition, files at `tests/testthat/test-<topic>.R`, network/build tests guarded with `skip_on_cran()` / `skip_if_offline()`; end-to-end build tests guarded behind `skip_if_not(nzchar(Sys.getenv("BINCRAFT_PATCH_E2E")))`.
+- New exported functions need roxygen with `@keywords internal` for non-user helpers; run `devtools::document()` after adding roxygen.
+- Patched-binary cache dir default: `/mnt/cache/patched-binaries`.
+- Platform tokens for matching = `c(<platform>, <family>, <arch>)`, e.g. `ubuntu-2604` → `c("ubuntu-2604","ubuntu","amd64")`.
+- Registry entry required fields: `package`, `versions`, `platforms`, `reason`. Optional: `env`, `configure_args`, `makevars`, `patch`.
+- One sentence per line in prose/commit messages; do not hard-wrap at 80 columns.
+- Use `fj -H codefloe.com` for any PR operations (Forgejo), not `gh`.
+
+---
+
+## Phase A — bincraft mechanism
+
+All Phase A paths are relative to `/Users/pjs/git/codefloe.com/rpkgs/bincraftr`.
+
+### Task A0: Proof of mechanism — pak installs a patched binary from a prepended `file://` repo
+
+This de-risks the core assumption before building anything on top: that `pak` installs a binary from a local `file://` repo in preference to CRAN for an equal version, and does so without recompiling. If this fails, the contingency (documented in Step 4) is to serve patched *source* and rely on `pkgcache` build-caching — the rest of the plan changes only inside `build_patched_binary()`.
+
+**Files:**
+- Create: `tools/verify-patch-mechanism.R`
+
+**Interfaces:**
+- Produces: a runnable script proving `pak::pkg_install()` resolves a local patched binary over CRAN. No package API.
+
+- [ ] **Step 1: Write the verification script**
+
+```r
+# tools/verify-patch-mechanism.R
+# Proves pak installs a patched binary from a prepended file:// repo instead of
+# CRAN's, without recompiling. Run inside a Linux build-env container:
+#   Rscript tools/verify-patch-mechanism.R
+# Exits 0 on success, 1 on failure.
+
+pkg <- "glue" # small, pure-R CRAN package
+sentinel <- "PatchMechanismProof"
+
+work <- tempfile("verify_")
+repo <- file.path(work, "repo", "src", "contrib")
+lib <- file.path(work, "lib")
+dir.create(repo, recursive = TRUE)
+dir.create(lib, recursive = TRUE)
+
+# 1. Download CRAN source for the current version.
+ap <- available.packages(repos = "https://cloud.r-project.org")
+ver <- ap[pkg, "Version"]
+src <- file.path(work, sprintf("%s_%s.tar.gz", pkg, ver))
+download.file(
+  sprintf("https://cloud.r-project.org/src/contrib/%s_%s.tar.gz", pkg, ver),
+  src, mode = "wb"
+)
+
+# 2. Unpack, inject a sentinel field into DESCRIPTION, build a binary.
+untar(src, exdir = work)
+desc <- file.path(work, pkg, "DESCRIPTION")
+writeLines(c(readLines(desc), sprintf("%s: yes", sentinel)), desc)
+pkgbuild::build(
+  file.path(work, pkg), binary = TRUE, vignettes = FALSE,
+  dest_path = repo, quiet = TRUE
+)
+built <- list.files(repo, pattern = sprintf("^%s_.*\\.tar\\.gz$", pkg), full.names = TRUE)
+file.rename(built[1L], file.path(repo, sprintf("%s_%s.tar.gz", pkg, ver)))
+cranlike::add_PACKAGES(sprintf("%s_%s.tar.gz", pkg, ver), repo)
+
+# 3. Install with the local repo prepended; assert our patched build won.
+withr::with_options(
+  list(repos = c(patched = sprintf("file://%s", dirname(dirname(repo))),
+                 CRAN = "https://cloud.r-project.org")),
+  pak::pkg_install(pkg, lib = lib, ask = FALSE, upgrade = FALSE)
+)
+
+installed_desc <- file.path(lib, pkg, "DESCRIPTION")
+ok <- file.exists(installed_desc) &&
+  any(grepl(sentinel, readLines(installed_desc)))
+
+if (ok) {
+  cat("PROOF PASSED: pak installed the patched local binary.\n")
+  quit(status = 0L)
+} else {
+  cat("PROOF FAILED: pak did not install the patched local binary.\n")
+  quit(status = 1L)
+}
+```
+
+- [ ] **Step 2: Run the proof in a build-env container**
+
+Run (amd64 example; use any supported build-env image):
+
+```bash
+just build-single ubuntu 2604 amd64 4.5.0 glue 1.0.0 1 || true   # warms the env
+docker run --rm -v "$PWD":/work -w /work reg.devxy.io/rpkgs/build-env-ubuntu:2604 \
+  Rscript tools/verify-patch-mechanism.R
+```
+
+Expected: final line `PROOF PASSED: pak installed the patched local binary.` and exit status 0.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tools/verify-patch-mechanism.R
+git commit -m "test(patches): prove pak installs a patched binary from a local file:// repo"
+```
+
+- [ ] **Step 4: Record the outcome / contingency**
+
+If the proof PASSED, proceed to Task A1 unchanged.
+If it FAILED (pak recompiled or picked CRAN's), the mechanism switches to serving patched *source*: in Task A4 `build_patched_binary()` skips `pkgbuild::build()` and instead repackages the patched source tree with `pkgbuild::build(binary = FALSE)`; everything else (registry, matching, cache, repo prepend) is unchanged because `pak` build-caches the compiled result via `pkgcache`. Note the chosen path in the commit message and continue.
+
+---
+
+### Task A1: Registry loading and normalization
+
+**Files:**
+- Create: `R/patches.R`
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Produces: `load_patch_registry(patches_dir)` → `list()` of normalized entries; each entry is a named list with `package`, `versions`, `platforms` (character vector), `env` (named list), `configure_args` (character), `makevars` (named list), `reason`, and `patch_path` (absolute path or `NULL`). `normalize_patch_entry(entry, patches_dir)` → one normalized entry; errors on missing required field or missing patch file.
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+# tests/testthat/test-patches.R
+test_that("load_patch_registry parses and normalizes entries", {
+  dir <- withr::local_tempdir()
+  writeLines("--- a patch ---", file.path(dir, "fix.patch"))
+  jsonlite::write_json(
+    list(list(
+      package = "RcppParallel", versions = "*",
+      platforms = list("alpine", "ubuntu-2604"),
+      env = list(RCPP_PARALLEL_USE_TBB = "0"),
+      patch = "fix.patch", reason = "bundled TBB fails"
+    )),
+    file.path(dir, "registry.json"), auto_unbox = TRUE
+  )
+
+  reg <- load_patch_registry(dir)
+
+  expect_length(reg, 1L)
+  expect_identical(reg[[1L]]$package, "RcppParallel")
+  expect_identical(reg[[1L]]$platforms, c("alpine", "ubuntu-2604"))
+  expect_identical(reg[[1L]]$env$RCPP_PARALLEL_USE_TBB, "0")
+  expect_identical(reg[[1L]]$configure_args, character(0L))
+  expect_true(file.exists(reg[[1L]]$patch_path))
+})
+
+test_that("load_patch_registry returns empty list when no registry", {
+  expect_identical(load_patch_registry(NULL), list())
+  expect_identical(load_patch_registry(withr::local_tempdir()), list())
+})
+
+test_that("normalize_patch_entry errors on missing required field", {
+  expect_error(
+    normalize_patch_entry(list(package = "x"), tempdir()),
+    "missing required field"
+  )
+})
+
+test_that("normalize_patch_entry errors on missing patch file", {
+  expect_error(
+    normalize_patch_entry(
+      list(package = "x", versions = "*", platforms = "alpine",
+           reason = "r", patch = "nope.patch"),
+      tempdir()
+    ),
+    "does not exist"
+  )
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL with "could not find function load_patch_registry".
+
+- [ ] **Step 3: Write minimal implementation**
+
+```r
+# R/patches.R
+
+#' Load and validate the patch registry
+#'
+#' Reads `registry.json` from `patches_dir` and returns normalized entries.
+#'
+#' @param patches_dir Directory containing `registry.json` and any patch files,
+#'   or `NULL` to disable patching.
+#' @return A list of normalized patch entries (possibly empty).
+#' @keywords internal
+load_patch_registry <- function(patches_dir) {
+  if (is.null(patches_dir)) {
+    return(list())
+  }
+  registry_file <- file.path(patches_dir, "registry.json")
+  if (!file.exists(registry_file)) {
+    log_warn(sprintf(
+      "Patch directory {.path %s} has no registry.json; patching disabled.",
+      patches_dir
+    ))
+    return(list())
+  }
+  raw <- jsonlite::fromJSON(registry_file, simplifyVector = FALSE)
+  lapply(raw, normalize_patch_entry, patches_dir = patches_dir)
+}
+
+#' Normalize and validate a single patch registry entry
+#'
+#' @param entry A list parsed from `registry.json`.
+#' @param patches_dir Directory used to resolve a relative `patch` path.
+#' @return The entry with defaults filled and `patch_path` resolved.
+#' @keywords internal
+normalize_patch_entry <- function(entry, patches_dir) {
+  required <- c("package", "versions", "platforms", "reason")
+  missing <- setdiff(required, names(entry))
+  if (length(missing) > 0L) {
+    stop(
+      sprintf("Patch entry is missing required field(s): %s", toString(missing)),
+      call. = FALSE
+    )
+  }
+  entry$platforms <- as.character(unlist(entry$platforms))
+  entry$env <- if (is.null(entry$env)) list() else entry$env
+  entry$configure_args <- if (is.null(entry$configure_args)) {
+    character(0L)
+  } else {
+    as.character(unlist(entry$configure_args))
+  }
+  entry$makevars <- if (is.null(entry$makevars)) list() else entry$makevars
+  if (!is.null(entry$patch)) {
+    patch_path <- file.path(patches_dir, entry$patch)
+    if (!file.exists(patch_path)) {
+      stop(
+        sprintf(
+          "Patch file '%s' for package '%s' does not exist.",
+          patch_path, entry$package
+        ),
+        call. = FALSE
+      )
+    }
+    entry$patch_path <- patch_path
+  } else {
+    entry$patch_path <- NULL
+  }
+  entry
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add R/patches.R tests/testthat/test-patches.R
+git commit -m "feat(patches): load and validate the patch registry"
+```
+
+---
+
+### Task A2: Platform matching and version-constraint satisfaction
+
+**Files:**
+- Modify: `R/patches.R`
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Consumes: normalized entries from Task A1.
+- Produces: `build_platform_tokens(platform, arch)` → character vector; `entry_matches_platform(entry, tokens)` → logical; `match_patch_entries(registry, platform, arch)` → filtered list; `version_satisfies(version, constraint)` → logical (constraint forms: `"*"` handled by caller, `"x.y.z"` exact, `">=x"`, `"<=x"`, `">x"`, `"<x"`, `"==x"`).
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+test_that("build_platform_tokens expands family and arch", {
+  expect_setequal(
+    build_platform_tokens("ubuntu-2604", "amd64"),
+    c("ubuntu-2604", "ubuntu", "amd64")
+  )
+  expect_setequal(
+    build_platform_tokens("alpine-324", "arm64"),
+    c("alpine-324", "alpine", "arm64")
+  )
+})
+
+test_that("match_patch_entries matches family, codename, arch, and wildcard", {
+  reg <- list(
+    list(package = "A", versions = "*", platforms = "alpine", reason = "r"),
+    list(package = "B", versions = "*", platforms = "ubuntu-2604", reason = "r"),
+    list(package = "C", versions = "*", platforms = "*", reason = "r"),
+    list(package = "D", versions = "*", platforms = "redhat", reason = "r")
+  )
+  got <- vapply(
+    match_patch_entries(reg, "ubuntu-2604", "amd64"),
+    function(e) e$package, character(1L)
+  )
+  expect_setequal(got, c("B", "C"))
+})
+
+test_that("version_satisfies handles operators and hyphenated versions", {
+  expect_true(version_satisfies("5.1.11-2", "5.1.11-2"))
+  expect_true(version_satisfies("5.1.11-2", "==5.1.11-2"))
+  expect_true(version_satisfies("5.1.12", ">=5.1.0"))
+  expect_false(version_satisfies("5.0.0", ">=5.1.0"))
+  expect_true(version_satisfies("5.1.11-2", "<=5.1.11-2"))
+  expect_false(version_satisfies("5.1.12", "<=5.1.11-2"))
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL with "could not find function build_platform_tokens".
+
+- [ ] **Step 3: Write minimal implementation (append to `R/patches.R`)**
+
+```r
+#' Build platform tokens for patch matching
+#' @keywords internal
+build_platform_tokens <- function(platform, arch) {
+  family <- sub("-.*$", "", platform)
+  unique(c(platform, family, arch))
+}
+
+#' Does a patch entry apply to the current platform tokens?
+#' @keywords internal
+entry_matches_platform <- function(entry, tokens) {
+  any(entry$platforms == "*") ||
+    length(intersect(entry$platforms, tokens)) > 0L
+}
+
+#' Filter registry entries applicable to the current build
+#' @keywords internal
+match_patch_entries <- function(registry, platform, arch) {
+  if (length(registry) == 0L) {
+    return(list())
+  }
+  tokens <- build_platform_tokens(platform, arch)
+  Filter(function(e) entry_matches_platform(e, tokens), registry)
+}
+
+#' Test whether a version satisfies a single constraint
+#'
+#' @param version A version string (CRAN style, may contain `-`).
+#' @param constraint One of `"x.y.z"`, `"==x"`, `">=x"`, `"<=x"`, `">x"`, `"<x"`.
+#' @keywords internal
+version_satisfies <- function(version, constraint) {
+  constraint <- trimws(constraint)
+  parts <- regmatches(
+    constraint,
+    regexec("^(>=|<=|==|>|<)?\\s*(.+)$", constraint)
+  )[[1L]]
+  op <- parts[2L]
+  target <- parts[3L]
+  v <- package_version(version)
+  t <- package_version(target)
+  if (op == "" || op == "==") {
+    return(v == t)
+  }
+  switch(
+    op,
+    ">=" = v >= t,
+    "<=" = v <= t,
+    ">" = v > t,
+    "<" = v < t,
+    FALSE
+  )
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add R/patches.R tests/testthat/test-patches.R
+git commit -m "feat(patches): platform matching and version-constraint checks"
+```
+
+---
+
+### Task A3: Cache key and version resolution
+
+**Files:**
+- Modify: `R/patches.R`
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Consumes: normalized entries.
+- Produces: `patch_cache_key(entry, version, platform, arch, r_minor)` → string `"<pkg>_<ver>_<platform>_<arch>_<rminor>_<hash12>"`, where `hash12` covers `env`/`configure_args`/`makevars`/patch bytes; `resolve_patch_version(entry)` → latest CRAN version satisfying `entry$versions`, or `NA_character_`; `describe_patch(entry)` → short human label.
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+test_that("patch_cache_key is stable and sensitive to env/patch changes", {
+  e1 <- list(package = "P", env = list(A = "1"),
+             configure_args = character(0L), makevars = list(),
+             patch_path = NULL)
+  e2 <- e1; e2$env <- list(A = "2")
+
+  k1 <- patch_cache_key(e1, "1.0", "alpine-324", "amd64", "4.5")
+  expect_identical(k1, patch_cache_key(e1, "1.0", "alpine-324", "amd64", "4.5"))
+  expect_false(identical(
+    k1, patch_cache_key(e2, "1.0", "alpine-324", "amd64", "4.5")
+  ))
+  expect_match(k1, "^P_1.0_alpine-324_amd64_4.5_[0-9a-f]{12}$")
+})
+
+test_that("resolve_patch_version returns latest for wildcard, NA when unmet", {
+  local_mocked_bindings(
+    cran_package = function(pkg) list(Version = "5.1.12"),
+    .package = "pkgsearch"
+  )
+  expect_identical(
+    resolve_patch_version(list(package = "RcppParallel", versions = "*")),
+    "5.1.12"
+  )
+  expect_identical(
+    resolve_patch_version(list(package = "RcppParallel", versions = ">=9.0")),
+    NA_character_
+  )
+})
+
+test_that("describe_patch summarizes the active overrides", {
+  expect_match(
+    describe_patch(list(env = list(RCPP_PARALLEL_USE_TBB = "0"),
+                        configure_args = character(0L), makevars = list(),
+                        patch_path = NULL)),
+    "env: RCPP_PARALLEL_USE_TBB=0"
+  )
+  expect_match(
+    describe_patch(list(env = list(), configure_args = character(0L),
+                        makevars = list(), patch_path = "/x/fix.patch")),
+    "source patch"
+  )
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL with "could not find function patch_cache_key".
+
+- [ ] **Step 3: Write minimal implementation (append to `R/patches.R`)**
+
+```r
+#' Compute the cache key for a patched binary
+#' @keywords internal
+patch_cache_key <- function(entry, version, platform, arch, r_minor) {
+  payload <- list(
+    env = entry$env,
+    configure_args = entry$configure_args,
+    makevars = entry$makevars,
+    patch = if (!is.null(entry$patch_path)) {
+      readBin(entry$patch_path, "raw", file.size(entry$patch_path))
+    } else {
+      raw(0L)
+    }
+  )
+  tmp <- tempfile()
+  on.exit(unlink(tmp), add = TRUE)
+  saveRDS(payload, tmp)
+  hash <- substr(unname(tools::md5sum(tmp)), 1L, 12L)
+  sprintf(
+    "%s_%s_%s_%s_%s_%s",
+    entry$package, version, platform, arch, r_minor, hash
+  )
+}
+
+#' Resolve the CRAN version to build for a patch entry
+#'
+#' Returns the latest CRAN version satisfying the entry's `versions` constraint,
+#' or `NA_character_` when CRAN's latest does not satisfy it or lookup fails.
+#' @keywords internal
+resolve_patch_version <- function(entry) {
+  latest <- tryCatch(
+    pkgsearch::cran_package(entry$package)$Version,
+    error = function(e) NA_character_
+  )
+  if (is.na(latest)) {
+    return(NA_character_)
+  }
+  if (identical(entry$versions, "*") || version_satisfies(latest, entry$versions)) {
+    return(latest)
+  }
+  NA_character_
+}
+
+#' Short human label describing a patch entry's overrides
+#' @keywords internal
+describe_patch <- function(entry) {
+  bits <- character(0L)
+  if (length(entry$env) > 0L) {
+    bits <- c(bits, sprintf(
+      "env: %s",
+      paste(
+        names(entry$env),
+        unlist(entry$env),
+        sep = "=", collapse = ","
+      )
+    ))
+  }
+  if (length(entry$configure_args) > 0L) {
+    bits <- c(bits, sprintf("configure: %s", toString(entry$configure_args)))
+  }
+  if (length(entry$makevars) > 0L) {
+    bits <- c(bits, "makevars")
+  }
+  if (!is.null(entry$patch_path)) {
+    bits <- c(bits, "source patch")
+  }
+  if (length(bits) == 0L) "no-op" else paste(bits, collapse = "; ")
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: PASS. (Note: `local_mocked_bindings` requires testthat >= 3.1.7; bincraft uses 3e.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add R/patches.R tests/testthat/test-patches.R
+git commit -m "feat(patches): cache key, version resolution, and patch description"
+```
+
+---
+
+### Task A4: Build a patched binary in isolation
+
+**Files:**
+- Modify: `R/patches.R`
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Consumes: a normalized entry, a resolved `version`, a `dest_dir`.
+- Produces: `download_cran_source(package, version, dest_dir, cran)` → path or `NULL`; `apply_source_patch(patch_path, pkg_src)` → logical; `configure_args_to_build_args(configure_args)` → character; `build_patched_binary(entry, version, dest_dir)` → path to built binary tarball or `NULL`.
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+test_that("configure_args_to_build_args formats configure args", {
+  expect_identical(configure_args_to_build_args(character(0L)), character(0L))
+  expect_identical(
+    configure_args_to_build_args(c("--with-foo", "--no-bar")),
+    "--configure-args=--with-foo --no-bar"
+  )
+})
+
+test_that("apply_source_patch returns FALSE when patch does not apply", {
+  src <- withr::local_tempdir()
+  writeLines("unrelated content", file.path(src, "file.txt"))
+  bad_patch <- tempfile(fileext = ".patch")
+  writeLines(c(
+    "--- a/missing.txt", "+++ b/missing.txt",
+    "@@ -1 +1 @@", "-nope", "+nope2"
+  ), bad_patch)
+  expect_false(apply_source_patch(bad_patch, src))
+})
+
+test_that("build_patched_binary returns NULL when download fails", {
+  local_mocked_bindings(download_cran_source = function(...) NULL)
+  expect_null(
+    build_patched_binary(
+      list(package = "P", env = list(), configure_args = character(0L),
+           makevars = list(), patch_path = NULL),
+      "1.0", withr::local_tempdir()
+    )
+  )
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL with "could not find function configure_args_to_build_args".
+
+- [ ] **Step 3: Write minimal implementation (append to `R/patches.R`)**
+
+```r
+#' Download a CRAN source tarball for an exact version
+#' @keywords internal
+download_cran_source <- function(
+  package,
+  version,
+  dest_dir,
+  cran = "https://cloud.r-project.org"
+) {
+  fname <- sprintf("%s_%s.tar.gz", package, version)
+  urls <- c(
+    sprintf("%s/src/contrib/%s", cran, fname),
+    sprintf("%s/src/contrib/Archive/%s/%s", cran, package, fname)
+  )
+  dest <- file.path(dest_dir, fname)
+  for (u in urls) {
+    ok <- tryCatch(
+      {
+        utils::download.file(u, dest, mode = "wb", quiet = TRUE)
+        file.exists(dest) && file.size(dest) > 0L
+      },
+      error = function(e) FALSE
+    )
+    if (isTRUE(ok)) {
+      return(dest)
+    }
+  }
+  log_warn(sprintf(
+    "Could not download CRAN source for {.pkg %s} %s.",
+    package, version
+  ))
+  NULL
+}
+
+#' Apply a unified diff to an unpacked source tree
+#'
+#' Uses `patch -p1 --forward` so an already-applied or non-applying patch fails
+#' cleanly (returns FALSE) instead of corrupting the tree.
+#' @keywords internal
+apply_source_patch <- function(patch_path, pkg_src) {
+  status <- system2(
+    "patch",
+    args = c(
+      "-p1", "--forward", "--batch",
+      "-d", shQuote(pkg_src),
+      "-i", shQuote(patch_path)
+    ),
+    stdout = FALSE, stderr = FALSE
+  )
+  identical(status, 0L)
+}
+
+#' Format configure args for `pkgbuild::build(args = ...)`
+#' @keywords internal
+configure_args_to_build_args <- function(configure_args) {
+  if (length(configure_args) == 0L) {
+    return(character(0L))
+  }
+  sprintf("--configure-args=%s", paste(configure_args, collapse = " "))
+}
+
+#' Build a patched binary for one registry entry, in isolation
+#'
+#' Downloads CRAN source for `version`, applies the source patch (if any), and
+#' builds a binary with the entry's env / configure / Makevars overrides scoped
+#' to this build only. Returns the built tarball path, or `NULL` on any failure.
+#' @keywords internal
+build_patched_binary <- function(entry, version, dest_dir) {
+  workdir <- tempfile("patch_build_")
+  dir.create(workdir, recursive = TRUE, showWarnings = FALSE)
+  on.exit(unlink(workdir, recursive = TRUE, force = TRUE), add = TRUE)
+
+  src_tarball <- download_cran_source(entry$package, version, workdir)
+  if (is.null(src_tarball)) {
+    return(NULL)
+  }
+
+  utils::untar(src_tarball, exdir = workdir)
+  pkg_src <- file.path(workdir, entry$package)
+
+  if (!is.null(entry$patch_path)) {
+    if (!apply_source_patch(entry$patch_path, pkg_src)) {
+      log_warn(sprintf(
+        "Patch for {.pkg %s} %s did not apply cleanly; skipping patched build.",
+        entry$package, version
+      ))
+      return(NULL)
+    }
+  }
+
+  build_env <- entry$env
+  if (length(entry$makevars) > 0L) {
+    mk <- tempfile(fileext = ".mk")
+    writeLines(
+      vapply(
+        names(entry$makevars),
+        function(k) sprintf("%s=%s", k, entry$makevars[[k]]),
+        character(1L)
+      ),
+      mk
+    )
+    build_env$R_MAKEVARS_USER <- mk
+  }
+
+  tryCatch(
+    withr::with_envvar(build_env, {
+      pkgbuild::build(
+        path = pkg_src,
+        binary = TRUE,
+        vignettes = FALSE,
+        dest_path = dest_dir,
+        args = configure_args_to_build_args(entry$configure_args),
+        quiet = TRUE
+      )
+    }),
+    error = function(e) {
+      log_warn(sprintf(
+        "Isolated patched build of {.pkg %s} %s failed: %s",
+        entry$package, version, conditionMessage(e)
+      ))
+      NULL
+    }
+  )
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add R/patches.R tests/testthat/test-patches.R
+git commit -m "feat(patches): build a patched binary in isolation from CRAN source"
+```
+
+---
+
+### Task A5: Orchestrate the local patched repo (cache + index)
+
+**Files:**
+- Modify: `R/patches.R`
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Consumes: all helpers above.
+- Produces: `prepare_patched_repo(patches_dir, platform, arch, r_minor, cache_dir, repo_dir)` → path to a `src/contrib`-style dir containing patched binaries + a `PACKAGES` index, or `NULL` when nothing matched/built. On a cache hit it copies the cached tarball into `repo_dir`; on a miss it builds, then writes the result into `cache_dir`.
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+test_that("prepare_patched_repo returns NULL when no entries match", {
+  dir <- withr::local_tempdir()
+  jsonlite::write_json(
+    list(list(package = "A", versions = "*", platforms = list("redhat"),
+              reason = "r")),
+    file.path(dir, "registry.json"), auto_unbox = TRUE
+  )
+  expect_null(
+    prepare_patched_repo(dir, "ubuntu-2604", "amd64", "4.5",
+                         cache_dir = withr::local_tempdir(),
+                         repo_dir = withr::local_tempdir())
+  )
+})
+
+test_that("prepare_patched_repo serves a cached binary and writes an index", {
+  dir <- withr::local_tempdir()
+  jsonlite::write_json(
+    list(list(package = "glue", versions = "*", platforms = list("*"),
+              env = list(A = "1"), reason = "r")),
+    file.path(dir, "registry.json"), auto_unbox = TRUE
+  )
+  cache <- withr::local_tempdir()
+  repo <- withr::local_tempdir()
+
+  local_mocked_bindings(
+    resolve_patch_version = function(entry) "1.0.0",
+    build_patched_binary = function(entry, version, dest_dir) {
+      f <- file.path(dest_dir, sprintf("%s_%s.tar.gz", entry$package, version))
+      writeLines("fake binary", f)
+      f
+    }
+  )
+
+  out <- prepare_patched_repo(dir, "ubuntu-2604", "amd64", "4.5",
+                              cache_dir = cache, repo_dir = repo)
+
+  expect_identical(out, repo)
+  expect_true(file.exists(file.path(repo, "glue_1.0.0.tar.gz")))
+  expect_true(file.exists(file.path(repo, "PACKAGES")))
+  # The build result was cached under the key.
+  expect_length(list.files(cache, pattern = "^glue_1.0.0_.*\\.tar\\.gz$"), 1L)
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL with "could not find function prepare_patched_repo".
+
+- [ ] **Step 3: Write minimal implementation (append to `R/patches.R`)**
+
+```r
+#' Prepare a local repo of patched binaries for the current build
+#'
+#' For each registry entry matching the current platform, ensures a patched
+#' binary is present in `repo_dir` (from `cache_dir` if available, else built
+#' and then cached) and writes a `PACKAGES` index over them.
+#'
+#' @param patches_dir Directory with `registry.json`, or `NULL`.
+#' @param platform Build platform, e.g. `"ubuntu-2604"`.
+#' @param arch Build arch, e.g. `"amd64"`.
+#' @param r_minor R `"major.minor"` string, e.g. `"4.5"`.
+#' @param cache_dir Persistent cache for patched binaries.
+#' @param repo_dir Directory to assemble the local repo in.
+#' @return `repo_dir` if at least one patched binary was produced, else `NULL`.
+#' @keywords internal
+prepare_patched_repo <- function(
+  patches_dir,
+  platform,
+  arch,
+  r_minor,
+  cache_dir = file.path("/mnt", "cache", "patched-binaries"),
+  repo_dir = tempfile("patched_repo_")
+) {
+  entries <- match_patch_entries(
+    load_patch_registry(patches_dir), platform, arch
+  )
+  if (length(entries) == 0L) {
+    return(NULL)
+  }
+
+  dir.create(repo_dir, recursive = TRUE, showWarnings = FALSE)
+  dir.create(cache_dir, recursive = TRUE, showWarnings = FALSE)
+
+  produced <- 0L
+  for (entry in entries) {
+    version <- resolve_patch_version(entry)
+    if (is.na(version)) {
+      log_warn(sprintf(
+        "No CRAN version of {.pkg %s} satisfies '%s'; patch skipped.",
+        entry$package, entry$versions
+      ))
+      next
+    }
+
+    key <- patch_cache_key(entry, version, platform, arch, r_minor)
+    cached <- file.path(cache_dir, sprintf("%s.tar.gz", key))
+    target <- file.path(
+      repo_dir, sprintf("%s_%s.tar.gz", entry$package, version)
+    )
+
+    if (file.exists(cached)) {
+      log_info(sprintf(
+        "Using cached patched binary for {.pkg %s} %s.",
+        entry$package, version
+      ))
+      file.copy(cached, target, overwrite = TRUE)
+    } else {
+      log_info(sprintf(
+        "Applying patch to {.pkg %s} %s [%s]: %s",
+        entry$package, version, describe_patch(entry), entry$reason
+      ))
+      built <- build_patched_binary(entry, version, repo_dir)
+      if (is.null(built)) {
+        next
+      }
+      if (!identical(normalizePath(built), normalizePath(target))) {
+        file.copy(built, target, overwrite = TRUE)
+      }
+      file.copy(target, cached, overwrite = TRUE)
+    }
+    produced <- produced + 1L
+  }
+
+  if (produced == 0L) {
+    return(NULL)
+  }
+  cranlike::add_PACKAGES(
+    list.files(repo_dir, pattern = "\\.tar\\.gz$"),
+    repo_dir
+  )
+  repo_dir
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: PASS.
+
+- [ ] **Step 5: Update imports and document**
+
+Add to `DESCRIPTION` `Imports:` (alphabetical) `jsonlite` if not present, and ensure `pkgsearch`, `pkgbuild`, `cranlike`, `withr` are listed (they are). Then:
+
+```bash
+Rscript -e 'devtools::document()'
+git add R/patches.R tests/testthat/test-patches.R DESCRIPTION NAMESPACE
+git commit -m "feat(patches): orchestrate local patched-binary repo with caching"
+```
+
+---
+
+### Task A6: Wire patched repo into the pak install path
+
+**Files:**
+- Modify: `R/install_helpers.R:333-389` (`run_pak_install_with_mutex`)
+- Modify: `R/install-deps.R:23-75` (`install_pkg_sys_deps`)
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Consumes: `prepare_patched_repo()`.
+- Produces: `run_pak_install_with_mutex(local_clone_dir_single, env_vars, patched_repo = NULL)` — prepends `file://<patched_repo>` to `options("repos")` for the install; `install_pkg_sys_deps(package_name, tag, local_clone_dir, platform, aggressive_cleanup = FALSE, patches = NULL, arch = NULL)` — builds the patched repo before installing.
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+test_that("run_pak_install_with_mutex prepends the patched repo to repos", {
+  seen <- NULL
+  local_mocked_bindings(
+    acquire_pak_mutex = function(...) tempfile(),
+    release_pak_mutex = function(...) invisible(NULL),
+    retry_with_backoff = function(func, ...) func()
+  )
+  local_mocked_bindings(
+    local_install_deps = function(...) {
+      seen <<- getOption("repos")
+      invisible(TRUE)
+    },
+    .package = "pak"
+  )
+
+  run_pak_install_with_mutex(
+    tempfile(), list(), patched_repo = "/tmp/patched"
+  )
+
+  expect_true(any(grepl("file:///tmp/patched", seen)))
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL — `patched_repo` argument not yet accepted / repos not prepended.
+
+- [ ] **Step 3: Edit `run_pak_install_with_mutex` in `R/install_helpers.R`**
+
+Change the signature line:
+
+```r
+run_pak_install_with_mutex <- function(local_clone_dir_single, env_vars) {
+```
+
+to:
+
+```r
+run_pak_install_with_mutex <- function(
+  local_clone_dir_single,
+  env_vars,
+  patched_repo = NULL
+) {
+```
+
+Replace the inner `retry_with_backoff(...)` block (the one wrapping `pak::local_install_deps`) with:
+
+```r
+          retry_with_backoff(function() {
+            withr::with_envvar(env_vars, {
+              repos <- getOption("repos")
+              if (!is.null(patched_repo)) {
+                repos <- c(
+                  patched = sprintf("file://%s", patched_repo),
+                  repos
+                )
+              }
+              withr::with_options(list(repos = repos), {
+                # Default to non-verbose (suppressed messages)
+                suppressMessages(pak::local_install_deps(sprintf(
+                  "%s",
+                  local_clone_dir_single
+                )))
+              })
+            })
+          })
+```
+
+- [ ] **Step 4: Edit `install_pkg_sys_deps` in `R/install-deps.R`**
+
+Change the signature to add `patches` and `arch`:
+
+```r
+install_pkg_sys_deps <- function(
+  package_name,
+  tag,
+  local_clone_dir,
+  platform = platform,
+  aggressive_cleanup = FALSE,
+  patches = NULL,
+  arch = NULL
+) {
+```
+
+Immediately before the `run_pak_install_with_mutex(...)` call, insert:
+
+```r
+  # Build a local repo of patched binaries (if any apply) and serve it to pak.
+  r_minor <- paste(
+    R.version$major,
+    strsplit(R.version$minor, ".", fixed = TRUE)[[1L]][1L],
+    sep = "."
+  )
+  patched_repo <- tryCatch(
+    prepare_patched_repo(patches, platform, arch, r_minor),
+    error = function(e) {
+      log_warn(sprintf("Patch preparation failed: %s", conditionMessage(e)))
+      NULL
+    }
+  )
+```
+
+and change the call from:
+
+```r
+  run_pak_install_with_mutex(
+    local_clone_dir_single,
+    env_vars
+  )
+```
+
+to:
+
+```r
+  run_pak_install_with_mutex(
+    local_clone_dir_single,
+    env_vars,
+    patched_repo = patched_repo
+  )
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add R/install_helpers.R R/install-deps.R tests/testthat/test-patches.R
+git commit -m "feat(patches): serve patched binaries to pak during dep install"
+```
+
+---
+
+### Task A7: Thread `patches` through the public build API
+
+**Files:**
+- Modify: `R/build_binaries.R` (`build_binary_package`, `execute_package_builds`, `build_single_tag`, `handle_system_dependencies`)
+- Create: `man-roxygen/param-patches.R`
+- Test: `tests/testthat/test-patches.R`
+
+**Interfaces:**
+- Produces: `build_binary_package(..., patches = NULL)` and the internal chain each carry `patches` down to `install_pkg_sys_deps()`. `handle_system_dependencies(..., patches = NULL)` passes `patches` and `arch` through.
+
+- [ ] **Step 1: Write the failing test**
+
+```r
+test_that("handle_system_dependencies forwards patches and arch", {
+  captured <- list()
+  local_mocked_bindings(
+    install_pkg_sys_deps = function(package_name, tag, local_clone_dir_single,
+                                    platform, patches = NULL, arch = NULL) {
+      captured <<- list(patches = patches, arch = arch)
+      invisible(TRUE)
+    }
+  )
+  handle_system_dependencies(
+    "RcppParallel", "5.1.11-2", "ubuntu-2604", tempfile(), "amd64",
+    NULL, NULL, NULL, NULL, NULL, NULL, NULL,
+    patches = "local/patches"
+  )
+  expect_identical(captured$patches, "local/patches")
+  expect_identical(captured$arch, "amd64")
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'`
+Expected: FAIL — `handle_system_dependencies` has no `patches` argument.
+
+- [ ] **Step 3: Create the roxygen template**
+
+```r
+# man-roxygen/param-patches.R
+#' @param patches Optional path to a patch registry directory containing a
+#'   `registry.json` (and any referenced diff files). When set, matching
+#'   packages are pre-built as patched binaries and served to `pak` during
+#'   dependency installation. Defaults to `NULL` (no patching).
+```
+
+- [ ] **Step 4: Edit the four functions in `R/build_binaries.R`**
+
+In `build_single_tag()`'s call to `handle_system_dependencies(...)`, add `patches = patches` as the final argument, and add `patches = NULL` to `build_single_tag`'s own signature plus `#' @template param-patches` to its roxygen block.
+
+Change `handle_system_dependencies` signature to end with `metadata_db_sslmode,` then add `patches = NULL`, and change its inner `install_pkg_sys_deps(...)` call from:
+
+```r
+      install_pkg_sys_deps(
+        package_name,
+        tag,
+        local_clone_dir_single,
+        platform
+      )
+```
+
+to:
+
+```r
+      install_pkg_sys_deps(
+        package_name,
+        tag,
+        local_clone_dir_single,
+        platform,
+        patches = patches,
+        arch = arch
+      )
+```
+
+In `execute_package_builds()`, add `patches = NULL` to the signature and pass `patches = patches` into its `build_single_tag(...)` call inside `worker_function`.
+
+In `build_binary_package()`, add `patches = NULL` to the signature (after `s3_package_cache`), add `#' @template param-patches` to its roxygen, and pass `patches = patches` into the `execute_package_builds(...)` call.
+
+- [ ] **Step 5: Document, test, and run package check**
+
+Run:
+
+```bash
+Rscript -e 'devtools::document()'
+Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'
+```
+
+Expected: PASS for the new test; `man/build_binary_package.Rd` etc. regenerated.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add R/build_binaries.R man-roxygen/param-patches.R man NAMESPACE tests/testthat/test-patches.R
+git commit -m "feat(patches): thread patches argument through build_binary_package"
+```
+
+---
+
+### Task A8: End-to-end patch test (guarded) and version bump
+
+**Files:**
+- Modify: `tests/testthat/test-patches.R`
+- Modify: `DESCRIPTION` (version), `NEWS.md`
+
+**Interfaces:**
+- Produces: a guarded e2e test proving a dependent package builds when its failing dependency is patched.
+
+- [ ] **Step 1: Add the guarded e2e test**
+
+```r
+test_that("a patched dependency unblocks a dependent build (e2e)", {
+  skip_if_not(nzchar(Sys.getenv("BINCRAFT_PATCH_E2E")))
+  skip_if_offline()
+
+  patches_dir <- withr::local_tempdir()
+  jsonlite::write_json(
+    list(list(
+      package = "RcppParallel", versions = "*", platforms = list("*"),
+      env = list(RCPP_PARALLEL_USE_TBB = "0"),
+      reason = "bundled TBB fails on this toolchain"
+    )),
+    file.path(patches_dir, "registry.json"), auto_unbox = TRUE
+  )
+
+  out <- withr::local_tempdir()
+  result <- build_binary_package(
+    "rts2", tag = "latest", local_output_dir_root = out,
+    upload = FALSE, archive = FALSE, patches = patches_dir
+  )
+  expect_true(isTRUE(result) || identical(result, "skipped"))
+})
+```
+
+- [ ] **Step 2: Run the e2e test in a container**
+
+Run:
+
+```bash
+docker run --rm -e BINCRAFT_PATCH_E2E=1 -v "$PWD":/work -w /work \
+  reg.devxy.io/rpkgs/build-env-ubuntu:2604 \
+  Rscript -e 'devtools::load_all("."); testthat::test_file("tests/testthat/test-patches.R")'
+```
+
+Expected: the e2e test runs (not skipped) and PASSES; build log shows `Applying patch to RcppParallel`.
+
+- [ ] **Step 3: Bump version and changelog**
+
+In `DESCRIPTION`, bump `Version:` to `4.3.0.9999`. Prepend to `NEWS.md`:
+
+```markdown
+# bincraft 4.3.0
+
+* `build_binary_package()` gains a `patches` argument: a registry of
+  per-package env / configure / Makevars overrides and source diffs that are
+  pre-built into patched binaries and served to pak, fixing compiler- and
+  OS-specific failures (e.g. RcppParallel) including for transitive deps.
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/testthat/test-patches.R DESCRIPTION NEWS.md
+git commit -m "test(patches): guarded end-to-end test; bump to 4.3.0.9999"
+```
+
+---
+
+## Phase B — build-cran-binaries registry and wiring
+
+All Phase B paths are relative to this repo (`build-cran-binaries`). Phase B depends on a bincraft build that includes Phase A (install the updated bincraft in the build containers, or bump the pinned version in `.crow/build-all-versions-install-deps.yaml`).
+
+### Task B1: Create the patch registry with the RcppParallel entry
+
+**Files:**
+- Create: `local/patches/registry.json`
+- Create: `local/patches/README.md`
+
+**Interfaces:**
+- Produces: the curated registry consumed by bincraft's `patches` argument.
+
+- [ ] **Step 1: Write the registry**
+
+```json
+[
+  {
+    "package": "RcppParallel",
+    "versions": "*",
+    "platforms": ["alpine", "ubuntu-2604"],
+    "env": { "RCPP_PARALLEL_USE_TBB": "0" },
+    "configure_args": [],
+    "makevars": {},
+    "patch": null,
+    "reason": "bundled Intel TBB fails to build on musl and on newer toolchains (e.g. g++ 15 on ubuntu-2604); disabling TBB falls back to TinyThread"
+  }
+]
+```
+
+- [ ] **Step 2: Write the README**
+
+`local/patches/README.md` documents the schema (copy the field table from `specs/2026-06-30-package-patching-design.md`), how to add an entry, and that source diffs go in `local/patches/<pkg>/<file>.patch` referenced by the `patch` field.
+
+- [ ] **Step 3: Verify it parses**
+
+Run: `Rscript -e 'x <- jsonlite::fromJSON("local/patches/registry.json", simplifyVector = FALSE); stopifnot(length(x) == 1L, x[[1]]$package == "RcppParallel"); cat("ok\n")'`
+Expected: `ok`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add local/patches/registry.json local/patches/README.md
+git commit -m "feat(patches): add patch registry with RcppParallel TBB workaround"
+```
+
+---
+
+### Task B2: Registry validator script
+
+**Files:**
+- Create: `local/validate-patches.R`
+
+**Interfaces:**
+- Consumes: `local/patches/registry.json`.
+- Produces: a script that exits non-zero on schema violations, missing patch files, or ambiguous overlapping entries.
+
+- [ ] **Step 1: Write the validator**
+
+```r
+#!/usr/bin/env Rscript
+# Validate local/patches/registry.json: schema, referenced patch files, and
+# ambiguous overlaps. Exits 1 on any problem. Used by pre-commit and CI.
+
+dir <- "local/patches"
+registry_file <- file.path(dir, "registry.json")
+if (!file.exists(registry_file)) {
+  cat("No registry.json found; nothing to validate.\n")
+  quit(status = 0L)
+}
+
+reg <- jsonlite::fromJSON(registry_file, simplifyVector = FALSE)
+required <- c("package", "versions", "platforms", "reason")
+errs <- character(0L)
+
+for (i in seq_along(reg)) {
+  e <- reg[[i]]
+  missing <- setdiff(required, names(e))
+  if (length(missing) > 0L) {
+    errs <- c(errs, sprintf(
+      "entry %d (%s): missing %s", i,
+      if (is.null(e$package)) "?" else e$package, toString(missing)
+    ))
+  }
+  if (!is.null(e$patch)) {
+    p <- file.path(dir, e$patch)
+    if (!file.exists(p)) {
+      errs <- c(errs, sprintf("entry %d (%s): patch file '%s' missing",
+                              i, e$package, p))
+    }
+  }
+}
+
+# Ambiguous overlap: two entries for the same package with identical platforms
+# and versions.
+keys <- vapply(reg, function(e) {
+  sprintf("%s|%s|%s", e$package,
+          paste(sort(as.character(unlist(e$platforms))), collapse = ","),
+          e$versions)
+}, character(1L))
+dups <- keys[duplicated(keys)]
+if (length(dups) > 0L) {
+  errs <- c(errs, sprintf("ambiguous duplicate entries: %s", toString(unique(dups))))
+}
+
+if (length(errs) > 0L) {
+  cat("Patch registry validation FAILED:\n")
+  cat(paste0("  - ", errs, "\n"))
+  quit(status = 1L)
+}
+cat(sprintf("Patch registry OK (%d entrie(s)).\n", length(reg)))
+```
+
+- [ ] **Step 2: Run it (expect success on the B1 registry)**
+
+Run: `Rscript local/validate-patches.R`
+Expected: `Patch registry OK (1 entrie(s)).` and exit 0.
+
+- [ ] **Step 3: Run it against a broken registry (expect failure)**
+
+Run:
+
+```bash
+cp local/patches/registry.json /tmp/reg.bak
+Rscript -e 'writeLines("[{\"package\":\"X\"}]", "local/patches/registry.json")'
+Rscript local/validate-patches.R; echo "exit=$?"
+cp /tmp/reg.bak local/patches/registry.json
+```
+
+Expected: prints `validation FAILED` with a missing-field message and `exit=1`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add local/validate-patches.R
+git commit -m "feat(patches): add registry validator script"
+```
+
+---
+
+### Task B3: Hook the validator into pre-commit
+
+**Files:**
+- Modify: `.pre-commit-config.yaml`
+
+**Interfaces:**
+- Produces: a local hook that runs `local/validate-patches.R` when the registry or patch files change.
+
+- [ ] **Step 1: Add the hook**
+
+Add a `repo: local` hook entry to `.pre-commit-config.yaml`:
+
+```yaml
+  - repo: local
+    hooks:
+      - id: validate-patches
+        name: validate patch registry
+        entry: Rscript local/validate-patches.R
+        language: system
+        files: ^local/patches/
+        pass_filenames: false
+```
+
+- [ ] **Step 2: Verify the hook runs**
+
+Run: `pre-commit run validate-patches --all-files`
+Expected: hook passes (`Patch registry OK`).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .pre-commit-config.yaml
+git commit -m "ci(patches): validate patch registry in pre-commit"
+```
+
+---
+
+### Task B4: Pass `patches` through the build entry points
+
+**Files:**
+- Modify: `local/build-one.R:99-119` (the `build_binary_package` call)
+- Modify: `local/build-all.R:125-145` (the `build_binary_package` call)
+
+**Interfaces:**
+- Consumes: the new bincraft `patches` argument (Phase A) and `local/patches/`.
+- Produces: both entry points pass `patches = "local/patches"`.
+
+- [ ] **Step 1: Edit `local/build-one.R`**
+
+In the `bincraft::build_binary_package(` call, add as a new argument (e.g. after `archive = TRUE,`):
+
+```r
+    patches = "local/patches",
+```
+
+- [ ] **Step 2: Edit `local/build-all.R`**
+
+In the `bincraft::build_binary_package(` call, add:
+
+```r
+      patches = "local/patches",
+```
+
+- [ ] **Step 3: Verify the scripts still parse**
+
+Run: `Rscript -e 'invisible(parse("local/build-one.R")); invisible(parse("local/build-all.R")); cat("parse ok\n")'`
+Expected: `parse ok`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add local/build-one.R local/build-all.R
+git commit -m "feat(patches): pass patch registry to bincraft build calls"
+```
+
+---
+
+### Task B5: Document the feature in the README
+
+**Files:**
+- Modify: `README.md`
+
+**Interfaces:**
+- Produces: a short "Patching packages" section explaining the registry and linking the design spec.
+
+- [ ] **Step 1: Add a README section**
+
+Add a `## Patching packages` section after the "Build Process" section describing: why patching exists (compiler/OS-specific failures cascading via shared deps like RcppParallel), where the registry lives (`local/patches/registry.json`), the two tiers (env/configure/Makevars overrides vs source diffs), and that bincraft pre-builds patched binaries served to pak. Link `specs/2026-06-30-package-patching-design.md`.
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "docs(patches): document the package patching workflow"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Registry in this repo, passed to bincraft → Task A7 (`patches` arg), B1 (registry), B4 (wiring). ✓
+- Mechanism in bincraft (resolve → pre-build → prepend repo → install) → A4–A6. ✓
+- Both tiers, env-first → A4 (`env`, `configure_args`, `makevars`, `patch` all applied; env is the cheap default and the RcppParallel entry uses only env). ✓
+- Pre-built patched binary served from a prepended local repo → A0 proof + A5/A6. ✓
+- Cache keyed by pkg/version/platform/arch/rminor/patchhash → A3 (`patch_cache_key`) + A5 (cache use). ✓
+- S3 upload of patched binaries → **partial**: A5 caches locally only. Cross-machine S3 reuse is deferred (see note below) to keep the first cut shippable; local `/mnt/cache` reuse already removes per-dependent rebuilds within a container. Recorded as out-of-first-cut, not dropped.
+- Error handling (diff fails → skip+warn; build fails → skip+warn; no match → skip; ambiguous overlap → validation error) → A4 (`apply_source_patch` FALSE path, build tryCatch), A5 (`resolve_patch_version` NA path), B2 (overlap validation). ✓
+- Observability (log line per applied patch) → A5 (`log_info` with `describe_patch`). DB metadata recording of applied patches is deferred with S3 (same note).
+- Testing (registry parse/match, cache key, integration, failure path) → A1–A5 unit tests, A8 e2e, A4 patch-fail test. ✓
+
+**Deferred from spec (call out to user):** S3 upload/reuse of patched binaries and recording applied patches in the Postgres build-metadata row. The local `/mnt/cache/patched-binaries` cache already prevents repeated rebuilds within a container; S3 reuse across CI jobs is a follow-up. If you want it in the first cut, add a Task A5b (upload `cached` tarball to a `…/patched/` S3 slot and check there before building) and a metadata column — say so and I'll insert them.
+
+**Placeholder scan:** No TBD/TODO; every code step shows complete code. README/registry-README prose steps describe exact content to write (acceptable for docs).
+
+**Type consistency:** `prepare_patched_repo` signature is identical across A5 (definition) and A6 (call site, via defaults). `patch_cache_key(entry, version, platform, arch, r_minor)` argument order matches between A3 and A5. `run_pak_install_with_mutex(..., patched_repo)` matches between A6 definition and the A6 test. `handle_system_dependencies(..., patches)` matches between A7 edit and A7 test. `build_patched_binary(entry, version, dest_dir)` matches A4 and A5.
+
+**Open risk:** Task A0 gates the whole approach; if it fails, the documented source-serving contingency keeps every later task valid with a localized change in A4.