fix(opencode): preserve exact-head dispatch queue position

.github/workflows/opencode-review.yml

@@ -501,6 +501,132 @@ jobs:
             exit 1
           fi
           echo "::add-mask::$app_token"
+
+          # GitHub native concurrency replaces an older pending group member
+          # even when cancel-in-progress is false, so the receiver deliberately
+          # has no lossy concurrency group. Avoid duplicate work here instead:
+          # inventory every active admission state twice so a transition cannot
+          # disappear between status queries, and collect older-head central
+          # runs for exact-identity retirement before posting the current head.
+          active_dispatch_title="OpenCode Review Dispatch ${TARGET_REPOSITORY}#${PR_NUMBER}@${HEAD_SHA}"
+          active_dispatch_prefix="OpenCode Review Dispatch ${TARGET_REPOSITORY}#${PR_NUMBER}@"
+          stale_dispatches_file="$(mktemp)"
+          same_head_found=false
+          trap 'rm -f "$helper" "$stale_dispatches_file"' EXIT
+          for inventory_pass in 1 2; do
+            for active_status in requested waiting pending queued in_progress; do
+              runs_url="repos/ContextualWisdomLab/.github/actions/workflows/opencode-review-dispatch.yml/runs?event=repository_dispatch&status=${active_status}&per_page=100"
+              if ! active_runs="$(GH_TOKEN="$app_token" gh api --paginate "$runs_url")"; then
+                echo "::error::Could not inspect active OpenCode dispatches; refusing a duplicate scheduler wake."
+                exit 1
+              fi
+              if ! same_head_active="$(jq -r -s --arg title "$active_dispatch_title" --arg status "$active_status" '
+                if all(.[]; (.workflow_runs | type) == "array")
+                  and all(
+                    .[] | .workflow_runs[];
+                    (.id | type) == "number"
+                    and .path == ".github/workflows/opencode-review-dispatch.yml"
+                    and .event == "repository_dispatch"
+                    and .status == $status
+                    and (.display_title | type) == "string"
+                  )
+                then
+                  any(
+                    .[] | .workflow_runs[];
+                    (.display_title | ascii_downcase) == ($title | ascii_downcase)
+                  )
+                else
+                  error("invalid workflow-runs response")
+                end
+              ' <<<"$active_runs")"; then
+                echo "::error::Active OpenCode dispatch data was invalid; refusing a duplicate scheduler wake."
+                exit 1
+              fi
+              case "$same_head_active" in
+                true) same_head_found=true ;;
+                false) ;;
+                *)
+                  echo "::error::Active OpenCode dispatch guard returned an invalid state."
+                  exit 1
+                  ;;
+              esac
+              jq -r -s --arg prefix "$active_dispatch_prefix" --arg title "$active_dispatch_title" '
+                .[] | .workflow_runs[]
+                | select((.display_title | ascii_downcase) | startswith($prefix | ascii_downcase))
+                | select((.display_title | ascii_downcase) != ($title | ascii_downcase))
+                | .id
+              ' <<<"$active_runs" >>"$stale_dispatches_file"
+            done
+          done
+
+          live_authority_matches() {
+            local live_pr live_head live_draft live_state
+            live_pr="$(gh api "repos/${TARGET_REPOSITORY}/pulls/${PR_NUMBER}")" || return 1
+            live_head="$(printf '%s' "$live_pr" | jq -r '.head.sha // empty')"
+            live_draft="$(printf '%s' "$live_pr" | jq -r 'if (.draft | type) == "boolean" then (.draft | tostring) else empty end')"
+            live_state="$(printf '%s' "$live_pr" | jq -r 'if (.state | type) == "string" then .state else empty end')"
+            [ "$live_state" = "open" ] && [ "$live_draft" = "false" ] &&
+              [ "${live_head,,}" = "${HEAD_SHA,,}" ]
+          }
+          if ! live_authority_matches; then
+            echo "Pull request authority changed before OpenCode dispatch; scheduler wake skipped."
+            exit 0
+          fi
+
+          while IFS= read -r stale_run_id; do
+            [ -n "$stale_run_id" ] || continue
+            if ! live_authority_matches; then
+              echo "Pull request authority changed before stale OpenCode retirement; scheduler wake skipped."
+              exit 0
+            fi
+            if ! GH_TOKEN="$app_token" gh api --method POST \
+              "repos/ContextualWisdomLab/.github/actions/runs/${stale_run_id}/cancel" >/dev/null; then
+              echo "::error::Could not cancel superseded central OpenCode dispatch ${stale_run_id}; refusing to add current-head work behind it."
+              exit 1
+            fi
+            cancellation_verified=false
+            for cancellation_attempt in 1 2 3 4 5 6; do
+              if ! stale_state="$(GH_TOKEN="$app_token" gh api \
+                "repos/ContextualWisdomLab/.github/actions/runs/${stale_run_id}" \
+                --jq '[.status // "", .conclusion // ""] | @tsv')"; then
+                echo "::error::Could not verify superseded central OpenCode dispatch ${stale_run_id} cancellation."
+                exit 1
+              fi
+              IFS=$'\t' read -r stale_status stale_conclusion <<<"$stale_state"
+              if [ "$stale_status" = "completed" ] &&
+                [ "$stale_conclusion" = "cancelled" ]; then
+                cancellation_verified=true
+                break
+              fi
+              case "$stale_status" in
+                requested|waiting|pending|queued|in_progress)
+                  ;;
+                completed)
+                  echo "::error::Superseded central OpenCode dispatch ${stale_run_id} completed with non-cancelled conclusion ${stale_conclusion:-<empty>}."
+                  exit 1
+                  ;;
+                *)
+                  echo "::error::Superseded central OpenCode dispatch ${stale_run_id} returned invalid status ${stale_status:-<empty>}."
+                  exit 1
+                  ;;
+              esac
+            done
+            if [ "$cancellation_verified" != "true" ]; then
+              echo "::error::Superseded central OpenCode dispatch ${stale_run_id} did not reach completed/cancelled after accepted cancellation."
+              exit 1
+            fi
+            echo "Verified cancelled superseded central OpenCode dispatch ${stale_run_id} after live exact-head revalidation."
+          done < <(sort -nu "$stale_dispatches_file")
+
+          if [ "$same_head_found" = "true" ]; then
+            echo "An exact-head OpenCode dispatch is already active; scheduler wake skipped after older-head retirement."
+            exit 0
+          fi
+
+          if ! live_authority_matches; then
+            echo "Pull request authority changed before OpenCode dispatch; scheduler wake skipped."
+            exit 0
+          fi
           jq -cn \
             --arg target_repository "$TARGET_REPOSITORY" \
             --arg pr_number "$PR_NUMBER" \
@@ -509,7 +635,8 @@ jobs:
             --arg pr_head_ref "$HEAD_REF" \
             --arg pr_head_sha "$HEAD_SHA" \
             --arg required_run_id "$GITHUB_RUN_ID" \
-            '{event_type:"opencode-review",client_payload:{target_repository:$target_repository,pr_number:$pr_number,pr_base_ref:$pr_base_ref,pr_base_sha:$pr_base_sha,pr_head_ref:$pr_head_ref,pr_head_sha:$pr_head_sha,required_run_id:$required_run_id}}' |
+            --argjson draft_review_only false \
+            '{event_type:"opencode-review",client_payload:{target_repository:$target_repository,pr_number:$pr_number,pr_base_ref:$pr_base_ref,pr_base_sha:$pr_base_sha,pr_head_ref:$pr_head_ref,pr_head_sha:$pr_head_sha,draft_review_only:$draft_review_only,required_run_id:$required_run_id}}' |
             GH_TOKEN="$app_token" gh api -X POST repos/ContextualWisdomLab/.github/dispatches --input -
 
       - name: Fail closed without a current-head OpenCode verdict

.github/workflows/pr-review-merge-scheduler.yml

@@ -87,8 +87,18 @@ concurrency:
     github.event_name == 'repository_dispatch' && github.event.client_payload.target_repository != '' && github.event.client_payload.pr_number != '' && format('target-{0}-pr-{1}', github.event.client_payload.target_repository, github.event.client_payload.pr_number) ||
     github.event_name == 'repository_dispatch' && github.event.client_payload.pr_number != '' && format('pr-{0}', github.event.client_payload.pr_number) ||
     github.event_name == 'repository_dispatch' && format('repo-dispatch-{0}', github.repository) ||
-    github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request_target' || github.event_name == 'pull_request_review' || github.event_name == 'repository_dispatch' }}
+    github.ref }}-${{
+    github.event_name == 'pull_request_target' && github.event.action == 'closed' && format('head-{0}-closed', github.event.pull_request.head.sha) ||
+    github.event_name == 'pull_request_target' && format('head-{0}', github.event.pull_request.head.sha) ||
+    github.event_name == 'pull_request_review' && format('head-{0}', github.event.pull_request.head.sha) ||
+    github.event_name == 'repository_dispatch' && github.event.client_payload.pr_head_sha != '' && format('head-{0}', github.event.client_payload.pr_head_sha) ||
+    'no-head' }}
+  # Preserve same-head admissions up to GitHub's documented pending limit
+  # without single-pending replacement; dispatch ordering remains
+  # platform-controlled. A new head receives a distinct group; the metadata-only
+  # cleanup job below retires only revalidated predecessor work and proves
+  # terminal cancellation.
+  queue: max
 
 # Scorecard Token-Permissions (alert #9): declare a least-privilege default at
 # the workflow level. The scan-pr-queue job that actually needs write access
@@ -98,6 +108,167 @@ permissions:
   contents: read
 
 jobs:
+  cancel-superseded-pr-runs:
+    if: >-
+      github.event_name == 'pull_request_target' &&
+      (
+        github.event.action == 'synchronize' ||
+        github.event.action == 'closed'
+      )
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      actions: write
+      contents: read
+      pull-requests: read
+    env:
+      GH_TOKEN: ${{ github.token }}
+      TARGET_REPOSITORY: ${{ github.repository }}
+      TARGET_PR_NUMBER: ${{ github.event.pull_request.number }}
+      TARGET_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      TARGET_ACTION: ${{ github.event.action }}
+    steps:
+      - name: Cancel revalidated predecessor scheduler runs
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if ! [[ "$TARGET_REPOSITORY" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]] ||
+            ! [[ "$TARGET_PR_NUMBER" =~ ^[1-9][0-9]*$ ]] ||
+            ! [[ "$TARGET_PR_HEAD_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then
+            echo "::error::Superseded-run cleanup rejected malformed target identity."
+            exit 1
+          fi
+
+          live_target_matches() {
+            local live_pull live_repository live_number live_state live_head_sha
+            live_pull="$(gh api "repos/${TARGET_REPOSITORY}/pulls/${TARGET_PR_NUMBER}")"
+            live_repository="$(jq -r '.base.repo.full_name // empty' <<<"$live_pull")"
+            live_number="$(jq -r '.number // 0' <<<"$live_pull")"
+            live_state="$(jq -r '.state // empty' <<<"$live_pull")"
+            live_head_sha="$(jq -r '.head.sha // empty' <<<"$live_pull")"
+            [ "$live_repository" = "$TARGET_REPOSITORY" ] &&
+              [ "$live_number" = "$TARGET_PR_NUMBER" ] &&
+              [ "${live_head_sha,,}" = "${TARGET_PR_HEAD_SHA,,}" ] && {
+                [ "$TARGET_ACTION:$live_state" = "synchronize:open" ] ||
+                  [ "$TARGET_ACTION:$live_state" = "closed:closed" ]
+              }
+          }
+
+          if ! live_target_matches; then
+            echo "Superseded-run cleanup skipped because the event no longer matches the live pull request."
+            exit 0
+          fi
+
+          inventory_dir="$(mktemp -d)"
+          trap 'rm -rf "$inventory_dir"' EXIT
+          : >"$inventory_dir/active-arrays.jsonl"
+          for inventory_pass in 1 2; do
+            for active_status in requested waiting pending queued in_progress; do
+              inventory_path="$inventory_dir/${inventory_pass}-${active_status}.json"
+              gh api --paginate --slurp \
+                "repos/${TARGET_REPOSITORY}/actions/workflows/pr-review-merge-scheduler.yml/runs?status=${active_status}&per_page=100" \
+                >"$inventory_path"
+              if ! inventory_counts="$(jq -er '
+                if type == "array" and length > 0
+                  and all(.[]; (.total_count | type) == "number")
+                  and all(.[]; (.workflow_runs | type) == "array")
+                then
+                  [([.[] | .workflow_runs[]] | length), (map(.total_count) | max)]
+                  | @tsv
+                else
+                  error("invalid workflow-run inventory")
+                end
+              ' "$inventory_path")"; then
+                echo "::error::Scheduler workflow-run inventory was invalid."
+                exit 1
+              fi
+              IFS=$'\t' read -r collected_count expected_count <<<"$inventory_counts"
+              if [ "$collected_count" -ne "$expected_count" ]; then
+                echo "::error::Scheduler workflow-run inventory was incomplete for ${active_status}: expected=${expected_count} collected=${collected_count}."
+                exit 1
+              fi
+              jq -c '[.[] | .workflow_runs[]]' \
+                "$inventory_path" \
+                >>"$inventory_dir/active-arrays.jsonl"
+            done
+          done
+          workflow_runs="$(jq -sc 'add // [] | unique_by(.id)' "$inventory_dir/active-arrays.jsonl")"
+          mapfile -t superseded_run_ids < <(
+            jq -r \
+              --argjson pr_number "$TARGET_PR_NUMBER" \
+              --argjson current_run_id "$GITHUB_RUN_ID" \
+              --arg target_head "${TARGET_PR_HEAD_SHA,,}" \
+              --arg target_action "$TARGET_ACTION" \
+              '
+              .[]
+              | select(.id != $current_run_id)
+              | select(
+                  .status == "requested" or
+                  .status == "waiting" or
+                  .status == "pending" or
+                  .status == "queued" or
+                  .status == "in_progress"
+                )
+              | select(
+                  any(
+                    .pull_requests[]?;
+                    (.head.sha // "" | ascii_downcase) as $run_pr_head
+                    | .number == $pr_number
+                    | select(
+                        $target_action == "closed" or
+                        (
+                          ($run_pr_head | test("^[0-9a-f]{40}$")) and
+                          $run_pr_head != $target_head
+                        )
+                      )
+                  )
+                )
+              | .id
+              ' <<<"$workflow_runs"
+          )
+
+          for run_id in "${superseded_run_ids[@]}"; do
+            if ! live_target_matches; then
+              echo "Superseded-run cleanup stopped because the target changed before cancellation."
+              exit 0
+            fi
+            if gh api --method POST \
+              "repos/${TARGET_REPOSITORY}/actions/runs/${run_id}/force-cancel" \
+              >/dev/null 2>&1; then
+              cancellation_verified=false
+              for attempt in 1 2 3 4 5 6; do
+                IFS=$'\t' read -r run_status run_conclusion < <(
+                  gh api "repos/${TARGET_REPOSITORY}/actions/runs/${run_id}" \
+                    --jq '[.status // "", .conclusion // ""] | @tsv'
+                )
+                if [ "$run_status" = "completed" ] &&
+                  [ "$run_conclusion" = "cancelled" ]; then
+                  cancellation_verified=true
+                  break
+                fi
+                if [ "$attempt" -lt 6 ]; then
+                  sleep 1
+                fi
+              done
+              if [ "$cancellation_verified" != "true" ]; then
+                echo "::error::Scheduler run $run_id did not reach completed/cancelled after accepted force-cancel."
+                exit 1
+              fi
+              echo "Verified cancelled scheduler run $run_id."
+              continue
+            fi
+            IFS=$'\t' read -r run_status run_conclusion < <(
+              gh api "repos/${TARGET_REPOSITORY}/actions/runs/${run_id}" \
+                --jq '[.status // "", .conclusion // ""] | @tsv'
+            )
+            if [ "$run_status" = "completed" ]; then
+              continue
+            fi
+            echo "::error::Could not force-cancel nonterminal scheduler run $run_id."
+            exit 1
+          done
+
   scan-pr-queue:
     # repository_dispatch review runs do not reliably carry pull_requests metadata.
     # Without this guard, one completed central review can wake a repo-wide scan.
@@ -219,6 +390,7 @@ jobs:
           GH_TOKEN: ${{ secrets.PR_REVIEW_MERGE_TOKEN || secrets.OPENCODE_APPROVE_TOKEN || steps.scheduler_app_token.outputs.token || github.token }}
           TARGET_REPOSITORY_INPUT: ${{ github.event.client_payload.target_repository || '' }}
           TARGET_PR_NUMBER: ${{ github.event.client_payload.pr_number || '' }}
+          TARGET_HEAD_SHA_INPUT: ${{ github.event.client_payload.pr_head_sha || '' }}
           TARGET_BASE_BRANCH_INPUT: ${{ github.event.client_payload.base_branch || '' }}
           ALLOWED_TARGET_REPOSITORIES: ${{ vars.OPENCODE_REPOSITORY_DISPATCH_TARGETS }}
         run: |
@@ -238,8 +410,9 @@ jobs:
             exit 1
           fi
           if ! [[ "$TARGET_REPOSITORY_INPUT" =~ ^ContextualWisdomLab/[A-Za-z0-9_.-]+$ ]] ||
-            ! [[ "$TARGET_PR_NUMBER" =~ ^[1-9][0-9]*$ ]]; then
-            printf '::error::Targeted scheduler dispatch rejected an invalid repository or pull request number. target=%s pr=%s\n' "${TARGET_REPOSITORY_INPUT:-<empty>}" "${TARGET_PR_NUMBER:-<empty>}"
+            ! [[ "$TARGET_PR_NUMBER" =~ ^[1-9][0-9]*$ ]] ||
+            ! [[ "$TARGET_HEAD_SHA_INPUT" =~ ^[0-9a-fA-F]{40}$ ]]; then
+            printf '::error::Targeted scheduler dispatch rejected invalid repository, pull request, or head identity. target=%s pr=%s head=%s\n' "${TARGET_REPOSITORY_INPUT:-<empty>}" "${TARGET_PR_NUMBER:-<empty>}" "${TARGET_HEAD_SHA_INPUT:-<empty>}"
             exit 1
           fi
 
@@ -281,6 +454,10 @@ jobs:
             printf '::error::Targeted scheduler dispatch base branch does not match the live PR. supplied=%s live=%s\n' "$TARGET_BASE_BRANCH_INPUT" "$live_base_branch"
             exit 1
           fi
+          if [ "${TARGET_HEAD_SHA_INPUT,,}" != "${live_head_sha,,}" ]; then
+            printf '::error::Targeted scheduler dispatch head does not match the live PR. supplied=%s live=%s\n' "$TARGET_HEAD_SHA_INPUT" "$live_head_sha"
+            exit 1
+          fi
 
           {
             printf 'repository=%s\n' "$TARGET_REPOSITORY_INPUT"

.github/workflows/trusted-uv-materializer-quality-ci.yml

@@ -155,7 +155,7 @@ jobs:
           python -m coverage report
 
       - name: Enforce complete production docstrings
-        run: python -m interrogate --fail-under 100 scripts/ci/materialize_base_python_requirements.py
+        run: python -m interrogate --fail-under 100 scripts/ci
 
       - name: Compile production and quality contracts
         run: |