@kungfu-tech/buildchain 3.0.2-alpha.5 → 3.0.2-alpha.7

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.5",
+    "version": "3.0.2-alpha.7",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v3",
@@ -175,7 +175,7 @@
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes"
       ],
       "breakingDigest": "sha256:acd401cfc46450115a3763fd4b679d85f185e8757ebd52510d6262e1533df4cf",
-      "auditDigest": "sha256:8b1ff8b2487980c879eec4ffbfa2a2207e54fc76c05d010b7eb4d619685caff4"
+      "auditDigest": "sha256:68f3ad7a1d880a26be48263d9d1d12c38ff89beb08e4f744509b1ca196a889c9"
     },
     {
       "contractVersion": 1,
@@ -498,7 +498,7 @@
         "release-state SHA is recorded as a durable audit entrance"
       ],
       "breakingDigest": "sha256:b627e1b2ece9b6049517a942c5139e342e6077cdd3d8962d61cef8481b1f70ad",
-      "auditDigest": "sha256:09b0794b6d0e4bc3638f52e8d58e2eb6d6ab7efd2a2f90247c48c8fa68beda16"
+      "auditDigest": "sha256:aad90c2b39ce3fd7d2d4df5833f388c3090f5eeaecfd97d03276d375eed9459b"
     },
     {
       "contractVersion": 1,
@@ -547,7 +547,7 @@
         "prose-only public claims downgrade the release trust passport audit"
       ],
       "breakingDigest": "sha256:f0b636eb925ddbf45ff1a8872454ab7b4dd98857cac12bb75217830130e62a16",
-      "auditDigest": "sha256:09b0794b6d0e4bc3638f52e8d58e2eb6d6ab7efd2a2f90247c48c8fa68beda16"
+      "auditDigest": "sha256:aad90c2b39ce3fd7d2d4df5833f388c3090f5eeaecfd97d03276d375eed9459b"
     },
     {
       "contractVersion": 1,
@@ -719,7 +719,7 @@
         "agents can discover supported Node APIs without importing internal file paths"
       ],
       "breakingDigest": "sha256:48f925608d3e2131d90936b07dc2a30341204cae3e6e785c0f77d61ad755c945",
-      "auditDigest": "sha256:c68a2dbb92a25a2a2838f8ff72954cc5898e1383e2bd8fcfe699c2c2563912dd"
+      "auditDigest": "sha256:f9d8d42ea1aaa81e127ad0aeaacf846f944369f49d06f5ee749078aae320e0ee"
     },
     {
       "contractVersion": 1,
@@ -3362,5 +3362,5 @@
     }
   ],
   "compatibilityDigest": "sha256:008b1c5a90a787cf30106829ac7aca68ab501f6d9c375e415d9c5c6b89039f46",
-  "contractDigest": "sha256:8b3db665d04a98e1c40ff386f164525a63699fd13c345bea2bc3e09f70656a07"
+  "contractDigest": "sha256:a92b0189000ef05785d4c5097189e20856838adf94307c4174f36d5271616d16"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-27T06:15:19.437Z",
-  "publishedAt": "2026-07-27T06:15:19.437Z",
+  "generatedAt": "2026-07-27T12:02:17.639Z",
+  "publishedAt": "2026-07-27T12:02:17.639Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "edd5b7573394e8724e26a2d47500705dc9b06d9d",
+  "sourceRevision": "c0ccc4b25d65ad0e007e36d8545dfdf06853bb89",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.5",
+    "version": "3.0.2-alpha.7",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -662,7 +662,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/dev-alpha-candidate-patrol.md",
-      "digest": "sha256:ffd96da21ed6a99e01d60b6545ca4a486d6c22dbf053f717a3a2cce5c3970a28",
+      "digest": "sha256:2ec29098775cdf7f4eb80014261e437f026e05ea7a2bd6086273cdf0273bf2c2",
       "headings": [
         {
           "level": 1,
@@ -675,7 +675,7 @@
           "anchor": "reusable-workflow"
         }
       ],
-      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-26\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-26\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and PR controller for repositories\nthat promote a development branch into a protected Alpha branch. It does not\npublish Alpha. The controller reads the exact heads of both branches, walks the\nbounded development history from newest to oldest (stopping early at the Alpha\nhead), and selects the newest commit that satisfies all of these conditions:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact commit SHA succeeded;\n- the latest completed Alpha preflight for the same commit SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe selected commit can be behind the observed development head when newer\ncommits have not completed both workflows yet. The decision binds the observed\nhead, selected SHA, and count of skipped newer commits. This makes a slow native\nverification lane live under continuous development without silently treating\nan unqualified head as releasable.\n\nHistory discovery is bounded to the newest 1000 development commits. The\ncontroller then compares the selected SHA to the exact Alpha head before it can\nbe eligible, so a bounded scan cannot turn a commit outside the promotion\nancestry into a candidate.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. Once the repository has proven that its\ntwo workflow names and branch topology produce exact same-SHA evidence, it may\nset `create-pull-request: true` and `dry-run: false`.\n\nCandidate mode creates one branch named from the target branch and the first 12\ncharacters of the full source SHA. An existing branch must point to the same\nfull SHA or the run fails. The controller then creates or reuses one open pull\nrequest from that immutable branch to the protected Alpha branch.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
+      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-27\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-27\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and single-flight PR controller for\nrepositories that promote a development branch into a protected Alpha branch.\nIt does not publish Alpha. The read-only observer reads the exact heads of both\nbranches, walks the\nbounded development history from newest to oldest (stopping early at the Alpha\nhead), and selects the newest commit that satisfies all of these conditions:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact commit SHA succeeded;\n- the latest completed Alpha preflight for the same commit SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe selected commit can be behind the observed development head when newer\ncommits have not completed both workflows yet. The decision binds the observed\nhead, selected SHA, and count of skipped newer commits. This makes a slow native\nverification lane live under continuous development without silently treating\nan unqualified head as releasable.\n\nHistory discovery is bounded to the newest 1000 development commits. The\ncontroller then compares the selected SHA to the exact Alpha head before it can\nbe eligible, so a bounded scan cannot turn a commit outside the promotion\nancestry into a candidate.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed as an auditable `blocked` or `stale` observation and cannot enter\nsettlement.\n\nThe companion state is\n`kungfu-buildchain-dev-alpha-candidate-state/v1`. Its current state is one of:\n\n- `observed`: no exact candidate is currently settleable;\n- `eligible-for-settlement`: a qualified candidate exists and no managed Alpha\n  candidate PR is active;\n- `active`: exactly one managed candidate PR is open;\n- `retained-next`: an active PR remains authoritative and the newest different\n  qualified SHA is retained as `nextCandidate`;\n- `stale`: the available exact-SHA evidence pair is outside policy age; or\n- `blocked`: qualification or reconciliation failed closed.\n\nWhen a newer qualified SHA replaces an earlier `nextCandidate`, the state also\nrecords that earlier SHA as `supersededCandidate`. Every state carries exact\nrepository, source/target refs and SHAs, workflow-run evidence through the\ncandidate decision, and canonical decision/state roots.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. The reusable workflow always runs an\n`observe` job with only Actions/content/pull-request read permissions. Once the\nrepository has proven that its two workflow names and branch topology produce\nexact same-SHA evidence, it may set `settlement-authorized: true` and\n`dry-run: false`. The older `create-pull-request` input remains a compatibility\nalias for settlement authorization.\n\nThe separately permissioned `settle` job re-runs the exact observation before\nany write. With no active managed candidate, it creates one branch named from\nthe target branch and the first 12 characters of the full source SHA. An\nexisting branch must point to the same full SHA or the run fails. With one\nactive managed candidate, it only updates the machine-readable state marker in\nthat PR body so repeated events and rapid dev progress cannot create another\ncandidate PR or another heavy candidate build. Foreign human-authored Alpha PRs\nare ignored. More than one open Buildchain-managed candidate fails closed.\n\nThe PR body is the bounded durable controller state: it preserves the active\ncandidate and newest retained `nextCandidate` without introducing an always-on\nservice. Once the active PR settles or is abandoned, the next execution\nrecomputes current exact-SHA qualification and creates only the newest still\nfresh candidate. It never trusts a `workflow_run` trigger SHA as evidence.\n\nConsumers should invoke this workflow after relevant qualification workflow\ncompletion and from an offset periodic fallback. GitHub may delay scheduled\nruns, so the event path supplies low latency while the fallback supplies\nrecovery. Workflow concurrency plus the server-side open-PR reconciliation\nmakes duplicate or delayed events idempotent.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
     },
     {
       "id": "manual:github-artifact-attestation",

package/dist/site/kfd-claims.json

@@ -21,7 +21,7 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "cfabd951fad28fb421abe155733557a50c4ec5fa4ce932b8edb427388596f717",
+    "sha256": "6d778d2a4d04a1b93ed21622719e08b3fa1e149af2941e09675c66582a3ebcdd",
     "summary": {
       "cliCommandCount": 97,
       "workflowCount": 55,
@@ -228,7 +228,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "cfabd951fad28fb421abe155733557a50c4ec5fa4ce932b8edb427388596f717",
+      "sha256": "6d778d2a4d04a1b93ed21622719e08b3fa1e149af2941e09675c66582a3ebcdd",
       "summary": {
         "cliCommandCount": 97,
         "workflowCount": 55,
@@ -3913,7 +3913,7 @@
           "visibility": "public",
           "participantFacing": true,
           "public": true,
-          "inputCount": 9,
+          "inputCount": 10,
           "inputs": [
             "alpha-workflow-path",
             "buildchain-ref",
@@ -3922,6 +3922,7 @@
             "dev-workflow-path",
             "dry-run",
             "max-age-seconds",
+            "settlement-authorized",
             "source-branch",
             "target-branch"
           ],

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.5",
+    "version": "3.0.2-alpha.7",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/node-api-registry.json

@@ -450,7 +450,7 @@
       "specifier": "@kungfu-tech/buildchain/release-passport",
       "export": "./release-passport",
       "target": "./packages/core/release-passport.js",
-      "digest": "sha256:09b0794b6d0e4bc3638f52e8d58e2eb6d6ab7efd2a2f90247c48c8fa68beda16",
+      "digest": "sha256:aad90c2b39ce3fd7d2d4df5833f388c3090f5eeaecfd97d03276d375eed9459b",
       "summary": "Release passport collection, verification, explanation, and evidence APIs.",
       "capabilityGroup": "release-passport-trust",
       "audience": [

package/dist/site/page-registry.json

@@ -596,7 +596,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/dev-alpha-candidate-patrol.md",
-      "digest": "sha256:ffd96da21ed6a99e01d60b6545ca4a486d6c22dbf053f717a3a2cce5c3970a28",
+      "digest": "sha256:2ec29098775cdf7f4eb80014261e437f026e05ea7a2bd6086273cdf0273bf2c2",
       "headings": [
         {
           "level": 1,
@@ -609,7 +609,7 @@
           "anchor": "reusable-workflow"
         }
       ],
-      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-26\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-26\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and PR controller for repositories\nthat promote a development branch into a protected Alpha branch. It does not\npublish Alpha. The controller reads the exact heads of both branches, walks the\nbounded development history from newest to oldest (stopping early at the Alpha\nhead), and selects the newest commit that satisfies all of these conditions:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact commit SHA succeeded;\n- the latest completed Alpha preflight for the same commit SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe selected commit can be behind the observed development head when newer\ncommits have not completed both workflows yet. The decision binds the observed\nhead, selected SHA, and count of skipped newer commits. This makes a slow native\nverification lane live under continuous development without silently treating\nan unqualified head as releasable.\n\nHistory discovery is bounded to the newest 1000 development commits. The\ncontroller then compares the selected SHA to the exact Alpha head before it can\nbe eligible, so a bounded scan cannot turn a commit outside the promotion\nancestry into a candidate.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. Once the repository has proven that its\ntwo workflow names and branch topology produce exact same-SHA evidence, it may\nset `create-pull-request: true` and `dry-run: false`.\n\nCandidate mode creates one branch named from the target branch and the first 12\ncharacters of the full source SHA. An existing branch must point to the same\nfull SHA or the run fails. The controller then creates or reuses one open pull\nrequest from that immutable branch to the protected Alpha branch.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
+      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-27\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-27\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and single-flight PR controller for\nrepositories that promote a development branch into a protected Alpha branch.\nIt does not publish Alpha. The read-only observer reads the exact heads of both\nbranches, walks the\nbounded development history from newest to oldest (stopping early at the Alpha\nhead), and selects the newest commit that satisfies all of these conditions:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact commit SHA succeeded;\n- the latest completed Alpha preflight for the same commit SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe selected commit can be behind the observed development head when newer\ncommits have not completed both workflows yet. The decision binds the observed\nhead, selected SHA, and count of skipped newer commits. This makes a slow native\nverification lane live under continuous development without silently treating\nan unqualified head as releasable.\n\nHistory discovery is bounded to the newest 1000 development commits. The\ncontroller then compares the selected SHA to the exact Alpha head before it can\nbe eligible, so a bounded scan cannot turn a commit outside the promotion\nancestry into a candidate.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed as an auditable `blocked` or `stale` observation and cannot enter\nsettlement.\n\nThe companion state is\n`kungfu-buildchain-dev-alpha-candidate-state/v1`. Its current state is one of:\n\n- `observed`: no exact candidate is currently settleable;\n- `eligible-for-settlement`: a qualified candidate exists and no managed Alpha\n  candidate PR is active;\n- `active`: exactly one managed candidate PR is open;\n- `retained-next`: an active PR remains authoritative and the newest different\n  qualified SHA is retained as `nextCandidate`;\n- `stale`: the available exact-SHA evidence pair is outside policy age; or\n- `blocked`: qualification or reconciliation failed closed.\n\nWhen a newer qualified SHA replaces an earlier `nextCandidate`, the state also\nrecords that earlier SHA as `supersededCandidate`. Every state carries exact\nrepository, source/target refs and SHAs, workflow-run evidence through the\ncandidate decision, and canonical decision/state roots.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. The reusable workflow always runs an\n`observe` job with only Actions/content/pull-request read permissions. Once the\nrepository has proven that its two workflow names and branch topology produce\nexact same-SHA evidence, it may set `settlement-authorized: true` and\n`dry-run: false`. The older `create-pull-request` input remains a compatibility\nalias for settlement authorization.\n\nThe separately permissioned `settle` job re-runs the exact observation before\nany write. With no active managed candidate, it creates one branch named from\nthe target branch and the first 12 characters of the full source SHA. An\nexisting branch must point to the same full SHA or the run fails. With one\nactive managed candidate, it only updates the machine-readable state marker in\nthat PR body so repeated events and rapid dev progress cannot create another\ncandidate PR or another heavy candidate build. Foreign human-authored Alpha PRs\nare ignored. More than one open Buildchain-managed candidate fails closed.\n\nThe PR body is the bounded durable controller state: it preserves the active\ncandidate and newest retained `nextCandidate` without introducing an always-on\nservice. Once the active PR settles or is abandoned, the next execution\nrecomputes current exact-SHA qualification and creates only the newest still\nfresh candidate. It never trusts a `workflow_run` trigger SHA as evidence.\n\nConsumers should invoke this workflow after relevant qualification workflow\ncompletion and from an offset periodic fallback. GitHub may delay scheduled\nruns, so the event path supplies low latency while the fallback supplies\nrecovery. Workflow concurrency plus the server-side open-PR reconciliation\nmakes duplicate or delayed events idempotent.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
     },
     {
       "id": "manual:github-artifact-attestation",

package/dist/site/public-surface-audit.json

@@ -1638,22 +1638,27 @@
           "dev-workflow-path",
           "dry-run",
           "max-age-seconds",
+          "settlement-authorized",
           "source-branch",
           "target-branch"
         ],
-        "inputCount": 9,
+        "inputCount": 10,
         "secrets": [
           "promotion-token"
         ],
         "secretCount": 1,
         "outputs": [
+          "active-candidate-pr",
+          "controller-state",
           "eligible",
+          "next-candidate-sha",
           "promotion-pr",
           "result-path",
           "selected-sha",
+          "settlement-action",
           "source-lock-ref"
         ],
-        "outputCount": 5
+        "outputCount": 9
       },
       {
         "id": "dev-merge-queue-governance",
@@ -4227,8 +4232,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "0be723caa314a36a1a36b03522527eb5b13e9b741e6566ff7f6ee06958df02ca",
-    "workflowRegistryDigest": "f199eeb327027cf62d35f6c9591a6dadc16142bbecce14c562b435dc4ff2f47e",
-    "pageRegistryDigest": "962ba466e4a22e5113f8f795c76c49da66359a7fdb303ab7f9abb07b865cfa06"
+    "workflowRegistryDigest": "18405fac6ddfebd647c2ba7d3927ec666e6d43dc1913043b0334c91e2bf143f1",
+    "pageRegistryDigest": "b453877a28760e2446d5b58ee2bcbb3edd1059731a4046166ce1a4fc6649624b"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-27T06:15:19.437Z",
-  "publishedAt": "2026-07-27T06:15:19.437Z",
+  "generatedAt": "2026-07-27T12:02:17.639Z",
+  "publishedAt": "2026-07-27T12:02:17.639Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "edd5b7573394e8724e26a2d47500705dc9b06d9d",
+  "sourceRevision": "c0ccc4b25d65ad0e007e36d8545dfdf06853bb89",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.5",
+    "version": "3.0.2-alpha.7",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-27T06:15:19.437Z",
-  "publishedAt": "2026-07-27T06:15:19.437Z",
+  "generatedAt": "2026-07-27T12:02:17.639Z",
+  "publishedAt": "2026-07-27T12:02:17.639Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "edd5b7573394e8724e26a2d47500705dc9b06d9d",
+  "sourceRevision": "c0ccc4b25d65ad0e007e36d8545dfdf06853bb89",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2-alpha.5",
+    "version": "3.0.2-alpha.7",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",

package/dist/site/workflow-registry.json

@@ -1238,22 +1238,27 @@
         "dev-workflow-path",
         "dry-run",
         "max-age-seconds",
+        "settlement-authorized",
         "source-branch",
         "target-branch"
       ],
-      "inputCount": 9,
+      "inputCount": 10,
       "secrets": [
         "promotion-token"
       ],
       "secretCount": 1,
       "outputs": [
+        "active-candidate-pr",
+        "controller-state",
         "eligible",
+        "next-candidate-sha",
         "promotion-pr",
         "result-path",
         "selected-sha",
+        "settlement-action",
         "source-lock-ref"
       ],
-      "outputCount": 5,
+      "outputCount": 9,
       "surface": "repository-patrol",
       "capabilityGroup": "governance-versioning",
       "status": "active"

package/docs/dev-alpha-candidate-patrol.md

@@ -8,20 +8,21 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-07-26
+last_reviewed: 2026-07-27
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-26
+  generated_at: 2026-07-27
   visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.
   invisible_context_boundary: No credentials, private logs, or private configuration were used.
 ---
 
 # Dev to Alpha Candidate Patrol
 
-Buildchain provides a reusable observation and PR controller for repositories
-that promote a development branch into a protected Alpha branch. It does not
-publish Alpha. The controller reads the exact heads of both branches, walks the
+Buildchain provides a reusable observation and single-flight PR controller for
+repositories that promote a development branch into a protected Alpha branch.
+It does not publish Alpha. The read-only observer reads the exact heads of both
+branches, walks the
 bounded development history from newest to oldest (stopping early at the Alpha
 head), and selects the newest commit that satisfies all of these conditions:
 
@@ -45,19 +46,56 @@ The decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records th
 source and target branches and SHAs, comparison distance, workflow paths, run
 identities and attempts, completion times, URLs, policy, and a canonical decision
 root. Missing, stale, failed, duplicate, or source-mismatched evidence fails
-closed.
+closed as an auditable `blocked` or `stale` observation and cannot enter
+settlement.
+
+The companion state is
+`kungfu-buildchain-dev-alpha-candidate-state/v1`. Its current state is one of:
+
+- `observed`: no exact candidate is currently settleable;
+- `eligible-for-settlement`: a qualified candidate exists and no managed Alpha
+  candidate PR is active;
+- `active`: exactly one managed candidate PR is open;
+- `retained-next`: an active PR remains authoritative and the newest different
+  qualified SHA is retained as `nextCandidate`;
+- `stale`: the available exact-SHA evidence pair is outside policy age; or
+- `blocked`: qualification or reconciliation failed closed.
+
+When a newer qualified SHA replaces an earlier `nextCandidate`, the state also
+records that earlier SHA as `supersededCandidate`. Every state carries exact
+repository, source/target refs and SHAs, workflow-run evidence through the
+candidate decision, and canonical decision/state roots.
 
 ## Reusable workflow
 
 Call `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository
-workflow. Start with `dry-run: true`. Once the repository has proven that its
-two workflow names and branch topology produce exact same-SHA evidence, it may
-set `create-pull-request: true` and `dry-run: false`.
+workflow. Start with `dry-run: true`. The reusable workflow always runs an
+`observe` job with only Actions/content/pull-request read permissions. Once the
+repository has proven that its two workflow names and branch topology produce
+exact same-SHA evidence, it may set `settlement-authorized: true` and
+`dry-run: false`. The older `create-pull-request` input remains a compatibility
+alias for settlement authorization.
+
+The separately permissioned `settle` job re-runs the exact observation before
+any write. With no active managed candidate, it creates one branch named from
+the target branch and the first 12 characters of the full source SHA. An
+existing branch must point to the same full SHA or the run fails. With one
+active managed candidate, it only updates the machine-readable state marker in
+that PR body so repeated events and rapid dev progress cannot create another
+candidate PR or another heavy candidate build. Foreign human-authored Alpha PRs
+are ignored. More than one open Buildchain-managed candidate fails closed.
+
+The PR body is the bounded durable controller state: it preserves the active
+candidate and newest retained `nextCandidate` without introducing an always-on
+service. Once the active PR settles or is abandoned, the next execution
+recomputes current exact-SHA qualification and creates only the newest still
+fresh candidate. It never trusts a `workflow_run` trigger SHA as evidence.
 
-Candidate mode creates one branch named from the target branch and the first 12
-characters of the full source SHA. An existing branch must point to the same
-full SHA or the run fails. The controller then creates or reuses one open pull
-request from that immutable branch to the protected Alpha branch.
+Consumers should invoke this workflow after relevant qualification workflow
+completion and from an offset periodic fallback. GitHub may delay scheduled
+runs, so the event path supplies low latency while the fallback supplies
+recovery. Workflow concurrency plus the server-side open-PR reconciliation
+makes duplicate or delayed events idempotent.
 
 The workflow never moves the Alpha ref directly, merges or auto-merges the pull
 request, publishes npm, creates a Git tag or GitHub Release, or changes branch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.2-alpha.5",
+  "version": "3.0.2-alpha.7",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/release-passport.js

@@ -1170,6 +1170,7 @@ export function createReleasePassport({
   controllerReceipts = [],
   controllerReceiptReferences = [],
   githubArtifactAttestations = [],
+  checkedAt = "",
 } = {}) {
   const normalizedTag = nonEmptyString(tag, "tag");
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: normalizedTag, sourceSha, workflow });
@@ -1189,7 +1190,7 @@ export function createReleasePassport({
     ? normalizeEvidenceDocument(distTagPromotionEvidence, "distTagPromotionEvidence")
     : undefined;
   const normalizedImpact = normalizeImpactLedger(impact, { tag: normalizedTag, line });
-  const generatedAt = nowIso();
+  const generatedAt = optionalString(checkedAt) || nowIso();
   const kfd1Metadata = resolveKfd1Metadata();
   const normalizedKfd1 = kfd1?.passportSection ? kfd1 : undefined;
   const normalizedKfd3 = kfd3?.passportSection ? kfd3 : undefined;
@@ -1465,6 +1466,7 @@ export function collectGitHubReleasePassport({
   releaseJsonExtra = "",
   publishJson = "",
   workflow = {},
+  checkedAt = "",
 } = {}) {
   const release = parseJsonInput(releaseJson, {}, { cwd, label: "releaseJson" });
   const releaseExtra = parseJsonInput(releaseJsonExtra, {}, { cwd, label: "releaseJsonExtra" });
@@ -1558,6 +1560,7 @@ export function collectGitHubReleasePassport({
   ];
   const resolvedTag = tag || release.tag_name || release.name || "";
   const resolvedOutputDir = path.resolve(cwd, outputDir);
+  const resolvedCheckedAt = optionalString(checkedAt) || nowIso();
   const productMechanism = defaultProductMechanism({ repository, productName });
   const artifactEvidence = createArtifactEvidence({ assets, repository, tag: resolvedTag, sourceSha, workflow });
   const bundledPublishEvidencePath = publishEvidenceMeta.value ? "evidence.json" : "";
@@ -1585,7 +1588,7 @@ export function collectGitHubReleasePassport({
         matrixRoot: kfdSupportMatrixMeta.sha256 ? `sha256:${kfdSupportMatrixMeta.sha256}` : "",
         gateResults: kfdProductGateMetas.map((meta) => meta.value),
         expectedSourceSha: sourceSha,
-        checkedAt: nowIso(),
+        checkedAt: resolvedCheckedAt,
       })
     : undefined;
   const passport = mergeAuthoritativePassportBase(createReleasePassport({
@@ -1644,6 +1647,7 @@ export function collectGitHubReleasePassport({
     publishEvidencePath: publishEvidenceMeta.path ? path.relative(resolvedOutputDir, publishEvidenceMeta.path).split(path.sep).join("/") : "",
     transactionStatePath: transactionMeta.path ? path.relative(resolvedOutputDir, transactionMeta.path).split(path.sep).join("/") : "",
     workflow,
+    checkedAt: resolvedCheckedAt,
   }), basePassportMeta.value, { requireKfd: requireBaseKfd });
   if (bundledPublishEvidencePath) {
     passport.evidence.publishEvidence = bundledPublishEvidencePath;
@@ -1657,7 +1661,7 @@ export function collectGitHubReleasePassport({
     productMechanism,
     kfdAgentHubEvidence: kfdAgentHubEvidenceMeta.value,
     kfdSupportEvidence: kfdSupport,
-    checkedAt: nowIso(),
+    checkedAt: resolvedCheckedAt,
   });
   const files = {
     "product-mechanism.json": productMechanism,
@@ -2473,6 +2477,7 @@ export async function verifyReleasePassport({
   productMechanismLocation = "",
   kfdAgentHubEvidenceLocation = "",
   kfdSupportEvidenceLocation = "",
+  checkedAt = nowIso(),
 } = {}) {
   const passport = await readJsonFromLocation(passportLocation);
   const basePath = /^https?:\/\//.test(passportLocation) ? passportLocation : path.resolve(passportLocation);
@@ -2513,6 +2518,7 @@ export async function verifyReleasePassport({
     productMechanism,
     kfdAgentHubEvidence,
     kfdSupportEvidence,
+    checkedAt,
   });
 }
 

package/scripts/dev-alpha-candidate-patrol.mjs

@@ -3,8 +3,16 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
 import { decideChannelCandidate } from "../packages/core/channel-candidate.js";
 
+export const DEV_ALPHA_CANDIDATE_STATE_SCHEMA =
+  "kungfu-buildchain-dev-alpha-candidate-state/v1";
+const STATE_MARKER_START = "<!-- buildchain-dev-alpha-candidate-state";
+const STATE_MARKER_END = "-->";
+const LEGACY_BODY_MARKER = "Buildchain exact-source channel candidate.";
+const EXACT_SHA = /^[0-9a-f]{40}$/u;
+
 function text(value = "") {
   return String(value ?? "").trim();
 }
@@ -46,7 +54,127 @@ function integer(value, fallback) {
   return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
 }
 
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonical(item)]),
+    );
+  }
+  return value;
+}
+
+function evidenceRoot(value) {
+  return `sha256:${crypto
+    .createHash("sha256")
+    .update(JSON.stringify(canonical(value)))
+    .digest("hex")}`;
+}
+
+function candidateStateMarker(state) {
+  return `${STATE_MARKER_START}\n${JSON.stringify(state)}\n${STATE_MARKER_END}`;
+}
+
+export function parseCandidateStateMarker(bodyInput) {
+  const body = String(bodyInput || "");
+  const start = body.indexOf(STATE_MARKER_START);
+  if (start < 0) return undefined;
+  const jsonStart = body.indexOf("\n", start);
+  const end = body.indexOf(STATE_MARKER_END, jsonStart + 1);
+  if (jsonStart < 0 || end < 0)
+    throw new Error("malformed Buildchain candidate state marker");
+  const state = JSON.parse(body.slice(jsonStart + 1, end).trim());
+  if (state.schema !== DEV_ALPHA_CANDIDATE_STATE_SCHEMA)
+    throw new Error(
+      `unsupported candidate state schema ${state.schema || "<empty>"}`,
+    );
+  return state;
+}
+
+function replaceCandidateStateMarker(bodyInput, state) {
+  const body = String(bodyInput || "").trimEnd();
+  const start = body.indexOf(STATE_MARKER_START);
+  if (start < 0) return `${body}\n\n${candidateStateMarker(state)}\n`;
+  const end = body.indexOf(STATE_MARKER_END, start);
+  if (end < 0) throw new Error("malformed Buildchain candidate state marker");
+  return `${body.slice(0, start).trimEnd()}\n\n${candidateStateMarker(state)}\n`;
+}
+
+function sourceShaFromLegacyBody(bodyInput) {
+  return String(bodyInput || "").match(/- Source SHA: `([0-9a-f]{40})`/u)?.[1];
+}
+
+function targetSlug(targetBranch) {
+  return targetBranch.replace(/[^A-Za-z0-9._-]+/g, "-");
+}
+
+export function managedCandidateFromPullRequest(pullRequest, targetBranch) {
+  const body = String(pullRequest.body || "");
+  const marker = parseCandidateStateMarker(body);
+  const expectedPrefix = `buildchain/candidate/${targetSlug(targetBranch)}/`;
+  const headRef = text(pullRequest.head?.ref);
+  const baseRef = text(pullRequest.base?.ref || targetBranch);
+  if (baseRef !== targetBranch) return undefined;
+  if (marker) {
+    if (marker.targetBranch !== targetBranch)
+      throw new Error(
+        `candidate PR #${pullRequest.number} state targets ${marker.targetBranch}, not ${targetBranch}`,
+      );
+    if (!headRef.startsWith(expectedPrefix))
+      throw new Error(
+        `candidate PR #${pullRequest.number} head ${headRef} is outside ${expectedPrefix}`,
+      );
+    const sourceSha = text(marker.activeCandidate?.sourceSha);
+    if (
+      !EXACT_SHA.test(sourceSha) ||
+      headRef !== `${expectedPrefix}${sourceSha.slice(0, 12)}`
+    ) {
+      throw new Error(
+        `candidate PR #${pullRequest.number} state does not bind its exact source-lock head`,
+      );
+    }
+    return {
+      number: Number(pullRequest.number),
+      url: text(pullRequest.html_url),
+      body,
+      sourceSha,
+      sourceLockRef: headRef,
+      decisionRoot: text(marker.activeCandidate?.decisionRoot),
+      nextCandidate: marker.nextCandidate || null,
+      state: marker,
+    };
+  }
+  if (!body.includes(LEGACY_BODY_MARKER) || !headRef.startsWith(expectedPrefix))
+    return undefined;
+  const sourceSha = sourceShaFromLegacyBody(body);
+  if (!sourceSha)
+    throw new Error(
+      `legacy candidate PR #${pullRequest.number} has no exact source SHA`,
+    );
+  if (headRef !== `${expectedPrefix}${sourceSha.slice(0, 12)}`)
+    throw new Error(
+      `legacy candidate PR #${pullRequest.number} does not bind its exact source-lock head`,
+    );
+  return {
+    number: Number(pullRequest.number),
+    url: text(pullRequest.html_url),
+    body,
+    sourceSha,
+    sourceLockRef: headRef,
+    decisionRoot: "",
+    nextCandidate: null,
+    state: null,
+  };
+}
+
 export function normalizeDevAlphaPatrolOptions(options = {}) {
+  const createPullRequest = bool(
+    options.createPullRequest ??
+      process.env.BUILDCHAIN_CHANNEL_PATROL_CREATE_PR,
+    false,
+  );
   return {
     repository: repository(
       options.repository ??
@@ -82,10 +210,11 @@ export function normalizeDevAlphaPatrolOptions(options = {}) {
         process.env.BUILDCHAIN_CHANNEL_PATROL_MAX_AGE_SECONDS,
       7 * 24 * 60 * 60,
     ),
-    createPullRequest: bool(
-      options.createPullRequest ??
-        process.env.BUILDCHAIN_CHANNEL_PATROL_CREATE_PR,
-      false,
+    createPullRequest,
+    settlementAuthorized: bool(
+      options.settlementAuthorized ??
+        process.env.BUILDCHAIN_CHANNEL_PATROL_SETTLEMENT_AUTHORIZED,
+      createPullRequest,
     ),
     dryRun: bool(
       options.dryRun ?? process.env.BUILDCHAIN_CHANNEL_PATROL_DRY_RUN,
@@ -183,11 +312,118 @@ export function selectLatestQualifiedSource({
       };
     }
   }
+  const staleSuccessfulPair = sourceHistory.some((sourceSha) => {
+    const rows = requiredWorkflowPaths.map((workflow) =>
+      latestByPath.get(workflow).get(sourceSha),
+    );
+    return (
+      rows.every(
+        (run) =>
+          run?.status === "completed" &&
+          run?.conclusion === "success" &&
+          run?.head_sha === sourceSha,
+      ) &&
+      rows.some(
+        (run) =>
+          !workflowEvidenceIsFreshAndSuccessful(run, { now, maxAgeSeconds }),
+      )
+    );
+  });
+  if (staleSuccessfulPair)
+    throw new Error(
+      "same-SHA workflow evidence is stale for every qualified source commit",
+    );
   throw new Error(
     "no source commit ahead of target has fresh completed successful same-SHA workflow evidence",
   );
 }
 
+function blockedCandidateDecision({
+  options,
+  sourceSha,
+  targetSha,
+  comparison,
+  reason,
+}) {
+  const body = {
+    schema: "kungfu-buildchain-channel-candidate-decision/v1",
+    eligible: false,
+    reason: "qualification-evidence-blocked",
+    repository: options.repository,
+    source: { branch: options.sourceBranch, sha: sourceSha },
+    target: { branch: options.targetBranch, sha: targetSha },
+    comparison: {
+      status: text(comparison.status || "unknown"),
+      aheadBy: Number(comparison.ahead_by || 0),
+    },
+    blockReason: text(reason),
+    decidedAt: options.now,
+  };
+  return { ...body, decisionRoot: evidenceRoot(body) };
+}
+
+function candidateFromDecision(decision) {
+  if (!decision.eligible) return null;
+  return {
+    sourceSha: decision.source.sha,
+    sourceLockRef: decision.sourceLockRef,
+    decisionRoot: decision.decisionRoot,
+    workflowEvidence: decision.workflowEvidence,
+  };
+}
+
+function candidateStateBody({
+  options,
+  targetSha,
+  decision,
+  activeCandidate,
+  nextCandidate,
+  supersededCandidate,
+}) {
+  const body = {
+    schema: DEV_ALPHA_CANDIDATE_STATE_SCHEMA,
+    repository: options.repository,
+    sourceBranch: options.sourceBranch,
+    targetBranch: options.targetBranch,
+    targetSha,
+    activeCandidate,
+    nextCandidate,
+    observationDecisionRoot: decision.decisionRoot || null,
+    observedAt: options.now,
+    ...(supersededCandidate ? { supersededCandidate } : {}),
+  };
+  return { ...body, stateRoot: evidenceRoot(body) };
+}
+
+function pullRequestBody({
+  options,
+  observedSourceHeadSha,
+  sourceSha,
+  skippedNewerCommitCount,
+  targetSha,
+  decision,
+  state,
+}) {
+  return [
+    LEGACY_BODY_MARKER,
+    "",
+    `- Source branch: \`${options.sourceBranch}\``,
+    `- Observed source HEAD: \`${observedSourceHeadSha}\``,
+    `- Source SHA: \`${sourceSha}\``,
+    `- Skipped newer unqualified commits: \`${skippedNewerCommitCount}\``,
+    `- Target branch/head: \`${options.targetBranch}\` / \`${targetSha}\``,
+    `- Decision root: \`${decision.decisionRoot}\``,
+    ...decision.workflowEvidence.map(
+      (row) =>
+        `- ${row.workflowName}: [run ${row.runId} attempt ${row.runAttempt}](${row.url})`,
+    ),
+    "",
+    "The source-lock branch must continue to point at the exact source SHA. This patrol never merges the PR, publishes a package, creates a tag, or creates a release.",
+    "",
+    candidateStateMarker(state),
+  ].join("\n");
+}
+
 export async function runDevAlphaCandidatePatrol(
   optionsInput = {},
   clientInput,
@@ -214,6 +450,7 @@ export async function runDevAlphaCandidatePatrol(
   let comparison = headComparison;
   let workflowEvidence = [];
   let skippedNewerCommitCount = 0;
+  let qualificationError;
   if (
     headComparison.status === "ahead" &&
     Number(headComparison.ahead_by) > 0
@@ -224,71 +461,189 @@ export async function runDevAlphaCandidatePatrol(
         client.listCompletedWorkflowRuns(workflow, options.sourceBranch),
       ),
     ]);
-    const selected = selectLatestQualifiedSource({
-      sourceHistory,
-      workflowRunsByPath: new Map(
-        requiredWorkflowPaths.map((workflow, index) => [
-          workflow,
-          workflowRunSets[index],
-        ]),
-      ),
-      requiredWorkflowPaths,
-      now: options.now,
-      maxAgeSeconds: options.maxAgeSeconds,
-    });
-    sourceSha = selected.sourceSha;
-    skippedNewerCommitCount = selected.skippedNewerCommitCount;
-    workflowEvidence = selected.workflowEvidence;
-    if (sourceSha !== observedSourceHeadSha)
-      comparison = await client.compare(targetSha, sourceSha);
+    try {
+      const selected = selectLatestQualifiedSource({
+        sourceHistory,
+        workflowRunsByPath: new Map(
+          requiredWorkflowPaths.map((workflow, index) => [
+            workflow,
+            workflowRunSets[index],
+          ]),
+        ),
+        requiredWorkflowPaths,
+        now: options.now,
+        maxAgeSeconds: options.maxAgeSeconds,
+      });
+      sourceSha = selected.sourceSha;
+      skippedNewerCommitCount = selected.skippedNewerCommitCount;
+      workflowEvidence = selected.workflowEvidence;
+      if (sourceSha !== observedSourceHeadSha)
+        comparison = await client.compare(targetSha, sourceSha);
+    } catch (error) {
+      qualificationError = error;
+    }
   }
-  const decision = decideChannelCandidate({
-    repository: options.repository,
-    sourceBranch: options.sourceBranch,
-    targetBranch: options.targetBranch,
-    sourceSha,
+  const decision = qualificationError
+    ? blockedCandidateDecision({
+        options,
+        sourceSha: observedSourceHeadSha,
+        targetSha,
+        comparison: headComparison,
+        reason: qualificationError.message,
+      })
+    : decideChannelCandidate({
+        repository: options.repository,
+        sourceBranch: options.sourceBranch,
+        targetBranch: options.targetBranch,
+        sourceSha,
+        targetSha,
+        comparison: { status: comparison.status, aheadBy: comparison.ahead_by },
+        selection: {
+          mode: "latest-qualified-source-ancestor",
+          observedSourceHeadSha,
+          skippedNewerCommitCount,
+        },
+        workflowEvidence,
+        requiredWorkflowPaths,
+        maxAgeSeconds: options.maxAgeSeconds,
+        now: options.now,
+      });
+  const openPullRequests = await client.listOpenPullRequests(
+    options.targetBranch,
+  );
+  const managedCandidates = openPullRequests
+    .map((pullRequest) =>
+      managedCandidateFromPullRequest(pullRequest, options.targetBranch),
+    )
+    .filter(Boolean);
+  for (const candidate of managedCandidates) {
+    if (
+      candidate.state &&
+      (candidate.state.repository !== options.repository ||
+        candidate.state.sourceBranch !== options.sourceBranch)
+    ) {
+      throw new Error(
+        `candidate PR #${candidate.number} state does not bind ${options.repository} ${options.sourceBranch}`,
+      );
+    }
+  }
+  if (managedCandidates.length > 1) {
+    throw new Error(
+      `multiple open Buildchain candidate PRs target ${options.targetBranch}: ${managedCandidates
+        .map((candidate) => `#${candidate.number}`)
+        .join(", ")}`,
+    );
+  }
+  let activeCandidate = managedCandidates[0] || null;
+  const observedCandidate = candidateFromDecision(decision);
+  let nextCandidate = null;
+  let supersededCandidate = null;
+  let controllerState = decision.eligible
+    ? "eligible-for-settlement"
+    : qualificationError
+      ? /stale/u.test(qualificationError.message)
+        ? "stale"
+        : "blocked"
+      : "observed";
+  if (activeCandidate) {
+    controllerState = "active";
+    if (
+      observedCandidate &&
+      observedCandidate.sourceSha !== activeCandidate.sourceSha
+    ) {
+      nextCandidate = observedCandidate;
+      controllerState = "retained-next";
+    }
+    if (
+      activeCandidate.nextCandidate &&
+      activeCandidate.nextCandidate.sourceSha !== nextCandidate?.sourceSha
+    ) {
+      supersededCandidate = activeCandidate.nextCandidate;
+    }
+  }
+  let state = candidateStateBody({
+    options,
     targetSha,
-    comparison: { status: comparison.status, aheadBy: comparison.ahead_by },
-    selection: {
-      mode: "latest-qualified-source-ancestor",
-      observedSourceHeadSha,
-      skippedNewerCommitCount,
-    },
-    workflowEvidence,
-    requiredWorkflowPaths,
-    maxAgeSeconds: options.maxAgeSeconds,
-    now: options.now,
+    decision,
+    activeCandidate: activeCandidate
+      ? {
+          sourceSha: activeCandidate.sourceSha,
+          sourceLockRef: activeCandidate.sourceLockRef,
+          decisionRoot: activeCandidate.decisionRoot || null,
+          pullRequestNumber: activeCandidate.number,
+          pullRequestUrl: activeCandidate.url,
+        }
+      : null,
+    nextCandidate,
+    supersededCandidate,
   });
   let pullRequest;
-  if (decision.eligible && options.createPullRequest && !options.dryRun) {
-    await client.ensureImmutableBranch(decision.sourceLockRef, sourceSha);
-    pullRequest = await client.ensurePullRequest({
-      head: decision.sourceLockRef,
-      base: options.targetBranch,
-      title: `Promote qualified ${options.sourceBranch} candidate ${sourceSha.slice(0, 12)} to ${options.targetBranch}`,
-      body: [
-        "Buildchain exact-source channel candidate.",
-        "",
-        `- Source branch: \`${options.sourceBranch}\``,
-        `- Observed source HEAD: \`${observedSourceHeadSha}\``,
-        `- Source SHA: \`${sourceSha}\``,
-        `- Skipped newer unqualified commits: \`${skippedNewerCommitCount}\``,
-        `- Target branch/head: \`${options.targetBranch}\` / \`${targetSha}\``,
-        `- Decision root: \`${decision.decisionRoot}\``,
-        ...decision.workflowEvidence.map(
-          (row) =>
-            `- ${row.workflowName}: [run ${row.runId} attempt ${row.runAttempt}](${row.url})`,
-        ),
-        "",
-        "The source-lock branch must continue to point at the exact source SHA. This patrol never merges the PR, publishes a package, creates a tag, or creates a release.",
-      ].join("\n"),
-    });
+  let settlementAction = "none";
+  if (options.settlementAuthorized && !options.dryRun) {
+    if (activeCandidate) {
+      const nextBody = replaceCandidateStateMarker(activeCandidate.body, state);
+      if (nextBody !== activeCandidate.body) {
+        await client.updatePullRequestBody(activeCandidate.number, nextBody);
+        settlementAction = nextCandidate
+          ? supersededCandidate
+            ? "supersede-next-candidate"
+            : "retain-next-candidate"
+          : "reconcile-active-candidate";
+      }
+      pullRequest = {
+        number: activeCandidate.number,
+        html_url: activeCandidate.url,
+      };
+    } else if (decision.eligible) {
+      await client.ensureImmutableBranch(decision.sourceLockRef, sourceSha);
+      state = candidateStateBody({
+        options,
+        targetSha,
+        decision,
+        activeCandidate: observedCandidate,
+        nextCandidate: null,
+        supersededCandidate: null,
+      });
+      pullRequest = await client.ensurePullRequest({
+        head: decision.sourceLockRef,
+        base: options.targetBranch,
+        title: `Promote qualified ${options.sourceBranch} candidate ${sourceSha.slice(0, 12)} to ${options.targetBranch}`,
+        body: pullRequestBody({
+          options,
+          observedSourceHeadSha,
+          sourceSha,
+          skippedNewerCommitCount,
+          targetSha,
+          decision,
+          state,
+        }),
+      });
+      settlementAction = "create-active-candidate";
+      controllerState = "active";
+      activeCandidate = {
+        number: Number(pullRequest.number || 0),
+        url: text(pullRequest.html_url),
+        sourceSha,
+        sourceLockRef: decision.sourceLockRef,
+        decisionRoot: decision.decisionRoot,
+      };
+    }
   }
   return {
     schema: "kungfu-buildchain-dev-alpha-candidate-patrol/v1",
     dryRun: options.dryRun,
     createPullRequest: options.createPullRequest,
+    settlementAuthorized: options.settlementAuthorized,
     decision,
+    controller: {
+      schema: DEV_ALPHA_CANDIDATE_STATE_SCHEMA,
+      state: controllerState,
+      activeCandidate,
+      nextCandidate,
+      supersededCandidate,
+      settlementAction,
+      stateRoot: state.stateRoot,
+    },
     pullRequest: pullRequest || null,
   };
 }
@@ -301,6 +656,8 @@ export function createGitHubChannelCandidateClient({
   repository: repositoryInput,
   token,
   fetchImpl = globalThis.fetch,
+  sleepImpl = (milliseconds) =>
+    new Promise((resolve) => setTimeout(resolve, milliseconds)),
 }) {
   const [owner, repo] = repository(repositoryInput).split("/");
   const headers = {
@@ -313,21 +670,37 @@ export function createGitHubChannelCandidateClient({
     requestPath,
     { method = "GET", body, allow404 = false } = {},
   ) {
-    const response = await fetchImpl(`https://api.github.com${requestPath}`, {
-      method,
-      headers: Object.fromEntries(
-        Object.entries(headers).filter(([, value]) => value),
-      ),
-      body: body === undefined ? undefined : JSON.stringify(body),
-    });
-    const raw = await response.text();
-    const payload = raw ? JSON.parse(raw) : undefined;
-    if (allow404 && response.status === 404) return undefined;
-    if (!response.ok)
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+      const response = await fetchImpl(`https://api.github.com${requestPath}`, {
+        method,
+        headers: Object.fromEntries(
+          Object.entries(headers).filter(([, value]) => value),
+        ),
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+      const raw = await response.text();
+      const payload = raw ? JSON.parse(raw) : undefined;
+      if (allow404 && response.status === 404) return undefined;
+      if (response.ok) return payload;
+      const retryable = response.status === 429 || response.status >= 500;
+      if (retryable && attempt < 3) {
+        const retryAfterHeader = response.headers?.get?.("retry-after");
+        const retryAfter =
+          retryAfterHeader === null || retryAfterHeader === undefined
+            ? Number.NaN
+            : Number(retryAfterHeader);
+        await sleepImpl(
+          Number.isFinite(retryAfter) && retryAfter >= 0
+            ? Math.min(retryAfter * 1000, 10_000)
+            : attempt * 250,
+        );
+        continue;
+      }
       throw new Error(
         `GitHub API ${method} ${requestPath} failed with ${response.status}: ${payload?.message || raw}`,
       );
-    return payload;
+    }
+    throw new Error(`GitHub API ${method} ${requestPath} exhausted retries`);
   }
   return {
     async resolveBranch(ref) {
@@ -368,6 +741,19 @@ export function createGitHubChannelCandidateClient({
       }
       return commits;
     },
+    async listOpenPullRequests(base) {
+      const pullRequests = [];
+      for (let page = 1; page <= 10; page += 1) {
+        const rows = await api(
+          `/repos/${owner}/${repo}/pulls?state=open&base=${encodeURIComponent(base)}&per_page=100&page=${page}`,
+        );
+        pullRequests.push(...rows);
+        if (rows.length < 100) return pullRequests;
+      }
+      throw new Error(
+        `open pull request history for ${base} exceeds 1000 rows`,
+      );
+    },
     async ensureImmutableBranch(ref, sourceSha) {
       const current = await api(
         `/repos/${owner}/${repo}/git/ref/heads/${encodeRef(ref)}`,
@@ -396,6 +782,12 @@ export function createGitHubChannelCandidateClient({
         })
       );
     },
+    async updatePullRequestBody(number, body) {
+      return api(`/repos/${owner}/${repo}/pulls/${number}`, {
+        method: "PATCH",
+        body: { body },
+      });
+    },
   };
 }
 
@@ -406,6 +798,10 @@ function markdown(result) {
     `Eligible: \`${result.decision.eligible}\` (${result.decision.reason})`,
     `Source: \`${result.decision.source.branch}@${result.decision.source.sha}\``,
     `Target: \`${result.decision.target.branch}@${result.decision.target.sha}\``,
+    `Controller state: \`${result.controller.state}\``,
+    `Active candidate: ${result.controller.activeCandidate?.url || "none"}`,
+    `Next candidate: \`${result.controller.nextCandidate?.sourceSha || "none"}\``,
+    `Settlement action: \`${result.controller.settlementAction}\``,
     `Dry run: \`${result.dryRun}\``,
     `Pull request: ${result.pullRequest?.html_url || "not created"}`,
     "",
@@ -428,6 +824,10 @@ async function main() {
       "selected-sha": result.decision.source.sha,
       "source-lock-ref": result.decision.sourceLockRef || "",
       "promotion-pr": result.pullRequest?.html_url || "",
+      "controller-state": result.controller.state,
+      "active-candidate-pr": result.controller.activeCandidate?.url || "",
+      "next-candidate-sha": result.controller.nextCandidate?.sourceSha || "",
+      "settlement-action": result.controller.settlementAction,
     };
     fs.appendFileSync(
       process.env.GITHUB_OUTPUT,

package/scripts/generate-channel-promotion-workflow.mjs

@@ -205,6 +205,8 @@ ${publicOutputs(outputs)}
 
 permissions:
   actions: write
+  artifact-metadata: write
+  attestations: write
   checks: write
   contents: write
   id-token: write
@@ -406,6 +408,8 @@ jobs:
     uses: kungfu-systems/buildchain/${alphaRoute.workflowPath}@${alphaRoute.callRef}
     permissions:
       actions: write
+      artifact-metadata: write
+      attestations: write
       checks: write
       contents: write
       id-token: write
@@ -422,6 +426,8 @@ ${alphaForwarded}
     uses: kungfu-systems/buildchain/${stableRoute.workflowPath}@${stableRoute.callRef}
     permissions:
       actions: write
+      artifact-metadata: write
+      attestations: write
       checks: write
       contents: write
       id-token: write