@mokoconsulting/mokoabs-mcp 0.0.0-stage → 4.0.2

package/.mokogit/workflows/cascade.yml

@@ -0,0 +1,645 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: MokoGIT.Workflow
+# INGROUP: MokoCLI.Cascade
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
+# PATH: /.mokogit/workflows/cascade.yml
+# VERSION: 03.07.00
+# BRIEF: (03.07.00) TOPOLOGY + SERVER-CASCADE NOTE (MokoCLI #965/#967): (1) R4 dev -> child-branch pass. The workflow previously cascaded ONLY the production branch (SRC) into CASCADE_TARGETS; it now does an optional SECOND pass that cascades `dev` into a new DEV_CHILD_TARGETS variable (reusing cascade_to with SRC repointed to dev). DEV_CHILD_TARGETS DEFAULTS TO EMPTY, so this is a strict no-op for every existing repo and must be opted into per repo/org -- no fleet behaviour changes until a repo sets it. The pass is guarded by branch_exists dev and self-skips when dev is absent. dev -> child REPOS remains the SYNC engine's responsibility and is intentionally NOT done here. (2) R3 is satisfied PRIMARILY by the MokoGIT server-side cascade (the Gitea-fork notifier fires per-merge -- including on [skip ci] commits the platform skips for workflows -- and auto-merges/fan-outs/chains via the cascade rule `mode`); this workflow is the SECONDARY/fallback layer (cron reconcile + workflow_dispatch after sync). The header/`on:` comments now state that explicitly. The daily cron is UNCHANGED (left intact as the documented safety-net). --- (03.06.00) RC4 WEDGE RECOVERY: when a cascade PR's mergeability check wedges in Gitea's internal "checking" state so every /merge returns HTTP 405 "Please try again later" indefinitely (MokoGIT #1729; neither the 12x retry loop + prime_merge_status nor a close+reopen of the SAME PR recovers it), the conflict-free path now ABANDONS the stuck PR and recreates a fresh ${SRC}->${TGT} PR (the only recovery -- a brand-new PR gets a clean check task), then retries the immediate merge once; non-405 failures still short-circuit straight to notify. --- RECONCILED (03.05.01): carries BOTH divergent 03.05.00 improvements. (1) SRC=stable fix: SRC resolves to the PRODUCTION branch via branch_exists() -- `stable` if it exists, else `main` if it exists, else default_branch -- so a channel-named repo whose DEFAULT is `dev` still back-merges stable -> dev instead of cascading dev -> rc/alpha/beta the wrong direction; every PR title/body/commit/log is labelled by the RESOLVED source (chore(sync): cascade ${SRC} -> <TGT>), no more misleading literal "main". (2) composer.json conflict resolution: composer.json version conflicts are inline-resolved to version=max (via resolve_json_version), same as Makefile PROJECT_VERSION, package.json and XML manifests, so a fix/chore->stable patch bump can no longer cascade a LOWER composer.json version onto a dev already bumped ahead (the DEV VERSION NEVER REGRESSES ON CASCADE); previously composer.json fell through to the '*' deeper-resolver/human path, blocking the cascade (Mokonyx #320/#408 manual reconcile) and racing the version between channels. Cascade the production branch -> the full release ladder (dev + on-demand rc/alpha/beta). Rolls up the retired cascade-dev.yml: one job loops the ladder, cascading the source into each target that EXISTS. dev is permanent and self-heals (recreated from main if missing after an RC-rename); rc/alpha/beta are on-demand and are SKIPPED when absent (never conjured). Branch-motivated (real push to main cascades down immediately) PLUS a daily scheduled safety-net: workflow_sync.php commits to stable/main carry [skip ci] and fire NO push trigger, so if its post-sync workflow_dispatch is missed the sync commits never back-merge and stable silently forks from dev (the MokonyxLicensing 79-commit drift incident). The cron reconciles stable/main -> dev periodically regardless of [skip ci]; it is idempotent/no-op when already in sync. Auto-merge clean, auto-resolve routine conflicts INLINE (manifest version=max / .mokogit-.gitea-.github -> main / docs-stamps -> dev) with no mokocli dependency, fall back to cascade_resolve.php then notify. Resolved merges are LANDED VIA PR (temp branch + PR-merge API), never direct-pushed to a protected target (the runner token is refused by the pre-receive hook). Conflict-free path does an IMMEDIATE PR merge so a clean cascade self-completes on repos with no required status checks.
+
+name: "Cascade Main -> Ladder"
+
+on:
+  # PRIMARY per-merge guarantee (MokoCLI #965 R3) is the MokoGIT SERVER-SIDE
+  # cascade: the Gitea-fork notifier fires on EVERY merge to the production
+  # branch -- INCLUDING [skip ci] commits, which the platform skips for
+  # workflows -- and auto-merges / fans out / chains transitively per the
+  # cascade rule `mode`. THIS WORKFLOW is the SECONDARY/fallback layer only.
+  #
+  # Branch-motivated: any real push to main/stable cascades to the ladder
+  # immediately. Sync commits from workflow_sync.php carry [skip ci] and are
+  # skipped by the platform (they fire no trigger at all), so workflow_sync.php
+  # dispatches this workflow directly (workflow_dispatch) after it changes a repo
+  # -- that is what carries .mokogit drift down the ladder.
+  push:
+    branches:
+      - main
+      - stable
+  # Safety-net: a daily schedule reconciles stable/main -> dev regardless of
+  # [skip ci]. If the post-sync workflow_dispatch is ever missed, [skip ci]-only
+  # sync commits to the production branch would otherwise never back-merge and the
+  # production branch silently forks from dev (the MokonyxLicensing 79-commit
+  # drift that blocked its stable cut, back-merged in Licensing PR #160). The cron
+  # closes that gap: it is idempotent -- cascade_to() skips any target already up
+  # to date -- so a repo already in sync is a no-op. Scheduled runs execute on the
+  # repo default (production) branch, matching the existing branch-guard convention.
+  schedule:
+    - cron: '17 6 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  MOKOGIT_URL: ${{ vars.MOKOGIT_URL || 'https://git.mokoconsulting.tech' }}
+  # ntfy destination is configured via repo or org variables (org vars are inherited).
+  NTFY_URL: ${{ vars.NTFY_URL || 'https://ntfy.mokoconsulting.tech' }}
+  NTFY_TOPIC: ${{ vars.CASCADE_NTFY_TOPIC || vars.NTFY_TOPIC || 'git-releases' }}
+  # The release ladder, high -> low. main cascades into each of these that exists.
+  # `dev` is permanent (self-heals); the rest are on-demand (skipped when absent).
+  # Overridable per repo/org via the CASCADE_TARGETS variable.
+  CASCADE_TARGETS: ${{ vars.CASCADE_TARGETS || 'dev rc alpha beta' }}
+  # R4 (MokoCLI #967): optional dev -> child-BRANCH cascade targets. DEFAULTS
+  # EMPTY so this is a strict no-op unless a repo/org opts in by setting the
+  # DEV_CHILD_TARGETS variable (e.g. a repo-local integration branch that must
+  # track dev). dev -> child REPOS is the SYNC engine's job, NOT this workflow.
+  DEV_CHILD_TARGETS: ${{ vars.DEV_CHILD_TARGETS || '' }}
+
+jobs:
+  cascade:
+    name: Cascade main -> ladder
+    runs-on: ubuntu-latest
+    # Branch-guard: only run on the production branch context. push is already
+    # filtered to main/stable above; scheduled and manual runs execute against the
+    # repo default (production) branch, so require ref_name == default_branch. This
+    # never fires the cascade from a feature/dev checkout.
+    if: >-
+      github.event_name == 'push' ||
+      github.ref_name == github.event.repository.default_branch
+    steps:
+      - name: Checkout (full history for merge/resolve)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ github.token }}
+
+      - name: Cascade main -> ladder (auto-resolve routine conflicts, else notify)
+        env:
+          TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          MOKOGIT_TOKEN: ${{ github.token }}
+        run: |
+          set -uo pipefail
+          API="${MOKOGIT_URL}/api/v1/repos/${REPO}"
+          AUTH="Authorization: token ${TOKEN}"
+          jqget() { python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('$1',''))" 2>/dev/null; }
+
+          # prime_merge_status(pr): a cascade PR carries NO CI, so its head commit
+          # has zero commit statuses -> Gitea reports the combined state as "pending"
+          # (never "success"). A Do:merge on such a PR is accepted (2xx) but SCHEDULED
+          # (merge-when-checks-succeed) and then waits forever for a success that can
+          # never arrive, so the cascade PR sits open and dev never advances past
+          # stable (fleet-wide drift; MokoCLI #813). Stamp a synthetic success status
+          # on the PR head so the (possibly deferred) merge lands immediately. Best
+          # effort; never fatal. $1 = PR number.
+          prime_merge_status() {
+            local sha
+            sha=$(curl -sf -H "$AUTH" "${API}/pulls/$1" 2>/dev/null | python3 -c "import sys,json; print(json.load(sys.stdin).get('head',{}).get('sha',''))" 2>/dev/null || true)
+            [ -n "$sha" ] && curl -s -o /dev/null -H "$AUTH" -H "Content-Type: application/json" \
+              -X POST "${API}/statuses/${sha}" \
+              -d '{"state":"success","context":"cascade/auto-merge","description":"Cascade PR: no CI required; approved for auto-merge (#813)."}' || true
+          }
+
+          # recreate_cascade_pr(): wedge recovery for MokoGIT #1729 (root cause 4). A
+          # cascade PR can get its mergeability check stuck in Gitea's internal
+          # "checking" state, so every /merge returns HTTP 405 "Please try again later"
+          # indefinitely -- the 12x retry loop and prime_merge_status cannot recover it,
+          # and close+reopen of the SAME PR keeps the wedged check. The ONLY fix is to
+          # abandon the PR and open a BRAND-NEW one for the same SRC->TGT, which gets a
+          # clean check task. Closes the current ${PR}, opens a fresh ${SRC}->${TGT} PR,
+          # and updates ${PR} (caller's local; bash dynamic scope, same as notify) to
+          # the new number. Returns 0 if a new PR now exists, 1 otherwise.
+          recreate_cascade_pr() {
+            echo "::warning::cascade PR #${PR} merge wedged in Gitea 'checking' (persistent 405); abandoning it and recreating ${SRC} -> ${TGT} (MokoGIT #1729)."
+            curl -s -o /dev/null -H "$AUTH" -H "Content-Type: application/json" \
+              -X PATCH "${API}/pulls/${PR}" -d '{"state":"closed"}' || true
+            local RESP NEWPR
+            RESP=$(curl -s -H "$AUTH" -H "Content-Type: application/json" -X POST "${API}/pulls" \
+              -d "{\"head\":\"${SRC}\",\"base\":\"${TGT}\",\"title\":\"chore(sync): cascade ${SRC} -> ${TGT} (recreated)\",\"body\":\"Recreated after the prior cascade PR wedged in Gitea 'checking' (405 'Please try again later'); see MokoGIT #1729.\"}")
+            NEWPR=$(printf '%s' "$RESP" | jqget number)
+            if [ -z "$NEWPR" ]; then
+              echo "::warning::Could not recreate cascade PR for ${TGT}: $RESP"; return 1
+            fi
+            PR="$NEWPR"
+            echo "Recreated cascade PR #${PR} (${SRC} -> ${TGT})"
+            return 0
+          }
+
+          # SRC = the production branch this cascade flows FROM. Resolve it to the
+          # PRODUCTION branch, NOT default_branch: use `stable` if it exists, else
+          # `main` if it exists, else fall back to the repo default. This is the
+          # SRC=stable fix -- a channel-named repo whose DEFAULT is `dev` must still
+          # back-merge stable -> dev (+rc/alpha/beta), never cascade dev DOWN the
+          # ladder in the wrong direction. Existence is probed with the same
+          # /branches/<name> API the target loop uses (#1294 model).
+          DEFAULT_BRANCH="${{ github.event.repository.default_branch }}"
+          branch_exists() { curl -sf -H "$AUTH" "${API}/branches/$1" >/dev/null 2>&1; }
+          if branch_exists stable; then
+            SRC="stable"
+          elif branch_exists main; then
+            SRC="main"
+          else
+            SRC="${DEFAULT_BRANCH}"
+          fi
+          echo "Cascade source (production) branch: ${SRC} (default_branch=${DEFAULT_BRANCH})"
+
+          # The source must exist. A dev-only repo (no stable/main branch) has
+          # nothing to cascade FROM, so skip the whole run immediately.
+          if ! branch_exists "${SRC}"; then
+            echo "No ${SRC} branch (dev-only repo) - nothing to cascade."; exit 0
+          fi
+
+          # notify(msg): ntfy that the CURRENT target ($TGT / $PR, dynamic scope from
+          # cascade_to) needs a manual merge. $1 = context sentence.
+          notify() {
+            curl -sS \
+              -H "Title: ${REPO}: ${TGT} cascade needs manual merge" \
+              -H "Tags: warning,twisted_rightwards_arrows" \
+              -H "Priority: high" \
+              -H "Click: ${MOKOGIT_URL}/${REPO}/pulls/${PR}" \
+              -d "${SRC} -> ${TGT} cascade PR #${PR} $1 It was NOT auto-merged; resolve it manually." \
+              "${NTFY_URL}/${NTFY_TOPIC}" || true
+          }
+
+          # Land the current (already-committed) resolved merge on the protected
+          # target branch WITHOUT a direct push. The runner's github.token is refused
+          # by the target's pre-receive / branch-protection hook on a direct push, but
+          # it CAN merge a PR. So publish HEAD to a throwaway branch and land it on the
+          # target through the PR API. Reads $TGT / $PR from cascade_to (dynamic scope).
+          # $1 = note for the merge comment.
+          land_on_target_via_pr() {
+            local note="$1"
+            local tmp="cascade/auto-${TGT}-$(git rev-parse --short HEAD)"
+            # Publish the resolved merge to a throwaway branch. Prefer MOKOGIT_TOKEN
+            # (guaranteed push rights); the temp branch is NON-protected, so this does
+            # not bypass the target's protection -- the target is only ever written via
+            # the PR-merge API below. Fall back to origin (github.token) if unset.
+            local remote="origin"
+            [ -n "${MOKOGIT_TOKEN:-}" ] && remote="https://x-access-token:${MOKOGIT_TOKEN}@${MOKOGIT_URL#https://}/${REPO}.git"
+            if ! git push -f "${remote}" "HEAD:refs/heads/${tmp}"; then
+              echo "::error::Could not publish resolved merge to ${tmp}"; return 1
+            fi
+            local tpr resp
+            tpr=$(curl -sf -H "$AUTH" "${API}/pulls?state=open&base=${TGT}" \
+              | python3 -c "import sys,json; d=json.load(sys.stdin); print(next((str(p['number']) for p in d if p.get('head',{}).get('ref')=='${tmp}'), ''))" 2>/dev/null || echo "")
+            if [ -z "$tpr" ]; then
+              resp=$(curl -s -H "$AUTH" -H "Content-Type: application/json" -X POST "${API}/pulls" \
+                -d "{\"head\":\"${tmp}\",\"base\":\"${TGT}\",\"title\":\"chore(sync): cascade ${SRC} -> ${TGT} (auto-resolved)\",\"body\":\"Auto-resolved cascade merge, landed via PR (${TGT} is protected; the runner token cannot direct-push).\"}")
+              tpr=$(printf '%s' "$resp" | jqget number)
+              if [ -z "$tpr" ]; then
+                echo "::error::Could not open temp cascade PR: $resp"
+                git push "${remote}" --delete "${tmp}" >/dev/null 2>&1 || true
+                return 1
+              fi
+            fi
+            # Any failure exit from here MUST tear down ${tmp} + PR #${tpr} so a failed
+            # run does not leave orphaned cascade/auto-* branches / PRs.
+            _cleanup_tmp() {
+              curl -s -H "$AUTH" -H "Content-Type: application/json" -X PATCH "${API}/pulls/${tpr}" -d '{"state":"closed"}' >/dev/null 2>&1 || true
+              git push "${remote}" --delete "${tmp}" >/dev/null 2>&1 || true
+            }
+            local m=""
+            for _ in 1 2 3 4 5 6; do
+              m=$(curl -sf -H "$AUTH" "${API}/pulls/${tpr}" | jqget mergeable)
+              case "$m" in True|False) break ;; esac
+              sleep 3
+            done
+            if [ "$m" != "True" ]; then
+              echo "::warning::Temp cascade PR #${tpr} not mergeable (mergeable=${m}); cleaning up."
+              _cleanup_tmp
+              return 1
+            fi
+            # Prefer an IMMEDIATE merge (delete_branch_after_merge is honoured on it).
+            # Right after PR creation MokoGIT may still be computing the merge base and
+            # returns HTTP 405 "Please try again later" -- retry with backoff. Do NOT rely
+            # on merge_when_checks_succeed as the primary path: on a repo with NO required
+            # checks it waits forever for checks that never run (target never lands).
+            prime_merge_status "${tpr}"
+            local code=000 attempt
+            for attempt in $(seq 1 12); do
+              code=$(curl -s -o /tmp/tmerge.json -w "%{http_code}" -H "$AUTH" -H "Content-Type: application/json" -X POST "${API}/pulls/${tpr}/merge" -d '{"Do":"merge","delete_branch_after_merge":true}')
+              { [ "$code" -ge 200 ] && [ "$code" -lt 300 ]; } && break
+              echo "::notice::merge attempt ${attempt} for temp PR #${tpr} got HTTP ${code}; retrying in 15s"
+              sleep 15
+            done
+            if ! { [ "$code" -ge 200 ] && [ "$code" -lt 300 ]; }; then
+              code=$(curl -s -o /tmp/tmerge.json -w "%{http_code}" -H "$AUTH" -H "Content-Type: application/json" -X POST "${API}/pulls/${tpr}/merge" -d '{"Do":"merge","merge_when_checks_succeed":true,"delete_branch_after_merge":true}')
+            fi
+            if [ "$code" -ge 200 ] && [ "$code" -lt 300 ]; then
+              echo "Cascade landed on ${TGT} via PR #${tpr} (merged, or scheduled to merge+delete when checks pass)."
+              curl -s -H "$AUTH" -H "Content-Type: application/json" -X POST "${API}/issues/${tpr}/comments" \
+                -d "{\"body\":\"${note}\"}" >/dev/null 2>&1 || true
+              # The original main->TGT PR is superseded by this resolved PR.
+              [ -n "${PR:-}" ] && curl -s -H "$AUTH" -H "Content-Type: application/json" -X PATCH "${API}/pulls/${PR}" \
+                -d '{"state":"closed"}' >/dev/null 2>&1 || true
+              return 0
+            fi
+            echo "::warning::Temp cascade PR #${tpr} merge returned HTTP ${code}: $(cat /tmp/tmerge.json); cleaning up."
+            _cleanup_tmp
+            return 1
+          }
+
+          # cascade_to(target): cascade main into one ladder target. Returns 0 on
+          # success/no-op/soft-fail-notified, non-zero only on an unexpected error so
+          # the loop can flag the run. $TGT / $PR are locals visible to the helpers
+          # above via bash dynamic scoping.
+          cascade_to() {
+            local TGT="$1"
+            local PR=""
+
+            # Target existence. dev is PERMANENT and self-heals; on-demand targets
+            # (rc/alpha/beta) are SKIPPED when absent -- an on-demand branch that does
+            # not exist must not be conjured into being by the cascade.
+            if ! curl -sf -H "$AUTH" "${API}/branches/${TGT}" >/dev/null 2>&1; then
+              if [ "$TGT" = "dev" ]; then
+                # LADDER FIX (defensive): the release ladder renames `dev` -> `rc` on
+                # promote and is meant to recreate a fresh `dev` from `main`. If that
+                # recreate ever fails to land, `dev` goes missing; recreate it from
+                # `main` via the Git POST /branches CREATE endpoint (governance permits
+                # ref creation even on a protected target; NOT a protection toggle).
+                # IDEMPOTENT: only runs when `dev` is genuinely absent.
+                echo "No dev branch - recreating it from ${SRC} (ladder RC-rename recovery)."
+                local CODE
+                CODE=$(curl -s -o /tmp/cascade_recreate_dev.json -w "%{http_code}" \
+                  -H "$AUTH" -H "Content-Type: application/json" \
+                  -X POST "${API}/branches" \
+                  -d "{\"new_branch_name\":\"dev\",\"old_branch_name\":\"${SRC}\"}")
+                if [ "$CODE" -ge 200 ] && [ "$CODE" -lt 300 ]; then
+                  echo "Recreated dev from ${SRC} (HTTP ${CODE}); continuing cascade."
+                else
+                  echo "::warning::Could not recreate dev from ${SRC} (HTTP ${CODE}): $(cat /tmp/cascade_recreate_dev.json 2>/dev/null)"
+                  echo "No dev branch and recreate failed - nothing to cascade to dev."; return 0
+                fi
+              else
+                echo "On-demand target '${TGT}' does not exist - skipping."; return 0
+              fi
+            fi
+
+            # 1. is main ahead of TGT?  Resolve BOTH sides to their BRANCH head SHAs
+            # first: the channel-named branch model (#1294) allows a same-named TAG
+            # (alpha/beta/stable exist as both a release tag AND a branch), and Gitea's
+            # compare resolves a bare ref as branch-OR-tag — so `compare/${TGT}...main`
+            # could measure against the like-named TAG and silently skip a needed
+            # cascade. The /branches/<name> API is branch-scoped, so its .commit.id is
+            # unambiguous; comparing by SHA can't be fooled by a same-named tag.
+            local AHEAD TGT_SHA MAIN_SHA
+            TGT_SHA=$(curl -sf -H "$AUTH" "${API}/branches/${TGT}" \
+              | python3 -c "import sys,json; print(json.load(sys.stdin).get('commit',{}).get('id',''))" 2>/dev/null || echo "")
+            MAIN_SHA=$(curl -sf -H "$AUTH" "${API}/branches/${SRC}" \
+              | python3 -c "import sys,json; print(json.load(sys.stdin).get('commit',{}).get('id',''))" 2>/dev/null || echo "")
+            if [ -z "$TGT_SHA" ] || [ -z "$MAIN_SHA" ]; then
+              echo "::warning::Could not resolve branch SHAs for ${TGT}/main — skipping cascade this run."; return 0
+            fi
+            AHEAD=$(curl -sf -H "$AUTH" "${API}/compare/${TGT_SHA}...${MAIN_SHA}" \
+              | python3 -c "import sys,json; print(json.load(sys.stdin).get('total_commits',0))" 2>/dev/null || echo 0)
+            if [ "${AHEAD:-0}" -eq 0 ]; then
+              echo "${TGT} already up to date with main."; return 0
+            fi
+            echo "main is ${AHEAD} commit(s) ahead of ${TGT}."
+
+            # 2. reuse an open main->TGT PR, else create one
+            PR=$(curl -sf -H "$AUTH" "${API}/pulls?state=open&base=${TGT}" \
+              | python3 -c "import sys,json; d=json.load(sys.stdin); print(next((str(p['number']) for p in d if p.get('head',{}).get('ref')=='${SRC}'), ''))" 2>/dev/null || echo "")
+            if [ -z "$PR" ]; then
+              local RESP
+              RESP=$(curl -s -H "$AUTH" -H "Content-Type: application/json" -X POST "${API}/pulls" \
+                -d "{\"head\":\"${SRC}\",\"base\":\"${TGT}\",\"title\":\"chore(sync): cascade ${SRC} -> ${TGT}\",\"body\":\"Automated cascade of ${SRC} into ${TGT}. Auto-merges when conflict-free, auto-resolves VERSION-stamp-only conflicts, otherwise left open for manual resolution.\"}")
+              PR=$(printf '%s' "$RESP" | jqget number)
+              if [ -z "$PR" ]; then
+                echo "::warning::Could not open cascade PR for ${TGT}: $RESP"; return 0
+              fi
+              echo "Opened cascade PR #${PR} (${SRC} -> ${TGT})"
+            else
+              echo "Reusing open cascade PR #${PR} (${SRC} -> ${TGT})"
+            fi
+
+            # 3. wait for MokoGIT to compute mergeability (conflict detection)
+            local MERGEABLE=""
+            for _ in 1 2 3 4 5 6; do
+              MERGEABLE=$(curl -sf -H "$AUTH" "${API}/pulls/${PR}" | jqget mergeable)
+              case "$MERGEABLE" in True|False) break ;; esac
+              sleep 3
+            done
+            echo "mergeable=${MERGEABLE}"
+
+            # 4a. conflict-free -> IMMEDIATE merge via API (retry 405 "try again later";
+            # only fall back to merge_when_checks_succeed if genuinely refused).
+            if [ "$MERGEABLE" = "True" ]; then
+              # Ensure the head has a passing status so Do:merge lands now, not deferred.
+              prime_merge_status "${PR}"
+              local CODE=000 attempt
+              for attempt in $(seq 1 12); do
+                CODE=$(curl -s -o /tmp/merge.json -w "%{http_code}" -H "$AUTH" -H "Content-Type: application/json" \
+                  -X POST "${API}/pulls/${PR}/merge" -d '{"Do":"merge"}')
+                { [ "$CODE" -ge 200 ] && [ "$CODE" -lt 300 ]; } && break
+                echo "::notice::merge attempt ${attempt} for cascade PR #${PR} got HTTP ${CODE}; retrying in 15s"
+                sleep 15
+              done
+              # Persistent 405 "Please try again later" across the whole retry loop ==
+              # the PR's mergeability check is wedged in Gitea's "checking" state
+              # (MokoGIT #1729 RC4). Recreating the PR is the ONLY recovery: close the
+              # wedged one, open a fresh ${SRC}->${TGT} PR, re-check mergeability, and
+              # retry the immediate merge ONCE on the new PR before any other fallback.
+              # Non-405 failures short-circuit this and fall straight through to notify.
+              if ! { [ "$CODE" -ge 200 ] && [ "$CODE" -lt 300 ]; } \
+                 && [ "$CODE" = "405" ] && grep -q "Please try again later" /tmp/merge.json 2>/dev/null \
+                 && recreate_cascade_pr; then
+                local MERGEABLE2=""
+                for _ in 1 2 3 4 5 6; do
+                  MERGEABLE2=$(curl -sf -H "$AUTH" "${API}/pulls/${PR}" | jqget mergeable)
+                  case "$MERGEABLE2" in True|False) break ;; esac
+                  sleep 3
+                done
+                if [ "$MERGEABLE2" = "True" ]; then
+                  prime_merge_status "${PR}"
+                  for attempt in $(seq 1 12); do
+                    CODE=$(curl -s -o /tmp/merge.json -w "%{http_code}" -H "$AUTH" -H "Content-Type: application/json" \
+                      -X POST "${API}/pulls/${PR}/merge" -d '{"Do":"merge"}')
+                    { [ "$CODE" -ge 200 ] && [ "$CODE" -lt 300 ]; } && break
+                    echo "::notice::merge attempt ${attempt} for recreated cascade PR #${PR} got HTTP ${CODE}; retrying in 15s"
+                    sleep 15
+                  done
+                fi
+              fi
+              # Still not merged -> last-resort deferred merge (merge-when-checks-succeed).
+              if ! { [ "$CODE" -ge 200 ] && [ "$CODE" -lt 300 ]; }; then
+                CODE=$(curl -s -o /tmp/merge.json -w "%{http_code}" -H "$AUTH" -H "Content-Type: application/json" \
+                  -X POST "${API}/pulls/${PR}/merge" -d '{"Do":"merge","merge_when_checks_succeed":true}')
+              fi
+              if [ "$CODE" -ge 200 ] && [ "$CODE" -lt 300 ]; then
+                echo "Cascade PR #${PR} merged (or scheduled to merge when checks pass)."
+                return 0
+              fi
+              echo "::warning::Auto-merge returned HTTP ${CODE}: $(cat /tmp/merge.json)"
+              notify "could not be auto-merged (HTTP ${CODE})."
+              return 0
+            fi
+
+            # 4b. conflicts -> try to auto-resolve if they are ONLY routine classes.
+            echo "PR not cleanly mergeable; checking whether conflicts are auto-resolvable..."
+            git config user.name  "MokoGIT Cascade"
+            git config user.email "actions@mokoconsulting.tech"
+            # Fetch the BRANCH refs explicitly (refs/heads/...): the channel-named
+            # branch model (#1294) allows a tag and a branch to share a name (e.g. a
+            # `stable`/`rc` release tag alongside the branch), so a bare `git fetch
+            # origin ${SRC} ${TGT}` could resolve to the same-named TAG and poison
+            # origin/${TGT} + the merge below. Pin refs/heads/* into the remote-tracking
+            # refs so only branches are considered.
+            git fetch --quiet origin \
+              "+refs/heads/${SRC}:refs/remotes/origin/${SRC}" \
+              "+refs/heads/${TGT}:refs/remotes/origin/${TGT}"
+            git checkout -B "${TGT}" "origin/${TGT}"
+
+            if git merge --no-ff --no-commit "origin/${SRC}" >/dev/null 2>&1; then
+              # Became clean at git level (e.g. mergeability was still computing).
+              git commit -m "chore(sync): cascade ${SRC} -> ${TGT} [skip ci]" >/dev/null
+              if land_on_target_via_pr "Cascade merged cleanly at git level and landed on ${TGT} via PR."; then return 0; fi
+              notify "merged cleanly but could not be landed on ${TGT} via PR."
+              return 0
+            fi
+
+            local CONFLICTS
+            CONFLICTS=$(git diff --name-only --diff-filter=U)
+            echo "Conflicted files:"; echo "${CONFLICTS}"
+
+            # --- Inline resolver (pure bash/git, NO mokocli dependency) -------------
+            #   * manifest <version> conflicts (*.xml with <extension) -> version =
+            #       max(TGT, main) via `sort -V`, preserving the file's indentation.
+            #   * .mokogit/** .gitea/** .github/** -> take main/canonical (--theirs).
+            #   * docs / CHANGELOG / stamp files    -> keep TGT            (--ours).
+            # Anything still conflicted falls through to cascade_resolve.php then human.
+            resolve_manifest_version() {
+              local f="$1"
+              local nonver
+              nonver=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                (c==1||c==2) && $0 !~ /<version>[^<]*<\/version>/ {print "X"}
+              ' "$f")
+              [ -n "$nonver" ] && return 1
+              local ours theirs maxv
+              ours=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                c==1' "$f" | sed -n 's/.*<version>\([^<]*\)<\/version>.*/\1/p' | head -n1)
+              theirs=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                c==2' "$f" | sed -n 's/.*<version>\([^<]*\)<\/version>.*/\1/p' | head -n1)
+              [ -z "$ours" ] && [ -z "$theirs" ] && return 1
+              maxv=$(printf '%s\n%s\n' "$ours" "$theirs" | grep -v '^$' | sort -V | tail -n1)
+              [ -z "$maxv" ] && return 1
+              awk -v maxv="$maxv" '
+                /^<<<<<<< /{c=1;next}
+                /^=======$/{c=2;next}
+                /^>>>>>>> /{c=0;next}
+                {
+                  if (c==2) next
+                  if (($0 ~ /<version>[^<]*<\/version>/) && (c==1)) {
+                    sub(/<version>[^<]*<\/version>/, "<version>" maxv "</version>")
+                  }
+                  print
+                }' "$f" > "${f}.resolved" && mv "${f}.resolved" "$f"
+              ! grep -qE '^(<<<<<<< |=======$|>>>>>>> )' "$f"
+            }
+
+            # resolve_makefile_version: auto-resolve a Makefile conflict whose ONLY
+            # conflicting content is the PROJECT_VERSION assignment, taking
+            # version = max(TGT, main) via `sort -V`. This closes the strand-dev gap:
+            # a version change that reaches the production branch out of band (e.g. a
+            # hotfix bump made directly on stable, bypassing bump-on-dev) can now
+            # cascade back to dev instead of parking an unresolved conflict.
+            resolve_makefile_version() {
+              local f="$1"
+              local nonver
+              nonver=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                (c==1||c==2) && $0 !~ /^[ \t]*PROJECT_VERSION[ \t]*[:?]*=/ {print "X"}
+              ' "$f")
+              [ -n "$nonver" ] && return 1
+              local ours theirs maxv
+              ours=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                c==1' "$f" | sed -n 's/^[ \t]*PROJECT_VERSION[ \t]*[:?]*=[ \t]*\([0-9][0-9.]*\).*/\1/p' | head -n1)
+              theirs=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                c==2' "$f" | sed -n 's/^[ \t]*PROJECT_VERSION[ \t]*[:?]*=[ \t]*\([0-9][0-9.]*\).*/\1/p' | head -n1)
+              [ -z "$ours" ] && [ -z "$theirs" ] && return 1
+              maxv=$(printf '%s\n%s\n' "$ours" "$theirs" | grep -v '^$' | sort -V | tail -n1)
+              [ -z "$maxv" ] && return 1
+              awk -v maxv="$maxv" '
+                /^<<<<<<< /{c=1;next}
+                /^=======$/{c=2;next}
+                /^>>>>>>> /{c=0;next}
+                {
+                  if (c==2) next
+                  if (($0 ~ /^[ \t]*PROJECT_VERSION[ \t]*[:?]*=/) && (c==1)) {
+                    sub(/[0-9][0-9.]*[0-9]/, maxv)
+                  }
+                  print
+                }' "$f" > "${f}.resolved" && mv "${f}.resolved" "$f"
+              ! grep -qE '^(<<<<<<< |=======$|>>>>>>> )' "$f"
+            }
+
+            # resolve_json_version: same idea for a package.json conflict whose ONLY
+            # conflicting content is the top-level "version" field -> version = max.
+            resolve_json_version() {
+              local f="$1"
+              local nonver
+              nonver=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                (c==1||c==2) && $0 !~ /"version"[ \t]*:/ {print "X"}
+              ' "$f")
+              [ -n "$nonver" ] && return 1
+              local ours theirs maxv
+              ours=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                c==1' "$f" | sed -n 's/.*"version"[ \t]*:[ \t]*"\([^"]*\)".*/\1/p' | head -n1)
+              theirs=$(awk '
+                /^<<<<<<< /{c=1;next} /^=======$/{c=2;next} /^>>>>>>> /{c=0;next}
+                c==2' "$f" | sed -n 's/.*"version"[ \t]*:[ \t]*"\([^"]*\)".*/\1/p' | head -n1)
+              [ -z "$ours" ] && [ -z "$theirs" ] && return 1
+              maxv=$(printf '%s\n%s\n' "$ours" "$theirs" | grep -v '^$' | sort -V | tail -n1)
+              [ -z "$maxv" ] && return 1
+              awk -v maxv="$maxv" '
+                /^<<<<<<< /{c=1;next}
+                /^=======$/{c=2;next}
+                /^>>>>>>> /{c=0;next}
+                {
+                  if (c==2) next
+                  if (($0 ~ /"version"[ \t]*:/) && (c==1)) {
+                    sub(/"[0-9][^"]*"/, "\"" maxv "\"")
+                  }
+                  print
+                }' "$f" > "${f}.resolved" && mv "${f}.resolved" "$f"
+              ! grep -qE '^(<<<<<<< |=======$|>>>>>>> )' "$f"
+            }
+
+            local f
+            for f in ${CONFLICTS}; do
+              case "$f" in
+                .mokogit/*|.gitea/*|.github/*)
+                  git checkout --theirs -- "$f" && git add -- "$f" \
+                    && echo "resolved (theirs/main): $f" ;;
+                *CHANGELOG*|*/docs/*|docs/*|*.md|*VERSION*|*.stamp)
+                  git checkout --ours -- "$f" && git add -- "$f" \
+                    && echo "resolved (ours/${TGT}): $f" ;;
+                *.xml)
+                  if grep -q '<extension' "$f" 2>/dev/null && resolve_manifest_version "$f"; then
+                    git add -- "$f"; echo "resolved (manifest version=max): $f"
+                  else
+                    echo "unresolved (xml, not a simple version stamp): $f"
+                  fi ;;
+                Makefile|*/Makefile)
+                  if resolve_makefile_version "$f"; then
+                    git add -- "$f"; echo "resolved (Makefile PROJECT_VERSION=max): $f"
+                  else
+                    echo "unresolved (Makefile, not a simple version bump): $f"
+                  fi ;;
+                package.json|*/package.json)
+                  if resolve_json_version "$f"; then
+                    git add -- "$f"; echo "resolved (package.json version=max): $f"
+                  else
+                    echo "unresolved (package.json, not a simple version bump): $f"
+                  fi ;;
+                composer.json|*/composer.json)
+                  if resolve_json_version "$f"; then
+                    git add -- "$f"; echo "resolved (composer.json version=max): $f"
+                  else
+                    echo "unresolved (composer.json, not a simple version bump): $f"
+                  fi ;;
+                *)
+                  echo "unresolved (needs deeper resolver): $f" ;;
+              esac
+            done
+
+            # If the inline pass cleared every conflict, land it -- no mokocli needed.
+            if [ -z "$(git diff --name-only --diff-filter=U)" ]; then
+              git commit -m "chore(sync): cascade ${SRC} -> ${TGT} (auto-resolved inline) [skip ci]" >/dev/null
+              if land_on_target_via_pr "Cascade auto-resolved inline (manifest version=max(${TGT},main), .mokogit/.gitea/.github -> main, docs/stamps -> ${TGT}) with no mokocli dependency, and landed on ${TGT} via PR."; then return 0; fi
+              notify "was auto-resolved inline but could not be landed on ${TGT} via PR."
+              return 0
+            fi
+
+            echo "Inline pass left conflicts; falling back to cascade_resolve.php..."
+            echo "Still conflicted:"; git diff --name-only --diff-filter=U
+
+            # --- Fallback: cascade_resolve.php (existing behaviour) -----------------
+            # BAILS (exit 2) on real code conflicts, so those still get a human.
+            # Standard mokocli install: FRESH from the MokoGIT Composer registry
+            # (PRIMARY); /opt/mokocli is a FAILSAFE only (may be stale). Registry path
+            # /api/packages/** is anon-allowlisted. git clone is the last resort.
+            local RESOLVER=""
+            local REG='{"type":"composer","url":"https://git.mokoconsulting.tech/api/packages/MokoConsulting/composer"}'
+            if ! command -v composer >/dev/null 2>&1; then
+              sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer >/dev/null 2>&1 || true
+            fi
+            rm -rf /tmp/mokocli
+            if command -v composer >/dev/null 2>&1 \
+               && composer create-project --no-install --no-interaction --no-progress --quiet \
+                    --repository="${REG}" mokoconsulting/mokocli /tmp/mokocli >/dev/null 2>&1 \
+               && [ -f /tmp/mokocli/cli/cascade_resolve.php ]; then
+              RESOLVER=/tmp/mokocli/cli/cascade_resolve.php
+              if command -v sudo >/dev/null 2>&1 && [ -d /opt/mokocli ] \
+                 && ! cmp -s /tmp/mokocli/cli/version_reset_dev.php /opt/mokocli/cli/version_reset_dev.php 2>/dev/null; then
+                sudo cp -a /tmp/mokocli/. /opt/mokocli/ 2>/dev/null || true
+              fi
+            elif [ -f /opt/mokocli/cli/cascade_resolve.php ]; then
+              echo "::warning::registry install failed — using /opt/mokocli FAILSAFE cascade_resolve.php (may be stale)"
+              RESOLVER=/opt/mokocli/cli/cascade_resolve.php
+            elif git clone --depth 1 --quiet \
+                   "https://x-access-token:${MOKOGIT_TOKEN}@${MOKOGIT_URL#https://}/MokoConsulting/mokocli.git" \
+                   /tmp/mokocli 2>/dev/null \
+                 || git clone --depth 1 --quiet "${MOKOGIT_URL}/MokoConsulting/mokocli.git" /tmp/mokocli 2>/dev/null; then
+              RESOLVER=/tmp/mokocli/cli/cascade_resolve.php
+            else
+              echo "::warning::On-demand mokocli install failed; cascade_resolve.php is UNAVAILABLE. Inline resolver handled the routine classes; any remaining conflicts need a human."
+              RESOLVER=/tmp/mokocli/cli/cascade_resolve.php
+            fi
+
+            if [ -f "$RESOLVER" ] && php "$RESOLVER" --path . --theirs-ref "origin/${SRC}"; then
+              git commit -m "chore(sync): cascade ${SRC} -> ${TGT} (auto-resolved) [skip ci]" >/dev/null
+              if land_on_target_via_pr "cascade_resolve auto-resolved the merge (manifests/workflows/docs/stamps, modify-delete) and landed on ${TGT} via PR."; then return 0; fi
+              notify "was auto-resolved but could not be landed on ${TGT} via PR."
+              return 0
+            fi
+
+            # Resolver unavailable, or it bailed on a real (code) conflict -> human.
+            git merge --abort || true
+            notify "has code conflicts cascade_resolve could not safely auto-resolve."
+            return 0
+          }
+
+          # Cascade main into every ladder target that exists, high -> low.
+          RC=0
+          for TGT in ${CASCADE_TARGETS}; do
+            echo "::group::cascade ${SRC} -> ${TGT}"
+            cascade_to "${TGT}" || { echo "::warning::cascade_to ${TGT} returned non-zero"; RC=1; }
+            echo "::endgroup::"
+          done
+
+          # R4 (MokoCLI #967): optional SECOND pass -- cascade dev into its child
+          # BRANCHES. Strict no-op unless DEV_CHILD_TARGETS is set (defaults empty),
+          # so no existing repo changes behaviour. Repoint SRC to `dev` so the same
+          # cascade_to/helpers flow dev -> each child; guarded by dev existing. A
+          # child named `dev` would be self-referential, so it is skipped. dev ->
+          # child REPOS is the SYNC engine's job and is intentionally not done here.
+          if [ -n "${DEV_CHILD_TARGETS// /}" ]; then
+            if branch_exists dev; then
+              SRC="dev"
+              echo "Dev-child cascade source branch: ${SRC}; targets: ${DEV_CHILD_TARGETS}"
+              for TGT in ${DEV_CHILD_TARGETS}; do
+                if [ "${TGT}" = "dev" ]; then
+                  echo "Skipping self-referential dev-child target 'dev'."; continue
+                fi
+                echo "::group::cascade ${SRC} -> ${TGT}"
+                cascade_to "${TGT}" || { echo "::warning::cascade_to ${TGT} returned non-zero"; RC=1; }
+                echo "::endgroup::"
+              done
+            else
+              echo "DEV_CHILD_TARGETS set but no dev branch - skipping dev-child cascade."
+            fi
+          fi
+
+          exit "${RC}"