@getarbiter/cli 0.5.0

package/dist/templates/github/workflows/06-nightly-lite.yml.ejs

@@ -0,0 +1,125 @@
+<%
+const _cm = (typeof collaborationMode !== 'undefined' ? collaborationMode : 'trunk-solo');
+const _runner = (_cm === 'gated-review' && isL3Plus)
+  ? "${{ vars.CI_BUILD_RUNNER_LABEL || 'ubuntu-latest' }}"
+  : "${{ fromJSON(vars.RUNNER_LABELS_TEST || '[\"ubuntu-latest\"]') }}";
+const _isSoloL3Plus = _cm === 'trunk-solo' && isL3Plus;
+%>name: Nightly Lite (T4-lite)
+
+on:
+  schedule:
+    - cron: '0 3 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: nightly-lite
+  cancel-in-progress: false
+
+jobs:
+  integration-full:
+    name: Full integration tests
+    runs-on: <%- _runner %>
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+<% if (language === 'typescript') { %>
+      - uses: ./.github/actions/setup-node-pnpm
+      - name: Integration tests (full)
+        run: npm run test:integration
+<% } else if (language === 'java') { %>
+      - uses: actions/setup-java@03ad4de0992f5dab5e18fcb136590ce7c4a0ac95 # v5.6.0
+        with:
+          distribution: temurin
+          java-version: '21'
+<% if (buildTool === 'gradle') { %>
+      - uses: gradle/actions/setup-gradle@ed408507eac070d1f99cc633dbcf757c94c7933a # v4
+      - name: Integration tests (full)
+        run: ./gradlew integrationTest
+<% } else { %>
+      - name: Integration tests (full)
+        run: mvn verify -P integration
+<% } %>
+<% } else if (language === 'go') { %>
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: go.mod
+      - name: Integration tests (full)
+        run: go test -tags integration -count=1 ./...
+<% } else if (language === 'python') { %>
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: .python-version
+      - run: pip install -e ".[dev]"
+      - name: Integration tests (full)
+        run: pytest -m integration
+<% } else if (language === 'rust') { %>
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - name: Integration tests (full)
+        run: cargo test --test '*' -- --include-ignored
+<% } %>
+
+  dep-cve-refresh:
+    name: Dependency CVE refresh
+    # #1756: pinned to a LITERAL GitHub-hosted runner, not the usual _runner
+    # self-hosted-capable fallback, on the assumption that GitHub-hosted runners
+    # are not containerized and therefore immune to the Docker-outside-of-Docker
+    # workspace-bind-mount defect that docker-container actions hit on a
+    # self-hosted runner whose own process runs inside a container. Enforced by
+    # scripts/check-docker-action-runner-safety.mjs.
+    # ADR-104: the java branch below runs Trivy fs (aquasecurity/trivy-action), a
+    # composite action with no workspace bind-mount — not subject to that defect
+    # class in the first place (same pattern as _shared-security.yml.ejs).
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+<% if (language === 'typescript') { %>
+      - uses: ./.github/actions/setup-node-pnpm
+      - name: npm audit
+        run: npm audit --omit=dev --audit-level=high
+<% } else if (language === 'java') { %>
+<%- include('_partials/trivy-fs-java.ejs') %>
+<% } else if (language === 'go') { %>
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: go.mod
+      - name: govulncheck
+        uses: golang/govulncheck-action@b625fbe08f3bccbe446d94fbf87fcc875a4f50ee  # v1
+        with:
+          # The action re-checkouts by default; after the explicit checkout above the
+          # second internal checkout adds a duplicate Authorization extraheader and
+          # git fails with 400 "Duplicate header" on private repos (#1865).
+          repo-checkout: false
+<% } else if (language === 'python') { %>
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: .python-version
+      - run: pip install pip-audit
+      - name: pip-audit
+        run: pip-audit --strict
+<% } else if (language === 'rust') { %>
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - name: cargo-audit
+        run: |
+          cargo install cargo-audit --locked
+          cargo audit
+<% } %>
+<% if (_isSoloL3Plus) { %>
+  solo-reactivation-check:
+    name: Solo reactivation check (§11.10(k))
+    runs-on: <%- _runner %>
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Check solo-dev reactivation trigger
+        run: node scripts/check-solo-reactivation.mjs
+        env:
+          EXTERNAL_AUDIT: ${{ vars.EXTERNAL_AUDIT || 'false' }}
+<% } %>

package/dist/templates/github/workflows/06-nightly.yml.ejs

@@ -0,0 +1,25 @@
+name: Nightly (T4)
+
+on:
+  schedule:
+    - cron: '0 2 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  actions: write
+
+concurrency:
+  group: nightly
+  cancel-in-progress: false
+
+jobs:
+  nightly:
+    name: Nightly jobs
+    uses: ./.github/workflows/_nightly.yml
+    permissions:
+      contents: read
+      issues: write
+      actions: write
+    secrets: inherit

package/dist/templates/github/workflows/07-weekly-lite.yml.ejs

@@ -0,0 +1,221 @@
+<%
+// PORT A2 (#1502): weekly-lite — emitted ONLY for trunk-solo L3+ (predicate in
+// src/generators/github.ts: cm === 'trunk-solo' && isL3Plus). A solo prod service
+// runs 06-nightly-lite + 09-heartbeat but is EXCLUDED from the full 07-weekly /
+// 08-monthly deep sweep, so it would never get a deep weekly security pass. This
+// lite weekly fills that gap with three lean jobs: dependency freshness, a stale
+// action-pin audit, and a deep-security subset (Semgrep SAST + full-history secret
+// scan). Mirrors the 06-nightly-lite gating shape. Schedule offset (05:00 Sun) to
+// avoid clashing with 06-nightly-lite (03:00 daily) and the full 07-weekly (04:00 Sun).
+const _runner = "${{ fromJSON(vars.RUNNER_LABELS_TEST || '[\"ubuntu-latest\"]') }}";
+%>name: Weekly Lite (T5-lite)
+
+on:
+  schedule:
+    - cron: '0 5 * * 0'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: weekly-lite
+  cancel-in-progress: false
+
+jobs:
+  dep-freshness:
+    name: Dependency freshness report (lite)
+    runs-on: <%- _runner %>
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+<% if (language === 'typescript') { %>
+      - uses: ./.github/actions/setup-node-pnpm
+      - name: Check outdated packages
+        run: npm outdated || true
+<% } else if (language === 'java') { %>
+      - uses: actions/setup-java@03ad4de0992f5dab5e18fcb136590ce7c4a0ac95 # v5.6.0
+        with:
+          distribution: temurin
+          java-version: '21'
+      - name: Check outdated dependencies
+        run: |
+<% if (buildTool === 'gradle') { %>
+          ./gradlew dependencyUpdates || true
+<% } else { %>
+          mvn versions:display-dependency-updates || true
+<% } %>
+<% } else if (language === 'go') { %>
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: go.mod
+      - name: Check outdated Go modules
+        run: go list -u -m all 2>/dev/null | grep '\[' || true
+<% } else if (language === 'python') { %>
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: .python-version
+      - run: pip install pip-review
+      - name: Check outdated packages
+        run: pip-review || true
+<% } else if (language === 'rust') { %>
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - name: Check outdated crates
+        run: |
+          cargo install cargo-outdated --locked || true
+          cargo outdated || true
+<% } %>
+
+  action-version-audit:
+    name: Stale action pin audit
+    runs-on: <%- _runner %>
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Find SHA-pinned actions older than 180 days
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          WORKFLOWS=$(find .github/workflows -name '*.yml' | head -20)
+          STALE=0
+          # Runners here are always GNU/Linux regardless of the runs-on label (#1785) —
+          # no BSD/macOS `date` fallback is ever reachable in this environment.
+          CUTOFF=$(date -d '180 days ago' +%s)
+          for wf in $WORKFLOWS; do
+            REFS=$(grep -oP 'uses: \S+@[a-f0-9]{40}' "$wf" | sed 's/uses: //' || true)
+            for ref in $REFS; do
+              ACTION=$(echo "$ref" | cut -d@ -f1)
+              SHA=$(echo "$ref" | cut -d@ -f2)
+              PUSHED=$(gh api "repos/$ACTION/git/commits/$SHA" --jq '.committer.date' 2>/dev/null || echo "")
+              if [ -n "$PUSHED" ]; then
+                # FAIL-OPEN-INTENT: an unparseable committer date (e.g. a null/odd API
+                # response) must not crash the whole audit — skip just this ref.
+                if ! PUSHED_EPOCH=$(date -d "$PUSHED" +%s 2>/dev/null); then
+                  echo "::warning::Could not parse commit date '$PUSHED' for $ref in $wf — skipping"
+                  continue
+                fi
+                if [ "$PUSHED_EPOCH" -lt "$CUTOFF" ]; then
+                  echo "::warning::Stale pin in $wf: $ref (pushed $PUSHED)"
+                  STALE=$((STALE + 1))
+                fi
+              fi
+            done
+          done
+          echo "Stale pins found: $STALE"
+
+  deep-security:
+    name: Deep security subset (Semgrep SAST + secret history)
+    runs-on: <%- _runner %>
+    timeout-minutes: 30
+    steps:
+      # #1311: self-hosted persistent workspaces can keep a stale
+      # .git/refs/**/*.lock from an interrupted run, which makes the
+      # deep checkout below fail with "cannot lock ref". No-op on
+      # ephemeral runners.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+      # PORT A2 (#1502): Semgrep is a 2nd SAST that covers what CodeQL misses for a
+      # trunk-solo project — trunk-solo gets no CodeQL (15-codeql) and no full
+      # 06-nightly Semgrep job, so this is its only SAST. Run via the pinned CLI
+      # (no unverified third-party action — INV-76 / the fabricated-pin lesson).
+      # Ruleset configurable via the SEMGREP_RULES repo/org variable.
+      - name: Install Semgrep (pinned CLI)
+        run: pip install semgrep
+      - name: Semgrep SAST (configurable ruleset)
+        env:
+          SEMGREP_RULES: ${{ vars.SEMGREP_RULES || 'auto' }}
+          # Informational by default; set repo/org var SEMGREP_STRICT=true to make
+          # findings fail the weekly-lite gate.
+          SEMGREP_STRICT: ${{ vars.SEMGREP_STRICT }}
+        run: |
+          set -uo pipefail
+          ARGS="--config ${SEMGREP_RULES} --sarif --output semgrep.sarif --metrics=off"
+          if [ "${SEMGREP_STRICT:-}" = "true" ]; then
+            semgrep scan ${ARGS} --error
+          else
+            semgrep scan ${ARGS} || echo "::warning::Semgrep reported findings (informational; set SEMGREP_STRICT=true to block)"
+          fi
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: semgrep-sarif
+          path: semgrep.sarif
+          retention-days: 30
+      # gitleaks-action downloads to a HARDCODED /tmp/gitleaks.tmp. On a self-hosted
+      # runner /tmp survives between jobs, so a leftover from an interrupted download
+      # fails every later install after both internal retries ("Destination file path
+      # /tmp/gitleaks.tmp already exists" then "parameter 'file' is required") — the
+      # cause of #2100.
+      # ponytail: unconditional delete — one gitleaks job per workflow run, so nothing
+      # else is mid-download. If gitleaks ever runs in parallel jobs on one runner,
+      # switch to the curl -> $RUNNER_TEMP/bin install shape used in 01-pr-fast.
+      - name: Clear stale gitleaks download temp
+        run: rm -f /tmp/gitleaks.tmp
+      - name: Gitleaks full history scan
+        uses: gitleaks/gitleaks-action@e0c47f4f8be36e29cdc102c57e68cb5cbf0e8d1e # v3.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: "false"
+        with:
+          args: detect --source . --log-opts="--all --full-history"
+
+  weekly-lite-required:
+    name: Weekly lite gate
+    needs:
+      - dep-freshness
+      - action-version-audit
+      - deep-security
+    if: always()
+    runs-on: <%- _runner %>
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Assert no hard failures
+        run: |
+          RESULTS=(
+            "${{ needs.dep-freshness.result }}"
+            "${{ needs.action-version-audit.result }}"
+            "${{ needs.deep-security.result }}"
+          )
+          FAILED=0
+          for r in "${RESULTS[@]}"; do
+            if [ "$r" = "failure" ]; then
+              FAILED=1
+            fi
+          done
+          if [ "$FAILED" = "1" ]; then
+            echo "::error::One or more weekly-lite jobs failed."
+            exit 1
+          fi
+          echo "Weekly-lite gate passed."
+
+      - name: File issue on failure
+        if: failure()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          # FAIL-OPEN-INTENT: idempotent create — label may already exist (labels.yml/_label-sync.yml own the canonical definition); self-heals an unsynced repo instead of crashing this step.
+          gh label create weekly-regression --color b60205 --description "Weekly (T5) workflow detected a regression" --repo "$GH_REPO" 2>/dev/null || true
+          EXISTING=$(gh issue list \
+            --label weekly-regression \
+            --state open \
+            --limit 1 \
+            --json number \
+            --repo "$GH_REPO" \
+            --jq '.[0].number // empty')
+          if [ -z "$EXISTING" ]; then
+            gh issue create \
+              --title "[weekly-lite] regression detected (${{ github.run_id }})" \
+              --body "Weekly-lite workflow failed. Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
+              --label weekly-regression \
+              --repo "$GH_REPO"
+          fi

package/dist/templates/github/workflows/07-weekly.yml.ejs

@@ -0,0 +1,23 @@
+name: Weekly (T5)
+
+on:
+  schedule:
+    - cron: '0 4 * * 0'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: weekly
+  cancel-in-progress: false
+
+jobs:
+  weekly:
+    name: Weekly jobs
+    uses: ./.github/workflows/_weekly.yml
+    permissions:
+      contents: read
+      issues: write
+    secrets: inherit

package/dist/templates/github/workflows/08-monthly.yml.ejs

@@ -0,0 +1,23 @@
+name: Monthly (T5b)
+
+on:
+  schedule:
+    - cron: '0 4 1 * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: monthly
+  cancel-in-progress: false
+
+jobs:
+  monthly:
+    name: Monthly jobs
+    uses: ./.github/workflows/_monthly.yml
+    permissions:
+      contents: read
+      issues: write
+    secrets: inherit

package/dist/templates/github/workflows/09-heartbeat.yml.ejs

@@ -0,0 +1,268 @@
+name: Heartbeat (T6)
+
+on:
+  schedule:
+    - cron: '0 6 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+  actions: read
+
+concurrency:
+  group: heartbeat
+  cancel-in-progress: true
+
+jobs:
+  assert-nightly-freshness:
+    name: Assert nightly ran within 26h
+    runs-on: ${{ fromJSON(vars.RUNNER_LABELS_TEST || '["ubuntu-latest"]') }}
+    timeout-minutes: 60
+    steps:
+      - name: Check nightly workflow freshness
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          RUN_INFO=$(gh run list \
+            --workflow=06-nightly.yml \
+            --limit 1 \
+            --json conclusion,createdAt \
+            --repo "$GH_REPO" 2>/dev/null || echo '[]')
+
+          CREATED_AT=$(echo "$RUN_INFO" | jq -r '.[0].createdAt // empty')
+          CONCLUSION=$(echo "$RUN_INFO" | jq -r '.[0].conclusion // empty')
+
+          if [ -z "$CREATED_AT" ]; then
+            echo "::error::No nightly run found. Heartbeat FAIL — nightly workflow has never run."
+            exit 1
+          fi
+
+          CREATED_EPOCH=$(date -d "$CREATED_AT" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CREATED_AT" +%s)
+          NOW_EPOCH=$(date +%s)
+          AGE_HOURS=$(( (NOW_EPOCH - CREATED_EPOCH) / 3600 ))
+
+          echo "Last nightly: $CREATED_AT (${AGE_HOURS}h ago, conclusion: $CONCLUSION)"
+
+          if [ "$AGE_HOURS" -gt 26 ]; then
+            echo "::error::Nightly workflow last ran ${AGE_HOURS}h ago — exceeds 26h threshold."
+            exit 1
+          fi
+
+          echo "Nightly freshness OK — last run ${AGE_HOURS}h ago."
+
+      - name: Ensure heartbeat-nightly-missed label exists
+        if: always()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          gh label create heartbeat-nightly-missed \
+            --description "Nightly workflow freshness check failed" \
+            --color "d73a4a" \
+            --repo "$GH_REPO" \
+            --force
+
+      - name: Open or close heartbeat issue
+        if: always()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          CHECK_OUTCOME: ${{ steps.check.outcome }}
+        run: |
+          EXISTING=$(gh issue list \
+            --label heartbeat-nightly-missed \
+            --state open \
+            --limit 1 \
+            --json number \
+            --repo "$GH_REPO" \
+            --jq '.[0].number // empty')
+
+          if [ "$CHECK_OUTCOME" = "failure" ]; then
+            if [ -z "$EXISTING" ]; then
+              gh issue create \
+                --title "[heartbeat] nightly workflow missed" \
+                --body "The nightly workflow (06-nightly.yml) has not run within the expected 26h window. Investigate immediately." \
+                --label heartbeat-nightly-missed \
+                --repo "$GH_REPO"
+            else
+              echo "Existing heartbeat issue #$EXISTING already open — skipping duplicate."
+            fi
+          else
+            if [ -n "$EXISTING" ]; then
+              gh issue close "$EXISTING" \
+                --comment "Heartbeat recovered — nightly workflow is fresh again." \
+                --repo "$GH_REPO"
+              echo "Closed recovered heartbeat issue #$EXISTING."
+            fi
+          fi
+
+  assert-weekly-freshness:
+    name: Assert weekly ran within 8 days
+    runs-on: ${{ fromJSON(vars.RUNNER_LABELS_TEST || '["ubuntu-latest"]') }}
+    timeout-minutes: 60
+    steps:
+      - name: Check weekly workflow freshness
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          RUN_INFO=$(gh run list \
+            --workflow=07-weekly.yml \
+            --limit 1 \
+            --json conclusion,createdAt \
+            --repo "$GH_REPO" 2>/dev/null || echo '[]')
+
+          CREATED_AT=$(echo "$RUN_INFO" | jq -r '.[0].createdAt // empty')
+          CONCLUSION=$(echo "$RUN_INFO" | jq -r '.[0].conclusion // empty')
+
+          if [ -z "$CREATED_AT" ]; then
+            echo "::error::No weekly run found. Heartbeat FAIL — weekly workflow has never run."
+            exit 1
+          fi
+
+          CREATED_EPOCH=$(date -d "$CREATED_AT" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CREATED_AT" +%s)
+          NOW_EPOCH=$(date +%s)
+          AGE_DAYS=$(( (NOW_EPOCH - CREATED_EPOCH) / 86400 ))
+
+          echo "Last weekly: $CREATED_AT (${AGE_DAYS}d ago, conclusion: $CONCLUSION)"
+
+          if [ "$AGE_DAYS" -gt 8 ]; then
+            echo "::error::Weekly workflow last ran ${AGE_DAYS}d ago — exceeds 8-day threshold."
+            exit 1
+          fi
+
+          echo "Weekly freshness OK — last run ${AGE_DAYS}d ago."
+
+      - name: Ensure heartbeat-weekly-missed label exists
+        if: always()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          gh label create heartbeat-weekly-missed \
+            --description "Weekly workflow freshness check failed" \
+            --color "d73a4a" \
+            --repo "$GH_REPO" \
+            --force
+
+      - name: Open or close heartbeat issue
+        if: always()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          CHECK_OUTCOME: ${{ steps.check.outcome }}
+        run: |
+          EXISTING=$(gh issue list \
+            --label heartbeat-weekly-missed \
+            --state open \
+            --limit 1 \
+            --json number \
+            --repo "$GH_REPO" \
+            --jq '.[0].number // empty')
+
+          if [ "$CHECK_OUTCOME" = "failure" ]; then
+            if [ -z "$EXISTING" ]; then
+              gh issue create \
+                --title "[heartbeat] weekly workflow missed" \
+                --body "The weekly workflow (07-weekly.yml) has not run within the expected 8-day window. Investigate immediately." \
+                --label heartbeat-weekly-missed \
+                --repo "$GH_REPO"
+            else
+              echo "Existing heartbeat issue #$EXISTING already open — skipping duplicate."
+            fi
+          else
+            if [ -n "$EXISTING" ]; then
+              gh issue close "$EXISTING" \
+                --comment "Heartbeat recovered — weekly workflow is fresh again." \
+                --repo "$GH_REPO"
+              echo "Closed recovered heartbeat issue #$EXISTING."
+            fi
+          fi
+
+  assert-monthly-freshness:
+    name: Assert monthly ran within 35 days
+    runs-on: ${{ fromJSON(vars.RUNNER_LABELS_TEST || '["ubuntu-latest"]') }}
+    timeout-minutes: 60
+    steps:
+      - name: Check monthly workflow freshness
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          RUN_INFO=$(gh run list \
+            --workflow=08-monthly.yml \
+            --limit 1 \
+            --json conclusion,createdAt \
+            --repo "$GH_REPO" 2>/dev/null || echo '[]')
+
+          CREATED_AT=$(echo "$RUN_INFO" | jq -r '.[0].createdAt // empty')
+          CONCLUSION=$(echo "$RUN_INFO" | jq -r '.[0].conclusion // empty')
+
+          if [ -z "$CREATED_AT" ]; then
+            echo "::error::No monthly run found. Heartbeat FAIL — monthly workflow has never run."
+            exit 1
+          fi
+
+          CREATED_EPOCH=$(date -d "$CREATED_AT" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CREATED_AT" +%s)
+          NOW_EPOCH=$(date +%s)
+          AGE_DAYS=$(( (NOW_EPOCH - CREATED_EPOCH) / 86400 ))
+
+          echo "Last monthly: $CREATED_AT (${AGE_DAYS}d ago, conclusion: $CONCLUSION)"
+
+          if [ "$AGE_DAYS" -gt 35 ]; then
+            echo "::error::Monthly workflow last ran ${AGE_DAYS}d ago — exceeds 35-day threshold."
+            exit 1
+          fi
+
+          echo "Monthly freshness OK — last run ${AGE_DAYS}d ago."
+
+      - name: Ensure heartbeat-monthly-missed label exists
+        if: always()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          gh label create heartbeat-monthly-missed \
+            --description "Monthly workflow freshness check failed" \
+            --color "d73a4a" \
+            --repo "$GH_REPO" \
+            --force
+
+      - name: Open or close heartbeat issue
+        if: always()
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          CHECK_OUTCOME: ${{ steps.check.outcome }}
+        run: |
+          EXISTING=$(gh issue list \
+            --label heartbeat-monthly-missed \
+            --state open \
+            --limit 1 \
+            --json number \
+            --repo "$GH_REPO" \
+            --jq '.[0].number // empty')
+
+          if [ "$CHECK_OUTCOME" = "failure" ]; then
+            if [ -z "$EXISTING" ]; then
+              gh issue create \
+                --title "[heartbeat] monthly workflow missed" \
+                --body "The monthly workflow (08-monthly.yml) has not run within the expected 35-day window. Investigate immediately." \
+                --label heartbeat-monthly-missed \
+                --repo "$GH_REPO"
+            else
+              echo "Existing heartbeat issue #$EXISTING already open — skipping duplicate."
+            fi
+          else
+            if [ -n "$EXISTING" ]; then
+              gh issue close "$EXISTING" \
+                --comment "Heartbeat recovered — monthly workflow is fresh again." \
+                --repo "$GH_REPO"
+              echo "Closed recovered heartbeat issue #$EXISTING."
+            fi
+          fi