Release: develop -> main

.coverage-visibility-allowlist

@@ -0,0 +1,30 @@
+# Coverage visibility allowlist — see scripts/check-coverage-visibility.sh.
+#
+# In-scope .dart files that legitimately produce NO coverable lines, so they
+# never emit an `SF:` record in the scoped tracefile and would otherwise trip
+# the visibility gate. Every entry here is a pure abstract interface / port, an
+# enum, const-only data, or a Drift table schema — there is no executable body
+# to cover.
+#
+# This is a ratchet: a NEW in-scope file that carries no coverage fails the
+# build. Fix it by adding a test that exercises it (preferred). Only add a line
+# here if the file genuinely has no coverable lines, and say why in a comment.
+# Blank lines and `#` comments are ignored. Paths are repo-relative.
+
+# Abstract interfaces / ports (implementations live elsewhere and are tested):
+lib/packages/io/backup_exclusion_port.dart
+lib/packages/io/documents_directory_port.dart
+lib/packages/service/biometric/biometric_port.dart
+lib/packages/service/price_service.dart
+lib/screens/kyc/steps/ident/cubits/kyc_ident/sumsub_ident_port.dart
+
+# Enums (no bodies):
+lib/packages/service/biometric/biometric_auth_outcome.dart
+lib/packages/service/dfx/models/payment/payment_info_error.dart
+lib/screens/restore_wallet/cubit/validate_seed/validate_seed_state.dart
+
+# Const-only data (covered as values by default_assets_test.dart, no lines):
+lib/packages/utils/default_assets.dart
+
+# Drift table schema (column getters carry coverage:ignore-line):
+lib/packages/storage/node_storage.dart

.github/workflows/golden-regenerate.yaml

@@ -37,19 +37,38 @@ jobs:
   regenerate:
     name: Regenerate golden baselines
     runs-on: [self-hosted, macOS, ARM64, m3-ultra, realunit-app]
-    timeout-minutes: 30
+    # Same reasoning as `golden-tests` in `pull-request.yaml`: the old 30 was
+    # sized for the cache era (~18 minutes of stalled Actions-cache overhead).
+    # Regeneration is that same workload plus a commit+push, so 15 minutes
+    # still leaves room for a cold Flutter SDK download, and it frees this
+    # repo's single self-hosted slot far sooner when a run wedges. Keep the
+    # two jobs' timeouts in sync, like the rest of their setup.
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
         with:
           # Explicit token so the later `git push` is authenticated. Without
           # this, checkout still works but the remote is configured with no
           # credential helper and the push fails with HTTP 403.
           token: ${{ secrets.GITHUB_TOKEN }}
+          # Single-slot runner can start minutes after dispatch. Default
+          # checkout pins github.sha (stale by then); render against that
+          # tree and the later push is rejected because the branch tip has
+          # moved. Checkout the live head instead (github.ref_name — the
+          # dispatched branch; workflow_dispatch always runs with --ref
+          # <branch>) so baselines match the tree they get committed to.
+          ref: ${{ github.ref_name }}
       - uses: subosito/flutter-action@v2
         with:
           flutter-version: "3.41.6"
           channel: "stable"
-          cache: true
+          # Self-hosted runner already keeps the Flutter SDK persistently
+          # under `_work/_tool` across runs. The Actions cache restore on
+          # this runner stalls at 0.5-0.8 MB/s, times out after the 10
+          # minute segment timeout, falls back to a cache miss anyway,
+          # then burns ~8 minutes on a cache-save — ~18 minutes of pure
+          # overhead that returns nothing useful here.
+          cache: false
       - run: flutter pub get
       - run: dart run tool/generate_localization.dart
       - run: dart run tool/generate_release_info.dart
@@ -75,9 +94,13 @@ jobs:
             exit 0
           fi
           git commit -m "test(goldens): regenerate baselines on the self-hosted runner"
-          # On protected branches (develop/main) this fails by design.
-          # The next step uploads the PNGs as an artifact so the user can
-          # still recover the regen output.
+          # Protected branches (develop/main): fails by design — no force-push,
+          # no bypass. Feature branches: after the ref: fix above this should
+          # normally succeed. If the branch still moves between checkout and
+          # push (now a seconds-wide window), fail loud; the fallback artifact
+          # step below still uploads the PNGs. Recovery: re-dispatch (cheap).
+          # Do NOT rebase or force-push — that would publish baselines that no
+          # longer match the tree head they were rendered against.
           git push
 
       # Runs only if the push step failed. Uploads the regenerated PNGs so

.github/workflows/handbook-build-check.yaml

@@ -68,8 +68,8 @@ jobs:
           set -euo pipefail
           bash scripts/assemble-handbook-screenshots.sh /tmp/handbook-shots
           count=$(ls -1 /tmp/handbook-shots/*.png | wc -l | tr -d ' ')
-          if [ "$count" != "61" ]; then
-            echo "expected 61 screenshots, got $count" >&2
+          if [ "$count" != "278" ]; then
+            echo "expected 278 screenshots, got $count" >&2
             exit 1
           fi
 
@@ -149,11 +149,11 @@ jobs:
             exit 1
           fi
 
-          # Screenshots dir must contain all 61 PNGs assembled from Goldens.
+          # Screenshots dir must contain all 278 PNGs assembled from Goldens.
           # Hit one of them through the auth gate to verify wiring end-to-end.
-          # Mix of original 01-26 range + new 27-61 range so a regression
-          # in either half surfaces here.
-          for name in 01-welcome 11-dashboard 26-terms 35-dashboard-with-balance 46-buy-kyc-required 52-sell-unknown-error 53-buy-payment-details 61-kyc-registration-tax-tin-error; do
+          # Mix of the original 01-61 range and the 62-268 batch (every Golden
+          # baseline) so a regression in either half surfaces here.
+          for name in 01-welcome 11-dashboard 26-terms 35-dashboard-with-balance 46-buy-kyc-required 52-sell-unknown-error 53-buy-payment-details 61-kyc-registration-tax-tin-error 62-welcome-page-android 219-settings-security-page-default 268-phone-number-field-default; do
             code=$(curl -s -o /dev/null -w '%{http_code}' -u "${HANDBOOK_USER:-x}:${HANDBOOK_PASS:-x}" "http://127.0.0.1:8080/screenshots/${name}.png")
             # 200 (auth happens to match) or 401 (auth fails but file exists)
             # both prove the file is on disk. 404 means it was not assembled.

.github/workflows/handbook-deploy.yaml

@@ -25,7 +25,7 @@ on:
     branches: [staging, develop]
     paths:
       - "docs/handbook/**"
-      - "test/goldens/screens/**"
+      - "test/goldens/**"
       - "scripts/assemble-handbook-screenshots.sh"
       - "scripts/assemble-handbook-store-listing.py"
       - "scripts/templates/store-listing.html.tmpl"

.github/workflows/handbook.yaml

@@ -317,13 +317,13 @@ jobs:
       - name: Stage web e2e baselines from web repo
         env:
           WEB_DIR: _web-checkout
-          # RealUnitCH/web commits 18 Playwright visual baselines under
+          # RealUnitCH/web commits 22 Playwright visual baselines under
           # tests/__screenshots__/{desktop-chromium,tablet-chromium,mobile-safari}/.
           # `-ne` below fails the build on ANY drift (add OR remove) so a change
           # to the committed set upstream requires an explicit bump here AND a
           # matching card edit in docs/handbook/de/index.html (#spec-web) in the
           # SAME change — same guard rationale as the api steps above.
-          EXPECTED_WEB_BASELINE_COUNT: 18
+          EXPECTED_WEB_BASELINE_COUNT: 22
         run: |
           set -euo pipefail
 

.github/workflows/pull-request.yaml

@@ -16,32 +16,25 @@ name: RealUnit Build
 #    below (saves macOS-runner minutes while work is still in progress).
 #  - `labeled` / `unlabeled` are intentionally omitted: realunit-app has
 #    no label-gated heavy job here (Tier 3 has its own workflow).
-#  - `push: develop` and `push: staging` keep post-merge verification
-#    as an authoritative source of truth, independent of any PR state.
-#    `staging` participates because feature → staging merges land an
-#    integration commit whose verification cannot be deferred to the
-#    auto-opened staging → develop PR (the gate must be authoritative
-#    at the moment the commit lands on staging). Other branches do not
-#    need a post-push check — the PR-event already covers them.
+#  - `push: develop` keeps post-merge verification as an authoritative
+#    source of truth. Staging fallback routing lives in the separate
+#    `staging-ci-fallback.yaml` workflow: it dispatches this workflow
+#    only when no ready staging → develop PR owns CI for the pushed SHA.
 #  - `workflow_dispatch` is kept as a manual override and is NOT
 #    draft-gated (see the job `if:` guard below).
 on:
   workflow_dispatch:
   push:
-    branches: [develop, staging]
+    branches: [develop]
   pull_request:
     branches-ignore: [main]
     types: [opened, synchronize, reopened, ready_for_review]
 
-# Group by PR number so a new push to the same PR cancels the
-# in-flight run for the outdated commit. macOS runners are scarce —
-# letting an obsolete run finish wastes ~10 minutes per push. Grouping
-# by SHA (the previous approach) put every commit in its own group,
-# which meant no cancellation ever happened and back-to-back pushes
-# queued sequentially.
-# Falls back to `github.ref` for `push` and `workflow_dispatch` events
-# (where there is no `pull_request.number`): `refs/heads/develop` for
-# post-merge runs, the dispatched ref for manual triggers.
+# Group PR runs by PR number, and push/dispatch runs by ref. A new SHA
+# cancels work for the outdated SHA in the same lane. Staging push
+# routing is isolated in `staging-ci-fallback.yaml`; it either relies on
+# this PR workflow or dispatches this workflow as a fallback, but never
+# shares a concurrency group with the PR run.
 concurrency:
   group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
@@ -60,7 +53,7 @@ jobs:
     runs-on: macos-latest
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: subosito/flutter-action@v2
         with:
           flutter-version: "3.41.6"
@@ -151,7 +144,7 @@ jobs:
 
       - name: Upload coverage report
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: coverage-lcov
           path: coverage/lcov.info
@@ -168,7 +161,7 @@ jobs:
       # fail-open (silent `exit 0`).
       - name: Upload coverage summary
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: coverage-summary
           path: coverage/lcov.summary
@@ -228,14 +221,20 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Download coverage summary
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
         with:
           name: coverage-summary
           path: coverage
 
+      - name: Download scoped coverage tracefile
+        uses: actions/download-artifact@v7
+        with:
+          name: coverage-lcov
+          path: coverage
+
       - name: Enforce coverage floor
         run: |
           set -euo pipefail
@@ -275,6 +274,18 @@ jobs:
             fi
           fi
 
+      # Closes the coverage blind spot the floor % alone cannot see: an in-scope
+      # file that no test ever loads is absent from lcov.info entirely, so it
+      # sits in neither the numerator nor the denominator and the scoped %
+      # stays 100 % while the file is wholly untested. This step enumerates the
+      # on-disk activated surface (same globs as the filter step above) and
+      # fails when a file carries no coverage and is not in the committed
+      # lineless allowlist. See scripts/check-coverage-visibility.sh.
+      - name: Enforce in-scope file visibility
+        run: |
+          set -euo pipefail
+          bash scripts/check-coverage-visibility.sh coverage/lcov.info .coverage-visibility-allowlist
+
   # Visual regression tests on the self-hosted runner. Goldens live
   # under `test/goldens/` and are validated pixel-for-pixel against committed
   # baselines under `test/goldens/screens/**/goldens/macos/`. The Mac Studio
@@ -295,14 +306,29 @@ jobs:
     name: Visual Regression
     if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
     runs-on: [self-hosted, macOS, ARM64, m3-ultra, realunit-app]
-    timeout-minutes: 30
+    # 30 was sized for the era when `subosito/flutter-action@v2` still pulled
+    # the SDK through the Actions cache and burned ~18 minutes on a stalled
+    # restore plus the trailing cache-save. Without that overhead the job
+    # finishes in ~1 minute, so 15 is generous headroom — it still covers the
+    # worst normal case, where the SDK is absent from the runner's persistent
+    # tool cache and has to be downloaded from scratch. The lower ceiling is
+    # what matters here: the self-hosted runner has exactly ONE slot for this
+    # repo, so a wedged job blocks every other PR until it is killed. 15 hands
+    # the slot back twice as fast as 30.
+    timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: subosito/flutter-action@v2
         with:
           flutter-version: "3.41.6"
           channel: "stable"
-          cache: true
+          # Self-hosted runner already keeps the Flutter SDK persistently
+          # under `_work/_tool` across runs. The Actions cache restore on
+          # this runner stalls at 0.5-0.8 MB/s, times out after the 10
+          # minute segment timeout, falls back to a cache miss anyway,
+          # then burns ~8 minutes on a cache-save — ~18 minutes of pure
+          # overhead that returns nothing useful here.
+          cache: false
       - run: flutter pub get
       - run: dart run tool/generate_localization.dart
       - run: dart run tool/generate_release_info.dart
@@ -311,7 +337,7 @@ jobs:
         run: flutter test test/goldens
       - name: Upload golden diff on failure
         if: failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: golden-diffs
           path: test/goldens/**/failures/**
@@ -328,10 +354,13 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
         with:
           go-version: "1.25.5"
+          # This repository has no Go module; caching would only emit a
+          # misleading "go.sum not found" warning for this audit-only job.
+          cache: false
 
       - name: Install bitbox-audit
         continue-on-error: true
@@ -359,7 +388,7 @@ jobs:
 
       - name: Upload audit report
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: bitbox-audit-report
           path: bitbox-audit-report.md

.github/workflows/staging-ci-fallback.yaml

@@ -0,0 +1,77 @@
+name: Staging CI Router
+
+# A staging push normally produces a `synchronize` event on the open
+# staging → develop promotion PR. That PR run owns the canonical required
+# checks. If the PR is missing, draft, stale, or cannot be queried, this
+# workflow dispatches the canonical RealUnit Build as a fail-safe.
+on:
+  push:
+    branches: [staging]
+  workflow_dispatch:
+
+permissions:
+  actions: write
+  contents: read
+  pull-requests: read
+
+# Only the newest staging SHA needs routing. This group is deliberately
+# isolated from RealUnit Build, so it can never cancel required PR checks.
+concurrency:
+  group: staging-ci-router-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  route:
+    name: Route staging CI
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Use PR CI or dispatch fail-safe CI
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          SHOULD_DISPATCH=true
+          REASON="manual routing request"
+
+          if [ "${GITHUB_EVENT_NAME}" = "push" ]; then
+            REASON="promotion PR lookup failed"
+            if PULLS_JSON="$(
+              gh api --method GET "/repos/${GITHUB_REPOSITORY}/pulls" \
+                -f state=open \
+                -f base=develop \
+                -f head="${GITHUB_REPOSITORY_OWNER}:staging" \
+                -f per_page=100
+            )"; then
+              if jq -e \
+                --arg repo "${GITHUB_REPOSITORY}" \
+                --arg sha "${GITHUB_SHA}" \
+                'any(.[]; .draft == false and .head.repo.full_name == $repo and .head.sha == $sha)' \
+                <<<"${PULLS_JSON}" >/dev/null; then
+                SHOULD_DISPATCH=false
+                REASON="ready promotion PR at this SHA owns canonical CI"
+              else
+                REASON="no ready promotion PR at this SHA"
+              fi
+            else
+              echo "::warning::Could not query the staging promotion PR; dispatching fail-safe CI"
+            fi
+          fi
+
+          if [ "${SHOULD_DISPATCH}" = "true" ]; then
+            gh workflow run pull-request.yaml \
+              --repo "${GITHUB_REPOSITORY}" \
+              --ref staging
+            echo "::notice::Dispatched RealUnit Build on staging (${REASON})"
+          else
+            echo "::notice::No fallback dispatch needed (${REASON})"
+          fi
+
+          {
+            echo "### Staging CI routing"
+            echo
+            echo "- Fallback dispatched: \`${SHOULD_DISPATCH}\`"
+            echo "- Reason: ${REASON}"
+            echo "- SHA: \`${GITHUB_SHA}\`"
+          } >> "${GITHUB_STEP_SUMMARY}"